@rebasepro/server 0.13.1-canary.gef9608c → 0.14.0

package/dist/auth/interfaces.d.ts

@@ -55,7 +55,21 @@ export interface OAuthProviderProfile {
     email: string;
     displayName?: string | null;
     photoUrl?: string | null;
-    /** Whether the OAuth provider has verified the user's email address */
+    /**
+     * Whether the provider reported that it verified this email address.
+     *
+     * This is not a display field. It is the sole authorization input to
+     * account linking: a `true` here lets the sign-in route attach the
+     * incoming identity to a pre-existing account that shares the address.
+     * Set it `true` **only** from a verification signal actually present in
+     * the provider's response — pass that signal through
+     * `providerVerifiedEmail()` rather than writing a literal, so a provider
+     * that reports nothing comes back `false`.
+     *
+     * `false` is not a failure: the user signs in and, if they already have an
+     * account, links through `POST /auth/link/<provider>`, which proves
+     * ownership with a live session instead of an unverified address.
+     */
     emailVerified?: boolean;
 }
 /**
@@ -138,6 +152,15 @@ export interface RefreshTokenInfo {
     revoked?: boolean;
     /** When the sign-in happened; carried across rotations, unlike createdAt. */
     sessionStartedAt?: Date;
+    /**
+     * The assurance level this session was established at. See
+     * {@link RefreshTokenSession.aal} — refresh reads it from here and mints
+     * the replacement access token at the same level.
+     *
+     * Absent on rows written before this column existed, and on repositories
+     * that do not store it; both read as `aal1`, the restrictive value.
+     */
+    aal?: "aal1" | "aal2";
 }
 /**
  * Identity of the sign-in a refresh token belongs to, threaded through
@@ -146,6 +169,16 @@ export interface RefreshTokenInfo {
 export interface RefreshTokenSession {
     id: string;
     startedAt: Date;
+    /**
+     * How this session was established: `aal2` only where a second factor was
+     * actually presented.
+     *
+     * Persisted because refresh has nothing else to go on. Deriving it at
+     * refresh time from "does this user have a factor?" would promote every
+     * pre-existing password-only session of a user who later enrolled — the
+     * assurance level is a property of the *sign-in*, not of the account.
+     */
+    aal?: "aal1" | "aal2";
 }
 /**
  * Password reset token info
@@ -408,6 +441,12 @@ export interface MfaFactor {
     verified: boolean;
     createdAt: Date;
     updatedAt: Date;
+    /**
+     * The highest TOTP time step ever accepted for this factor. A code whose
+     * step is at or below it has already been spent — see
+     * {@link MfaRepository.claimMfaFactorCounter}.
+     */
+    lastUsedCounter?: number | null;
 }
 /**
  * MFA challenge information
@@ -418,6 +457,8 @@ export interface MfaChallengeInfo {
     createdAt: Date;
     verifiedAt?: Date;
     ipAddress?: string;
+    /** Failed verifications recorded against this challenge so far. */
+    attempts?: number;
 }
 /**
  * Recovery code data structure
@@ -450,6 +491,19 @@ export interface MfaRepository {
      * Mark an MFA factor as verified
      */
     verifyMfaFactor(factorId: string): Promise<void>;
+    /**
+     * Replace a factor's stored ciphertext with an equivalent one.
+     *
+     * Used only to re-wrap a secret under the current `MFA_ENCRYPTION_KEY`
+     * after it opened with an older one, so that a key rotation completes as
+     * users sign in rather than needing a migration. The plaintext secret is
+     * unchanged, so a repository that does not implement this is not broken —
+     * its factors simply stay on the key that wrote them, and that key has to
+     * remain in `MFA_ENCRYPTION_KEY_PREVIOUS`.
+     *
+     * Optional for that reason: callers must check before calling.
+     */
+    updateMfaFactorSecret?(factorId: string, secretEncrypted: string): Promise<void>;
     /**
      * Delete an MFA factor
      */
