passkey

type AfterAuthenticationHook func(ctx context.Context, passkey *entity.Passkey, user *entity.User, session *entity.Session) error

type AfterRegistrationHook func(ctx context.Context, passkey *entity.Passkey, user *entity.User) error

type AuthenticationFailedPayload struct {
	UserID         *string        `json:"userId,omitempty"`
	ChallengeToken string         `json:"challengeToken"`
	Reason         string         `json:"reason"`
	Extra          map[string]any `json:"extra,omitempty"`
	Timestamp      time.Time      `json:"timestamp"`
}

type AuthenticationOptionsCreatedPayload struct {
	UserID         *string        `json:"userId,omitempty"`
	ChallengeToken string         `json:"challengeToken"`
	ExpiresAt      time.Time      `json:"expiresAt"`
	Extra          map[string]any `json:"extra,omitempty"`
	Timestamp      time.Time      `json:"timestamp"`
}

type AuthenticationOptionsResult struct {
	Options        *protocol.CredentialAssertion `json:"options"`
	ChallengeToken string                        `json:"challengeToken"`
	ExpiresAt      time.Time                     `json:"expiresAt"`
}

type AuthenticationVerifiedPayload struct {
	Passkey   *entity.Passkey `json:"passkey"`
	User      *entity.User    `json:"user"`
	Session   *entity.Session `json:"session"`
	Extra     map[string]any  `json:"extra,omitempty"`
	Timestamp time.Time       `json:"timestamp"`
}

type CeremonyType string

type Config struct {
	RPDisplayName                string                               // Relying Party human-readable name (default: "GoModularAuth")
	RPID                         string                               // Relying Party domain identifier (default: "localhost")
	RPOrigins                    []string                             // Allowed origin URLs (e.g. "http://localhost:3000")
	ChallengeTimeout             time.Duration                        // Ephemeral challenge lifespan (default: 5 minutes)
	RequireSessionOnRegistration bool                                 // Enforce caller session during registration (default: true)
	UserVerification             protocol.UserVerificationRequirement // User verification requirement (default: "preferred")
	ResidentKey                  protocol.ResidentKeyRequirement      // Resident key / Discoverable credential preference (default: "preferred")
	Attestation                  protocol.ConveyancePreference        // Attestation conveyance preference (default: "none")
	AuthenticatorAttachment      *protocol.AuthenticatorAttachment    // Optional attachment ("platform" or "cross-platform")
	SessionDuration              time.Duration                        // Lifespan of created user sessions (default: 7 days)
	ResolveUser                  ResolveUserFunc                      // User resolution callback
	AfterRegistration            AfterRegistrationHook                // Post-registration hook
	AfterAuthentication          AfterAuthenticationHook              // Post-authentication hook
}

type DeletePasskeyParams struct {
	ID           string `json:"id"`
	CallerUserID string `json:"callerUserId"`
	plugin.ExtraContainer
}

type GenerateAuthenticationOptionsParams struct {
	UserID *string `json:"userId,omitempty"` // Optional. Omit for discoverable/resident key/autofill login.
	plugin.ExtraContainer
}

type GenerateRegistrationOptionsParams struct {
	UserID                  string                            `json:"userId,omitempty"`
	UserName                string                            `json:"userName,omitempty"`
	UserDisplayName         string                            `json:"userDisplayName,omitempty"`
	AuthenticatorAttachment *protocol.AuthenticatorAttachment `json:"authenticatorAttachment,omitempty"`
	Context                 *string                           `json:"context,omitempty"`
	CustomName              *string                           `json:"customName,omitempty"`
	plugin.ExtraContainer
}

type ListPasskeysParams struct {
	UserID string `json:"userId"`
	plugin.ExtraContainer
}

type Option func(*Config)

type PasskeyChallenge struct {
	Token       string       `json:"token"`
	Type        CeremonyType `json:"type"`
	Challenge   string       `json:"challenge"`
	UserID      *string      `json:"userId,omitempty"`
	UserName    *string      `json:"userName,omitempty"`
	DisplayName *string      `json:"displayName,omitempty"`
	Context     *string      `json:"context,omitempty"`
	SessionData string       `json:"sessionData"` // Serialized JSON of webauthn.SessionData
	ExpiresAt   time.Time    `json:"expiresAt"`
	CreatedAt   time.Time    `json:"createdAt"`
}

