idv

type AzureConfig ¶ added in v0.4.1

type AzureConfig struct {
	Endpoint   string
	Key        string
	SessionTTL time.Duration // session token validity; default 10m
	HTTPClient *http.Client  // optional override for tests
}

AzureConfig configures an AzureProvider. Endpoint is the Cognitive Services endpoint URL (e.g. https://my-face.cognitiveservices.azure.com) and Key is the subscription key.

type AzureProvider ¶ added in v0.4.1

type AzureProvider struct {
	// contains filtered or unexported fields
}

AzureProvider implements Provider using Azure AI Face Liveness Detection (passive + active liveness). Document OCR + face-match against the document can be layered on top in a follow-up.

API reference:

POST {endpoint}/face/v1.2-preview.1/detectLiveness/singleModal/sessions
GET  {endpoint}/face/v1.2-preview.1/detectLiveness/singleModal/sessions/{id}

func NewAzureProvider(cfg AzureConfig) (*AzureProvider, error)

func (p *AzureProvider) BeginVerification(ctx context.Context, req Request) (*Session, error)

func (p *AzureProvider) GetVerification(ctx context.Context, providerSessionID string) (*StatusResult, error)

func (p *AzureProvider) Name() string

type Provider ¶

type Provider interface {
	// Name returns the provider identifier (e.g., "azure", "stub").
	// It is persisted in IdentityVerificationRecord.Provider so an
	// audit reader can tell which backend issued a session.
	Name() string

	// BeginVerification creates a new verification session.
	BeginVerification(ctx context.Context, req Request) (*Session, error)

	// GetVerification returns the current state of an existing
	// session. Sync providers (Azure Face API) query the upstream
	// service; async providers (Onfido webhooks) return their last
	// known state, which the caller's webhook handler keeps fresh.
	GetVerification(ctx context.Context, providerSessionID string) (*StatusResult, error)
}

Provider is the pluggable identity-verification backend. The service layer holds exactly one Provider for the lifetime of the process; multi-provider deployments use a Provider that dispatches on tenant configuration internally.

type Request ¶

type Request struct {
	UserID      string // local user id, used as the provider-side actor
	TenantID    string // local tenant id, for providers that scope by it
	Email       string // optional, for applicant creation
	DisplayName string // optional, for applicant creation
	RedirectURL string // optional, for hosted-flow providers
}

Request is the input to BeginVerification. All fields except UserID are optional; providers that need them (e.g. Onfido's applicant API) read what is present and ignore the rest.

type Session ¶

type Session struct {
	ProviderSessionID string    // provider's identifier for the check
	SessionToken      string    // opaque token the client SDK exchanges
	ExpiresAt         time.Time // when SessionToken stops accepting captures
}

Session is what a provider returns from BeginVerification. The caller persists ProviderSessionID alongside the locally-issued verification_id and returns SessionToken + ExpiresAt to the client so the SDK can drive document capture and liveness.

type StatusResult ¶

type StatusResult struct {
	Status          string    // one of Status* constants
	RejectionReason string    // empty unless Status == StatusRejected
	CompletedAt     time.Time // zero if Status is pending/in_review
}

Status is the current state of a verification as reported by the provider. The CompletedAt zero value means the provider has not reached a terminal verdict yet.

type StubProvider ¶

type StubProvider struct {
	// Verdict controls the StatusResult returned by GetVerification
	// for sessions whose verdict has not been set explicitly. Defaults
	// to StatusApproved so tests of the happy path do not need setup.
	Verdict string

	// Clock returns the current time. Tests may override.
	Clock func() time.Time

	// SessionTTL is the lifetime applied to ExpiresAt. Defaults to 15m.
	SessionTTL time.Duration
	// contains filtered or unexported fields
}

StubProvider is an in-process Provider for tests and bring-up. It accepts every BeginVerification call, returns a deterministic SessionToken, and lets the test set the verdict that subsequent GetVerification calls will report.

Production deployments MUST replace this with a real provider (e.g. AzureProvider). Wiring intentionally defaults to StubProvider only when no provider is configured, so a misconfigured deploy fails closed: signups marked verified by the stub will not pass the real-provider gate in any non-test environment.

func NewStubProvider() *StubProvider

func (s *StubProvider) BeginVerification(_ context.Context, _ Request) (*Session, error)

func (s *StubProvider) GetVerification(_ context.Context, providerSessionID string) (*StatusResult, error)

func (s *StubProvider) Name() string

func (s *StubProvider) SetVerdict(providerSessionID, status, reason string)