lookup

type AuthStore interface {
	Login(ctx context.Context, req sectypes.LoginRequest) (*sectypes.LoginResponse, error)
	Register(ctx context.Context, req sectypes.RegisterRequest) (*sectypes.LoginResponse, error)
	Logout(ctx context.Context, req sectypes.LogoutRequest) error
	// Session resolves a session token to its user. reference says where the token came
	// from ("authenticate", "cookie", "refresh"); the procedure backend passes it through.
	Session(ctx context.Context, token, reference string) (*sectypes.UserContext, error)
	// TouchSession records last activity for a session token. user is the context the
	// session resolved to; the procedure backend passes it to the update procedure.
	TouchSession(ctx context.Context, token string, user *sectypes.UserContext) error
	Refresh(ctx context.Context, refreshToken string) (*sectypes.LoginResponse, error)
	// LoginAPIKey logs in with a raw header/generic API key. Unknown, expired, inactive and
	// wrong-type keys all return the same error.
	LoginAPIKey(ctx context.Context, rawKey string, claims map[string]any) (*sectypes.LoginResponse, error)
	JWTLogin(ctx context.Context, req sectypes.LoginRequest) (*sectypes.LoginResponse, error)
	JWTLogout(ctx context.Context, req sectypes.LogoutRequest) error
	ResetRequest(ctx context.Context, req sectypes.PasswordResetRequest) (*sectypes.PasswordResetResponse, error)
	ResetComplete(ctx context.Context, req sectypes.PasswordResetCompleteRequest) error
}

type Column struct {
	Entity Entity
	Name   string
}

type Config struct {
	// Dialect names a registered dialect ("postgres", "sqlite", "mysql", "mssql", or one added
	// with dialect.Register). Empty = detect from the driver.
	Dialect string
	// Mode is the default mode for every operation. See ModeDefault.
	Mode Mode
	// Overrides sets the mode per operation, e.g. direct for OpSession, procedure for OpLogin.
	Overrides map[Op]Mode
	// Procs overrides procedure names; empty fields keep the default.
	Procs ProcNames
	// Schema overrides table and column names; missing entries keep the default.
	Schema Schema
}

type Consent struct {
	UserID    int       `json:"user_id"`
	ClientID  string    `json:"client_id"`
	Scopes    []string  `json:"scopes"`
	ExpiresAt time.Time `json:"expires_at"`
}

type DeviceCode struct {
	DeviceHash   string       `json:"device_hash"`
	UserCode     string       `json:"user_code"`
	ClientID     string       `json:"client_id"`
	Scopes       []string     `json:"scopes,omitempty"`
	Status       DeviceStatus `json:"status"`
	UserID       int          `json:"user_id,omitempty"`
	SessionToken string       `json:"session_token,omitempty"`
	Interval     int          `json:"interval"` // minimum seconds between polls
	ExpiresAt    time.Time    `json:"expires_at"`
}

type DeviceStatus string

type Entity string

type KeyStore interface {
	Create(ctx context.Context, req sectypes.CreateKeyRequest, keyHash string) (*sectypes.UserKey, error)
	List(ctx context.Context, userID int, keyType sectypes.KeyType) ([]sectypes.UserKey, error)
	// Delete soft-deletes a key after verifying ownership and returns its hash so callers can
	// invalidate caches. The hash is empty when the backend cannot report it.
	Delete(ctx context.Context, userID int, keyID int64) (keyHash string, err error)
	Validate(ctx context.Context, keyHash string, keyType sectypes.KeyType) (*sectypes.UserKey, error)
}

type Mode string

type OAuthClientStore interface {
	RegisterClient(ctx context.Context, client *sectypes.OAuthServerClient) (*sectypes.OAuthServerClient, error)
	GetClient(ctx context.Context, clientID string) (*sectypes.OAuthServerClient, error)
	SaveCode(ctx context.Context, code *sectypes.OAuthCode) error
	// ExchangeCode atomically consumes an authorization code.
	ExchangeCode(ctx context.Context, code string) (*sectypes.OAuthCode, error)
	Introspect(ctx context.Context, token string) (*sectypes.OAuthTokenInfo, error)
	Revoke(ctx context.Context, token string) error
	// UpdateClient rewrites the registration fields of an existing client (RFC 7592).
	UpdateClient(ctx context.Context, client *sectypes.OAuthServerClient) error
	// DeleteClient deactivates a client.
	DeleteClient(ctx context.Context, clientID string) error
}