@@ -486,6 +540,32 @@ export interface MfaRepository {
      * Check if a user has any verified MFA factors
      */
     hasVerifiedMfaFactors(uid: string): Promise<boolean>;
+    /**
+     * Claim a TOTP time step for a factor: succeed once, then never again for
+     * that step or any earlier one.
+     *
+     * One statement, claim-and-act — `UPDATE … WHERE last_used_counter IS NULL
+     * OR last_used_counter < $counter RETURNING id`. A read-then-write would
+     * let two requests carrying the same code both pass the check before either
+     * wrote, which is precisely the replay this exists to stop.
+     *
+     * Optional so a repository written against an older release still compiles;
+     * where it is absent, an accepted code stays replayable for the rest of its
+     * window and the route says so in the log.
+     *
+     * @returns true when the step was claimed by this call, false when it had
+     *          already been spent.
+     */
+    claimMfaFactorCounter?(factorId: string, counter: number): Promise<boolean>;
+    /**
+     * Record a failed verification against a challenge and return the new
+     * total. Atomic (`UPDATE … SET attempts = attempts + 1 RETURNING attempts`)
+     * so concurrent guesses cannot share one increment.
+     *
+     * Optional; where it is absent the route falls back to the rate limiters
+     * alone.
+     */
+    recordMfaChallengeAttempt?(challengeId: string): Promise<number>;
 }
 /**
  * Combined auth repository interface for convenience

package/dist/auth/jwt.d.ts

@@ -14,6 +14,18 @@ export interface AccessTokenPayload {
     roles: string[];
     /** Authentication Assurance Level: aal1 = password/oauth, aal2 = MFA verified */
     aal?: "aal1" | "aal2";
+    /**
+     * When the token was issued, in seconds since the epoch — the standard JWT
+     * `iat` claim, which `jsonwebtoken` sets on every token it signs.
+     *
+     * Carried through verification because revocation needs it: `logout`,
+     * `change-password`, `reset-password` and `DELETE /auth/sessions` all stamp
+     * a `tokensValidAfter` watermark on the user, and a token is void if it was
+     * issued before that mark. `verifyAccessToken` used to rebuild the payload
+     * from three claims and drop this one, so nothing downstream could make the
+     * comparison and the watermark was read on exactly one path — refresh.
+     */
+    iat?: number;
     /** Email claim from the JWT, if present */
     email?: string;
     /** Display name claim from the JWT, if present */
@@ -98,6 +110,34 @@ export declare function getRefreshTokenTtlMs(): number;
  * Calculate refresh token expiration date
  */
 export declare function getRefreshTokenExpiry(): Date;