type PasskeyDeletedPayload struct {
	PasskeyID string    `json:"passkeyId"`
	UserID    string    `json:"userId"`
	Timestamp time.Time `json:"timestamp"`
}

type PasskeyRegistrationUser struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	DisplayName string `json:"displayName"`
}

type PasskeyUpdatedPayload struct {
	Passkey   *entity.Passkey `json:"passkey"`
	OldName   *string         `json:"oldName,omitempty"`
	NewName   string          `json:"newName"`
	Timestamp time.Time       `json:"timestamp"`
}

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

type RegistrationFailedPayload struct {
	UserID         *string        `json:"userId,omitempty"`
	ChallengeToken string         `json:"challengeToken"`
	Reason         string         `json:"reason"`
	Extra          map[string]any `json:"extra,omitempty"`
	Timestamp      time.Time      `json:"timestamp"`
}

type RegistrationOptionsCreatedPayload struct {
	UserID         string         `json:"userId"`
	UserName       string         `json:"userName"`
	ChallengeToken string         `json:"challengeToken"`
	ExpiresAt      time.Time      `json:"expiresAt"`
	Extra          map[string]any `json:"extra,omitempty"`
	Timestamp      time.Time      `json:"timestamp"`
}

type RegistrationOptionsResult struct {
	Options        *protocol.CredentialCreation `json:"options"`
	ChallengeToken string                       `json:"challengeToken"`
	ExpiresAt      time.Time                    `json:"expiresAt"`
}

type RegistrationVerifiedPayload struct {
	Passkey   *entity.Passkey `json:"passkey"`
	User      *entity.User    `json:"user"`
	Extra     map[string]any  `json:"extra,omitempty"`
	Timestamp time.Time       `json:"timestamp"`
}