type OAuthGrantStore interface {
	// SaveConsent replaces the consent of (UserID, ClientID).
	SaveConsent(ctx context.Context, c Consent) error
	// GetConsent returns the unexpired consent or ErrNotFound.
	GetConsent(ctx context.Context, userID int, clientID string) (*Consent, error)
	RevokeConsent(ctx context.Context, userID int, clientID string) error

	SaveRefresh(ctx context.Context, t RefreshToken) error
	// RotateRefresh atomically consumes the token with hash oldHash and stores next in the same
	// family. It returns the consumed token. An unknown, expired or revoked token is
	// ErrRefreshInvalid. A token that was already consumed revokes its family and returns the
	// token together with ErrRefreshReused so the caller can end the session.
	RotateRefresh(ctx context.Context, oldHash string, next RefreshToken) (*RefreshToken, error)
	// PeekRefresh returns the token without consuming it. Unknown, expired and revoked tokens are
	// ErrRefreshInvalid; an already rotated token is returned so RotateRefresh can report its reuse.
	PeekRefresh(ctx context.Context, hash string) (*RefreshToken, error)
	RevokeRefreshFamily(ctx context.Context, familyID string) error
	// RevokeRefreshBySession revokes every refresh token bound to a session token.
	RevokeRefreshBySession(ctx context.Context, sessionToken string) error

	CreateDevice(ctx context.Context, d DeviceCode) error
	// DeviceByUserCode returns the unexpired pending device authorization or ErrNotFound.
	DeviceByUserCode(ctx context.Context, userCode string) (*DeviceCode, error)
	// DeviceDecide approves or denies the device authorization of userCode.
	DeviceDecide(ctx context.Context, userCode string, approve bool, userID int, sessionToken string) error
	// DevicePoll implements the token endpoint side: it enforces the poll interval and returns
	// one of ErrDevicePending, ErrDeviceSlowDown, ErrDeviceDenied, ErrDeviceExpired or, once
	// approved, the record (consumed: it cannot be polled again).
	DevicePoll(ctx context.Context, deviceHash string) (*DeviceCode, error)

	SavePushedRequest(ctx context.Context, r PushedRequest) error
	// ConsumePushedRequest returns and deletes the request or ErrNotFound.
	ConsumePushedRequest(ctx context.Context, requestURI string) (*PushedRequest, error)

	// SeenJTI records key until expires and reports whether it was already recorded. It is the
	// replay cache for DPoP proofs and client assertions.
	SeenJTI(ctx context.Context, key string, expires time.Time) (bool, error)
}

type OAuthRefreshSession struct {
	UserID      int       `json:"user_id"`
	AccessToken string    `json:"access_token"`
	TokenType   string    `json:"token_type"`
	Expiry      time.Time `json:"expiry"`
}

type OAuthSession struct {
	SessionToken string
	UserID       int
	AccessToken  string
	RefreshToken string
	TokenType    string
	ExpiresAt    time.Time
	Provider     string
}

type OAuthUserStore interface {
	GetOrCreateUser(ctx context.Context, user *sectypes.UserContext, provider string) (int, error)
	CreateSession(ctx context.Context, session OAuthSession) error
	GetByRefreshToken(ctx context.Context, refreshToken string) (*OAuthRefreshSession, error)
	UpdateRefreshToken(ctx context.Context, userID int, oldRefreshToken, newSessionToken, newAccessToken, newRefreshToken string, expiresAt time.Time) error
	GetUser(ctx context.Context, userID int) (*sectypes.UserContext, error)
}

type Op string

type PasskeyCredentialRecord struct {
	UserID          int
	CredentialID    string // base64
	PublicKey       string // base64
	AttestationType string
	SignCount       uint32
	Transports      []string
	BackupEligible  bool
	BackupState     bool
	Name            string
}

type PasskeyCredentialRef struct {
	CredentialID string   `json:"credential_id"`
	Transports   []string `json:"transports"`
}