+/**
+ * The `purpose` claim carried by a credential that stands between "first factor
+ * accepted" and "session issued".
+ *
+ * A pre-auth token is NOT a session and must never be usable as one:
+ * {@link verifyAccessToken} refuses any token carrying a `purpose`, so this
+ * value cannot authenticate a request no matter which route it is presented to.
+ * The only thing that reads it is the MFA challenge pair, which exchanges it —
+ * plus a second factor — for a real session.
+ */
+export declare const MFA_PENDING_PURPOSE = "mfa-pending";
+/**
+ * Mint the short-lived credential handed back with an `MFA_REQUIRED` response.
+ *
+ * Short-lived on purpose: it is the window in which a caller who has proven the
+ * first factor may present the second, not a session to be carried around. Five
+ * minutes matches the challenge TTL.
+ */
+export declare function generateMfaPendingToken(uid: string, expiresInSeconds?: number): string;
+/**
+ * Verify a pre-auth token and return the user it was minted for.
+ *
+ * Returns `null` for anything else — including a perfectly valid *access*
+ * token, which must not be interchangeable with this one in either direction.
+ */
+export declare function verifyMfaPendingToken(token: string): {
+    uid: string;
+} | null;
 export interface DownloadTokenPayload {
     purpose: "file-read";
     path: string;

package/dist/auth/linkedin-oauth.d.ts

@@ -1,4 +1,5 @@
 import type { OAuthProvider } from "./interfaces";
+import { type OAuthCodeFlowPayload } from "./oauth-code-flow";
 export interface LinkedinUserInfo {
     linkedinId: string;
     email: string;
@@ -12,7 +13,4 @@ export interface LinkedinUserInfo {
 export declare function createLinkedinProvider(config: {
     clientId: string;
     clientSecret: string;
-}): OAuthProvider<{
-    code: string;
-    redirectUri: string;
-}>;
+}): OAuthProvider<OAuthCodeFlowPayload>;

package/dist/auth/mfa-crypto.d.ts

@@ -3,7 +3,36 @@
  *
  * - Derives a 32-byte key via SHA-256 from `MFA_ENCRYPTION_KEY` or `JWT_SECRET`.
  * - Generates a random 12-byte IV per encryption call.
- * - Returns ciphertexts in the format `iv_hex:authTag_hex:ciphertext_hex`.
+ * - Stamps the key that made the ciphertext, so the key can be changed without
+ *   locking every enrolled user out — see "Rotating the key" below.
+ *
+ * ## Rotating the key
+ *
+ * A ciphertext used to be `iv:authTag:ciphertext` and recorded nothing about
+ * which key produced it, while the key was re-derived from the environment on
+ * every call. Setting `MFA_ENCRYPTION_KEY` on a deployment that had been
+ * falling back to `JWT_SECRET` therefore made every stored factor undecryptable
+ * — AES-GCM authenticates, so it did not return a wrong secret, it threw, and
+ * every MFA sign-in failed until the variable was removed again.
+ *
+ * Now a ciphertext carries `v1.<keyId>`, where `keyId` is derived from the key
+ * itself (no key names to keep in sync), and decryption runs against a list of
+ * candidates: `MFA_ENCRYPTION_KEY`, then each comma-separated entry in
+ * `MFA_ENCRYPTION_KEY_PREVIOUS`, then `JWT_SECRET`. To rotate:
+ *
+ * 1. **Deploy this code first.** It reads both formats. Doing it the other way
+ *    round — setting the key before the readers understand the old ciphertexts
+ *    — is the outage this exists to prevent.
+ * 2. Move the old value into `MFA_ENCRYPTION_KEY_PREVIOUS` and set the new one
+ *    as `MFA_ENCRYPTION_KEY`.
+ * 3. Each factor is re-wrapped with the current key the next time its owner
+ *    authenticates (`openTotpSecret` reports it via `rewrapped`).
+ * 4. Once every enrolled user has signed in, drop `MFA_ENCRYPTION_KEY_PREVIOUS`.
+ *    Any factor still on the old key then fails loudly, naming the key id,
+ *    rather than being silently unreadable.
+ *
+ * Trial decryption across candidates is safe here: GCM's auth tag is a 128-bit
+ * MAC, so a wrong key throws instead of yielding a plausible-looking secret.
  *
  * @module
  */
@@ -11,13 +40,35 @@
  * Encrypt a plaintext TOTP secret.
  *
  * @param plaintext - The Base32 TOTP secret to encrypt.
- * @returns A string in the format `iv_hex:authTag_hex:ciphertext_hex`.
+ * @returns A string in the format `v1.<keyId>:iv_hex:authTag_hex:ciphertext_hex`.
  */
 export declare function encryptTotpSecret(plaintext: string): string;
+/** What a factor's stored secret opened to, and whether it should be re-stored. */
+export interface OpenedTotpSecret {
+    /** The Base32 TOTP secret. */
+    secret: string;
+    /**
+     * Set when the secret opened with something other than the current key —
+     * the same secret, re-encrypted under it. Persist this and the factor
+     * stops depending on the old key. `null` when it is already current.
+     */
+    rewrapped: string | null;
+}
+/**
+ * Decrypt a stored TOTP secret, reporting whether it wants re-wrapping.
+ *
+ * Accepts both the key-stamped format and the original unstamped
+ * `iv:authTag:ciphertext`, which is tried against each candidate in turn.
+ */
+export declare function openTotpSecret(ciphertext: string): OpenedTotpSecret;
 /**
  * Decrypt a previously encrypted TOTP secret.
  *
- * @param ciphertext - A string in the format `iv_hex:authTag_hex:ciphertext_hex`.
+ * Prefer {@link openTotpSecret} on any path that can persist the result —
+ * this wrapper discards the re-wrapped form, so a factor read through it stays
+ * on whichever key it was written with.
+ *
+ * @param ciphertext - A stored TOTP secret, in either format.
  * @returns The original Base32 TOTP secret.
  */
 export declare function decryptTotpSecret(ciphertext: string): string;

package/dist/auth/mfa-gate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The gate between "first factor accepted" and "session issued".
+ *
+ * MFA used to be modelled as an optional step-up that no resource required: a
+ * user could enrol TOTP, print recovery codes, and change nothing about what a
+ * stolen password bought, because every session-minting route issued a full
+ * `aal1` token without ever asking whether the account had a second factor.
+ * This module is the ask. It lives apart from the routes so that there is one
+ * decision, made once, that `createSessionAndTokens` cannot be extended past —
+ * a new sign-in route inherits the gate by construction rather than by the
+ * author remembering it.
+ *
+ * @module
+ */
+import type { AuthRepository } from "./interfaces";
+/** Error code a client watches for to switch a sign-in into its second step. */
+export declare const MFA_REQUIRED_CODE = "MFA_REQUIRED";
+/** Shape carried in `error.details` of an {@link MFA_REQUIRED_CODE} response. */
+export interface MfaRequiredDetails {
+    /**
+     * Short-lived, purpose-scoped credential proving the first factor was
+     * accepted. It is refused as a session everywhere (`verifyAccessToken`
+     * rejects purpose-scoped tokens); `POST /auth/mfa/challenge` and
+     * `POST /auth/mfa/challenge/verify` are the only routes that accept it.
+     */
+    mfaToken: string;
+    /** The verified factors the caller may answer the challenge with. */
+    factors: Array<{
+        id: string;
+        factorType: string;
+        friendlyName?: string;
+    }>;
+}
+/**
+ * Refuse to mint a session for an account whose second factor has not been
+ * presented, handing back what the client needs to present it.
+ *
+ * A 401 rather than a 200 with a different body: a client that has not been
+ * taught about MFA must fail, not proceed. The credential in `details` is
+ * useless for anything except the challenge routes.
+ */
+export declare function assertMfaSatisfied(authRepo: AuthRepository, uid: string): Promise<void>;

package/dist/auth/mfa-routes.d.ts

@@ -4,4 +4,29 @@ import { HonoEnv } from "../api/types";
 import type { AuthModuleConfig } from "./routes";
 import { resolveAuthHooks } from "./auth-hooks";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
-export declare function mountMfaRoutes(router: Hono<HonoEnv>, config: AuthModuleConfig, ops: ReturnType<typeof resolveAuthHooks>, parseBody: <T>(schema: z.ZodSchema<T>, body: unknown) => T, applyTransformHook?: (response: AuthResponsePayload, method: TransformAuthResponseContext["method"], request: Request, uid: string) => Promise<AuthResponsePayload>): void;
+interface MfaRoutesConfig {
+    router: Hono<HonoEnv>;
+    config: AuthModuleConfig;
+    ops: ReturnType<typeof resolveAuthHooks>;
+    parseBody: <T>(schema: z.ZodSchema<T>, body: unknown) => T;
+    buildAuthResponse: (user: {
+        id: string;
+        email: string;
+        displayName?: string | null;
+        photoUrl?: string | null;
+        emailVerified?: boolean;
+        isAnonymous?: boolean;
+        metadata?: Record<string, unknown> | null;
+    }, roleIds: string[], accessToken: string, refreshToken: string, providerId: string) => unknown;
+    createSessionAndTokens: (uid: string, userAgent: string, ipAddress: string, options?: {
+        skipMfaGate?: boolean;
+        aal?: "aal1" | "aal2";
+    }) => Promise<{
+        roleIds: string[];
+        accessToken: string;
+        refreshToken: string;
+    }>;
+    applyTransformHook?: (response: AuthResponsePayload, method: TransformAuthResponseContext["method"], request: Request, uid: string) => Promise<AuthResponsePayload>;
+}
+export declare function mountMfaRoutes(opts: MfaRoutesConfig): void;
+export {};

package/dist/auth/mfa.d.ts

@@ -25,6 +25,22 @@ export declare function generateTotp(secret: Buffer, timeStep?: number): string;
  * @returns true if the token is valid within the window
  */
 export declare function verifyTotp(secret: Buffer, token: string, window?: number): boolean;
+/**
+ * Verify a TOTP token and report *which* time step matched.
+ *
+ * RFC 6238 §5.2 requires that an accepted OTP not be accepted a second time,
+ * and a boolean cannot express what was accepted: with `window = 1` the same
+ * six digits stay valid for up to 90 seconds, so a code observed once — by a
+ * phishing relay, over a shoulder, in a pasted support message — can be
+ * presented again for the rest of that window. The caller records the returned
+ * counter against the factor and refuses anything at or below it.
+ *
+ * @param secret - The shared secret as a Buffer
+ * @param token - The 6-digit TOTP code to verify
+ * @param window - Number of time steps to check on each side (default: 1)
+ * @returns The matched time step, or `null` when no step in the window matches
+ */
+export declare function verifyTotpCounter(secret: Buffer, token: string, window?: number): number | null;
 /**
  * Generate a new TOTP secret and return the setup information
  *

package/dist/auth/microsoft-oauth.d.ts

@@ -1,16 +1,31 @@
 import type { OAuthProvider } from "./interfaces";
+import { type OAuthCodeFlowPayload } from "./oauth-code-flow";
 /**
  * Creates a Microsoft / Entra ID (Azure AD) OAuth Provider integration.
  *
  * Supports both personal Microsoft accounts and work/school (Azure AD) accounts
  * via the "common" tenant endpoint. Uses the authorization code flow.
+ *
+ * ## On `emailVerified`
+ *
+ * Microsoft Graph exposes no email-verification field, and `mail` is *not* a
+ * substitute: it is a directory attribute a tenant administrator sets to any
+ * string they like, through Graph or AAD Connect sync. With the default
+ * `tenantId: "common"` every Entra tenant in the world is an accepted issuer,
+ * so "there is a `mail` value" would mean "anybody who can create a free
+ * tenant can nominate any address" — including one that already has an account
+ * here.
+ *
+ * The only signal Microsoft offers is the `xms_edov` ("email domain owner
+ * verified") optional claim on the id_token, so that is what this provider
+ * reads, off a signature-verified token. If the app registration does not emit
+ * `xms_edov`, sign-in still works and the address comes back unverified —
+ * which routes the user to `POST /auth/link/microsoft` rather than silently
+ * handing them somebody else's account.
  */
 export declare function createMicrosoftProvider(config: {
     clientId: string;
     clientSecret: string;
     /** Tenant ID. Defaults to "common" which allows both personal and organizational accounts. */
     tenantId?: string;
-}): OAuthProvider<{
-    code: string;
-    redirectUri: string;
-}>;
+}): OAuthProvider<OAuthCodeFlowPayload>;