type Repository interface {
	// CreatePasskey persists a new WebAuthn passkey credential record.
	//
	// Function:
	//   Called upon completing a WebAuthn registration ceremony to store public key credentials.
	//
	// Storage:
	//   Database (GORM / SQL) - Persistent storage for WebAuthn public keys.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - passkey: The Passkey entity containing credential ID, public key, counter, and transports.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   INSERT INTO passkeys (id, user_id, credential_id, public_key, counter, aaguid, name, created_at, updated_at)
	//   VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9);
	CreatePasskey(ctx context.Context, passkey *entity.Passkey) error

	// GetPasskeyByID retrieves a passkey credential by its primary key ID.
	//
	// Function:
	//   Used during passkey management (viewing or renaming passkeys).
	//
	// Storage:
	//   Database (GORM / SQL) - Passkey record lookup by ID.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - id: Unique passkey record identifier.
	//
	// Returns:
	//   - *entity.Passkey: Matching passkey entity if found.
	//   - error: ErrPasskeyNotFound if missing, or database error.
	//
	// Example SQL:
	//   SELECT id, user_id, credential_id, public_key, counter, aaguid, name, created_at, updated_at FROM passkeys WHERE id = $1 LIMIT 1;
	GetPasskeyByID(ctx context.Context, id string) (*entity.Passkey, error)

	// GetPasskeyByCredentialID retrieves a passkey credential by its raw WebAuthn credential ID.
	//
	// Function:
	//   Used during authentication ceremony verification to locate the matching public key.
	//
	// Storage:
	//   Database (GORM / SQL) - Query by unique credential ID string.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - credentialID: Base64URL encoded credential ID string.
	//
	// Returns:
	//   - *entity.Passkey: Matching passkey entity if found.
	//   - error: ErrPasskeyNotFound if missing, or database error.
	//
	// Example SQL:
	//   SELECT id, user_id, credential_id, public_key, counter, aaguid, name, created_at, updated_at FROM passkeys WHERE credential_id = $1 LIMIT 1;
	GetPasskeyByCredentialID(ctx context.Context, credentialID string) (*entity.Passkey, error)

	// ListPasskeysByUserID retrieves all registered passkey credentials belonging to a user.
	//
	// Function:
	//   Used during user security settings listing or passwordless sign-in user credential discovery.
	//
	// Storage:
	//   Database (GORM / SQL) - Query registered credentials by user ID.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: Target user identifier.
	//
	// Returns:
	//   - []*entity.Passkey: Slice of registered passkey credentials.
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   SELECT id, user_id, credential_id, public_key, counter, aaguid, name, created_at, updated_at FROM passkeys WHERE user_id = $1;
	ListPasskeysByUserID(ctx context.Context, userID string) ([]*entity.Passkey, error)

	// UpdatePasskey updates mutable attributes of an existing passkey (e.g. friendly name).
	//
	// Function:
	//   Used when a user renames a registered passkey.
	//
	// Storage:
	//   Database (GORM / SQL) - Record update.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - passkey: Modified passkey entity.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   UPDATE passkeys SET name = $1, updated_at = $2 WHERE id = $3;
	UpdatePasskey(ctx context.Context, passkey *entity.Passkey) error

	// UpdatePasskeyCounter updates the signature counter of a passkey after successful assertion.
	//
	// Function:
	//   Called after validating an authentication ceremony response to prevent clone attacks.
	//
	// Storage:
	//   Database (GORM / SQL) - Signature counter update.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - id: Unique passkey record ID.
	//   - newCounter: Incrementally higher signature counter value.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   UPDATE passkeys SET counter = $1, updated_at = $2 WHERE id = $3;
	UpdatePasskeyCounter(ctx context.Context, id string, newCounter uint32) error

	// DeletePasskey permanently removes a single passkey credential record.
	//
	// Function:
	//   Called when a user revokes or deletes a passkey in security settings.
	//
	// Storage:
	//   Database (GORM / SQL) - Passkey credential deletion.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - id: Passkey record identifier.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   DELETE FROM passkeys WHERE id = $1;
	DeletePasskey(ctx context.Context, id string) error

	// DeletePasskeysByUserID purges all passkeys belonging to a user.
	//
	// Function:
	//   Called during user account deletion.
	//
	// Storage:
	//   Database (GORM / SQL) - Bulk passkey deletion.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: Target user identifier.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   DELETE FROM passkeys WHERE user_id = $1;
	DeletePasskeysByUserID(ctx context.Context, userID string) error

	// SavePasskeyChallenge persists an ephemeral WebAuthn ceremony challenge record.
	//
	// Function:
	//   Called during generate-register-options and generate-authenticate-options endpoints.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Short-lived in-flight challenge token with TTL.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - challenge: Ephemeral PasskeyChallenge state.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   INSERT INTO passkey_challenges (token, type, challenge, user_id, session_data, expires_at, created_at) VALUES ($1, $2, $3, $4, $5, $6, $7);
	//
	// Example Cache (Redis):
	//   err := rdb.Set(ctx, "webauthn:challenge:" + challenge.Token, bytes, ttl).Err()
	SavePasskeyChallenge(ctx context.Context, challenge *PasskeyChallenge) error

	// GetPasskeyChallenge retrieves an active ceremony challenge record by challenge token string.
	//
	// Function:
	//   Used to inspect challenge state without consuming it.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Ephemeral challenge lookup.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - token: Ephemeral challenge token identifier.
	//
	// Returns:
	//   - *PasskeyChallenge: Matching challenge state.
	//   - error: ErrChallengeNotFound if missing or expired.
	//
	// Example SQL:
	//   SELECT token, type, challenge, user_id, session_data, expires_at, created_at FROM passkey_challenges WHERE token = $1 LIMIT 1;
	//
	// Example Cache (Redis):
	//   val, err := rdb.Get(ctx, "webauthn:challenge:" + token).Bytes()
	GetPasskeyChallenge(ctx context.Context, token string) (*PasskeyChallenge, error)

	// ConsumePasskeyChallenge atomically retrieves and removes an in-flight ceremony challenge record.
	//
	// Function:
	//   Called during ceremony verification endpoints to ensure single-use replay protection.
	//
	// Storage:
	//   Cache (Redis GETDEL / Memory) - Atomic read-and-delete single-use challenge consumption.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - token: Ephemeral challenge token identifier.
	//
	// Returns:
	//   - *PasskeyChallenge: The consumed challenge state if valid.
	//   - error: ErrChallengeNotFound if missing, or ErrChallengeExpired if passed validity time.
	//
	// Example SQL:
	//   DELETE FROM passkey_challenges WHERE token = $1 AND expires_at > $2 RETURNING token, type, challenge, user_id, session_data, expires_at, created_at;
	//
	// Example Cache (Redis):
	//   val, err := rdb.GetDel(ctx, "webauthn:challenge:" + token).Bytes()
	ConsumePasskeyChallenge(ctx context.Context, token string) (*PasskeyChallenge, error)

	// DeletePasskeyChallenge removes a challenge record from storage by token.
	//
	// Function:
	//   Called during explicit cancellation or cleanup.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Challenge token eviction.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - token: Challenge token string.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   DELETE FROM passkey_challenges WHERE token = $1;
	//
	// Example Cache (Redis):
	//   err := rdb.Del(ctx, "webauthn:challenge:" + token).Err()
	DeletePasskeyChallenge(ctx context.Context, token string) error

	// GetUserByID retrieves user profile details by ID.
	//
	// Function:
	//   Used during passkey registration to populate WebAuthn User Entity details (name, display name).
	//
	// Storage:
	//   Database (GORM / SQL) - User primary key lookup.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: Target user identifier.
	//
	// Returns:
	//   - *entity.User: Matching user entity if found.
	//   - error: ErrUserNotFound if missing, or database error.
	//
	// Example SQL:
	//   SELECT id, email, name, email_verified, created_at, updated_at FROM users WHERE id = $1 LIMIT 1;
	GetUserByID(ctx context.Context, userID string) (*entity.User, error)

	// GetUserByEmail retrieves user profile details by email address.
	//
	// Function:
	//   Used during passwordless authentication initiation when identifying user by email.
	//
	// Storage:
	//   Database (GORM / SQL) - Query user by email address.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - email: User primary email address.
	//
	// Returns:
	//   - *entity.User: Matching user entity if found.
	//   - error: ErrUserNotFound if missing, or database error.
	//
	// Example SQL:
	//   SELECT id, email, name, email_verified, created_at, updated_at FROM users WHERE email = $1 LIMIT 1;
	GetUserByEmail(ctx context.Context, email string) (*entity.User, error)

	// CreateSession initializes and persists a new authenticated user session.
	//
	// Function:
	//   Called after successful passkey authentication ceremony completion.
	//
	// Storage:
	//   Database (GORM / SQL) - Active session creation.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - session: DTO containing user ID, token, expiration, IP address, and user agent.
	//
	// Returns:
	//   - *entity.Session: Populated active session entity.
	//   - error: ErrUnableToCreateSession on failure.
	//
	// Example SQL:
	//   INSERT INTO sessions (id, user_id, token, expires_at, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6);
	CreateSession(ctx context.Context, session *dto.CreateSessionParams) (*entity.Session, error)
}

type ResolveUserFunc func(ctx context.Context, queryContext *string, extra map[string]any) (*PasskeyRegistrationUser, error)

type UpdatePasskeyParams struct {
	ID           string `json:"id"`
	CallerUserID string `json:"callerUserId"`
	Name         string `json:"name"`
	plugin.ExtraContainer
}

type VerifyAuthenticationParams struct {
	ChallengeToken string                                `json:"challengeToken"`
	Origin         string                                `json:"origin,omitempty"`
	Response       *protocol.CredentialAssertionResponse `json:"response"`
	plugin.ExtraContainer
}

type VerifyAuthenticationResult struct {
	User    *entity.User    `json:"user"`
	Session *entity.Session `json:"session"`
	Passkey *entity.Passkey `json:"passkey"`
}

type VerifyRegistrationParams struct {
	ChallengeToken string                               `json:"challengeToken"`
	Origin         string                               `json:"origin,omitempty"`
	Response       *protocol.CredentialCreationResponse `json:"response"`
	Name           *string                              `json:"name,omitempty"`
	CallerUserID   *string                              `json:"callerUserId,omitempty"`
	plugin.ExtraContainer
}