@relyt/auth 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Relyt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,218 @@
-# Temporary Holding Version
+# @relyt/auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Token tooling for Relyt managed auth:
+
+- server-side JWT verification: `createVerifier` / `verifyToken` (EdDSA only, keys from the auth host's remote JWKS);
+- a token cache for browsers and Node: `createAuthClient`;
+- a Next.js middleware entry: `@relyt/auth/next` (`createAuthMiddleware`, `getClaims`, `setTokenCookie`, `clearTokenCookie`);
+- cross-site social sign-in helpers: `startSocialSignIn` / `completeSocialSignIn` (browser) and `createSocialStart` / `exchangeHandoffCode` (server-side proxy).
+
+The package uses Web APIs only (`fetch`, WebCrypto, `URL`, …), so the main entry runs in browsers, Node and the Next.js edge runtime. Its only runtime dependency is [`jose`](https://github.com/panva/jose).
+
+## Install
+
+```sh
+npm install @relyt/auth
+# or
+pnpm add @relyt/auth
+```
+
+Requirements:
+
+- Node.js 20 or later (the test suite runs on Node 22 and 24; CI also builds and smoke-tests the package on Node 20);
+- ESM only (`"type": "module"`); TypeScript types are included;
+- `next` is an optional peer dependency, needed only for `@relyt/auth/next`. Supported: **`^14.2.35` or `>=15.5.28 <16`**. The test suite runs on Next 15.5.28.
+
+## Verifying tokens on the server
+
+```ts
+import { createVerifier, verifyToken, RelytAuthError } from "@relyt/auth";
+
+const verify = createVerifier({ issuer: "https://<authHost>" });
+
+try {
+  const claims = await verify(token); // RelytClaims: sub, iss, aud, iat, exp, role, app_role, cv, o?, act?
+} catch (e) {
+  if (e instanceof RelytAuthError && e.code === "jwks_unavailable") {
+    // keys could not be fetched: answer 503, not 401
+  }
+  // invalid_token / invalid_claims ⇒ 401
+}
+
+// One-off form: options are resolved on every call; the remote key set is still shared per cache key.
+const claims = await verifyToken(token, { issuer: "https://<authHost>" });
+```
+
+What is fixed and what is configurable:
+
+- `algorithms` is pinned to `["EdDSA"]` and cannot be changed. `alg: none`, HMAC and other algorithms are rejected, and `jku` / `x5u` / embedded `jwk` headers are never followed.
+- `issuer` is the expected value of **both** `iss` and `aud`. It must be exactly an origin (`https://host[:port]`, no trailing slash, no path, nothing URL normalization would rewrite) because the token's `iss` is compared to it verbatim. Plain `http` is accepted only for `localhost`, `127.0.0.1` and `[::1]`.
+- `jwksUrl` defaults to `${issuer}/.well-known/jwks.json`; its origin follows the same rule as `issuer`.
+- `clockToleranceS` defaults to 30 and must be ≤ 60 (after a key rotation, the auth host keeps the retired key in its JWKS for only 60 s beyond the token lifetime).
+- `maxTokenAgeS` defaults to 900. On top of jose's `maxTokenAge` (which bounds the age of `iat`), the SDK also rejects tokens whose issued lifetime `exp − iat` is not in `(0, maxTokenAgeS]`.
+- `cooldownMs` (default 30 000) and `timeoutMs` (default 5 000) control the remote JWKS fetch. The key set is cached per process (keyed by JWKS URL, cooldown and timeout, LRU of 64 entries) and kept for up to 5 minutes; an unknown `kid` triggers an earlier refetch, at most once per cooldown.
+- `onEvent` receives `verify_failed` events (code and issuer only, never the token).
+- Required claims: `exp`, `iat`, `sub`. The payload shape is checked as well (`role` must be `"authenticated"`, `cv` an integer, `o` / `act` well-formed when present); unknown extra claims are preserved.
+
+## Client token cache: `createAuthClient`
+
+```ts
+import { createAuthClient } from "@relyt/auth";
+
+// Cookie mode (same-site app): the browser sends the auth host's session cookie.
+const client = createAuthClient({ authUrl: "https://<authHost>" });
+
+// Bearer mode (cross-site app or Node): you store the session token and provide it.
+let sessionToken: string | null = null;
+const bearerClient = createAuthClient({
+  authUrl: "https://<authHost>",
+  sessionToken: () => sessionToken,
+  onSessionToken: (t) => (sessionToken = t),
+});
+
+const jwt = await client.getToken(); // cached; refreshed `refreshAheadS` (default 120 s) before expiry
+await fetch("/api/todos", { headers: { authorization: `Bearer ${jwt}` } });
+
+client.peekToken(); // cached token if still valid locally, else null (never triggers a request)
+await client.getSession(); // session object, or null when signed out; may prime the token cache
+client.clear(); // sign-out: drops the cache and cancels in-flight refreshes and retry waits
+```
+
+- **The client only carries tokens; it never verifies them.** Trust decisions happen only on the server (`verifyToken` / `getClaims`).
+- Concurrent `getToken()` calls share one request. A result that arrives after `clear()` is never written back to the cache.
+- Retries: only a `503` with a readable `Retry-After` header is retried, at most 3 times, waiting `Retry-After` clamped to [0, 10] s (2 s when the value is invalid). Everything else fails immediately.
+- **Worst-case latency of `getToken()` is 90 s**: at most 4 requests of `timeoutMs` (default 15 s) each, plus 3 backoff waits of at most 10 s (4 × 15 + 3 × 10).
+- `refreshAheadS` must be within [10, 600]; `timeoutMs` must be an integer within [1 000, 60 000].
+
+## Next.js: `@relyt/auth/next`
+
+```ts
+// middleware.ts
+import { createAuthMiddleware } from "@relyt/auth/next";
+export const middleware = createAuthMiddleware({
+  issuer: process.env.RELYT_AUTH_ISSUER!, // "https://<authHost>", from configuration only
+  signInUrl: "/sign-in",
+  publicPaths: ["/sign-in", "/api/public", /^\/_next\//],
+});
+export const config = { matcher: ["/((?!_next/static|favicon.ico).*)"] };
+
+// app/api/x/route.ts
+import { getClaims, RelytAuthUnavailableError } from "@relyt/auth/next";
+export async function GET(req: Request) {
+  try {
+    const c = await getClaims(req, { issuer: process.env.RELYT_AUTH_ISSUER! });
+    if (!c) return new Response(null, { status: 401 });
+    return Response.json({ sub: c.sub });
+  } catch (e) {
+    if (e instanceof RelytAuthUnavailableError) return new Response(null, { status: 503, headers: { "retry-after": "2" } });
+    throw e;
+  }
+}
+```
+
+- **Where the token comes from**: first `Authorization: Bearer`, then the cookie `__Host-relyt-at` (change it with `cookieName`; the middleware, `getClaims` and `setTokenCookie` share the same default). A cookie name that occurs more than once is treated as no token. **A present `Authorization` header is authoritative**: if its value is not a valid `Bearer <token>` (e.g. `Basic …`, or empty), the request has no token and there is no fallback to the cookie. With `cookieOnApi: false`, API paths accept bearer tokens only; the route-side counterpart is `getClaims(req, o, { cookie: false })` (default `true`), which reads `Authorization` only.
+- **Failure behaviour**: API paths (`apiPrefix`, default `/api/`; a prefix ending in `/` also covers the bare path `/api`; or any request whose `Accept` contains `application/json`) get 401 `{"error":"unauthorized"}`, with `WWW-Authenticate: Bearer` when there is no token and `Bearer error="invalid_token"` when the token is invalid. Pages get 307 for GET/HEAD and 303 for other methods, redirecting to `signInUrl?next=<relative path>` (if `next`, once decoded, contains a control character / DEL, starts with `//` or `/\`, contains `\`, or resolves cross-origin, it becomes `/`). When the JWKS is unavailable the answer is 503 `{"error":"auth_unavailable"}` with `Retry-After: 2`.
+- **Claims are never forwarded**: the middleware strips every incoming `x-relyt-*` header and never writes claim headers. Route handlers must call `getClaims` themselves to re-verify (so a route missed by the matcher, or a bypassed middleware, never makes a forged header effective). By default `getClaims` throws `RelytAuthUnavailableError` when the JWKS is unavailable; pass `{ onUnavailable: "null" }` to get `null` instead.
+- **The issuer comes from configuration, not from the request**: `issuer` is taken from the options only, never from `Host` / `X-Forwarded-Host`, and the token's `iss` / `aud` are compared to it verbatim. Only a relative `signInUrl` is resolved against the request URL (affecting just the redirect target's origin). **Use an absolute `signInUrl` in production**: a relative one is resolved against the request's `Host`, so a proxy that passes through a forged `Host` changes the redirect target. 401 / 307 / 303 / 503 responses all carry `Cache-Control: no-store`.
+- **Only the server writes the cookie**: `setTokenCookie(res, token)` writes `HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=min(900, exp − now)` (an already expired token clears the cookie instead). Sign-out must call `clearTokenCookie(res)` on the server (same attributes plus `Max-Age=0`); browser JS cannot clear an HttpOnly cookie. `setTokenCookie` throws `RelytAuthError("config")` if the serialized cookie exceeds 4000 bytes (browsers silently drop oversized cookies).
+- **The `__Host-` prefix requires `Secure`**: Safari refuses `__Host-` / `Secure` cookies on `http://localhost`, so develop locally over https, or use Chrome / Firefox.
+- **CSRF**: cookie-authenticated APIs have a CSRF surface (`SameSite=Lax` blocks cross-site POSTs, but not same-site subdomains or side-effecting GETs). **Use bearer tokens for APIs and the cookie only for page navigation**; set `cookieOnApi: false` where needed.
+- **Tokens without `kid`**: while the JWKS holds two keys (rotation overlap), a token without a `kid` header cannot select a key and is always rejected (401 / `null`).
+- **Known limitation**: on a cold auth host (one that has not yet loaded the tenant's configuration), a busy / cold-read failure makes the CORS preflight of a non-simple cross-origin request itself return 503. The browser only sees a `TypeError` and cannot read `Retry-After`. By design the client does not retry network errors and fails immediately; in cookie mode the public 503 of the auth routes is likewise unreadable. Non-browser callers are not affected.
+
+## Cross-site social sign-in: `startSocialSignIn` / `completeSocialSignIn`
+
+When the app and the auth host are on different sites, social sign-in uses "auth host start endpoint + single-use handoff code + PKCE exchange" and does not rely on cross-site cookies.
+
+```ts
+import { createAuthClient, startSocialSignIn, completeSocialSignIn } from "@relyt/auth";
+
+// Sign-in button: generates a PKCE verifier, stores it in sessionStorage, navigates the top-level window to the auth host
+await startSocialSignIn({ authUrl, provider: "google", callbackURL: "https://app.example.com/auth/callback" });
+
+// Callback page https://app.example.com/auth/callback
+let sessionToken: string | null = null;
+const client = createAuthClient({ authUrl, sessionToken: () => sessionToken, onSessionToken: (t) => (sessionToken = t) });
+try {
+  await completeSocialSignIn({ authUrl, client, onSessionToken: (t) => (sessionToken = t) });
+} catch (e) {
+  // RelytAuthError: oauth_error (e.oauthError) / no_pending_sign_in / missing_code /
+  // invalid_handoff_code / invalid_origin / rate_limited (e.retryAfterS) / unavailable / network / bad_response
+}
+```
+
+- `responseMode` defaults to `"fragment"` (the code arrives as `#relyt_code=` and never reaches server logs or the Referer); with `"query"` it arrives as `?relyt_code=`.
+- The very first thing `completeSocialSignIn` does is remove `relyt_code` / `error` from the address bar with `history.replaceState`. The verifier is taken out once and deleted. If this tab has no pending sign-in record, it **never exchanges** the code (defending against planted codes) and throws `no_pending_sign_in`.
+- The exchange is not retried: a code is valid for 60 s, single use, and invalidated on submission. After a failure, let the user click sign-in again.
+- `completeSocialSignIn` is re-entrant: calling it again while one call is in progress (React StrictMode's double effect) returns the same promise, so the code is exchanged once and `onSessionToken` is called once. The pending record is bound to `authUrl` and valid for 10 minutes; a mismatched or expired record is handled as `no_pending_sign_in`.
+- `e.retryAfterS` on `rate_limited` uses the same parser as `createAuthClient`: clamped to ≤ 10 s, 2 when the value is invalid, `undefined` when there is no `Retry-After` header.
+- Server-side proxy (Node / Next route handler, query mode): start with the pure builder `createSocialStart` (touches neither sessionStorage nor location, works in browsers and Node) and exchange with `exchangeHandoffCode({ authUrl, code, codeVerifier })`, which returns `{ sessionToken }` and sends no Origin. Your server keeps the verifier and binds it to the initiating user's own session:
+
+  ```ts
+  // GET /login/google (server)
+  const { url, codeVerifier } = await createSocialStart({ authUrl, provider: "google", callbackURL: "https://app.example.com/auth/callback", responseMode: "query" });
+  session.relytVerifier = codeVerifier;           // store in your own server-side session (bound to an HttpOnly cookie); never log it
+  return Response.redirect(url, 302);
+
+  // GET /auth/callback?relyt_code=… (server)
+  const v = session.relytVerifier; delete session.relytVerifier;   // single use
+  const { sessionToken } = await exchangeHandoffCode({ authUrl, code, codeVerifier: v });
+  ```
+  The auth host rate-limits failed exchanges per source IP (10 per 60 s). In proxy mode all users share your server's egress IP, so one user's failures eat into everyone's budget.
+
+### Callback page rules
+
+These are a security boundary: PKCE cannot stop a flow that the attacker started themselves; the defence is the integrity of the callback page.
+
+1. Call `completeSocialSignIn` **before loading any third-party script** (analytics, ads, chat widgets and the like all go after it).
+2. The callback page **must not do an HTTP redirect** before the code has been read, and must not contain an open redirect (a fragment is carried along or lost on redirect).
+3. Register the **exact** callback URLs in the console (`callbackURL` / `errorCallbackURL` / `newUserCallbackURL` are matched verbatim, no wildcards), and add the app's **exact origin** (e.g. `https://app.example.com`) to `trustedOrigins`, without wildcards. If the origin is not registered, the CORS preflight of the exchange request fails in the browser and the SDK can only report `network` (it cannot read the 403, so it will not be `invalid_origin`); when troubleshooting, check `trustedOrigins` first. `invalid_origin` only appears for non-browser callers that send their own `Origin` header.
+4. In query mode the code appears in the access logs of the server hosting the callback page; use it only when the exchange must be proxied by your server. Add `<meta name="referrer" content="no-referrer">` to the callback page so the code is not sent in the Referer to other resources on the page.
+5. **Every page that can receive the redirect back** (`callbackURL`, `newUserCallbackURL`, `errorCallbackURL`) must call `completeSocialSignIn`; otherwise the code or the error stays in the address bar and the pending record is never consumed.
+6. The page that starts the sign-in and the callback page must have **exactly the same origin** (`www.example.com` and `example.com` differ): the verifier lives in sessionStorage, which is isolated per origin, so after an origin change it cannot be read and the result is `no_pending_sign_in`.
+
+## Errors
+
+Every failure is a `RelytAuthError` with a stable `code`, a `retryable` flag and a fixed English `message`. Messages never include tokens, response bodies or URL query strings.
+
+| `code` | Meaning | `retryable` by default | Extra fields |
+|---|---|---|---|
+| `unauthenticated` | not signed in (401 / 403 from the auth host, or the session-token provider failed) | no | `status` |
+| `unavailable` | auth service unavailable (503) | yes (no when `Retry-After` is missing or after a failed exchange) | `status` |
+| `network` | network error or timeout | yes (no for the social exchange) | |
+| `bad_response` | unexpected response from the auth host | no | `status` |
+| `invalid_token` | signature, algorithm, issuer, audience or time check failed | no | |
+| `invalid_claims` | payload shape is invalid | no | |
+| `jwks_unavailable` | signing keys could not be fetched | yes | |
+| `config` | invalid option | no | `option` (option name only, never the value) |
+| `invalid_handoff_code` | invalid or expired sign-in code (400) | no | `status` |
+| `invalid_origin` | origin not trusted by the auth host (403, non-browser callers only) | no | `status` |
+| `rate_limited` | too many requests (429) | no | `status`, `retryAfterS` |
+| `no_pending_sign_in` | no pending sign-in in this browser session | no | |
+| `missing_code` | sign-in code missing from the callback URL | no | |
+| `oauth_error` | the social provider reported an error | no | `oauthError` (filtered to `^[a-z0-9_]{1,64}$`, otherwise `"unknown"`) |
+
+`@relyt/auth/next` additionally exports `RelytAuthUnavailableError` (a `RelytAuthError` with code `jwks_unavailable`), thrown by `getClaims` so route handlers can answer 503.
+
+## Security notes
+
+- Tokens, session tokens, handoff codes, PKCE verifiers and cookie values never appear in errors, events or logs. The SDK itself never calls `console`.
+- The issuer always comes from configuration; it is never derived from the token or the request.
+- Verification fails closed: any error the SDK does not recognise becomes `invalid_token`.
+- Report security issues privately through [GitHub security advisories](https://github.com/relytcloud/relyt-auth-js/security/advisories/new) rather than public issues.
+
+## Development
+
+This repository uses **pnpm** (version pinned in `packageManager`; enable it with `corepack enable`).
+
+```sh
+pnpm install
+pnpm run typecheck
+pnpm test          # builds dist/ first, then runs vitest (Node 22 or 24)
+pnpm run build
+npm pack --dry-run # inspect the published file list
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/claims.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Token payload type. Mirrors the claim set issued by the Relyt auth service; if the service adds or renames a
+ * claim, update `CLAIM_KEYS` and `checkClaimsShape` in this file together.
+ */
+export interface RelytClaims {
+    sub: string;
+    iss: string;
+    aud: string | string[];
+    iat: number;
+    exp: number;
+    nbf?: number;
+    role: "authenticated";
+    app_role: string | null;
+    cv: number;
+    o?: {
+        id: string;
+        slug: string;
+        role: string;
+        perms: string[] | null;
+    };
+    act?: {
+        sub: string;
+    };
+    /** Forward compatible: unknown extra claims are preserved as-is. */
+    [extra: string]: unknown;
+}
+export declare const CLAIM_KEYS: readonly ["role", "app_role", "o", "cv", "act"];
+export declare const REGISTERED_CLAIM_KEYS: readonly ["sub", "iss", "aud", "exp", "iat"];
+/** Payload shape check only. Time and issuer checks are done by jose plus the post-checks in verify.ts. */
+export declare function checkClaimsShape(p: Record<string, unknown>): boolean;

package/dist/claims.js

@@ -0,0 +1,27 @@
+export const CLAIM_KEYS = ["role", "app_role", "o", "cv", "act"];
+export const REGISTERED_CLAIM_KEYS = ["sub", "iss", "aud", "exp", "iat"];
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isStr = (v) => typeof v === "string";
+/** Payload shape check only. Time and issuer checks are done by jose plus the post-checks in verify.ts. */
+export function checkClaimsShape(p) {
+    if (!isStr(p.sub))
+        return false;
+    if (p.role !== "authenticated")
+        return false;
+    if (!(p.app_role === null || isStr(p.app_role)))
+        return false;
+    if (!Number.isInteger(p.cv))
+        return false;
+    if (p.o !== undefined) {
+        const o = p.o;
+        if (!isObj(o) || !isStr(o.id) || !isStr(o.slug) || !isStr(o.role))
+            return false;
+        if (!(o.perms === null || (Array.isArray(o.perms) && o.perms.every(isStr))))
+            return false;
+    }
+    if (p.act !== undefined) {
+        if (!isObj(p.act) || !isStr(p.act.sub))
+            return false;
+    }
+    return true;
+}

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+import { type AuthEvent } from "./errors.js";
+export interface AuthClientOptions {
+    /** `https://<authHost>`: no trailing slash, no path (same rule as the issuer). */
+    authUrl: string;
+    /** Set ⇒ bearer mode (`Authorization: Bearer`, `credentials: "omit"`); unset ⇒ cookie mode. */
+    sessionToken?: () => string | null | Promise<string | null>;
+    /** Called when the response carries a `set-auth-token` header. */
+    onSessionToken?: (t: string) => void;
+    /** Refresh lead time in seconds; default 120, must be within [10, 600]. */
+    refreshAheadS?: number;
+    fetch?: typeof fetch;
+    /** Per-request timeout in integer milliseconds; default 15_000, must be within [1_000, 60_000]. A timeout counts as `network` and is not retried. */
+    timeoutMs?: number;
+    onEvent?: (e: AuthEvent) => void;
+}
+export interface AuthClient {
+    getToken(): Promise<string>;
+    peekToken(): string | null;
+    getSession(): Promise<unknown | null>;
+    clear(): void;
+}
+/** Retry-After → milliseconds: integer seconds or IMF-fixdate (relative to the local clock), clamped to [0, 10] s; invalid ⇒ 2 s. */
+export declare function retryAfterMs(raw: string): number;
+export declare function createAuthClient(o: AuthClientOptions): AuthClient;

package/dist/client.js

@@ -0,0 +1,243 @@
+// Client-side token cache. Uses Web APIs only (browser / Node / edge runtime).
+// The client only carries tokens, it never trusts them: no signature check here; verification happens server-side in verifyToken.
+import { TOKEN_TTL_S } from "./constants.js";
+import { RelytAuthError } from "./errors.js";
+import { normalizeIssuer } from "./issuer.js";
+import { decodePayloadUnverified } from "./jwt-payload.js";
+import { num } from "./options.js";
+/** Retry only on "503 with a readable Retry-After", at most 3 retries (4 requests in total). */
+const MAX_RETRIES = 3;
+const RA_MAX_S = 10;
+const RA_INVALID_S = 2;
+const IMF_FIXDATE = /^[A-Za-z]{3}, \d{2} [A-Za-z]{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+/** Sentinel used when racing the session-token provider against the timeout (only ever resolves, never rejects, so no unhandled rejection). */
+const ABORTED = Symbol("aborted");
+/** Provider threw / produced an invalid header value: no `cause`, so the original TypeError message cannot leak the session token. */
+const unauth = () => new RelytAuthError("unauthenticated", { retryable: false });
+/** Retry-After → milliseconds: integer seconds or IMF-fixdate (relative to the local clock), clamped to [0, 10] s; invalid ⇒ 2 s. */
+export function retryAfterMs(raw) {
+    const s = raw.trim();
+    let sec;
+    if (/^\d+$/.test(s))
+        sec = Number(s);
+    else if (IMF_FIXDATE.test(s) && !Number.isNaN(Date.parse(s)))
+        sec = (Date.parse(s) - Date.now()) / 1000;
+    else
+        sec = RA_INVALID_S;
+    return Math.round(Math.min(RA_MAX_S, Math.max(0, sec)) * 1000);
+}
+/** Returns `exp − iat` in seconds; undecodable or outside (0, TOKEN_TTL_S] ⇒ null (reported as bad_response, never cached). */
+function lifetimeS(token) {
+    if (typeof token !== "string")
+        return null;
+    const payload = decodePayloadUnverified(token);
+    if (payload === null)
+        return null;
+    const { iat, exp } = payload;
+    if (typeof iat !== "number" || typeof exp !== "number")
+        return null;
+    const d = exp - iat;
+    return Number.isFinite(d) && d > 0 && d <= TOKEN_TTL_S ? d : null;
+}
+export function createAuthClient(o) {
+    if (typeof o !== "object" || o === null)
+        throw new RelytAuthError("config", { option: "authUrl" });
+    let base;
+    try {
+        base = normalizeIssuer(o.authUrl);
+    }
+    catch {
+        throw new RelytAuthError("config", { option: "authUrl" });
+    }
+    const refreshAheadMs = num(o.refreshAheadS, 120, "refreshAheadS", (n) => n >= 10 && n <= 600) * 1000;
+    const timeoutMs = num(o.timeoutMs, 15_000, "timeoutMs", (n) => Number.isInteger(n) && n >= 1_000 && n <= 60_000);
+    const doFetch = o.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    let cache = null;
+    let inflight = null;
+    let gen = 0;
+    /** One per generation: aborted by clear() to cancel pending backoff waits. */
+    let genAc = new AbortController();
+    const emit = (e) => {
+        try {
+            o.onEvent?.(e);
+        }
+        catch {
+            /* a throwing callback must not affect token retrieval */
+        }
+    };
+    /** Generation-guarded write: results of a generation that predates clear() are never stored. */
+    const store = (g, token, d, receivedAt) => {
+        if (g === gen)
+            cache = { token, expiresAtLocal: receivedAt + d * 1000 };
+    };
+    /**
+     * Sends one request and reads the whole body. The timeout uses AbortController + setTimeout, equivalent to
+     * `AbortSignal.timeout(timeoutMs)` but clearable on completion; any rejection (including timeout / TypeError) ⇒ network, no retry.
+     */
+    async function request(path) {
+        // Start the timer first: the time spent in sessionToken() counts towards timeoutMs.
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), timeoutMs);
+        try {
+            const headers = new Headers();
+            let credentials = "include";
+            if (o.sessionToken) {
+                credentials = "omit";
+                const provider = o.sessionToken;
+                const aborted = new Promise((r) => ac.signal.addEventListener("abort", () => r(ABORTED), { once: true }));
+                let st;
+                try {
+                    st = await Promise.race([Promise.resolve().then(() => provider()), aborted]);
+                }
+                catch {
+                    throw unauth();
+                }
+                if (st === ABORTED)
+                    throw new RelytAuthError("network");
+                if (typeof st === "string" && st !== "") {
+                    try {
+                        headers.set("authorization", `Bearer ${st}`);
+                    }
+                    catch {
+                        throw unauth();
+                    }
+                }
+            }
+            try {
+                const res = await doFetch(`${base}${path}`, { method: "GET", headers, credentials, signal: ac.signal });
+                const receivedAt = Date.now();
+                const body = await res.text();
+                return { res, body, receivedAt };
+            }
+            catch {
+                throw new RelytAuthError("network");
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Backoff wait; an abort triggered by clear() clears the timer and rejects with unauthenticated. */
+    const sleep = (ms, signal) => new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(unauth());
+        const onAbort = () => {
+            clearTimeout(t);
+            reject(unauth());
+        };
+        const t = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    async function refresh(g) {
+        const signal = genAc.signal;
+        for (let attempt = 0;; attempt++) {
+            if (g !== gen)
+                throw new RelytAuthError("unauthenticated", { retryable: false });
+            const { res, body, receivedAt } = await request("/api/auth/token");
+            if (res.status === 200) {
+                let token;
+                try {
+                    token = JSON.parse(body)?.token;
+                }
+                catch {
+                    token = undefined;
+                }
+                const d = lifetimeS(token);
+                if (d === null) {
+                    emit({ type: "token_refresh", code: "bad_response", status: 200, attempt });
+                    throw new RelytAuthError("bad_response", { status: 200 });
+                }
+                store(g, token, d, receivedAt);
+                emit({ type: "token_refresh", status: 200, attempt });
+                return token;
+            }
+            if (res.status === 401 || res.status === 403) {
+                if (g === gen)
+                    cache = null;
+                emit({ type: "token_refresh", code: "unauthenticated", status: res.status, attempt });
+                throw new RelytAuthError("unauthenticated", { status: res.status });
+            }
+            if (res.status === 503) {
+                // Decided by the response header only, never by the body code. If CORS hides the header, get() is null ⇒ no retry.
+                const ra = res.headers.get("retry-after");
+                if (ra !== null && attempt < MAX_RETRIES) {
+                    if (g !== gen)
+                        throw unauth();
+                    emit({ type: "retry", status: 503, attempt: attempt + 1 });
+                    await sleep(retryAfterMs(ra), signal);
+                    continue;
+                }
+                emit({ type: "token_refresh", code: "unavailable", status: 503, attempt });
+                throw new RelytAuthError("unavailable", { status: 503, retryable: ra !== null });
+            }
+            emit({ type: "token_refresh", code: "bad_response", status: res.status, attempt });
+            throw new RelytAuthError("bad_response", { status: res.status, retryable: false });
+        }
+    }
+    return {
+        getToken() {
+            if (cache && cache.expiresAtLocal - Date.now() > refreshAheadMs)
+                return Promise.resolve(cache.token);
+            if (inflight)
+                return inflight;
+            const p = refresh(gen).finally(() => {
+                if (inflight === p)
+                    inflight = null;
+            });
+            inflight = p;
+            return p;
+        },
+        peekToken() {
+            return cache && cache.expiresAtLocal > Date.now() ? cache.token : null;
+        },
+        async getSession() {
+            const g = gen;
+            const { res, body, receivedAt } = await request("/api/auth/get-session");
+            if (res.status === 401 || res.status === 403) {
+                if (g === gen)
+                    cache = null;
+                return null;
+            }
+            if (res.status === 503)
+                throw new RelytAuthError("unavailable", { status: 503, retryable: res.headers.get("retry-after") !== null });
+            if (res.status !== 200)
+                throw new RelytAuthError("bad_response", { status: res.status, retryable: false });
+            let data;
+            try {
+                data = JSON.parse(body);
+            }
+            catch {
+                throw new RelytAuthError("bad_response", { status: 200 });
+            }
+            const st = res.headers.get("set-auth-token");
+            if (g === gen && st !== null && st !== "" && o.onSessionToken) {
+                try {
+                    o.onSessionToken(st);
+                }
+                catch {
+                    /* a throwing application callback must not affect the result */
+                }
+            }
+            if (data === null) {
+                if (g === gen)
+                    cache = null;
+                return null;
+            }
+            const jwt = res.headers.get("set-auth-jwt");
+            const d = lifetimeS(jwt);
+            if (jwt !== null && d !== null)
+                store(g, jwt, d, receivedAt);
+            return data;
+        },
+        clear() {
+            cache = null;
+            inflight = null;
+            gen += 1;
+            genAc.abort();
+            genAc = new AbortController();
+        },
+    };
+}

package/dist/constants.d.ts

@@ -0,0 +1,4 @@
+/** Upper bound of a token's issued lifetime in seconds: default `maxTokenAgeS` for verification and the client's `exp − iat` upper bound. */
+export declare const TOKEN_TTL_S = 900;
+/** Upper bound of the clock tolerance in seconds: how long the auth service keeps a retired key in its JWKS after rotation, beyond the token TTL. */
+export declare const MAX_CLOCK_TOLERANCE_S = 60;

package/dist/constants.js

@@ -0,0 +1,5 @@
+// Duration constants that must match the Relyt auth service (copied; see test/package.test.ts).
+/** Upper bound of a token's issued lifetime in seconds: default `maxTokenAgeS` for verification and the client's `exp − iat` upper bound. */
+export const TOKEN_TTL_S = 900;
+/** Upper bound of the clock tolerance in seconds: how long the auth service keeps a retired key in its JWKS after rotation, beyond the token TTL. */
+export const MAX_CLOCK_TOLERANCE_S = 60;

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+/** Unified SDK error. `message` is a fixed English phrase per code and never includes tokens, response bodies or URL query strings. */
+export type RelytAuthErrorCode = "unauthenticated" | "unavailable" | "network" | "bad_response" | "invalid_token" | "invalid_claims" | "jwks_unavailable" | "config" | "invalid_handoff_code" | "invalid_origin" | "rate_limited" | "no_pending_sign_in" | "missing_code" | "oauth_error";
+export declare class RelytAuthError extends Error {
+    readonly code: RelytAuthErrorCode;
+    readonly retryable: boolean;
+    readonly status?: number;
+    /** `config` only: name of the offending option (option names are not secret). */
+    readonly option?: string;
+    /** `rate_limited` only: integer seconds from the `retry-after` response header (when present and valid). */
+    readonly retryAfterS?: number;
+    /** `oauth_error` only: the `error` value from the callback URL, filtered by `^[a-z0-9_]{1,64}$`, otherwise `"unknown"`. */
+    readonly oauthError?: string;
+    constructor(code: RelytAuthErrorCode, o?: {
+        retryable?: boolean;
+        status?: number;
+        option?: string;
+        retryAfterS?: number;
+        oauthError?: string;
+    });
+}
+/** Event payload: codes and counters only, never a token. */
+export type AuthEvent = {
+    type: "token_refresh" | "retry" | "verify_failed" | "jwks_fetch";
+    code?: string;
+    status?: number;
+    attempt?: number;
+    kid?: string;
+    issuer?: string;
+};