package/dist/auth/middleware.d.ts

@@ -1,4 +1,5 @@
 import { MiddlewareHandler, Context } from "hono";
+import type { AuthRepository } from "./interfaces";
 import { DataDriver } from "@rebasepro/types";
 import { AccessTokenPayload } from "./jwt";
 import type { HonoEnv } from "../api/types";
@@ -85,6 +86,31 @@ export declare const requireAuth: MiddlewareHandler<HonoEnv>;
  */
 export declare function createRequireAuth(options?: {
     serviceKey?: string;
+    /**
+     * Read this user's roles from the database, replacing whatever the token
+     * claims.
+     *
+     * Without it, `requireAdmin` downstream trusts the `roles` array inside the
+     * access token — so demoting an administrator does nothing until that token
+     * expires, and in the meantime the demoted admin can call
+     * `PUT /api/admin/users/<self>` and put the role back for good. The data
+     * plane already re-reads roles per request (`builtin-auth-adapter`); the
+     * admin routes, which are the ones that can grant roles, did not.
+     *
+     * Optional because two call sites have no repository in scope. A route that
+     * can supply one should: the cost is one indexed lookup on requests that
+     * are already administrative.
+     */
+    resolveRoles?: (uid: string) => Promise<string[]>;
+    /**
+     * Repository used to check the token-revocation watermark.
+     *
+     * Separate from {@link resolveRoles} only because that one is a narrow
+     * function; a caller with a repository should pass it here so a token
+     * invalidated by `logout` or a password reset stops working on admin routes
+     * too, not just on the data plane.
+     */
+    revocationRepo?: Pick<AuthRepository, "getTokensValidAfter">;
 }): MiddlewareHandler<HonoEnv>;
 /**
  * Middleware that requires the user to have an admin or schema-admin role.

package/dist/auth/oauth-code-flow.d.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+/**
+ * The authorization-code request shape every OAuth provider accepts, and the
+ * two derivations of it that were previously copy-pasted twelve times.
+ *
+ * Twelve providers declared their own `z.object({ code, redirectUri })` and
+ * each decided independently whether to accept a PKCE verifier (one did) and
+ * how to read a verification signal off the provider's profile response (five
+ * skipped the question and hardcoded `true`). One predicate, twelve
+ * implementations — so the controls below live here and every provider calls
+ * them, which is what makes it impossible for a thirteenth provider to ship
+ * without them.
+ */
+/** The request body every authorization-code provider consumes. */
+export interface OAuthCodeFlowPayload {
+    /** Authorization code returned to the client by the provider. */
+    code: string;
+    /**
+     * Redirect URI the code was issued against. Echoed to the token endpoint,
+     * which is what binds the code to the client that started the flow — and
+     * why the route allowlists it before `verify` ever runs
+     * (see `isRedirectUriAllowed`).
+     */
+    redirectUri: string;
+    /**
+     * PKCE verifier, when the client started the flow with a
+     * `code_challenge`. Forwarded to the token endpoint verbatim.
+     */
+    codeVerifier?: string;
+}
+/**
+ * Build the request schema for an authorization-code provider.
+ *
+ * `pkce` defaults to `"optional"`: the client decides whether it sent a
+ * `code_challenge`, and providers that do not implement PKCE simply never see
+ * a verifier because their clients never generate one. `"required"` is for
+ * providers that mandate PKCE (Twitter/X).
+ */
+export declare function oauthCodeFlowSchema(opts?: {
+    pkce?: "required" | "optional";
+}): z.ZodObject<{
+    code: z.ZodString;
+    redirectUri: z.ZodString;
+    codeVerifier: z.ZodString | z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The `code_verifier` token-endpoint parameter, or nothing.
+ *
+ * Returned as a spreadable object so a provider adds PKCE with one `...` in
+ * its existing body literal, rather than branching.
+ */
+export declare function pkceTokenParams(codeVerifier?: string): Record<string, string>;
+/**
+ * Normalise a provider's email-verification signal into the boolean that
+ * `OAuthProviderProfile.emailVerified` promises.
+ *
+ * The whole point is the default: anything that is not an affirmative
+ * verification signal — `undefined`, `null`, a missing field, an empty string,
+ * `false` — becomes `false`. A provider that reports nothing therefore cannot
+ * accidentally assert that it verified the address, which is exactly the
+ * mistake five providers had made.
+ *
+ * Accepts the string forms because OIDC issuers are inconsistent about whether
+ * `email_verified` is a JSON boolean or a string.
+ */
+export declare function providerVerifiedEmail(signal: unknown): boolean;

package/dist/auth/oauth-signin-policy.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The two decisions the OAuth sign-in route makes before it will hand a caller
+ * an existing account, extracted so they are stated once for all twelve
+ * providers and can be tested without a provider, a network or a database.
+ */
+/** Why an incoming OAuth identity may not be auto-attached to an existing account. */
+export type AutoLinkRefusal = 
+/** The provider did not report that it verified the address. */
+"provider-email-unverified"
+/**
+ * The local account holds a password nobody ever proved they own: it was
+ * created through `POST /auth/register`, which does not verify the
+ * address. Attaching a provider identity to it would hand the session to
+ * whoever registered the address first — the classic pre-hijack.
+ */
+ | "local-account-unverified";
+export type AutoLinkDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: AutoLinkRefusal;
+};
+/** The part of an existing user row the decision depends on. */
+export interface AutoLinkExistingUser {
+    emailVerified: boolean;
+    passwordHash?: string | null;
+}
+/**
+ * May an OAuth identity be attached to a pre-existing account found *by email*?
+ *
+ * Both sides have to be trustworthy, and only one of them used to be checked:
+ *
+ *  - the **provider** must have verified the address, or the caller has not
+ *    shown they control it;
+ *  - the **local account** must itself be trustworthy — either its address was
+ *    verified, or it has no password at all (it was created by an OAuth
+ *    sign-in or an invitation, so there is no credential an attacker could
+ *    have planted in advance).
+ *
+ * A refusal is not a dead end: `POST /auth/link/<provider>` attaches the
+ * identity once the caller proves ownership by holding a session.
+ */
+export declare function decideOAuthAutoLink(args: {
+    providerEmailVerified: boolean | undefined;
+    existingUser: AutoLinkExistingUser;
+}): AutoLinkDecision;
+/**
+ * Is `redirectUri` one the operator authorised?
+ *
+ * The provider's own registered-URI match is a real control but a coarse one:
+ * it authorises *every* URI registered on that OAuth client, so a `localhost`
+ * entry kept for development, or a second product sharing the client id, can
+ * mint codes this backend accepts. An empty or absent allowlist keeps the old
+ * behaviour (the provider's check is the only one) so existing deployments are
+ * unaffected; setting one narrows it to the origins this backend serves.
+ *
+ * Comparison is on origin plus path, with the origin lowercased and a trailing
+ * slash ignored — query strings and fragments are not part of the identity of a
+ * redirect URI, and neither is the case of the host.
+ */
+export declare function isRedirectUriAllowed(redirectUri: string, allowlist?: string[]): boolean;

