identity

package
v0.24.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type IdentityHooks

type IdentityHooks struct {
	// OnRegisterTx fires INSIDE the user-creation transaction; only paths
	// that create a user in one transaction (password register, admin
	// create) fire it. An error rolls the registration back. Bind roles and
	// other must-succeed-with-the-user state here. It never fires on the
	// JIT paths (OAuth / verification code) — those users come to life
	// outside any caller-owned transaction.
	OnRegisterTx func(ctx context.Context, tx pgx.Tx, userID string) error

	// AfterRegister fires AFTER COMMIT on every registration path (password,
	// admin create, OAuth JIT, code JIT) with tx intentionally absent — the
	// nil-tx trap is structurally gone. MUST be idempotent: failures are
	// logged at ERROR, surfaced as LoginResult.ProvisioningPending, and the
	// account's next login re-fires it (consumers using the provisioning
	// factory get login-time convergence for free). Never fails the
	// registration or the login that triggered it.
	AfterRegister func(ctx context.Context, userID string) error

	// AfterLogin fires after a session has been established on every
	// successful login (password, verification code, third-party
	// completion); sessionID identifies the session just created.
	// Observational: an error is logged at WARN and never blocks the login.
	AfterLogin func(ctx context.Context, userID, sessionID string) error

	// OnLoginFailed fires on every rejected authentication (wrong password,
	// bad/expired verification code, too many attempts, signup-gate block),
	// keyed by the attempted email and a hashed source IP. Observational:
	// an error is logged at WARN and swallowed — a down risk sink must not
	// turn a failed login into a 5xx.
	OnLoginFailed func(ctx context.Context, email, ipHash string) error

	// AfterPasswordChange fires after the user's own ChangePassword
	// succeeds (new hash stored, all previous sessions revoked, a fresh
	// session issued). It does not fire on admin resets or reset-link
	// flows. Observational: an error is logged at WARN only.
	AfterPasswordChange func(ctx context.Context, userID string) error
}

IdentityHooks is the identity domain's extension surface. The register hooks are split by lifecycle, not by transport (ADR 0016):

  • OnRegisterTx covers state that must succeed WITH the user (role binding, tenant rows) — it shares the creation transaction's atomicity.
  • AfterRegister covers post-commit provisioning (personal workspace, welcome email, onboarding credits) — it must be idempotent because a failure never rolls the user back and is re-fired on the next login by consumers using the provisioning factory.

The nil-tx trap of the pre-split single AfterRegister (one signature serving in-transaction and post-commit paths; a hook written for the transactional path panicked on OAuth/code JIT) is structurally gone: the post-commit hook has no transaction parameter.

func ChainHooks added in v0.17.0

func ChainHooks(hooks ...IdentityHooks) IdentityHooks

ChainHooks composes several IdentityHooks into the single hook value the services accept (WithHooks / WithIdentityHooks take exactly one). It exists because the extension points are composition magnets — provisioning takes AfterRegister/AfterLogin (ADR 0016), the legal module takes the same pair for acceptance evidence — and without a chain one product hook would silently shadow the other at the wiring site.

Field semantics follow hooks.go, not a new policy:

  • OnRegisterTx runs in argument order and SHORT-CIRCUITS on the first error: it is the transactional hook, an error rolls the registration back, and later hooks must not run inside a doomed transaction whose earlier hook already failed.
  • AfterRegister / AfterLogin / OnLoginFailed / AfterPasswordChange are observational: every chained hook runs even when an earlier one fails (one sink being down must not starve the others), errors are joined and returned so the identity caller keeps its existing contract — AfterRegister's joined error still surfaces as LoginResult.ProvisioningPending and re-fires on the next login, the others are logged at WARN and swallowed by the caller. The chain itself never logs: the identity firing sites already do, and the joined error names the failing hook index for attribution.

nil safety: nil arguments and nil hook fields are skipped entirely; a field with no surviving contributor stays nil so the firing site's fast-path check keeps skipping it.

Directories

Path Synopsis
adapters

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL