@korajs/auth 1.0.0-beta.12 → 1.0.0-beta.14

package/dist/server.d.ts

@@ -1,65 +1,105 @@
-import { A as AuthTokens, T as TokenPayload } from './operation-encryptor-DRmKNWpF.js';
-export { O as OperationEncryptionError, e as OperationEncryptor, f as OperationEncryptorConfig, h as computePublicKeyThumbprint, l as isEncryptedField, v as verifyChallenge } from './operation-encryptor-DRmKNWpF.js';
-import { KoraError } from '@korajs/core';
+import { A as AuthTokens, T as TokenPayload } from './operation-encryptor-DDdlb9bm.js';
+export { O as OperationEncryptionError, e as OperationEncryptor, f as OperationEncryptorConfig, h as computePublicKeyThumbprint, l as isEncryptedField, v as verifyChallenge } from './operation-encryptor-DDdlb9bm.js';
+import { ScopeMap, KoraError } from '@korajs/core';
 
+/**
+ * Default window during which a just-rotated refresh token may be presented
+ * once more and receive the SAME successor pair (NEW-AUTH-3). Covers a rotation
+ * response lost on a flaky network without opening a long replay window.
+ */
+declare const DEFAULT_REFRESH_REUSE_GRACE_MS = 30000;
+/**
+ * Payload of an `mfa_pending` token: proof that the first factor succeeded,
+ * accepted ONLY by the MFA verification step and rejected everywhere else
+ * (`validateToken` does not recognise its type).
+ */
+interface MfaPendingPayload {
+    jti: string;
+    sub: string;
+    dev: string;
+    type: 'mfa_pending';
+    iat: number;
+    exp: number;
+    /** Methods already satisfied (for example `['pwd']`). */
+    amr: string[];
+}
+/** Result of an atomic {@link TokenRevocationStore.consume}. */
+interface ConsumeResult {
+    /** True only for the single call that consumed the id first. */
+    firstUse: boolean;
+    /** When the id was first consumed (milliseconds since epoch). */
+    consumedAt: number;
+}
 /**
  * Interface for server-side token revocation storage.
  *
  * Implementing this interface allows the TokenManager to:
- * - Revoke individual tokens by their `jti`
- * - Detect refresh token reuse (potential theft indicator)
- * - Invalidate all tokens for a specific device on revocation
+ * - Revoke individual tokens (and token families) by id
+ * - Rotate refresh tokens atomically (each refresh token mints at most one successor)
+ * - Invalidate every credential a device or a user obtained before a point in time
  *
- * The in-memory implementation ({@link InMemoryTokenRevocationStore}) is suitable
- * for development. Production deployments should use a persistent store (Redis, database).
+ * Shipped implementations: {@link InMemoryTokenRevocationStore} (development),
+ * `SqliteTokenRevocationStore` and `PostgresTokenRevocationStore`. The SQLite and
+ * Postgres user stores expose one sharing their database through
+ * `getTokenRevocationStore()`, which `createKoraAuthServer` uses by default.
  */
 interface TokenRevocationStore {
     /**
-     * Check whether a token has been revoked.
-     * @param jti - The JWT ID to check
-     * @returns true if the token has been revoked
+     * Check whether a token (or token family, keyed `family:<id>`) has been revoked.
+     * @param jti - The JWT ID (or family key) to check
      */
     isRevoked(jti: string): Promise<boolean>;
     /**
-     * Revoke a specific token by its JWT ID.
-     * @param jti - The JWT ID to revoke
-     * @param expiresAt - The token's original expiration time (seconds since epoch).
-     *   The store may use this to auto-purge expired revocations.
+     * Revoke a specific token (or token family) by id.
+     * @param jti - The JWT ID (or family key) to revoke
+     * @param expiresAt - Expiry in seconds since epoch; the store may purge after it
      */
     revoke(jti: string, expiresAt: number): Promise<void>;
     /**
-     * Revoke all tokens associated with a specific device.
-     * Called when a device is revoked to invalidate all its tokens.
-     * @param deviceId - The device ID whose tokens should be revoked
+     * Atomically mark an id as consumed (test-and-set). Exactly one concurrent
+     * caller observes `firstUse: true`, on every instance sharing the store.
+     * @param jti - The id to consume
+     * @param expiresAt - Expiry in seconds since epoch; the store may purge after it
      */
-    revokeAllForDevice(deviceId: string): Promise<void>;
+    consume(jti: string, expiresAt: number): Promise<ConsumeResult>;
+    /** Whether an id has been consumed (read-only; never consumes). */
+    isConsumed(jti: string): Promise<boolean>;
     /**
-     * Check whether all tokens for a device have been revoked.
-     * @param deviceId - The device ID to check
-     * @returns true if the device's token family has been revoked
+     * Reject every token for a device issued at or before `before` (ms). Later
+     * tokens (a fresh sign-in on the same device) stay valid. Monotonic: a
+     * smaller `before` never lowers an existing cut-off.
      */
-    isDeviceRevoked(deviceId: string): Promise<boolean>;
+    revokeAllForDevice(deviceId: string, before?: number): Promise<void>;
+    /** Cut-off (ms) recorded by {@link revokeAllForDevice}, or null. */
+    getDeviceRevokedBefore(deviceId: string): Promise<number | null>;
+    /**
+     * Reject every token for a user issued at or before `before` (ms). Used by
+     * password reset and change, admin session revocation and user deletion.
+     */
+    revokeAllForUser(userId: string, before?: number): Promise<void>;
+    /** Cut-off (ms) recorded by {@link revokeAllForUser}, or null. */
+    getUserRevokedBefore(userId: string): Promise<number | null>;
 }
 /**
  * In-memory token revocation store.
  *
- * Suitable for development and testing. Revoked tokens are stored in a Set
- * and automatically cleaned up when they would have expired naturally.
- *
- * **Not suitable for production**: revocations are lost on server restart
- * and not shared across server instances. Use a Redis or database-backed
- * store in production.
+ * Suitable for development and testing. Revocations are lost on restart and not
+ * shared across instances, so `createKoraAuthServer` refuses it in production
+ * unless `allowInMemory: true` is set.
  */
 declare class InMemoryTokenRevocationStore implements TokenRevocationStore {
     private readonly revokedTokens;
-    private readonly revokedDevices;
+    private readonly consumed;
+    private readonly deviceCutoffs;
+    private readonly userCutoffs;
     isRevoked(jti: string): Promise<boolean>;
     revoke(jti: string, expiresAt: number): Promise<void>;
-    revokeAllForDevice(deviceId: string): Promise<void>;
-    /**
-     * Check if a device has been revoked.
-     */
-    isDeviceRevoked(deviceId: string): Promise<boolean>;
+    consume(jti: string, expiresAt: number): Promise<ConsumeResult>;
+    isConsumed(jti: string): Promise<boolean>;
+    revokeAllForDevice(deviceId: string, before?: number): Promise<void>;
+    getDeviceRevokedBefore(deviceId: string): Promise<number | null>;
+    revokeAllForUser(userId: string, before?: number): Promise<void>;
+    getUserRevokedBefore(userId: string): Promise<number | null>;
     /**
      * Remove expired revocations to prevent unbounded memory growth.
      * Call periodically (e.g., every hour) in long-running servers.
@@ -78,8 +118,6 @@ interface TokenManagerConfig {
      *
      * For key rotation, provide an array of secrets. The first secret is used for
      * signing new tokens; all secrets are tried during verification (newest first).
-     * This allows graceful rotation: add the new secret at index 0, then remove
-     * the old secret after all tokens signed with it have expired.
      */
     secret: string | string[];
     /** Access token lifetime in milliseconds (default: 15 minutes) */
@@ -89,22 +127,48 @@ interface TokenManagerConfig {
     /** Device credential lifetime in milliseconds (default: 90 days) */
     deviceCredentialLifetime?: number;
     /**
-     * Optional token revocation store. When provided, enables:
-     * - Individual token revocation via `revokeToken()`
-     * - Refresh token reuse detection (consumed tokens are tracked)
-     * - Device-level token invalidation via `revokeDeviceTokens()`
-     *
+     * Optional token revocation store. When provided, enables revocation,
+     * atomic refresh rotation with reuse detection, and device/user cut-offs.
      * Without a revocation store, tokens are valid until they expire.
      */
     revocationStore?: TokenRevocationStore;
+    /**
+     * Window (ms) during which a just-rotated refresh token is accepted ONCE more
+     * and returns the same successor pair. Set 0 to disable. Default 30 seconds.
+     */
+    refreshReuseGraceMs?: number;
+}
+/** Options for minting a token set. */
+interface IssueTokenOptions {
+    /** Refresh-token family to continue. A new family is started when omitted. */
+    family?: string;
+    /** Authentication methods (RFC 8176) to record, for example `['pwd', 'otp']`. */
+    amr?: string[];
 }
+/** Why a refresh was refused. */
+type RefreshFailureReason = 'invalid' | 'revoked' | 'reused' | 'in_progress' | 'device_revoked' | 'user_revoked';
+/** Outcome of {@link TokenManager.rotateRefreshToken}. */
+type RefreshResult = {
+    ok: true;
+    tokens: {
+        accessToken: string;
+        refreshToken: string;
+    };
+    /** The verified payload of the refresh token that was presented. */
+    payload: TokenPayload;
+    /** True when this was the one grace replay of a just-rotated token. */
+    replayed: boolean;
+} | {
+    ok: false;
+    reason: RefreshFailureReason;
+};
 /**
  * Server-side token manager responsible for issuing, refreshing, and validating
  * Kora authentication tokens.
  *
  * Uses HMAC-SHA256 signed JWTs with unique `jti` identifiers for every token.
- * Supports key rotation (multiple secrets), token revocation, and refresh token
- * reuse detection.
+ * Supports key rotation (multiple secrets), token revocation, token families and
+ * atomic, rotation-safe refresh.
  *
  * @example
  * ```typescript
@@ -113,14 +177,9 @@ interface TokenManagerConfig {
  *   revocationStore: new InMemoryTokenRevocationStore(),
  * })
  *
- * // Issue all tokens at once
  * const tokens = tokenManager.issueTokens('user-123', 'device-456')
- *
- * // Validate an access token
- * const payload = tokenManager.validateToken(tokens.accessToken)
- *
- * // Refresh when the access token expires
- * const newTokens = await tokenManager.refreshAccessToken(tokens.refreshToken)
+ * const payload = await tokenManager.validateTokenWithRevocation(tokens.accessToken)
+ * const next = await tokenManager.rotateRefreshToken(tokens.refreshToken)
  * ```
  */
 declare class TokenManager {
@@ -130,46 +189,38 @@ declare class TokenManager {
     private readonly refreshTokenLifetime;
     private readonly deviceCredentialLifetime;
     private readonly revocationStore;
+    private readonly refreshReuseGraceMs;
+    /** Refresh jtis whose rotation is executing on this instance right now. */
+    private readonly rotating;
     constructor(config: TokenManagerConfig);
     /**
      * Generate a cryptographically random secret suitable for HMAC-SHA256 signing.
      *
-     * Returns a 64-character hex string (32 bytes / 256 bits of entropy).
-     * Store this securely (environment variable, secrets manager) — never in source code.
-     *
      * @returns A random 256-bit hex-encoded secret
      */
     static generateSecret(): string;
+    /** The revocation store this manager enforces, if any. */
+    getRevocationStore(): TokenRevocationStore | undefined;
     /**
      * Issue a signed JWT access token.
      *
-     * Access tokens are short-lived (default 15 minutes) and used to authorize
-     * API requests. When expired, use {@link refreshAccessToken} with a valid
-     * refresh token to obtain a new one.
-     *
      * @param userId - The subject (user ID) to encode in the token
      * @param deviceId - The device ID of the requesting device
+     * @param options - Family and authentication methods to record
      * @returns A signed JWT string with type 'access'
      */
-    issueAccessToken(userId: string, deviceId: string): string;
+    issueAccessToken(userId: string, deviceId: string, options?: IssueTokenOptions): string;
     /**
      * Issue a signed JWT refresh token.
      *
-     * Refresh tokens are longer-lived (default 90 days) and used exclusively
-     * to obtain new access tokens via {@link refreshAccessToken}. They should
-     * be stored securely and never sent to resource APIs.
-     *
      * @param userId - The subject (user ID) to encode in the token
      * @param deviceId - The device ID of the requesting device
+     * @param options - Family and authentication methods to record
      * @returns A signed JWT string with type 'refresh'
      */
-    issueRefreshToken(userId: string, deviceId: string): string;
+    issueRefreshToken(userId: string, deviceId: string, options?: IssueTokenOptions): string;
     /**
-     * Issue a signed device credential token.
-     *
-     * Device credentials are long-lived tokens bound to a device's public key.
-     * They include a `mustCheckinBy` deadline; if the device does not check in
-     * before this deadline, the credential should be treated as revoked.
+     * Issue a signed device credential token bound to a device's public key.
      *
      * @param userId - The subject (user ID) to encode in the token
      * @param deviceId - The device ID of the requesting device
@@ -178,77 +229,192 @@ declare class TokenManager {
      */
     issueDeviceCredential(userId: string, deviceId: string, publicKeyThumbprint: string): string;
     /**
-     * Issue a complete set of authentication tokens.
-     *
-     * Always issues an access token and refresh token. If a `publicKeyThumbprint`
-     * is provided, also issues a device credential.
+     * Issue a complete set of authentication tokens for a new session. The access
+     * and refresh token share a fresh family id.
      *
      * @param userId - The subject (user ID) to encode in the tokens
      * @param deviceId - The device ID of the requesting device
-     * @param publicKeyThumbprint - Optional SHA-256 thumbprint of the device's public key.
-     *   When provided, a device credential is included in the returned tokens.
+     * @param publicKeyThumbprint - Optional device key thumbprint; adds a device credential
+     * @param options - Authentication methods to record
      * @returns An {@link AuthTokens} object containing the issued tokens
      */
-    issueTokens(userId: string, deviceId: string, publicKeyThumbprint?: string): AuthTokens;
+    issueTokens(userId: string, deviceId: string, publicKeyThumbprint?: string, options?: Omit<IssueTokenOptions, 'family'>): AuthTokens;
+    /**
+     * Issue a short-lived `mfa_pending` token after a successful first factor
+     * for a user enrolled in MFA (AUTH-10). It grants nothing by itself.
+     *
+     * @param userId - The user who passed the first factor
+     * @param deviceId - The device the session will be bound to
+     * @param amr - Methods already satisfied (for example `['pwd']`)
+     * @returns A signed JWT of type `mfa_pending`
+     */
+    issueMfaPendingToken(userId: string, deviceId: string, amr: string[]): string;
+    /**
+     * Verify an `mfa_pending` token without consuming it, so a mistyped code can
+     * be retried with the same token (TOTP checks have their own backoff).
+     *
+     * @param token - The `mfa_pending` JWT
+     * @returns Its payload, or null when invalid, expired or already redeemed
+     */
+    verifyMfaPendingToken(token: string): Promise<MfaPendingPayload | null>;
     /**
-     * Validate and decode a token.
+     * Redeem an `mfa_pending` token exactly once (atomic across instances).
      *
-     * Verifies the HMAC-SHA256 signature (trying all configured secrets for key rotation),
-     * checks that the token has not expired, and validates all required claims.
-     * Returns null (rather than throwing) for invalid or expired tokens, so callers
-     * can handle authentication failure without try/catch.
+     * @param payload - A payload returned by {@link verifyMfaPendingToken}
+     * @returns True only for the single successful redemption
+     */
+    redeemMfaPendingToken(payload: MfaPendingPayload): Promise<boolean>;
+    /**
+     * Validate and decode a token's signature, expiry and claims.
+     *
+     * This does NOT consult revocation. Every request-authorization path must use
+     * {@link validateTokenWithRevocation} (or `BuiltInAuthRoutes.authenticateAccess`).
      *
      * @param token - The JWT string to validate
-     * @returns The decoded {@link TokenPayload} if valid, or null if the token is
-     *   invalid, expired, or missing required claims
+     * @returns The decoded {@link TokenPayload}, or null if invalid or expired
      */
     validateToken(token: string): TokenPayload | null;
     /**
-     * Validate a token and check it against the revocation store.
-     *
-     * Like {@link validateToken}, but also checks whether the token's `jti` has been
-     * revoked or belongs to a revoked device. Requires a revocation store to be configured.
+     * Validate a token and check every revocation primitive: the token's own
+     * `jti`, its family, the device cut-off and the per-user cut-off.
      *
      * @param token - The JWT string to validate
      * @returns The decoded {@link TokenPayload} if valid and not revoked, or null otherwise
      */
     validateTokenWithRevocation(token: string): Promise<TokenPayload | null>;
+    /**
+     * Why an otherwise valid token is no longer accepted, or null when it is.
+     */
+    revocationReason(payload: TokenPayload): Promise<'revoked' | 'device_revoked' | 'user_revoked' | null>;
     /**
      * Revoke a specific token by its JWT ID.
      *
-     * Requires a revocation store to be configured. After revocation, the token
-     * will be rejected by {@link validateTokenWithRevocation}.
-     *
      * @param jti - The JWT ID of the token to revoke
      * @param expiresAt - The token's expiration time (seconds since epoch)
      */
     revokeToken(jti: string, expiresAt: number): Promise<void>;
     /**
-     * Revoke all tokens for a specific device.
+     * Revoke a whole refresh-token family (one sign-in and all its rotations,
+     * including the access tokens minted along the way).
      *
-     * Called when a device is revoked to ensure all its existing tokens
-     * (access, refresh, and device credentials) are invalidated.
+     * @param family - The family id (`fam` claim)
+     * @param expiresAt - Latest expiry of any token in the family (seconds since epoch)
+     */
+    revokeFamily(family: string, expiresAt: number): Promise<void>;
+    /**
+     * Revoke every token issued to a device up to now. A later sign-in on the
+     * same device issues tokens that are accepted again.
      *
      * @param deviceId - The device ID whose tokens should be revoked
      */
     revokeDeviceTokens(deviceId: string): Promise<void>;
     /**
-     * Refresh an access token using a valid refresh token.
+     * Revoke every token issued to a user up to now (password reset or change,
+     * admin session revocation, account deletion).
      *
-     * Implements **refresh token rotation with reuse detection**: a new refresh token
-     * is issued alongside the new access token. The old refresh token's `jti` is
-     * recorded in the revocation store (if configured). If a previously consumed
-     * refresh token is presented again, it indicates potential token theft.
+     * @param userId - The user whose credentials should be revoked
+     */
+    revokeAllForUser(userId: string): Promise<void>;
+    /**
+     * Rotate a refresh token: atomically consume it and mint its successor pair.
      *
-     * Returns null if the provided token is invalid, expired, or not a refresh token.
+     * - Each refresh `jti` mints at most one successor family member (AUTH-6).
+     * - A concurrent duplicate on this instance gets `in_progress` (retry later).
+     * - Within the grace window, presenting a just-rotated token ONCE more returns
+     *   the SAME successor pair, so a response lost on the wire does not sign the
+     *   user out (NEW-AUTH-3).
+     * - Any other reuse revokes the token FAMILY, never the device (NEW-AUTH-1).
      *
      * @param refreshToken - The refresh token JWT string
-     * @returns A new access/refresh token pair, or null if the refresh token is invalid
+     * @returns The successor pair, or the reason the refresh was refused
+     */
+    rotateRefreshToken(refreshToken: string): Promise<RefreshResult>;
+    /**
+     * Refresh an access token using a valid refresh token.
+     *
+     * Convenience wrapper over {@link rotateRefreshToken} that collapses every
+     * failure to null. HTTP handlers should use `rotateRefreshToken` so they can
+     * tell a client to retry (`in_progress`) instead of signing it out.
+     *
+     * @param refreshToken - The refresh token JWT string
+     * @returns A new access/refresh token pair, or null if the refresh was refused
      */
     refreshAccessToken(refreshToken: string): Promise<{
         accessToken: string;
         refreshToken: string;
     } | null>;
+    private rotate;
+    /**
+     * Deterministically mint the successor pair of a refresh token. The jtis and
+     * issue time derive from the consumed token and its consumption time, so a
+     * grace replay re-signs byte-identical tokens without storing them.
+     */
+    private successorTokens;
+    private deriveJti;
+    private basePayload;
+    private sign;
+    private verifySignature;
+}
+
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Verified identity of a sync session, derived on the server from a validated
+ * access token. Never contains client-supplied values.
+ */
+interface VerifiedSyncClaims {
+    /** Verified user id (`sub`). */
+    userId: string;
+    /** Verified device id (`dev`). */
+    deviceId: string;
+    /** The user's email from the user store. */
+    email: string;
+    /** The user's display name from the user store. */
+    name: string;
+}
+/**
+ * Server-side scope derivation for the sync auth provider (AUTH-1).
+ *
+ * The result is the session's complete grant: the client handshake can only
+ * narrow it, and a schema-scoped collection whose binding is unresolved is
+ * denied (`SCOPE_REQUIRED`), never widened.
+ */
+interface SyncScopeOptions {
+    /**
+     * Extra verified scope values merged over the default `{ userId }`, for
+     * example `{ orgId: await orgOf(userId) }`. Every schema-scoped collection is
+     * bound from these values. Return `undefined`/`null` for a key to deny the
+     * collections that need it.
+     */
+    scopeValues?: (claims: VerifiedSyncClaims) => MaybePromise<Record<string, unknown>>;
+    /**
+     * Full explicit grant. When provided it replaces the default derivation:
+     * collections it omits are not visible. Use `claimScopes(values, explicit)`
+     * from `@korajs/core` to combine claim binding with explicit predicates.
+     */
+    resolveScopes?: (claims: VerifiedSyncClaims) => MaybePromise<ScopeMap>;
+}
+/** Auth context returned to `@korajs/server` by the sync auth provider. */
+interface SyncAuthContext {
+    userId: string;
+    scopes?: Record<string, Record<string, unknown>>;
+    metadata?: Record<string, unknown>;
+    /** Access-token expiry (ms since epoch); a session must not outlive it (AUTH-11). */
+    expiresAt?: number;
+}
+/** Structural `AuthProvider` returned by `toSyncAuthProvider()`. */
+interface SyncAuthProvider {
+    authenticate(token: string): Promise<SyncAuthContext | null>;
+    /**
+     * Revocation feed (device revoke, sign-out, password reset or change, admin
+     * revoke). `KoraSyncServer` subscribes automatically and terminates the
+     * matching live sessions (AUTH-11).
+     *
+     * @returns An unsubscribe function
+     */
+    onRevoke?(listener: (event: {
+        userId: string;
+        deviceId?: string;
+    }) => void | Promise<void>): () => void;
 }
 
 /**
@@ -302,6 +468,13 @@ interface AuthDevice {
 declare class DuplicateEmailError extends KoraError {
     constructor();
 }
+/**
+ * Thrown when a device id is already registered to a different user. A token's
+ * `dev` claim must always name a device owned by its `sub` (AUTH-5).
+ */
+declare class DeviceOwnershipError extends KoraError {
+    constructor(deviceId: string);
+}
 /**
  * Generic interface for user and device persistence.
  *
@@ -334,7 +507,11 @@ interface UserStore {
     findByEmail(email: string): Promise<StoredUser | null>;
     /** Find a user by ID. */
     findById(id: string): Promise<StoredUser | null>;
-    /** Register a device for a user. Idempotent if device already exists and is not revoked. */
+    /**
+     * Register a device for a user. Idempotent for the same owner (a revoked
+     * device is re-activated). Must throw {@link DeviceOwnershipError} when the id
+     * already belongs to a different user.
+     */
     registerDevice(params: {
         id: string;
         userId: string;
@@ -359,6 +536,12 @@ interface UserStore {
     delete(userId: string): Promise<void>;
     /** Update the last-seen timestamp for a device. No-op if device does not exist. */
     touchDevice(deviceId: string): Promise<void>;
+    /**
+     * Optional token revocation store that lives with the user data (same
+     * database). `createKoraAuthServer` uses it by default, so revocations
+     * persist and are shared exactly as far as users are.
+     */
+    getTokenRevocationStore?(): TokenRevocationStore;
 }
 /**
  * In-memory user and device store for the built-in auth provider.
@@ -387,6 +570,10 @@ declare class InMemoryUserStore implements UserStore {
     private readonly devicesById;
     /** Device IDs indexed by user ID for fast listing */
     private readonly devicesByUserId;
+    /** Revocations live with the users, so every server sharing this store shares them. */
+    private readonly revocationStore;
+    /** The token revocation store that shares this store's lifetime. */
+    getTokenRevocationStore(): TokenRevocationStore;
     /**
      * Create a new user account.
      *
@@ -421,9 +608,10 @@ declare class InMemoryUserStore implements UserStore {
     /**
      * Register a device for a user.
      *
-     * If a device with the same ID already exists and is not revoked, it is
-     * returned as-is (idempotent registration). If it was previously revoked,
-     * it is re-activated with updated details.
+     * If a device with the same ID already exists for the same user and is not
+     * revoked, it is returned as-is (idempotent registration). If it was
+     * previously revoked, it is re-activated with updated details. A device id
+     * owned by another user is refused.
      *
      * @param params - Device registration parameters
      * @param params.id - Unique device identifier
@@ -431,6 +619,7 @@ declare class InMemoryUserStore implements UserStore {
      * @param params.publicKey - Base64url-encoded device public key or thumbprint
      * @param params.name - Human-readable device name
      * @returns The registered device record
+     * @throws {DeviceOwnershipError} If the id is registered to another user
      */
     registerDevice(params: {
         id: string;
@@ -598,6 +787,61 @@ interface AuthRoutesConfig {
      * (10 attempts per minute).
      */
     rateLimiter?: RateLimiter;
+    /**
+     * Called after credentials are revoked (sign-out, device revocation, user-wide
+     * revocation). `createKoraAuthServer().bindSyncServer()` uses it to end live
+     * sync sessions (AUTH-11).
+     */
+    onRevoke?: (event: AuthRevocationEvent) => void | Promise<void>;
+    /**
+     * Second-factor verifier (a `TotpManager` fits). When configured, users with
+     * MFA enabled get `{ mfaRequired, mfaToken }` from sign-in instead of tokens,
+     * and only `POST /auth/mfa/verify` issues their session (AUTH-10).
+     */
+    mfa?: MfaVerifier;
+}
+/** Second-factor checks used at sign-in. `TotpManager` implements this. */
+interface MfaVerifier {
+    isEnabled(userId: string): Promise<boolean>;
+    verify(userId: string, code: string): Promise<boolean>;
+    verifyRecoveryCode?(userId: string, recoveryCode: string): Promise<boolean>;
+}
+/** Sign-in result for a user who still has to pass the second factor. */
+interface MfaChallenge {
+    mfaRequired: true;
+    /** Short-lived token accepted only by `POST /auth/mfa/verify`. */
+    mfaToken: string;
+}
+/** Successful primary authentication: a session, or an MFA challenge. */
+type SignInResult = {
+    user: AuthUser;
+    tokens: AuthTokens;
+} | MfaChallenge;
+/**
+ * Describes credentials that were just revoked, so live sessions holding them
+ * (for example open sync connections) can be terminated.
+ */
+type AuthRevocationEvent = {
+    kind: 'device';
+    userId: string;
+    deviceId: string;
+} | {
+    kind: 'user';
+    userId: string;
+} | {
+    kind: 'session';
+    userId: string;
+    deviceId: string;
+    family: string | null;
+};
+/** Result of {@link BuiltInAuthRoutes.authenticateAccess}. */
+interface AuthenticatedAccess {
+    /** Verified access-token payload. */
+    payload: TokenPayload;
+    /** The token's user, as stored. */
+    user: StoredUser;
+    /** The token's device record (null when the token was minted without one). */
+    device: AuthDevice | null;
 }
 /**
  * Response envelope returned by all auth route handlers.
@@ -608,12 +852,19 @@ interface AuthRoutesConfig {
 interface AuthRouteResponse<T> {
     /** HTTP status code */
     status: number;
-    /** Either the success payload or an error message */
+    /**
+     * Either the success payload or an error message. `code` is a stable,
+     * machine-readable Kora error code; clients use it to tell a definitive
+     * rejection from a proxy or captive-portal response.
+     */
     body: {
         data: T;
     } | {
         error: string;
+        code?: string;
     };
+    /** Optional response headers (for example `Retry-After`). */
+    headers?: Record<string, string>;
 }
 /**
  * HTTP route handlers for the built-in Kora auth provider.
@@ -654,7 +905,70 @@ declare class BuiltInAuthRoutes {
     private readonly tokenManager;
     private readonly challengeStore;
     private readonly rateLimiter;
+    private readonly revokeListeners;
+    /** Lazily computed hash used to equalize sign-in timing for unknown emails. */
+    private dummyCredential;
+    private readonly mfa;
     constructor(config: AuthRoutesConfig);
+    /**
+     * Finish a successful primary authentication (password, OAuth): issue a
+     * session, or an MFA challenge when the user is enrolled in MFA. No
+     * full-privilege token is ever issued to an MFA user without a fresh second
+     * factor.
+     *
+     * @param user - The authenticated user
+     * @param deviceId - The (already registered) device
+     * @param amr - Methods satisfied so far (for example `['pwd']`)
+     */
+    completePrimaryAuthentication(user: AuthUser, deviceId: string, amr: string[]): Promise<AuthRouteResponse<SignInResult>>;
+    /**
+     * Handle the second factor (POST /auth/mfa/verify).
+     *
+     * Exchanges an `mfa_pending` token plus a TOTP code (or recovery code) for a
+     * session whose tokens carry `amr` including `otp` (or `rcv`). The pending
+     * token is redeemed once; a wrong code can be retried until it expires.
+     */
+    handleMfaVerify(body: {
+        mfaToken?: unknown;
+        code?: unknown;
+        recoveryCode?: unknown;
+    }): Promise<AuthRouteResponse<{
+        user: AuthUser;
+        tokens: AuthTokens;
+    }>>;
+    /**
+     * Subscribe to credential revocations (sign-out, device revocation,
+     * user-wide revocation).
+     *
+     * @param listener - Called after each revocation is persisted
+     * @returns An unsubscribe function
+     */
+    onRevoke(listener: (event: AuthRevocationEvent) => void | Promise<void>): () => void;
+    /**
+     * Authenticate an access token for any request-authorization path.
+     *
+     * The single check used by every HTTP route and by the sync provider: it
+     * verifies signature and expiry, the token's own revocation, its family, the
+     * device cut-off, the per-user cut-off, that the user still exists, and that
+     * the device record is neither revoked nor owned by someone else.
+     *
+     * @param token - Raw access token (without "Bearer ")
+     * @returns The verified access, or null when the token must be rejected
+     */
+    authenticateAccess(token: string): Promise<AuthenticatedAccess | null>;
+    /**
+     * Revoke every credential a user holds (password reset or change, admin
+     * session revocation, account deletion) and notify revocation listeners.
+     *
+     * @param userId - The user whose sessions end now
+     */
+    revokeAllForUser(userId: string): Promise<void>;
+    private emitRevoke;
+    /**
+     * Register the device for a successful primary authentication, refusing ids
+     * owned by another user.
+     */
+    private registerSignInDevice;
     /**
      * Handle user sign-up (POST /auth/signup).
      *
@@ -699,10 +1013,7 @@ declare class BuiltInAuthRoutes {
         password: string;
         deviceId?: string;
         devicePublicKey?: string;
-    }, clientIp?: string): Promise<AuthRouteResponse<{
-        user: AuthUser;
-        tokens: AuthTokens;
-    }>>;
+    }, clientIp?: string): Promise<AuthRouteResponse<SignInResult>>;
     /**
      * Handle token refresh (POST /auth/refresh).
      *
@@ -832,17 +1143,24 @@ declare class BuiltInAuthRoutes {
      * @returns A 64-character hex string (32 random bytes)
      */
     static generateChallenge(): string;
+    private getDummyCredential;
     /**
      * Creates a sync server auth provider compatible with `@korajs/server`.
      *
      * The returned object implements the `AuthProvider` interface from
      * `@korajs/server`, validating access tokens and returning an auth
-     * context containing the user ID and device metadata. This bridges
-     * the built-in auth system with the sync server's authentication layer.
+     * context containing the user ID, device metadata and a SERVER-DERIVED
+     * scope grant. The client handshake can only narrow that grant (AUTH-1).
+     *
+     * By default the grant binds every schema-scoped collection from
+     * `{ userId: <verified sub> }`. Collections scoped by any other key (for
+     * example `orgId`) are denied until `scopeValues` or `resolveScopes`
+     * supplies it; they are never widened to "every tenant".
      *
      * Also checks device revocation status during authentication, ensuring
      * that revoked devices are rejected even if their tokens haven't expired.
      *
+     * @param options - Optional server-side scope derivation
      * @returns An object with an `authenticate` method suitable for KoraSyncServer's `auth` config
      *
      * @example
@@ -850,17 +1168,13 @@ declare class BuiltInAuthRoutes {
      * const routes = new BuiltInAuthRoutes({ userStore, tokenManager })
      * const syncServer = new KoraSyncServer({
      *   store,
-     *   auth: routes.toSyncAuthProvider(),
+     *   auth: routes.toSyncAuthProvider({
+     *     scopeValues: async ({ userId }) => ({ orgId: await orgOf(userId) }),
+     *   }),
      * })
      * ```
      */
-    toSyncAuthProvider(): {
-        authenticate(token: string): Promise<{
-            userId: string;
-            scopes?: Record<string, Record<string, unknown>>;
-            metadata?: Record<string, unknown>;
-        } | null>;
-    };
+    toSyncAuthProvider(options?: SyncScopeOptions): SyncAuthProvider;
 }
 
 /**
@@ -1021,6 +1335,20 @@ declare class InMemoryLinkedIdentityStore implements LinkedIdentityStore {
     delete(userId: string, provider: string): Promise<void>;
 }
 
+/** What an OAuth flow is for. A state minted for one purpose is useless for the other. */
+type OAuthFlowPurpose = 'signin' | 'link';
+/** Binding requested when an authorization URL is created (AUTH-3). */
+interface OAuthFlowBinding {
+    /** The flow purpose. Defaults to `'signin'`. */
+    purpose?: OAuthFlowPurpose;
+    /** For `'link'`: the authenticated Kora user starting the flow. */
+    userId?: string;
+    /**
+     * A random secret held only by the initiating client (an HttpOnly cookie on
+     * the web, memory for native/PKCE). Only its SHA-256 is stored server-side.
+     */
+    binding?: string;
+}
 /**
  * In-memory OAuth state store for development.
  * Use Redis or a database in production for multi-server deployments.
@@ -1080,7 +1408,7 @@ declare class OAuthManager {
      * Generate an authorization URL for the user to visit.
      * Returns the URL and the state parameter for CSRF validation.
      */
-    getAuthorizationUrl(providerId: string, metadata?: Record<string, unknown>): Promise<{
+    getAuthorizationUrl(providerId: string, metadata?: Record<string, unknown>, flow?: OAuthFlowBinding): Promise<{
         url: string;
         state: string;
     }>;
@@ -1089,12 +1417,17 @@ declare class OAuthManager {
      * Validates the state parameter, exchanges the code for tokens,
      * and fetches user info.
      *
+     * The state is single-use and is redeemable only for the purpose it was
+     * minted for, by the same user (for linking) and the same client binding.
+     * A mismatch is rejected before the code is exchanged.
+     *
      * @param providerId - The OAuth provider
      * @param code - The authorization code from the callback
      * @param state - The state parameter from the callback
+     * @param expected - The purpose, user and client binding of this callback
      * @returns Tokens and user info from the provider
      */
-    handleCallback(providerId: string, code: string, state: string): Promise<{
+    handleCallback(providerId: string, code: string, state: string, expected?: OAuthFlowBinding): Promise<{
         tokens: OAuthTokens;
         userInfo: OAuthUserInfo;
         stateMetadata?: Record<string, unknown>;
@@ -1156,9 +1489,21 @@ interface OAuthServerConfig extends Omit<OAuthManagerConfig, 'providers'> {
      */
     allowUnlinkLastIdentity?: boolean;
 }
-interface CreateKoraAuthServerOptions {
+interface CreateKoraAuthServerOptions extends SyncScopeOptions {
     /** Existing user store. Defaults to InMemoryUserStore for development. */
     userStore?: UserStore;
+    /**
+     * Token revocation store. Defaults to the user store's own revocation store
+     * (`userStore.getTokenRevocationStore()`), so revocations persist and are shared
+     * exactly as far as the users are.
+     */
+    revocationStore?: TokenRevocationStore;
+    /**
+     * Allow in-memory user or revocation stores when `NODE_ENV=production`.
+     * In-memory stores lose every account and every revocation on restart and are
+     * not shared between instances, so production refuses them by default.
+     */
+    allowInMemory?: boolean;
     /** Existing token manager. Overrides `jwtSecret` and `tokenManager` options. */
     tokenManager?: TokenManager;
     /** JWT secret. Required in production when `tokenManager` is not provided. */
@@ -1171,6 +1516,22 @@ interface CreateKoraAuthServerOptions {
     oauth?: OAuthServerConfig;
     challengeStore?: ChallengeStore;
     rateLimiter?: RateLimiter;
+    /**
+     * Second-factor verifier (for example a `TotpManager`). Users with MFA enabled
+     * then sign in in two steps: `{ mfaRequired, mfaToken }`, then
+     * `POST /auth/mfa/verify` with `{ mfaToken, code }`.
+     */
+    mfa?: MfaVerifier;
+}
+/**
+ * The part of `KoraSyncServer` the auth server needs to end live sessions.
+ * Structural, so `@korajs/auth` does not depend on `@korajs/server`.
+ */
+interface SyncSessionTerminator {
+    terminateSessions(filter: {
+        userId?: string;
+        deviceId?: string;
+    }): unknown;
 }
 interface KoraAuthServer {
     routes: BuiltInAuthRoutes;
@@ -1178,8 +1539,31 @@ interface KoraAuthServer {
     tokenManager: TokenManager;
     oauth?: OAuthManager;
     linkedIdentityStore?: LinkedIdentityStore;
-    auth: ReturnType<BuiltInAuthRoutes['toSyncAuthProvider']>;
+    /** Sync auth provider with server-derived scopes (pass to `KoraSyncServer`). */
+    auth: SyncAuthProvider;
     handleRequest(request: KoraAuthHttpRequest): Promise<AuthRouteResponse<unknown>>;
+    /**
+     * Revoke every credential a user holds (call after a password change made
+     * outside these routes, an admin action or an account deletion).
+     */
+    revokeAllForUser(userId: string): Promise<void>;
+    /** Subscribe to credential revocations. Returns an unsubscribe function. */
+    onRevoke(listener: (event: AuthRevocationEvent) => void | Promise<void>): () => void;
+    /**
+     * End live sync sessions when their credentials are revoked (AUTH-11).
+     * Requires a sync server exposing `terminateSessions({ userId, deviceId })`.
+     * A `KoraSyncServer` constructed with this server's `auth` provider already
+     * follows its revocations; call this for a server built with a wrapping or
+     * custom provider. Binding both is harmless. Returns an unsubscribe function.
+     */
+    bindSyncServer(server: SyncSessionTerminator): () => void;
+}
+/**
+ * Thrown by `createKoraAuthServer` in production when a store would silently
+ * lose accounts or revocations on restart.
+ */
+declare class InMemoryAuthStoreError extends KoraError {
+    constructor(which: 'userStore' | 'revocationStore');
 }
 /**
  * Create the built-in Kora auth server with production-shaped defaults.
@@ -1189,6 +1573,85 @@ interface KoraAuthServer {
  */
 declare function createKoraAuthServer(options?: CreateKoraAuthServerOptions): KoraAuthServer;
 
+/**
+ * Minimal better-sqlite3 subset to avoid a hard dependency on the package.
+ */
+interface SqliteRevocationDatabase {
+    exec(source: string): void;
+    prepare(source: string): {
+        run(...params: unknown[]): {
+            changes: number;
+        };
+        get(...params: unknown[]): unknown;
+    };
+}
+/**
+ * SQLite-backed {@link TokenRevocationStore} (better-sqlite3).
+ *
+ * Revocations survive restarts and are shared by every process using the same
+ * database file. `consume` is a single `INSERT ... ON CONFLICT DO NOTHING`, so it
+ * is atomic: better-sqlite3 executes statements synchronously under SQLite's
+ * write lock.
+ *
+ * @example
+ * ```typescript
+ * const userStore = await createSqliteUserStore({ filename: './auth.db' })
+ * const revocationStore = userStore.getTokenRevocationStore()
+ * ```
+ */
+declare class SqliteTokenRevocationStore implements TokenRevocationStore {
+    private readonly db;
+    constructor(db: SqliteRevocationDatabase);
+    isRevoked(jti: string): Promise<boolean>;
+    revoke(jti: string, expiresAt: number): Promise<void>;
+    consume(jti: string, expiresAt: number): Promise<ConsumeResult>;
+    isConsumed(jti: string): Promise<boolean>;
+    revokeAllForDevice(deviceId: string, before?: number): Promise<void>;
+    getDeviceRevokedBefore(deviceId: string): Promise<number | null>;
+    revokeAllForUser(userId: string, before?: number): Promise<void>;
+    getUserRevokedBefore(userId: string): Promise<number | null>;
+    /** Delete revocations and consumptions whose tokens have expired. */
+    cleanup(): Promise<void>;
+    private setCutoff;
+    private getCutoff;
+}
+
+/**
+ * Minimal postgres-js tagged-template client.
+ */
+type PostgresRevocationClient = (template: TemplateStringsArray, ...args: unknown[]) => Promise<Record<string, unknown>[]>;
+/**
+ * PostgreSQL-backed {@link TokenRevocationStore} (postgres-js).
+ *
+ * Shared by every server instance using the database. `consume` is one
+ * `INSERT ... ON CONFLICT DO NOTHING RETURNING`, so exactly one concurrent
+ * caller, on any instance, consumes a refresh token (AUTH-6).
+ *
+ * @example
+ * ```typescript
+ * const userStore = await createPostgresUserStore({ connectionString })
+ * const revocationStore = userStore.getTokenRevocationStore()
+ * ```
+ */
+declare class PostgresTokenRevocationStore implements TokenRevocationStore {
+    private readonly sql;
+    private readonly ready;
+    constructor(sql: PostgresRevocationClient);
+    private ensureTables;
+    isRevoked(jti: string): Promise<boolean>;
+    revoke(jti: string, expiresAt: number): Promise<void>;
+    consume(jti: string, expiresAt: number): Promise<ConsumeResult>;
+    isConsumed(jti: string): Promise<boolean>;
+    revokeAllForDevice(deviceId: string, before?: number): Promise<void>;
+    getDeviceRevokedBefore(deviceId: string): Promise<number | null>;
+    revokeAllForUser(userId: string, before?: number): Promise<void>;
+    getUserRevokedBefore(userId: string): Promise<number | null>;
+    /** Delete revocations and consumptions whose tokens have expired. */
+    cleanup(): Promise<void>;
+    private setCutoff;
+    private getCutoff;
+}
+
 /**
  * Creates a signed JWT (HS256) from a payload and secret.
  *
@@ -1348,8 +1811,12 @@ interface PasswordResetStore {
     store(token: PasswordResetToken): Promise<void>;
     /** Look up a token. Returns null if not found. */
     get(token: string): Promise<PasswordResetToken | null>;
-    /** Mark a token as consumed. */
-    consume(token: string): Promise<void>;
+    /**
+     * Mark a token as consumed. Should be atomic and return `true` only for the
+     * call that consumed a not-yet-consumed token; `false` makes the reset fail
+     * as already used. Returning nothing is accepted for older stores.
+     */
+    consume(token: string): Promise<boolean | undefined>;
     /** Count active (non-consumed, non-expired) tokens for an email. */
     countActiveForEmail(email: string): Promise<number>;
     /** Remove expired tokens. */
@@ -1368,11 +1835,23 @@ interface PasswordResetConfig {
     /** Max reset requests per email in the TTL window. Defaults to 3. */
     maxRequestsPerEmail?: number;
     /**
-     * Callback invoked when a reset is requested.
-     * The developer must implement email sending.
-     * If not provided, the token is returned in the route response (development mode).
+     * Callback invoked when a reset is requested. The developer must implement
+     * email sending: the token must only ever reach the account's mailbox.
      */
     onResetRequested?: (email: string, token: string, expiresAt: number) => void | Promise<void>;
+    /**
+     * Development only: also return the reset token in the `requestReset`
+     * response when no `onResetRequested` callback is configured. Ignored when
+     * `NODE_ENV=production`; the token is never disclosed to the requester there.
+     * @default false
+     */
+    exposeTokenForDevelopment?: boolean;
+    /**
+     * Called after a password is reset or changed, once every earlier credential
+     * of the user has been revoked. Use it to end live sessions (for example
+     * `authServer.revokeAllForUser` when the user store has no revocation store).
+     */
+    onPasswordChanged?: (userId: string) => void | Promise<void>;
 }
 declare class PasswordResetError extends KoraError {
     constructor(message: string, code: string, context?: Record<string, unknown>);
@@ -1390,7 +1869,7 @@ declare class InMemoryPasswordResetStore implements PasswordResetStore {
     private tokens;
     store(token: PasswordResetToken): Promise<void>;
     get(token: string): Promise<PasswordResetToken | null>;
-    consume(token: string): Promise<void>;
+    consume(token: string): Promise<boolean>;
     countActiveForEmail(email: string): Promise<number>;
     cleanExpired(): Promise<number>;
 }
@@ -1419,13 +1898,16 @@ declare class PasswordResetManager {
     private readonly tokenTtlMs;
     private readonly maxRequestsPerEmail;
     private readonly onResetRequested?;
+    private readonly exposeTokenForDevelopment;
+    private readonly onPasswordChanged?;
+    private warnedNoDelivery;
     constructor(config: PasswordResetConfig);
     /**
      * Request a password reset for an email.
-     * Always returns success to prevent email enumeration.
+     * Always returns the same success response to prevent email enumeration.
      *
-     * If a callback is configured, invokes it with the token.
-     * In development mode (no callback), returns the token in the response.
+     * The token is delivered only through `onResetRequested`. It is returned in
+     * the response only with `exposeTokenForDevelopment: true` outside production.
      */
     requestReset(email: string): Promise<{
         status: number;
@@ -1464,6 +1946,11 @@ declare class PasswordResetManager {
             error: string;
         };
     }>;
+    /**
+     * A password change kills every earlier credential (AUTH-7b): every access
+     * and refresh token issued before now is rejected on every path.
+     */
+    private revokeEarlierCredentials;
 }
 
 /**
@@ -1641,7 +2128,10 @@ interface SqliteDatabase$1 {
  */
 declare class SqliteUserStore implements UserStore {
     private readonly db;
+    private revocationStore;
     constructor(db: SqliteDatabase$1);
+    /** Token revocations stored in the same SQLite database as the users. */
+    getTokenRevocationStore(): TokenRevocationStore;
     private ensureTables;
     createUser(params: {
         email: string;
@@ -1687,6 +2177,19 @@ declare function createSqliteUserStore(options: {
 interface PostgresClient$1 {
     begin<T>(fn: (sql: PostgresClient$1) => Promise<T>): Promise<T>;
     (template: TemplateStringsArray, ...args: unknown[]): Promise<Record<string, unknown>[]>;
+    /** postgres-js: close every connection of the pool (optional in this subset). */
+    end?(options?: {
+        timeout?: number;
+    }): Promise<void>;
+}
+/** Options for {@link PostgresUserStore}. */
+interface PostgresUserStoreOptions {
+    /**
+     * Whether {@link PostgresUserStore.close} ends the client's connections. True for
+     * a store made by `createPostgresUserStore` (it opened the client); false by
+     * default for a client you pass in, which you end yourself.
+     */
+    ownsClient?: boolean;
 }
 /**
  * PostgreSQL-backed user and device store using postgres-js.
@@ -1706,12 +2209,32 @@ interface PostgresClient$1 {
  *   connectionString: 'postgres://user:pass@localhost:5432/mydb',
  * })
  * const routes = new BuiltInAuthRoutes({ userStore, tokenManager })
+ * // On shutdown (or at the end of a script):
+ * await userStore.close()
  * ```
  */
 declare class PostgresUserStore implements UserStore {
     private readonly sql;
     private readonly ready;
-    constructor(sql: PostgresClient$1);
+    private revocationStore;
+    private readonly ownsClient;
+    private closed;
+    constructor(sql: PostgresClient$1, options?: PostgresUserStoreOptions);
+    /**
+     * Release the store's database connections, so a script using it can exit. Waits
+     * for table creation to settle first. A client passed to the constructor is left
+     * open unless `ownsClient` was set (end it yourself). Idempotent.
+     *
+     * @example
+     * ```typescript
+     * const users = await createPostgresUserStore({ connectionString })
+     * const device = await users.findDevice(nodeId)
+     * await users.close()
+     * ```
+     */
+    close(): Promise<void>;
+    /** Token revocations stored in the same Postgres database as the users. */
+    getTokenRevocationStore(): TokenRevocationStore;
     private ensureTables;
     createUser(params: {
         email: string;
@@ -2044,6 +2567,22 @@ interface ExternalJwtProviderConfig {
      * ```
      */
     mapClaims?: (claims: Record<string, unknown>) => ExternalUserInfo;
+    /**
+     * Accepted audience(s) (`aud`). When set, tokens for any other audience are
+     * rejected, even if they share the signing secret. Defaults to
+     * `'authenticated'` when `providerName` is `'supabase'`.
+     */
+    audience?: string | string[];
+    /** Accepted issuer(s) (`iss`). When set, tokens from any other issuer are rejected. */
+    issuer?: string | string[];
+    /**
+     * Verified scope values for the sync grant, derived from the validated claims
+     * (AUTH-1). Merged over `{ userId }`; every schema-scoped collection is bound
+     * from them, and a collection whose binding is missing is denied.
+     */
+    scopeValues?: (claims: Record<string, unknown>) => Record<string, unknown>;
+    /** Full explicit sync grant from the validated claims (replaces the default). */
+    resolveScopes?: (claims: Record<string, unknown>) => ScopeMap | Promise<ScopeMap>;
 }
 /**
  * Authentication provider adapter for external JWT issuers.
@@ -2088,6 +2627,10 @@ declare class ExternalJwtProvider implements AuthProviderAdapter {
     private readonly jwtSecret;
     private readonly customValidateToken;
     private readonly mapClaims;
+    private readonly audiences;
+    private readonly issuers;
+    private readonly scopeValues;
+    private readonly resolveScopes;
     constructor(config: ExternalJwtProviderConfig);
     /**
      * Not supported for external providers.
@@ -2200,6 +2743,8 @@ declare class ExternalJwtProvider implements AuthProviderAdapter {
      * @returns The decoded claims object, or null if the token is invalid
      */
     private extractClaims;
+    /** Enforce configured `aud` / `iss` so tokens for another service are refused. */
+    private audienceAndIssuerMatch;
 }
 
 /**
@@ -2506,6 +3051,12 @@ declare function verifyRegistrationResponse(params: {
     expectedChallenge: string;
     expectedOrigin: string;
     expectedRpId: string;
+    /**
+     * Require the User Verified (UV) flag. Kora's options request
+     * `userVerification: 'required'`, so the response must honour it.
+     * @default true
+     */
+    requireUserVerification?: boolean;
 }): Promise<RegistrationVerificationResult>;
 /** Options returned by generateAuthenticationOptions for the client. */
 interface AuthenticationOptions {
@@ -2605,6 +3156,12 @@ declare function verifyAuthenticationResponse(params: {
     expectedRpId: string;
     publicKey: string;
     previousSignCount: number;
+    /**
+     * Require the User Verified (UV) flag. Kora's options request
+     * `userVerification: 'required'`, so the assertion must honour it.
+     * @default true
+     */
+    requireUserVerification?: boolean;
 }): Promise<AuthenticationVerificationResult>;
 
 /**
@@ -2808,7 +3365,11 @@ interface OrgStore {
     /** Consume an invitation (mark as accepted). Returns the invitation details. */
     consumeInvitation(token: string): Promise<OrgInvitation>;
     /** Revoke a pending invitation. */
-    revokeInvitation(invitationId: string): Promise<void>;
+    /**
+     * Revoke a pending invitation of `orgId`. Must throw InvitationNotFoundError
+     * when the invitation belongs to another org (AUTH-4).
+     */
+    revokeInvitation(orgId: string, invitationId: string): Promise<void>;
     /** List pending invitations for an organization. */
     listPendingInvitations(orgId: string): Promise<OrgInvitation[]>;
     /** List pending invitations for a specific email address. */
@@ -2847,7 +3408,7 @@ declare class InMemoryOrgStore implements OrgStore {
     createInvitation(orgId: string, invitedBy: string, params: CreateInvitationParams): Promise<OrgInvitation>;
     getInvitationByToken(token: string): Promise<OrgInvitation | null>;
     consumeInvitation(token: string): Promise<OrgInvitation>;
-    revokeInvitation(invitationId: string): Promise<void>;
+    revokeInvitation(orgId: string, invitationId: string): Promise<void>;
     listPendingInvitations(orgId: string): Promise<OrgInvitation[]>;
     listInvitationsForEmail(email: string): Promise<OrgInvitation[]>;
     cleanExpiredInvitations(): Promise<number>;
@@ -2873,7 +3434,26 @@ interface OrgRouteResponse<T> {
 interface OrgRoutesConfig {
     /** The organization store backing all org operations */
     orgStore: OrgStore;
+    /**
+     * Resolves a user's email and its verification status (a `UserStore`
+     * satisfies this). Invitations are listed and accepted only for the caller's
+     * own VERIFIED email; without a lookup, pass the verified identity to
+     * `acceptInvitation` / `listMyInvitations` explicitly.
+     */
+    userLookup?: {
+        findById(userId: string): Promise<{
+            email: string;
+            emailVerified: boolean;
+        } | null>;
+    };
+}
+/** A server-verified email identity used to match invitations. */
+interface VerifiedEmailIdentity {
+    email: string;
+    emailVerified: boolean;
 }
+/** Invitation as shown to its invitee: the secret token is never included. */
+type InviteeInvitation = Omit<OrgInvitation, 'token'>;
 /**
  * Server-side route handlers for organization management.
  *
@@ -2893,6 +3473,7 @@ interface OrgRoutesConfig {
  */
 declare class OrgRoutes {
     private readonly store;
+    private readonly userLookup;
     constructor(config: OrgRoutesConfig);
     /**
      * Create a new organization. The authenticated user becomes the owner.
@@ -2965,11 +3546,17 @@ declare class OrgRoutes {
         role?: unknown;
     }): Promise<OrgRouteResponse<OrgInvitation>>;
     /**
-     * Accept an invitation by its token. The authenticated user joins the org.
+     * Accept an invitation by its token. The authenticated user joins the org
+     * only if the invitation was addressed to the user's own verified email.
+     *
+     * @param userId - The authenticated user
+     * @param params - The invitation token
+     * @param identity - The user's verified email identity; resolved through
+     *   `userLookup` when omitted
      */
     acceptInvitation(userId: string, params: {
         token?: unknown;
-    }): Promise<OrgRouteResponse<Membership>>;
+    }, identity?: VerifiedEmailIdentity): Promise<OrgRouteResponse<Membership>>;
     /**
      * Revoke a pending invitation. Requires admin or higher.
      */
@@ -2981,9 +3568,15 @@ declare class OrgRoutes {
      */
     listPendingInvitations(userId: string, orgId: string): Promise<OrgRouteResponse<OrgInvitation[]>>;
     /**
-     * List pending invitations for the authenticated user's email.
+     * List pending invitations addressed to the authenticated user's own
+     * verified email. The email is resolved server-side (never taken from the
+     * request) and invitation tokens are never returned.
+     *
+     * @param userId - The authenticated user
+     * @param identity - The user's verified identity; resolved through `userLookup` when omitted
      */
-    listMyInvitations(email: string): Promise<OrgRouteResponse<OrgInvitation[]>>;
+    listMyInvitations(userId: string, identity?: VerifiedEmailIdentity): Promise<OrgRouteResponse<InviteeInvitation[]>>;
+    private resolveIdentity;
     /**
      * Check if the caller has the required role in the org.
      * Returns an error response if not authorized, or null if authorized.
@@ -3609,6 +4202,10 @@ interface TotpSecret {
      * until the first code is consumed.
      */
     lastUsedTimeStep?: number;
+    /** Consecutive failed code checks (TOTP or recovery). Reset on success. */
+    failedAttempts?: number;
+    /** While set and in the future, every code check fails without being evaluated. */
+    lockedUntil?: number;
 }
 /**
  * Setup result returned when enabling TOTP MFA.
@@ -3635,6 +4232,14 @@ interface TotpStore {
 declare class TotpError extends KoraError {
     constructor(message: string, code: string, context?: Record<string, unknown>);
 }
+/**
+ * Thrown by `disable` / `regenerateRecoveryCodes` while code checks are locked
+ * after repeated failures (AUTH-10). `verify` returns false instead.
+ */
+declare class TotpLockedError extends TotpError {
+    readonly lockedUntil: number;
+    constructor(lockedUntil: number);
+}
 declare class TotpInvalidCodeError extends TotpError {
     constructor();
 }
@@ -3659,31 +4264,6 @@ declare class InMemoryTotpStore implements TotpStore {
     getByUserId(userId: string): Promise<TotpSecret | null>;
     delete(userId: string): Promise<void>;
 }
-/**
- * Manages TOTP-based Multi-Factor Authentication.
- *
- * Implements RFC 6238 (TOTP) and RFC 4226 (HOTP) with Web Crypto API.
- * Compatible with Google Authenticator, Authy, 1Password, and other
- * TOTP-compatible authenticator apps.
- *
- * @example
- * ```typescript
- * const totp = new TotpManager({
- *   issuer: 'MyApp',
- *   store: new InMemoryTotpStore(),
- * })
- *
- * // Step 1: Enable MFA (returns QR code URI and recovery codes)
- * const setup = await totp.enable('user-123', 'alice@example.com')
- * // Show setup.uri as QR code, show setup.recoveryCodes once
- *
- * // Step 2: Verify setup with a code from authenticator app
- * await totp.verifySetup('user-123', '123456')
- *
- * // Step 3: On login, verify TOTP code
- * const valid = await totp.verify('user-123', '654321')
- * ```
- */
 declare class TotpManager {
     private readonly store;
     private readonly issuer;
@@ -3739,7 +4319,19 @@ declare class TotpManager {
      * Get the number of remaining recovery codes for a user.
      */
     remainingRecoveryCodes(userId: string): Promise<number>;
-    private validateCode;
+    private isLocked;
+    private assertNotLocked;
+    /**
+     * Count a failed code check. After FREE_FAILURES consecutive failures, code
+     * checks lock for an exponentially growing period (30s, 60s, ... up to 15
+     * minutes), which bounds online guessing of a 6-digit code (AUTH-10) without
+     * a permanent lockout an attacker could trigger at will.
+     */
+    private recordFailure;
+    /** consumeCode plus failure accounting. */
+    private checkTotp;
+    /** A matching time-step that has not been consumed yet, or null. */
+    private matchFreshTimeStep;
     /**
      * Find the TOTP time-step counter (within the acceptance window) whose
      * generated code matches `code`, or null if none matches. Comparison is
@@ -3922,6 +4514,19 @@ interface AdminApiConfig {
     sessionStore?: SessionStore;
     /** Audit logger (optional) */
     auditLogger?: AuditLogger;
+    /**
+     * Authorization check for the acting admin. When set, every method that
+     * takes an `adminId` throws {@link AdminUnauthorizedError} unless it returns
+     * true. Without it, the app must gate access to AdminApi itself.
+     */
+    isAdmin?: (adminId: string) => boolean | Promise<boolean>;
+    /**
+     * Revoke every credential of a user (defaults to the user store's token
+     * revocation store). Called by `revokeUserSessions`, `suspend`-style flows
+     * and `deleteUser`, so JWTs and refresh tokens die with the session rows.
+     * Pass `authServer.revokeAllForUser` to also end live sync sessions.
+     */
+    revokeAllForUser?: (userId: string) => Promise<void>;
 }
 /**
  * Paginated result set.
@@ -3990,7 +4595,13 @@ declare class AdminApi {
     private readonly userStore;
     private readonly sessionStore;
     private readonly auditLogger;
+    private readonly isAdmin;
+    private readonly revokeAllForUserFn;
     constructor(config: AdminApiConfig);
+    /** Throws AdminUnauthorizedError unless the configured `isAdmin` accepts the actor. */
+    private authorize;
+    /** Kill every JWT and refresh token of a user, not just session rows (AUTH-7b/AUTH-14). */
+    private revokeCredentials;
     /**
      * Get a user by ID with full details.
      */
@@ -4150,9 +4761,24 @@ declare class InMemoryWebhookStore implements WebhookStore {
 declare class WebhookManager {
     private readonly store;
     private readonly fetchFn;
+    private readonly allowPrivateTargets;
+    private readonly resolveHost;
+    /**
+     * @param config.store - Endpoint and delivery storage
+     * @param config.fetch - Custom fetch. A custom fetch (for example through an
+     *   egress proxy) owns its own network policy, so Kora skips its delivery-time
+     *   DNS check unless `resolveHost` is also given.
+     * @param config.allowPrivateTargets - Development only: allow http:// and
+     *   loopback/private/link-local targets. Default false.
+     * @param config.resolveHost - Resolve a hostname to addresses at delivery time
+     *   (defaults to node:dns when no custom fetch is given), so a public name that
+     *   points at a private address is refused (SSRF, DNS rebinding).
+     */
     constructor(config: {
         store: WebhookStore;
         fetch?: typeof globalThis.fetch;
+        allowPrivateTargets?: boolean;
+        resolveHost?: (host: string) => Promise<string[]>;
     });
     /**
      * Register a new webhook endpoint.
@@ -4192,11 +4818,26 @@ declare class WebhookManager {
      */
     dispatch(event: WebhookEvent, data: Record<string, unknown>): Promise<void>;
     private deliverToEndpoint;
+    private assertDeliverable;
+}
+/** Thrown when a webhook URL points at a non-public target. */
+declare class WebhookTargetError extends WebhookError {
+    constructor(url: string);
 }
 /**
- * Verify a webhook payload signature.
- * Useful for consumers of webhooks to verify authenticity.
+ * Verify a webhook payload signature (`X-Webhook-Signature: t=<unix>,v1=<hex>`).
+ *
+ * The HMAC covers `${t}.${payload}`, and a delivery older (or newer) than
+ * `toleranceSeconds` is rejected, so a captured delivery cannot be replayed.
+ *
+ * @param payload - The raw request body
+ * @param signature - The `X-Webhook-Signature` header
+ * @param secret - The endpoint secret
+ * @param options - `toleranceSeconds` (default 300)
+ * @returns True when the signature is valid and fresh
  */
-declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
+declare function verifyWebhookSignature(payload: string, signature: string, secret: string, options?: {
+    toleranceSeconds?: number;
+}): Promise<boolean>;
 
-export { AdminApi, type AdminApiConfig, AdminApiError, AdminUnauthorizedError, AdminUserNotFoundError, type AdminUserUpdate, type AuditAction, type AuditEntry, AuditLogError, type AuditLogQuery, type AuditLogStore, AuditLogger, type AuthDevice, type AuthProviderAdapter, AuthProviderError, type AuthRouteResponse, type AuthRoutesConfig, type AuthUser, type AuthenticationOptions, type AuthenticationVerificationResult, BUILT_IN_ROLES, BuiltInAuthRoutes, BuiltInProvider, CannotRemoveOwnerError, type ChallengeStore, CircularInheritanceError, type ClerkAdapterConfig, type CollectionScopeResolver, type CreateInvitationParams, type CreateKoraAuthServerOptions, type CreateOrgParams, type CreateSessionParams, DuplicateEmailError, DuplicateLinkedIdentityError, type EmailVerificationConfig, EmailVerificationError, EmailVerificationManager, type EmailVerificationStore, type EmailVerificationToken, ExternalAuthOperationNotSupportedError, ExternalJwtProvider, type ExternalJwtProviderConfig, ExternalTokenValidationError, type ExternalUserInfo, INVITATION_STATUSES, InMemoryAuditLogStore, InMemoryChallengeStore, InMemoryEmailVerificationStore, InMemoryLinkedIdentityStore, InMemoryOAuthStateStore, InMemoryOrgStore, InMemoryPasswordResetStore, InMemoryRateLimiter, InMemorySessionStore, InMemoryTokenRevocationStore, InMemoryTotpStore, InMemoryUserStore, InMemoryWebhookStore, InsufficientRoleError, InvalidPermissionError, InvitationExpiredError, InvitationNotFoundError, type InvitationStatus, type KoraAuthHttpRequest, type KoraAuthServer, type LinkedIdentity, type LinkedIdentityStore, MemberAlreadyExistsError, type Membership, MembershipNotFoundError, OAuthCodeExchangeError, OAuthError, OAuthManager, type OAuthManagerConfig, type OAuthProviderConfig, OAuthProviderNotFoundError, type OAuthServerConfig, type OAuthState, OAuthStateMismatchError, type OAuthStateStore, type OAuthTokens, type OAuthUserInfo, OAuthUserInfoError, ORG_ROLES, OrgError, type OrgInvitation, OrgNotFoundError, type OrgRole, type OrgRouteResponse, OrgRoutes, type OrgRoutesConfig, OrgScopeResolver, OrgSlugTakenError, type OrgStore, type Organization, type PaginatedResult, PasskeyVerificationError, type PasswordResetConfig, PasswordResetError, PasswordResetManager, type PasswordResetStore, type PasswordResetToken, type Permission, PostgresLinkedIdentityStore, PostgresOAuthStateStore, PostgresUserStore, ROLE_HIERARCHY, type RateLimiter, type RbacConfig, RbacEngine, RbacError, type RegistrationOptions, type RegistrationVerificationResult, ResetRateLimitedError, ResetTokenExpiredError, ResetTokenNotFoundError, type RoleDefinition, RoleNotFoundError, type ScopeContext, type ScopeFilter, type Session, SessionError, SessionExpiredError, SessionLimitExceededError, SessionManager, type SessionManagerConfig, SessionMfaRequiredError, SessionNotFoundError, type SessionStore, type SignInParams, type SignUpParams, SqliteLinkedIdentityStore, SqliteOAuthStateStore, SqliteUserStore, type StoredUser, type SupabaseAdapterConfig, type SyncScopes, TokenManager, type TokenManagerConfig, type TokenRevocationStore, TotpAlreadyEnabledError, type TotpConfig, TotpError, TotpInvalidCodeError, TotpManager, TotpNotEnabledError, TotpNotVerifiedError, TotpRecoveryExhaustedError, type TotpSecret, type TotpSetupResult, type TotpStore, type UpdateOrgParams, type UserListQuery, type UserStore, VerificationTokenExpiredError, VerificationTokenNotFoundError, type WebhookDelivery, type WebhookEndpoint, WebhookEndpointNotFoundError, WebhookError, type WebhookEvent, WebhookManager, type WebhookPayload, type WebhookStore, base32Decode, base32Encode, createClerkAdapter, createKoraAuthServer, createPostgresLinkedIdentityStore, createPostgresOAuthStateStore, createPostgresOAuthStores, createPostgresUserStore, createSqliteLinkedIdentityStore, createSqliteOAuthStateStore, createSqliteOAuthStores, createSqliteUserStore, createSupabaseAdapter, decodeJwt, defineRoles, encodeJwt, generateAuthenticationOptions, generateRegistrationOptions, githubProvider, googleProvider, hasRoleLevel, hashPassword, isExpired, microsoftProvider, parsePermission, permissionCovers, verifyAuthenticationResponse, verifyJwt, verifyPassword, verifyRegistrationResponse, verifyWebhookSignature };
+export { AdminApi, type AdminApiConfig, AdminApiError, AdminUnauthorizedError, AdminUserNotFoundError, type AdminUserUpdate, type AuditAction, type AuditEntry, AuditLogError, type AuditLogQuery, type AuditLogStore, AuditLogger, type AuthDevice, type AuthProviderAdapter, AuthProviderError, type AuthRevocationEvent, type AuthRouteResponse, type AuthRoutesConfig, type AuthUser, type AuthenticatedAccess, type AuthenticationOptions, type AuthenticationVerificationResult, BUILT_IN_ROLES, BuiltInAuthRoutes, BuiltInProvider, CannotRemoveOwnerError, type ChallengeStore, CircularInheritanceError, type ClerkAdapterConfig, type CollectionScopeResolver, type ConsumeResult, type CreateInvitationParams, type CreateKoraAuthServerOptions, type CreateOrgParams, type CreateSessionParams, DEFAULT_REFRESH_REUSE_GRACE_MS, DeviceOwnershipError, DuplicateEmailError, DuplicateLinkedIdentityError, type EmailVerificationConfig, EmailVerificationError, EmailVerificationManager, type EmailVerificationStore, type EmailVerificationToken, ExternalAuthOperationNotSupportedError, ExternalJwtProvider, type ExternalJwtProviderConfig, ExternalTokenValidationError, type ExternalUserInfo, INVITATION_STATUSES, InMemoryAuditLogStore, InMemoryAuthStoreError, InMemoryChallengeStore, InMemoryEmailVerificationStore, InMemoryLinkedIdentityStore, InMemoryOAuthStateStore, InMemoryOrgStore, InMemoryPasswordResetStore, InMemoryRateLimiter, InMemorySessionStore, InMemoryTokenRevocationStore, InMemoryTotpStore, InMemoryUserStore, InMemoryWebhookStore, InsufficientRoleError, InvalidPermissionError, InvitationExpiredError, InvitationNotFoundError, type InvitationStatus, type IssueTokenOptions, type KoraAuthHttpRequest, type KoraAuthServer, type LinkedIdentity, type LinkedIdentityStore, MemberAlreadyExistsError, type Membership, MembershipNotFoundError, type MfaChallenge, type MfaPendingPayload, type MfaVerifier, OAuthCodeExchangeError, OAuthError, OAuthManager, type OAuthManagerConfig, type OAuthProviderConfig, OAuthProviderNotFoundError, type OAuthServerConfig, type OAuthState, OAuthStateMismatchError, type OAuthStateStore, type OAuthTokens, type OAuthUserInfo, OAuthUserInfoError, ORG_ROLES, OrgError, type OrgInvitation, OrgNotFoundError, type OrgRole, type OrgRouteResponse, OrgRoutes, type OrgRoutesConfig, OrgScopeResolver, OrgSlugTakenError, type OrgStore, type Organization, type PaginatedResult, PasskeyVerificationError, type PasswordResetConfig, PasswordResetError, PasswordResetManager, type PasswordResetStore, type PasswordResetToken, type Permission, PostgresLinkedIdentityStore, PostgresOAuthStateStore, type PostgresRevocationClient, PostgresTokenRevocationStore, PostgresUserStore, type PostgresUserStoreOptions, ROLE_HIERARCHY, type RateLimiter, type RbacConfig, RbacEngine, RbacError, type RefreshFailureReason, type RefreshResult, type RegistrationOptions, type RegistrationVerificationResult, ResetRateLimitedError, ResetTokenExpiredError, ResetTokenNotFoundError, type RoleDefinition, RoleNotFoundError, type ScopeContext, type ScopeFilter, type Session, SessionError, SessionExpiredError, SessionLimitExceededError, SessionManager, type SessionManagerConfig, SessionMfaRequiredError, SessionNotFoundError, type SessionStore, type SignInParams, type SignInResult, type SignUpParams, SqliteLinkedIdentityStore, SqliteOAuthStateStore, type SqliteRevocationDatabase, SqliteTokenRevocationStore, SqliteUserStore, type StoredUser, type SupabaseAdapterConfig, type SyncAuthContext, type SyncAuthProvider, type SyncScopeOptions, type SyncScopes, type SyncSessionTerminator, TokenManager, type TokenManagerConfig, type TokenRevocationStore, TotpAlreadyEnabledError, type TotpConfig, TotpError, TotpInvalidCodeError, TotpLockedError, TotpManager, TotpNotEnabledError, TotpNotVerifiedError, TotpRecoveryExhaustedError, type TotpSecret, type TotpSetupResult, type TotpStore, type UpdateOrgParams, type UserListQuery, type UserStore, VerificationTokenExpiredError, VerificationTokenNotFoundError, type VerifiedSyncClaims, type WebhookDelivery, type WebhookEndpoint, WebhookEndpointNotFoundError, WebhookError, type WebhookEvent, WebhookManager, type WebhookPayload, type WebhookStore, WebhookTargetError, base32Decode, base32Encode, createClerkAdapter, createKoraAuthServer, createPostgresLinkedIdentityStore, createPostgresOAuthStateStore, createPostgresOAuthStores, createPostgresUserStore, createSqliteLinkedIdentityStore, createSqliteOAuthStateStore, createSqliteOAuthStores, createSqliteUserStore, createSupabaseAdapter, decodeJwt, defineRoles, encodeJwt, generateAuthenticationOptions, generateRegistrationOptions, githubProvider, googleProvider, hasRoleLevel, hashPassword, isExpired, microsoftProvider, parsePermission, permissionCovers, verifyAuthenticationResponse, verifyJwt, verifyPassword, verifyRegistrationResponse, verifyWebhookSignature };