type PasskeyStore interface {
	Store(ctx context.Context, rec PasskeyCredentialRecord) (int64, error)
	// Get returns the owner and signature counter of a credential.
	Get(ctx context.Context, credentialID string) (userID int, signCount uint32, err error)
	UpdateCounter(ctx context.Context, credentialID string, newCounter uint32) (cloneWarning bool, err error)
	List(ctx context.Context, userID int) ([]sectypes.PasskeyCredential, error)
	Delete(ctx context.Context, userID int, credentialID string) error
	Rename(ctx context.Context, userID int, credentialID, name string) error
	ByUsername(ctx context.Context, username string) (userID int, creds []PasskeyCredentialRef, err error)
	Login(ctx context.Context, userID int, claims map[string]any) (*sectypes.LoginResponse, error)
}

type PolicyStore interface {
	ColumnSecurity(ctx context.Context, userID int, schema, table string) ([]sectypes.ColumnSecurity, error)
	RowSecurity(ctx context.Context, userRef any, schema, table string) (sectypes.RowSecurity, error)
}

type ProcNames struct {

	// Auth procedures (DatabaseAuthenticator)
	Login         string // default: "resolvespec_login"
	Register      string // default: "resolvespec_register"
	Logout        string // default: "resolvespec_logout"
	Session       string // default: "resolvespec_session"
	SessionUpdate string // default: "resolvespec_session_update"
	RefreshToken  string // default: "resolvespec_refresh_token"
	LoginAPIKey   string // default: "resolvespec_login_api_key"

	// JWT procedures (JWTAuthenticator)
	JWTLogin  string // default: "resolvespec_jwt_login"
	JWTLogout string // default: "resolvespec_jwt_logout"

	// Security policy procedures
	ColumnSecurity string // default: "resolvespec_column_security"
	RowSecurity    string // default: "resolvespec_row_security"

	// TOTP procedures (DatabaseTwoFactorProvider)
	TOTPEnable             string // default: "resolvespec_totp_enable"
	TOTPDisable            string // default: "resolvespec_totp_disable"
	TOTPGetStatus          string // default: "resolvespec_totp_get_status"
	TOTPGetSecret          string // default: "resolvespec_totp_get_secret"
	TOTPRegenerateBackup   string // default: "resolvespec_totp_regenerate_backup_codes"
	TOTPValidateBackupCode string // default: "resolvespec_totp_validate_backup_code"

	// Passkey procedures (DatabasePasskeyProvider)
	PasskeyStoreCredential    string // default: "resolvespec_passkey_store_credential"
	PasskeyGetCredsByUsername string // default: "resolvespec_passkey_get_credentials_by_username"
	PasskeyGetCredential      string // default: "resolvespec_passkey_get_credential"
	PasskeyUpdateCounter      string // default: "resolvespec_passkey_update_counter"
	PasskeyGetUserCredentials string // default: "resolvespec_passkey_get_user_credentials"
	PasskeyDeleteCredential   string // default: "resolvespec_passkey_delete_credential"
	PasskeyUpdateName         string // default: "resolvespec_passkey_update_name"
	PasskeyLogin              string // default: "resolvespec_passkey_login"

	// Password reset procedures (DatabaseAuthenticator)
	PasswordResetRequest  string // default: "resolvespec_password_reset_request"
	PasswordResetComplete string // default: "resolvespec_password_reset"

	// OAuth2 procedures (DatabaseAuthenticator OAuth2 methods)
	OAuthGetOrCreateUser    string // default: "resolvespec_oauth_getorcreateuser"
	OAuthCreateSession      string // default: "resolvespec_oauth_createsession"
	OAuthGetRefreshToken    string // default: "resolvespec_oauth_getrefreshtoken"
	OAuthUpdateRefreshToken string // default: "resolvespec_oauth_updaterefreshtoken"
	OAuthGetUser            string // default: "resolvespec_oauth_getuser"

	// OAuth2 server procedures (OAuthServer persistence)
	OAuthRegisterClient string // default: "resolvespec_oauth_register_client"
	OAuthGetClient      string // default: "resolvespec_oauth_get_client"
	OAuthSaveCode       string // default: "resolvespec_oauth_save_code"
	OAuthExchangeCode   string // default: "resolvespec_oauth_exchange_code"
	OAuthIntrospect     string // default: "resolvespec_oauth_introspect"
	OAuthRevoke         string // default: "resolvespec_oauth_revoke"
	OAuthUpdateClient   string // default: "resolvespec_oauth_update_client"
	OAuthDeleteClient   string // default: "resolvespec_oauth_delete_client"

	// OAuth2 server grant procedures (consents, refresh tokens, device codes, PAR, replay cache).
	// Each takes a jsonb request and returns (p_success, p_error, p_data).
	OAuthSaveConsent         string // default: "resolvespec_oauth_save_consent"
	OAuthGetConsent          string // default: "resolvespec_oauth_get_consent"
	OAuthRevokeConsent       string // default: "resolvespec_oauth_revoke_consent"
	OAuthSaveRefresh         string // default: "resolvespec_oauth_save_refresh"
	OAuthRotateRefresh       string // default: "resolvespec_oauth_rotate_refresh"
	OAuthPeekRefresh         string // default: "resolvespec_oauth_peek_refresh"
	OAuthRevokeRefreshFamily string // default: "resolvespec_oauth_revoke_refresh_family"
	OAuthRevokeRefreshByUser string // default: "resolvespec_oauth_revoke_refresh_session"
	OAuthCreateDevice        string // default: "resolvespec_oauth_create_device"
	OAuthDeviceByUserCode    string // default: "resolvespec_oauth_device_by_user_code"
	OAuthDeviceDecide        string // default: "resolvespec_oauth_device_decide"
	OAuthDevicePoll          string // default: "resolvespec_oauth_device_poll"
	OAuthSavePAR             string // default: "resolvespec_oauth_save_par"
	OAuthConsumePAR          string // default: "resolvespec_oauth_consume_par"
	OAuthSeenJTI             string // default: "resolvespec_oauth_seen_jti"

	// Keystore procedures (KeyStore)
	KeystoreGetUserKeys string // default: "resolvespec_keystore_get_user_keys"
	KeystoreCreateKey   string // default: "resolvespec_keystore_create_key"
	KeystoreDeleteKey   string // default: "resolvespec_keystore_delete_key"
	KeystoreValidateKey string // default: "resolvespec_keystore_validate_key"
}

