@~lyre/auth 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -1,3 +1,270 @@
+import { KeyObject } from 'node:crypto';
+
+type OidcErrorCode = 
+/** Client misconfiguration (e.g. client_secret_basic without a secret). */
+'invalid_config'
+/** Callback `state` missing or not the one this app sent (possible CSRF). */
+ | 'state_mismatch'
+/** Accounts redirected back with `?error=…` (e.g. access_denied). */
+ | 'authorization_error'
+/** Callback carried no `code`. */
+ | 'missing_code'
+/** Callback `iss` parameter (RFC 9207) is not our issuer. */
+ | 'issuer_mismatch'
+/** Discovery document unreachable or invalid. */
+ | 'discovery_failed'
+/** JWKS unreachable or invalid. */
+ | 'jwks_fetch_failed'
+/** fetch() itself failed (DNS, connection refused, …). */
+ | 'network_error'
+/** Token endpoint answered non-2xx (see `oauthError`, e.g. invalid_grant, invalid_client). */
+ | 'token_request_failed'
+/** Token endpoint answered 2xx with an unusable body. */
+ | 'invalid_token_response'
+/** `openid` was requested but no id_token came back. */
+ | 'missing_id_token'
+/** Not a well-formed compact JWS. */
+ | 'invalid_jwt'
+/** Header alg is not RS256 (blocks `none`, HS256 key confusion, …). */
+ | 'unsupported_alg'
+/** No JWKS key matches the token's `kid`, even after a refetch. */
+ | 'unknown_kid' | 'invalid_signature' | 'audience_mismatch' | 'token_expired' | 'token_not_yet_valid' | 'nonce_mismatch'
+/** A token that is not an access token (e.g. an id_token) was presented as one. */
+ | 'wrong_token_type'
+/** userinfo answered non-2xx, or its `sub` disagrees with the token. */
+ | 'userinfo_failed' | 'revocation_failed';
+declare class OidcError extends Error {
+    readonly code: OidcErrorCode;
+    /** HTTP status from Accounts, when the failure was an HTTP response. */
+    readonly status?: number;
+    /** OAuth `error` field (`invalid_grant`, `invalid_client`, `access_denied`, …). */
+    readonly oauthError?: string;
+    readonly oauthErrorDescription?: string;
+    constructor(code: OidcErrorCode, message: string, details?: {
+        status?: number;
+        oauthError?: string;
+        oauthErrorDescription?: string;
+        cause?: unknown;
+    });
+}
+declare function isOidcError(error: unknown, code?: OidcErrorCode): error is OidcError;
+type OidcEndpoints = {
+    authorization: string;
+    token: string;
+    userinfo: string;
+    jwks: string;
+    revocation: string;
+    endSession: string;
+};
+/** Paths fixed by the contract, resolved against the issuer when discovery is off. */
+declare const ACCOUNTS_ENDPOINT_PATHS: Readonly<OidcEndpoints>;
+declare const DEFAULT_OIDC_SCOPES: readonly ["openid", "profile", "email", "offline_access"];
+type TokenEndpointAuthMethod = 'client_secret_basic' | 'client_secret_post' | 'none';
+type CommonVerifierOptions = {
+    /** Issuer, e.g. `https://accounts.nipate.africa`. Tokens must carry exactly this `iss`. */
+    issuer: string;
+    /** Load endpoints from `/.well-known/openid-configuration` (cached). Default false: contract paths. */
+    discovery?: boolean;
+    /** Override individual endpoints (absolute URLs or paths relative to the issuer). */
+    endpoints?: Partial<OidcEndpoints>;
+    fetchImpl?: typeof fetch;
+    /** Allowed clock skew for exp/nbf, seconds. Default 30. */
+    clockToleranceSec?: number;
+    /** Discovery cache TTL. Default 1h. */
+    metadataCacheTtlMs?: number;
+    /** JWKS cache TTL. Default 1h. */
+    jwksCacheTtlMs?: number;
+    /** Minimum gap between JWKS refetches triggered by an unknown kid. Default 5s. */
+    jwksRefetchCooldownMs?: number;
+    /** Clock, epoch ms. For tests. */
+    now?: () => number;
+};
+type OidcClientOptions = CommonVerifierOptions & {
+    /** The app's client id (its app id in Accounts). Tokens must carry it as `aud`. */
+    clientId: string;
+    /** Confidential apps only. Public apps (browser-only, CLI) have none. */
+    clientSecret?: string;
+    /** Must match a registered redirect URI character for character. */
+    redirectUri: string;
+    /** Where Accounts sends the browser after `/auth/logout`. */
+    postLogoutRedirectUri?: string;
+    /** Default `openid profile email offline_access`. */
+    scopes?: readonly string[] | string;
+    /** Default `client_secret_basic` when a secret is set, otherwise `none`. */
+    tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
+};
+type OidcLoginRequest = {
+    /** Send the browser here. */
+    url: string;
+    /** Keep these three server-side (or in a signed httpOnly cookie) until the callback. */
+    state: string;
+    nonce: string;
+    codeVerifier: string;
+};
+type OidcLoginExpectation = Pick<OidcLoginRequest, 'state' | 'nonce' | 'codeVerifier'>;
+type TokenSet = {
+    accessToken: string;
+    tokenType: 'Bearer';
+    expiresIn: number;
+    /** Epoch ms at which the access token expires (local clock). */
+    expiresAt: number;
+    /** Rotates on every refresh: always store the new one; the old one stops working. */
+    refreshToken?: string;
+    idToken?: string;
+    scope?: string;
+    raw: Record<string, unknown>;
+};
+type IdTokenClaims = {
+    iss: string;
+    sub: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    auth_time?: number;
+    nonce?: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    picture?: string;
+    [claim: string]: unknown;
+};
+type AccessTokenClaims = {
+    iss: string;
+    sub: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    /** Tenant id. */
+    tid?: string | null;
+    /** Accounts session id. */
+    sid?: string;
+    /** Space-separated scopes. */
+    scope?: string;
+    jti?: string;
+    [claim: string]: unknown;
+};
+type UserInfo = {
+    sub: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    picture?: string;
+    [claim: string]: unknown;
+};
+type VerifiedAccessToken = {
+    claims: AccessTokenClaims;
+    /** `jwks`: verified locally. `userinfo`: JWKS unreachable, Accounts vouched for it remotely. */
+    verifiedBy: 'jwks' | 'userinfo';
+};
+declare function randomToken(bytes?: number): string;
+/** RFC 7636 S256: BASE64URL(SHA256(ascii(verifier))). */
+declare function pkceChallenge(verifier: string): string;
+declare function createPkcePair(): {
+    codeVerifier: string;
+    codeChallenge: string;
+};
+type MetadataSource = {
+    get(): Promise<OidcEndpoints>;
+};
+declare class JwksStore {
+    private readonly metadata;
+    private readonly fetchImpl;
+    private readonly ttlMs;
+    private readonly cooldownMs;
+    private readonly now;
+    private keys;
+    private anonymous;
+    private fetchedAt;
+    private inflight;
+    /** Number of JWKS fetches performed (observability / tests). */
+    fetchCount: number;
+    constructor(metadata: MetadataSource, fetchImpl: typeof fetch, ttlMs: number, cooldownMs: number, now: () => number);
+    private refresh;
+    private lookup;
+    getKey(kid: string | undefined): Promise<KeyObject>;
+}
+/** True when the string has the shape of a compact JWS (three base64url segments). */
+declare function looksLikeJwt(token: string): boolean;
+type AccessTokenVerifierOptions = CommonVerifierOptions & {
+    /**
+     * Accepted `aud` values (client ids). Omit to accept a token issued to any app; the caller
+     * then reads `claims.aud` to see which app it was issued for.
+     */
+    audience?: string | readonly string[];
+    /**
+     * When the JWKS (or discovery) cannot be reached, ask Accounts' userinfo endpoint instead.
+     * Default true. Never used for a token that fails verification against a reachable JWKS.
+     */
+    remoteFallback?: boolean;
+};
+type AccessTokenVerifier = {
+    verify(token: string, options?: {
+        audience?: string | readonly string[];
+    }): Promise<VerifiedAccessToken>;
+    fetchUserInfo(accessToken: string): Promise<UserInfo>;
+    metadata(): Promise<OidcEndpoints>;
+    /** @internal */
+    readonly _jwks: JwksStore;
+};
+declare function createAccessTokenVerifier(opts: AccessTokenVerifierOptions): AccessTokenVerifier;
+type OidcClient = {
+    readonly clientId: string;
+    readonly issuer: string;
+    readonly scope: string;
+    readonly authMethod: TokenEndpointAuthMethod;
+    metadata(): Promise<OidcEndpoints>;
+    /** Step 1: build the /auth/authorize URL. Keep `state`, `nonce`, `codeVerifier` until the callback. */
+    beginLogin(options?: {
+        scopes?: readonly string[] | string;
+        prompt?: string;
+        loginHint?: string;
+        extraParams?: Record<string, string>;
+    }): Promise<OidcLoginRequest>;
+    /** Steps 3–5: check state, exchange the code (with PKCE verifier), verify the id_token. */
+    handleCallback(input: {
+        /** The full callback URL, or just its query parameters. */
+        url?: string | URL;
+        params?: URLSearchParams | Record<string, string | undefined>;
+        expected: Partial<OidcLoginExpectation> | null | undefined;
+    }): Promise<{
+        claims: IdTokenClaims;
+        tokens: TokenSet;
+    }>;
+    /** Low-level code exchange. Does NOT verify the id_token: call `verifyIdToken(t, { nonce })` yourself. */
+    exchangeCode(input: {
+        code: string;
+        codeVerifier: string;
+    }): Promise<TokenSet>;
+    /** grant_type=refresh_token. The returned `refreshToken` replaces the old one, which is now dead. */
+    refresh(refreshToken: string, options?: {
+        scopes?: readonly string[] | string;
+    }): Promise<TokenSet>;
+    /** POST /api/auth/revoke. Throws OidcError('revocation_failed') on a non-2xx answer. */
+    revoke(token: string, tokenTypeHint?: 'refresh_token' | 'access_token'): Promise<void>;
+    verifyIdToken(idToken: string, options?: {
+        nonce?: string;
+    }): Promise<IdTokenClaims>;
+    /** Verify locally against the JWKS (aud defaults to this client id); userinfo fallback if the JWKS is down. */
+    verifyAccessToken(token: string, options?: {
+        audience?: string | readonly string[];
+        remoteFallback?: boolean;
+    }): Promise<VerifiedAccessToken>;
+    fetchUserInfo(accessToken: string): Promise<UserInfo>;
+    /** /auth/logout?client_id=…&post_logout_redirect_uri=… */
+    logoutUrl(options?: {
+        postLogoutRedirectUri?: string;
+        state?: string;
+        idTokenHint?: string;
+    }): Promise<string>;
+    /** @internal */
+    readonly _jwks: JwksStore;
+};
+declare function createOidcClient(opts: OidcClientOptions): OidcClient;
+
 type PermissionSet = string[];
 type AccountsIdentity = {
     id: string;
@@ -49,18 +316,29 @@ type PlatformSession = {
     expiresAt?: string;
 };
 type AccountsClientConfig = {
+    /** Accounts origin, e.g. `https://accounts.nipate.africa`. */
     baseUrl?: string;
+    /** OIDC issuer. Defaults to `baseUrl`. Added 0.12.0. */
+    issuer?: string;
     clientId: string;
+    /** Confidential apps only; public apps leave it unset. */
     clientSecret?: string;
     redirectUri: string;
+    /** Absolute URL Accounts returns the browser to after `/auth/logout`. */
     logoutRedirectUri?: string;
+    /** Requested scopes. Default `openid profile email offline_access`. Added 0.12.0. */
+    scopes?: string[];
+    /** Load endpoints from `/.well-known/openid-configuration`. Default false. Added 0.12.0. */
+    discovery?: boolean;
     useMock?: boolean;
 };
+/** @deprecated Since 0.12.0; legacy login state. See `OidcLoginRequest`. */
 type AuthorizationState = {
     nonce: string;
     nextPath: string;
     tenantSlug?: string;
 };
+/** @deprecated Since 0.12.0; legacy token response with a `user`. See `TokenSet` + `IdTokenClaims`. */
 type AccountsTokenResponse = {
     access_token: string;
     refresh_token?: string;
@@ -86,10 +364,22 @@ type SyncAccountsUserResult = {
 };
 type SyncAccountsUser = (identity: AccountsIdentity) => SyncAccountsUserResult | Promise<SyncAccountsUserResult>;
 declare function createAccountsClientConfig(input?: Partial<AccountsClientConfig>): AccountsClientConfig;
+/**
+ * Build an OIDC client from an AccountsClientConfig (issuer falls back to baseUrl). Added 0.12.0.
+ */
+declare function createOidcClientFromConfig(config: AccountsClientConfig, overrides?: Partial<OidcClientOptions>): OidcClient;
+/** Map verified id_token (and optional userinfo) claims to an AccountsIdentity. Added 0.12.0. */
+declare function identityFromClaims(claims: IdTokenClaims | UserInfo, userInfo?: UserInfo): AccountsIdentity;
+/** Only same-origin absolute paths: `/x` yes, `//evil.example` and `/\\evil` no. */
+declare function safeNextPath(value: string | null | undefined): string;
 declare function createPlatformAuth(): {
     readSession(cookieHeader: string | null | undefined): PlatformSession;
     requirePrincipal(session: PlatformSession): AuthenticatedPrincipal;
 };
+/**
+ * @deprecated Since 0.12.0. Sends no PKCE, nonce or scope, which Accounts now refuses. Use
+ * `createOidcClient().beginLogin()` (+ `createLoginStateCookie`). Still used for mock mode.
+ */
 declare function beginAccountsLoginRedirect(config: AccountsClientConfig, options: {
     nextPath?: string;
     tenantSlug?: string;
@@ -99,6 +389,10 @@ declare function beginAccountsLoginRedirect(config: AccountsClientConfig, option
     stateValue: string;
     stateCookie: string;
 };
+/**
+ * @deprecated Since 0.12.0. Trusts the token response's `user` instead of a verified id_token. Use
+ * `createOidcClient().handleCallback()` (+ `readLoginStateCookie`). Still used for mock mode.
+ */
 declare function handleAccountsCallback(input: {
     config: AccountsClientConfig;
     code: string;
@@ -116,6 +410,10 @@ declare function handleAccountsCallback(input: {
     sessionCookie: string;
     clearStateCookie: string;
 }>;
+/**
+ * @deprecated Since 0.12.0. JSON body, no PKCE verifier, no client authentication. Use
+ * `createOidcClient().exchangeCode()` or `.handleCallback()`.
+ */
 declare function exchangeAuthorizationCode(input: {
     config: AccountsClientConfig;
     code: string;
@@ -142,6 +440,26 @@ type CookieOptions = {
     secure?: boolean;
 };
 declare function clearPlatformSessionCookie(opts?: CookieOptions): string;
+/** Set-Cookie string for a PlatformSession (HMAC-signed when `secret` is set). Added 0.12.0. */
+declare function createPlatformSessionCookie(session: PlatformSession, opts?: CookieOptions, secret?: string): string;
+declare const LOGIN_STATE_COOKIE_NAME = "accounts_oidc_login";
+type StoredLogin = OidcLoginExpectation & {
+    nextPath: string;
+    tenantSlug?: string;
+    /** Epoch seconds when the login started. */
+    issuedAt: number;
+};
+declare function createLoginStateCookie(login: OidcLoginRequest | OidcLoginExpectation, options?: {
+    nextPath?: string;
+    tenantSlug?: string;
+    secret?: string;
+    cookieOptions?: CookieOptions;
+}): string;
+/** Read (and, with a secret, verify) the login state cookie. Null when absent, forged or older than 10 minutes. */
+declare function readLoginStateCookie(cookieHeader: string | null | undefined, options?: {
+    secret?: string;
+}): StoredLogin | null;
+declare function clearLoginStateCookie(opts?: CookieOptions): string;
 type ServiceKeyApp = {
     id: string;
     slug: string;
@@ -162,6 +480,10 @@ declare function introspectServiceKey(input: {
     key: string;
     fetchImpl?: typeof fetch;
 }): Promise<ServiceKeyContext | null>;
+/**
+ * @deprecated Since 0.12.0. The contract signs out by revoking the refresh token
+ * (`OidcClient.revoke`) and optionally sending the browser to `OidcClient.logoutUrl()`.
+ */
 declare function logoutFromAccounts(input: {
     config: Pick<AccountsClientConfig, 'baseUrl'>;
     accessToken: string;
@@ -188,4 +510,4 @@ type AccountsWebhookEvent = {
 declare function normalizeAccountsWebhook(payload: unknown): AccountsWebhookEvent;
 declare function scopeSatisfied(granted: string[] | undefined, required: string): boolean;
 
-export { type AccountsClientConfig, type AccountsIdentity, type AccountsTokenResponse, type AccountsWebhookEvent, type AuthenticatedPrincipal, type AuthorizationState, type CookieOptions, type LocalUser, type PermissionSet, type PlatformSession, type ServiceKeyApp, type ServiceKeyContext, type SyncAccountsUser, type SyncAccountsUserResult, type TenantAccessContext, type TenantContext, type TenantMembership, beginAccountsLoginRedirect, clearPlatformSessionCookie, createAccountsClientConfig, createPlatformAuth, exchangeAuthorizationCode, handleAccountsCallback, identityPassthroughSync, introspectServiceKey, logoutFromAccounts, normalizeAccountsWebhook, readPlatformSessionCookie, resolveActiveTenant, scopeSatisfied, serviceKeyFromRequest, syncAccountsUser, verifyWebhookSignature };
+export { ACCOUNTS_ENDPOINT_PATHS, type AccessTokenClaims, type AccessTokenVerifier, type AccessTokenVerifierOptions, type AccountsClientConfig, type AccountsIdentity, type AccountsTokenResponse, type AccountsWebhookEvent, type AuthenticatedPrincipal, type AuthorizationState, type CookieOptions, DEFAULT_OIDC_SCOPES, type IdTokenClaims, LOGIN_STATE_COOKIE_NAME, type LocalUser, type OidcClient, type OidcClientOptions, type OidcEndpoints, OidcError, type OidcErrorCode, type OidcLoginExpectation, type OidcLoginRequest, type PermissionSet, type PlatformSession, type ServiceKeyApp, type ServiceKeyContext, type StoredLogin, type SyncAccountsUser, type SyncAccountsUserResult, type TenantAccessContext, type TenantContext, type TenantMembership, type TokenEndpointAuthMethod, type TokenSet, type UserInfo, type VerifiedAccessToken, beginAccountsLoginRedirect, clearLoginStateCookie, clearPlatformSessionCookie, createAccessTokenVerifier, createAccountsClientConfig, createLoginStateCookie, createOidcClient, createOidcClientFromConfig, createPkcePair, createPlatformAuth, createPlatformSessionCookie, exchangeAuthorizationCode, handleAccountsCallback, identityFromClaims, identityPassthroughSync, introspectServiceKey, isOidcError, logoutFromAccounts, looksLikeJwt, normalizeAccountsWebhook, pkceChallenge, randomToken, readLoginStateCookie, readPlatformSessionCookie, resolveActiveTenant, safeNextPath, scopeSatisfied, serviceKeyFromRequest, syncAccountsUser, verifyWebhookSignature };

package/dist/index.js

@@ -1,34 +1,70 @@
 import {
+  ACCOUNTS_ENDPOINT_PATHS,
+  DEFAULT_OIDC_SCOPES,
+  LOGIN_STATE_COOKIE_NAME,
+  OidcError,
   beginAccountsLoginRedirect,
+  clearLoginStateCookie,
   clearPlatformSessionCookie,
+  createAccessTokenVerifier,
   createAccountsClientConfig,
+  createLoginStateCookie,
+  createOidcClient,
+  createOidcClientFromConfig,
+  createPkcePair,
   createPlatformAuth,
+  createPlatformSessionCookie,
   exchangeAuthorizationCode,
   handleAccountsCallback,
+  identityFromClaims,
   identityPassthroughSync,
   introspectServiceKey,
+  isOidcError,
   logoutFromAccounts,
+  looksLikeJwt,
   normalizeAccountsWebhook,
+  pkceChallenge,
+  randomToken,
+  readLoginStateCookie,
   readPlatformSessionCookie,
   resolveActiveTenant,
+  safeNextPath,
   scopeSatisfied,
   serviceKeyFromRequest,
   syncAccountsUser,
   verifyWebhookSignature
-} from "./chunk-TQNQLX3C.js";
+} from "./chunk-F2GDXTY4.js";
 export {
+  ACCOUNTS_ENDPOINT_PATHS,
+  DEFAULT_OIDC_SCOPES,
+  LOGIN_STATE_COOKIE_NAME,
+  OidcError,
   beginAccountsLoginRedirect,
+  clearLoginStateCookie,
   clearPlatformSessionCookie,
+  createAccessTokenVerifier,
   createAccountsClientConfig,
+  createLoginStateCookie,
+  createOidcClient,
+  createOidcClientFromConfig,
+  createPkcePair,
   createPlatformAuth,
+  createPlatformSessionCookie,
   exchangeAuthorizationCode,
   handleAccountsCallback,
+  identityFromClaims,
   identityPassthroughSync,
   introspectServiceKey,
+  isOidcError,
   logoutFromAccounts,
+  looksLikeJwt,
   normalizeAccountsWebhook,
+  pkceChallenge,
+  randomToken,
+  readLoginStateCookie,
   readPlatformSessionCookie,
   resolveActiveTenant,
+  safeNextPath,
   scopeSatisfied,
   serviceKeyFromRequest,
   syncAccountsUser,

package/dist/nest.d.ts

@@ -1,5 +1,6 @@
-import { AccountsWebhookEvent, ServiceKeyContext, AccountsClientConfig } from './index.js';
+import { AccountsWebhookEvent, ServiceKeyContext, AccountsClientConfig, AccessTokenVerifierOptions } from './index.js';
 export { normalizeAccountsWebhook } from './index.js';
+import 'node:crypto';
 
 /**
  * The minimum a request must expose. Fastify's `request` satisfies this as-is
@@ -37,17 +38,34 @@ type UserSessionContext = {
     userId: string;
     email?: string;
     name?: string;
+    /** Accounts session id (`sid`). Empty when the token carries none. */
     sessionId: string;
-    /** The app the session was issued for. Null for sessions created outside an app context. */
+    /** The app (client id) the token was issued for: the JWT `aud`. */
     appId: string | null;
     tenantId: string | null;
     expiresAt?: string;
+    /** Scopes granted to the token (JWT `scope`). Added 0.12.0. */
+    scopes?: string[];
+    /** How the token was checked. Added 0.12.0. */
+    verifiedBy?: 'jwks' | 'userinfo' | 'legacy-me';
 };
 type UserSessionResolverOptions = {
-    config: Pick<AccountsClientConfig, 'baseUrl'>;
+    /** `baseUrl` is the Accounts origin; `issuer` defaults to it. */
+    config: Pick<AccountsClientConfig, 'baseUrl'> & Partial<Pick<AccountsClientConfig, 'issuer' | 'discovery'>>;
     fetchImpl?: typeof fetch;
-    /** Cache TTL in ms. Default 60_000; 0 disables caching. */
+    /** Cache TTL in ms. Default 60_000; 0 disables caching. Never outlives the token's exp. */
     cacheTtlMs?: number;
+    /**
+     * Accept only tokens issued to these client ids (`aud`). Strongly recommended: without it a
+     * token issued to ANY Nipate app is accepted and the caller must check `appId` itself.
+     */
+    audience?: string | readonly string[];
+    /** Ask userinfo when the JWKS is unreachable. Default true. */
+    remoteFallback?: boolean;
+    /** Check opaque (pre-JWT) bearers via GET /api/auth/me. Default true; turn off once Accounts issues JWTs. */
+    legacySessionTokens?: boolean;
+    /** Extra verifier options (endpoints, clock tolerance, JWKS cache TTL/cooldown, clock). */
+    verifier?: Partial<Omit<AccessTokenVerifierOptions, 'issuer' | 'audience' | 'fetchImpl'>>;
 };
 /** A session bearer is any Authorization: Bearer token that is NOT an `sk_` service key. */
 declare function sessionTokenFromHeaders(carrier: HeaderCarrier): string | null;

package/dist/nest.js

@@ -1,10 +1,12 @@
 import {
+  createAccessTokenVerifier,
   introspectServiceKey,
+  looksLikeJwt,
   normalizeAccountsWebhook,
   scopeSatisfied,
   serviceKeyFromRequest,
   verifyWebhookSignature
-} from "./chunk-TQNQLX3C.js";
+} from "./chunk-F2GDXTY4.js";
 
 // src/nest.ts
 import { createHash } from "crypto";
@@ -60,9 +62,42 @@ function sessionTokenFromHeaders(carrier) {
 function createUserSessionResolver(opts) {
   const ttl = opts.cacheTtlMs ?? 6e4;
   const cache = /* @__PURE__ */ new Map();
-  const fetchImpl = opts.fetchImpl ?? fetch;
-  async function introspect(token) {
-    const base = opts.config.baseUrl?.replace(/\/$/, "");
+  const fetchImpl = opts.fetchImpl ?? ((...args) => fetch(...args));
+  const base = opts.config.baseUrl?.trim().replace(/\/$/, "");
+  const issuer = (opts.config.issuer ?? base)?.trim();
+  const legacy = opts.legacySessionTokens ?? true;
+  let verifier = null;
+  if (issuer) {
+    verifier = createAccessTokenVerifier({
+      discovery: opts.config.discovery,
+      ...opts.verifier,
+      issuer,
+      audience: opts.audience,
+      remoteFallback: opts.remoteFallback ?? true,
+      fetchImpl
+    });
+  }
+  async function viaJwt(token) {
+    if (!verifier) return null;
+    try {
+      const { claims, verifiedBy } = await verifier.verify(token);
+      const aud = Array.isArray(claims.aud) ? claims.aud[0] : claims.aud;
+      return {
+        userId: claims.sub,
+        email: typeof claims.email === "string" ? claims.email : void 0,
+        name: typeof claims.name === "string" ? claims.name : void 0,
+        sessionId: claims.sid ?? "",
+        appId: aud ?? null,
+        tenantId: claims.tid ?? null,
+        expiresAt: new Date(claims.exp * 1e3).toISOString(),
+        scopes: claims.scope ? claims.scope.split(" ").filter(Boolean) : [],
+        verifiedBy
+      };
+    } catch {
+      return null;
+    }
+  }
+  async function viaLegacyMe(token) {
     if (!base || !token) return null;
     try {
       const res = await fetchImpl(new URL("/api/auth/me", base), {
@@ -73,19 +108,27 @@ function createUserSessionResolver(opts) {
       const userId = data.user?.id;
       const sessionId = data.session?.id;
       if (!userId || !sessionId) return null;
+      const appId = data.session?.appId ?? null;
+      const allowed = opts.audience === void 0 ? null : typeof opts.audience === "string" ? [opts.audience] : opts.audience;
+      if (allowed && (!appId || !allowed.includes(appId))) return null;
       return {
         userId,
         email: data.user?.emailAddress ?? data.user?.email,
         name: data.user?.name,
         sessionId,
-        appId: data.session?.appId ?? null,
+        appId,
         tenantId: data.session?.tenantId ?? null,
-        expiresAt: data.session?.expiresAt
+        expiresAt: data.session?.expiresAt,
+        verifiedBy: "legacy-me"
       };
     } catch {
       return null;
     }
   }
+  async function introspect(token) {
+    if (looksLikeJwt(token)) return viaJwt(token);
+    return legacy ? viaLegacyMe(token) : null;
+  }
   async function resolve(carrier) {
     const token = sessionTokenFromHeaders(carrier);
     if (!token) return null;
@@ -94,7 +137,10 @@ function createUserSessionResolver(opts) {
     const cached = ttl > 0 ? cache.get(hash) : void 0;
     if (cached && cached.expires > now) return cached.value;
     const ctx = await introspect(token);
-    if (ttl > 0) cache.set(hash, { value: ctx, expires: now + ttl });
+    if (ttl > 0) {
+      const exp = ctx?.expiresAt ? Date.parse(ctx.expiresAt) : Infinity;
+      cache.set(hash, { value: ctx, expires: Math.min(now + ttl, exp) });
+    }
     return ctx;
   }
   function invalidate(token) {

package/dist/sveltekit.d.ts

@@ -1,6 +1,7 @@
 import { RequestEvent, Handle } from '@sveltejs/kit';
-import { AccountsWebhookEvent, PlatformSession, AccountsClientConfig, ServiceKeyContext, SyncAccountsUser, CookieOptions } from './index.js';
+import { AccountsWebhookEvent, PlatformSession, AccountsClientConfig, ServiceKeyContext, SyncAccountsUser, CookieOptions, OidcClientOptions, OidcClient } from './index.js';
 export { clearPlatformSessionCookie } from './index.js';
+import 'node:crypto';
 
 type SvelteKitAuthOptions = {
     /** Accounts client config (use createAccountsClientConfig()). */
@@ -29,6 +30,23 @@ type SvelteKitAuthOptions = {
      * recommended in production, since the session payload includes tenant memberships.
      */
     sessionSecret?: string;
+    /** OIDC client overrides (issuer, scopes, discovery, endpoints, tokenEndpointAuthMethod…). Added 0.12.0. */
+    oidc?: Partial<OidcClientOptions>;
+    /** A prebuilt client; takes precedence over `config` + `oidc`. Added 0.12.0. */
+    client?: OidcClient;
+    fetchImpl?: typeof fetch;
+    /**
+     * Refresh the Accounts access token when it is within 60s of expiry and the session holds a
+     * refresh token. Default true. A refused refresh (reused/revoked token) logs the session out.
+     */
+    refreshTokens?: boolean;
+    /**
+     * After local sign-out, send the browser to Accounts' `/auth/logout` to end the Accounts session
+     * too (returning to `config.logoutRedirectUri`). Default false: only this app signs out.
+     */
+    endAccountsSession?: boolean;
+    /** Render a failed callback. Default: a plain 400 naming the OidcError code. */
+    onAuthError?: (error: unknown, event: RequestEvent) => Response | Promise<Response>;
 };
 type PlatformLocals = {
     session: PlatformSession;