Extension reference: callbacks and storage contracts

Use this reference when adapting the package to your application's data and policy. It lists constructor callbacks and storage interfaces, when the package calls them, and whether their return value or failure can stop a flow. The exported symbol is the stable API name; the descriptive label is only a navigation aid.

How to read the reference

Two properties decide how a trigger point behaves, and every row states both.

• Control — what the seam can do to the flow:

  • blocks — the seam runs inside the flow and can stop it. It denies by return value (null, false, { approved: false }, an issue string) or by throwing; either way the flow does not continue as if nothing happened.

  • fire-and-forget — the seam is for a side effect (audit, notification, re-render). Its throw is caught and logged, never rethrown, so it cannot affect the outcome. Use it when you need observability, not a gate.

• On throw — what a thrown error actually does at the call site, traced to the code, because this is where accidental and deliberate behaviour diverge. A blocks seam usually surfaces the throw as a specific protocol error; a fire-and-forget seam swallows it. Rows call out the cases where a throw does something surprising.

Stability. A trigger-point's export name is public API under stability.md — renaming one is a breaking change, and its throw contract is part of the wire behaviour the servers promise. The Symbol column names the exact export; that name, not the informal trigger-point label, is the stable identifier.

Authorization server — @udibo/oauth2/server

Seams on AuthorizationServer and its grants. Unless noted, a throw from a seam reached through an endpoint is caught by that endpoint and converted to an RFC 6749 §5.2 error response (or, on the authorize path once the redirect URI is validated, a redirect to the client with error=…).

Resource server — @udibo/oauth2/server/resource

authenticate() does not try/catch its seams; the adapter boundary (handleAuthError) converts what they throw. The readers deliberately keep a down issuer (temporarily_unavailable) distinct from an invalid token (invalid_token).

Identity — @udibo/oauth2/identity

The identity protections are opt-in: rateLimiter and lockout do nothing unless you pass them. passwordPolicy is not — the policy check runs on every signUp and resetPassword, at its 8–256 character defaults when you pass nothing; the option only tightens it. A throw from a store or hook here propagates out of the IdentityService method you called and up to your route, unless the row says otherwise.

External providers — @udibo/oauth2/identity/external

ExternalAuthFlow is deliberately storage-free and has no callback hooks of its own: finish() returns a verified ExternalProfile and your app does find-or-create-user, session start, and rejection outside the flow, in its own try/catch. The seams below live on the provider connectors.

MFA — @udibo/oauth2/identity/mfa

MfaService decides nothing about when to demand a factor — that stays your app's sign-in policy. It exposes read methods (enrollmentStatus, isEnrolled) and a verify you call; there is no app-supplied challenge hook to veto (see Gaps). The app implements one required interface plus the two shared optional seams.

Hono BFF — @udibo/oauth2/hono/bff

Hono adapters — authorization server & identity

Client — @udibo/oauth2/client

React auth forms — @udibo/oauth2/react/components

Seams on the headless useAuthForm hook and the prebuilt components.

Known gaps

These responsibilities stay in the application or use a separate API.

• No dedicated pre-registration veto. The only way to reject a sign-up on something other than the password is to throw from IdentityUserStore.create (or reject the password with a passwordPolicy validator). There is no beforeCreate/allowlist/domain-restriction seam.

• No service-layer post-authentication hook. After signIn verifies a credential, nothing app-supplied can inspect or veto the success (e.g. force MFA, reject a disabled user) — that gating lives in your route.

• Access-token claims use a separate API. The authorization server's userClaims reaches ID tokens and UserInfo. Use createJwtAccessTokenGenerator and its claims options when your app issues JWT access tokens.

• No MFA-challenge seam in IdentityService. IdentityService has zero MFA integration; MFA is the separate @udibo/oauth2/identity/mfa module, and when to demand a factor is your app's decision.

Failure behavior to account for

• A signing failure surfaces after the token row is persisted. tokenService.save runs before mintIdToken / JWT-access-token generation, so a signing-key outage returns server_error for a token that already exists.

• Inconsistent legacy-credential contract. A getLegacyCredential throw aborts sign-in, but a clearLegacyCredential throw is swallowed — even though the docs tell implementers to provide both together.

• BFF resolveUser / resolveOrigin throws are misclassified. Failures in these post-exchange app hooks are relabeled invalid_grant "code exchange failed" because they sit inside the exchange try/catch.

• BFF onCallbackError is unguarded. A throw from the error handler itself propagates to Hono (500).