type Provider struct {
	Auth        AuthStore
	Keys        KeyStore
	OAuthClient OAuthClientStore
	OAuthUser   OAuthUserStore
	OAuthGrant  OAuthGrantStore
	Passkey     PasskeyStore
	TOTP        TOTPStore
	Policy      PolicyStore
}

type PushedRequest struct {
	RequestURI string            `json:"request_uri"`
	ClientID   string            `json:"client_id"`
	Params     map[string]string `json:"params"`
	ExpiresAt  time.Time         `json:"expires_at"`
}

type RefreshToken struct {
	TokenHash    string         `json:"token_hash"`
	FamilyID     string         `json:"family_id"`
	ClientID     string         `json:"client_id"`
	UserID       int            `json:"user_id"`
	SessionToken string         `json:"session_token"`
	Scopes       []string       `json:"scopes,omitempty"`
	Extra        map[string]any `json:"extra,omitempty"` // nonce, auth_time, acr, sid, dpop_jkt, resource
	ExpiresAt    time.Time      `json:"expires_at"`
}

type Resolved struct {
	Config
	Procs  ProcNames
	Schema Schema
}

type Schema map[Entity]Table

type TOTPStore interface {
	Enable(ctx context.Context, userID int, secret string, hashedCodes []string) error
	Disable(ctx context.Context, userID int) error
	Status(ctx context.Context, userID int) (bool, error)
	Secret(ctx context.Context, userID int) (string, error)
	RegenerateBackupCodes(ctx context.Context, userID int, hashedCodes []string) error
	ValidateBackupCode(ctx context.Context, userID int, codeHash string) (bool, error)
}

type Table struct {
	// Schema optionally qualifies the table (schema.table). Empty = unqualified.
	Schema string
	// Name is the physical table name. Empty = default (the entity name).
	Name string
	// Columns maps logical column name -> physical column name. Missing = default.
	Columns map[string]string
}