package/dist/auth/oidc-id-token.d.ts

@@ -0,0 +1,61 @@
+import jwt from "jsonwebtoken";
+/**
+ * Minimal JWKS-backed id_token verification, shared by the OIDC providers.
+ *
+ * Apple's id_token used to be `split(".")` + `JSON.parse`, justified by the
+ * comment "we only need the payload". That skips `aud` — nothing confirmed the
+ * token was minted for *this* Services ID rather than another one under the
+ * same Apple team — along with `iss`, `exp` and the signature. Microsoft did
+ * not request an id_token at all and inferred verification from a directory
+ * attribute instead.
+ *
+ * Deliberately hand-rolled rather than pulling in a JWKS client: the only
+ * cryptography here is `jsonwebtoken`'s (already a dependency) and Node's own
+ * JWK→KeyObject import. What this file adds is key discovery and a cache.
+ */
+export interface OidcIdTokenClaims {
+    sub: string;
+    iss: string;
+    aud: string | string[];
+    exp: number;
+    email?: string;
+    email_verified?: boolean | string;
+    nonce?: string;
+    [claim: string]: unknown;
+}
+export interface VerifyOidcIdTokenOptions {
+    /** The compact JWS to verify. */
+    idToken: string;
+    /** JWKS endpoint of the issuer. */
+    jwksUri: string;
+    /**
+     * Expected `iss`. A `RegExp` is for multi-tenant issuers whose tenant id is
+     * part of the issuer URL (Entra ID with `tenantId: "common"`); everything
+     * else passes the exact string.
+     */
+    issuer: string | RegExp;
+    /** Expected `aud` — the client/services id this backend is configured with. */
+    audience: string;
+    /** Permitted signing algorithms. Defaults to RS256, which is what Apple and Entra use. */
+    algorithms?: jwt.Algorithm[];
+    /** Seconds of clock skew tolerated on `exp`/`iat`. Defaults to 60. */
+    clockToleranceSec?: number;
+    /** Expected `nonce`, when the client bound one to the authorization request. */
+    nonce?: string;
+    /** Injection point for tests; defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** Drops the JWKS cache. Exported for tests; nothing in the runtime calls it. */
+export declare function resetJwksCache(): void;
+/**
+ * Verify an id_token's signature, `aud`, `iss` and `exp`, and return its claims.
+ *
+ * Throws on any failure — callers treat a throw as "reject this sign-in",
+ * never as "continue without the claims".
+ */
+export declare function verifyOidcIdToken(options: VerifyOidcIdTokenOptions): Promise<OidcIdTokenClaims>;
+/**
+ * `verifyOidcIdToken` that reports failure as `null` and logs it, for the one
+ * call site that has to decide between "reject" and "degrade".
+ */
+export declare function tryVerifyOidcIdToken(providerId: string, options: VerifyOidcIdTokenOptions): Promise<OidcIdTokenClaims | null>;