@passflow/node 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MadAppGang Pty Ltd
+
+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,180 @@
-# Temporary Holding Version
+# @passflow/node
 
-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.
+Protect your own API with Passflow tokens. One import and one middleware call give you token verification, an authentication-level floor, a freshness requirement, and the exact RFC 9470 challenge the Passflow browser SDK needs to run a step-up.
+
+Requires Node.js 22.12 or newer, and Express, Fastify and Hono are optional peers, so you install only the framework you use.
+
+```bash
+npm install @passflow/node
+```
+
+```js
+import { AAL2, createVerifier } from '@passflow/node';
+import { getAuth, passflowExpress } from '@passflow/node/express';
+import express from 'express';
+
+const verifier = createVerifier({ issuer: 'https://auth.example.com', audience: '7f3a9c21d4b8e6' });
+const passflow = passflowExpress(verifier);
+
+const app = express();
+app.get('/invoices', passflow.requireACR(AAL2), (req, res) => res.json({ sub: getAuth(req).sub }));
+app.post('/transfers', passflow.requireFresh(300), (_req, res) => res.json({ ok: true }));
+```
+
+`audience` is the ID of a Passflow application, or a list of them. The Passflow documentation has step-by-step tutorials for Express, Fastify and Hono (`docs/tutorials/node-backend.md`) and a runnable API in `examples/resource-server`.
+
+## Use it with a framework
+
+### Express
+
+`passflowExpress(verifier)` returns `authenticate`, `requireACR(min)` and `requireFresh(seconds)`, and the last two work alone without `authenticate` in front. Claims live on `req.passflow`, which `getAuth(req)` reads, and that name cannot collide with the global `auth` type that `express-jwt` declares.
+
+```js
+app.get('/me', passflow.authenticate, (req, res) => res.json({ sub: getAuth(req).sub }));
+```
+
+### Fastify
+
+Register the plugin once per instance, because it only decorates: routes opt in one at a time and public routes are untouched.
+
+```js
+import { AAL2, createVerifier } from '@passflow/node';
+import { getAuth, passflowFastify } from '@passflow/node/fastify';
+import Fastify from 'fastify';
+
+const verifier = createVerifier({ issuer: 'https://auth.example.com', audience: '7f3a9c21d4b8e6' });
+
+const app = Fastify();
+await app.register(passflowFastify, { verifier });
+
+app.get('/invoices', { preHandler: app.passflow.requireACR(AAL2) }, async (request) => ({
+  subject: getAuth(request).sub,
+}));
+```
+
+A second registration throws Fastify's own `FST_ERR_DEC_ALREADY_PRESENT`, so use `createFastifyHooks(verifier)` for every further verifier. It returns the same three hooks with no plugin and no decoration.
+
+### Hono
+
+`@passflow/node` and `@passflow/node/hono` import no Node built-ins, so they run on any runtime with WebCrypto and `fetch`.
+
+```js
+import { AAL2, createVerifier } from '@passflow/node';
+import { getAuth, passflowHono } from '@passflow/node/hono';
+import { Hono } from 'hono';
+
+const passflow = passflowHono(createVerifier({ issuer: 'https://auth.example.com', audience: '7f3a9c21d4b8e6' }));
+const app = new Hono();
+
+app.get('/invoices', passflow.requireACR(AAL2), (c) => c.json({ subject: getAuth(c).sub }));
+```
+
+## Responses and CORS
+
+| Situation | Status | `WWW-Authenticate` |
+|---|---|---|
+| No token, or not a `Bearer` token | 401 | `Bearer` |
+| Invalid or expired token | 401 | `Bearer error="invalid_token"` |
+| Token below the required level | 401 | `Bearer error="insufficient_user_authentication", acr_values="2"` |
+| Authentication too old | 401 | `Bearer error="insufficient_user_authentication", max_age=300` |
+| Key set unavailable | 503 | none |
+
+Every rejection has `Cache-Control: no-store` and an empty body, and the middleware writes it directly, so your own error handler cannot drop the challenge. The browser SDK acts only on the step-up challenge, and the library never sends one for an authentication failure. Nothing from the token, the request or the key set URL appears in any error or response, and the package writes no logs.
+
+A browser hides `WWW-Authenticate` from a cross-origin page unless the response names it in `Access-Control-Expose-Headers`. The SDK then sees a bare 401 and cannot start the step-up, and a `*` entry does not cover the header on a credentialed request.
+
+Each adapter exports `exposeChallengeHeader`, which adds the header to your CORS options and keeps the entries you already have, under the option name that framework's middleware uses: `exposedHeaders` for `cors` and `@fastify/cors`, `exposeHeaders` for `hono/cors`.
+
+```js
+import { exposeChallengeHeader } from '@passflow/node/express';
+import cors from 'cors';
+
+app.use(cors(exposeChallengeHeader({ origin: 'https://app.example.com', credentials: true })));
+```
+
+`CHALLENGE_HEADER` and `CORS_EXPOSED_HEADERS` are exported if you build the list yourself.
+
+## Claims, configuration and composition
+
+### Reading the claims
+
+`getAuth(req)` throws `PassflowUsageError` when no Passflow middleware ran, which your framework turns into a 500.
+
+```ts
+type PassflowClaims = {
+  sub: string; iss: string; aud: string[]; exp: number; iat?: number;
+  authTime?: number;   // whole Unix seconds; absent when the claim is absent, not a number or beyond ±2^53
+  acr: string;         // '0' when the claim is absent or not a string
+  amr: string[]; scopes: string[]; sid?: string; type: string;
+  tenants: Record<string, TenantMembership>;
+  verifiedAt: number;  // the verifier's clock at verification, in Unix seconds
+  raw: Record<string, unknown>;
+};
+```
+
+`rolesOf(claims, tenantId)` returns the roles of the tenant's root group. Compare levels with `acrSatisfies(acr, min)`, which is exact over the whole 64-bit range and never satisfied by a required level that parses to 0. `acrLevel(acr)` returns a `number` for display only. It is exact up to 2^53, and the library never decides with it.
+
+### Configuration
+
+```js
+createVerifier({
+  issuer: 'https://auth.example.com',       // required, exact match
+  audience: ['7f3a9c21d4b8e6', 'b81e4d07a39c52'], // required: a string or a list; the token must name at least one
+  jwksUrl: 'https://auth.example.com/.well-known/jwks.json', // this is the default; OIDC discovery is not fetched
+  allowInsecureJwksUrl: false, // https is required except on loopback hosts, unless this is set
+  leewaySeconds: 30,           // exp and nbf only
+  tokenTypes: ['access'],
+  now: () => new Date(),
+  jwks: {
+    maxAge: 600000,            // ms; a set older than this keeps answering while it reloads in the background
+    minRefreshInterval: 30000, // ms; at most one attempt per interval for a background reload, after a failure or for an unknown kid
+    maxStale: 3600000,         // ms; how long after the last successful fetch a stale set is trusted
+    maxBytes: 1048576,         // response body cap
+    timeout: 5000,             // ms, an integer up to 2147483647
+    fetch,                     // replaces the global fetch, for proxies
+  },
+});
+```
+
+An invalid configuration throws `TypeError` naming the option, at startup. `requireACR('gold')` throws too, because 'gold' has no level above 0. A freshness limit must truncate to a whole number of seconds from 1 to `Number.MAX_SAFE_INTEGER`. Leaving a `jwks` option out gives the default. An explicit `0` is a value: `maxAge: 0` starts a background reload on every verification, gated by `minRefreshInterval`, and `minRefreshInterval: 0` removes the gate, both legal and both discouraged. `maxBytes: 0`, `maxStale: 0` and `timeout: 0` throw.
+
+Build one verifier per trust policy, at startup, because each owns a key cache.
+
+### Stacking verifiers
+
+An adapter's `authenticate` always verifies the presented token and replaces any claims on the request. `requireACR` and `requireFresh` act on existing claims only when their own verifier produced that exact object. Otherwise they verify the presented token themselves. A broad verifier upstream therefore cannot let a token outside a route's issuer, audiences or token types through on its level alone:
+
+```js
+app.use(broad.authenticate);
+app.get('/restricted', narrow.requireACR('2'), handler);
+```
+
+A token outside `narrow`'s policy gets `invalid_token`, never a step-up. The identity rule is strict: two verifiers built from the same configuration re-verify each other's claims, and so does a spread or cloned claims object. A wrapper object that delegates to `verifier.verify` is a different identity for the same reason, and each case costs one more signature check and never a bypass. Keep one verifier per trust policy, and put the narrowest verifier's method directly on the route.
+
+In Fastify, the broad hook goes on an encapsulated scope and the narrow one on the route:
+
+```js
+await app.register(async (scope) => {
+  scope.addHook('preHandler', scope.passflow.authenticate);
+  scope.get('/restricted', { preHandler: createFastifyHooks(narrowVerifier).requireACR('2') }, handler);
+});
+```
+
+## Key set behaviour
+
+The key set is fetched and cached by this package, with the same rules and defaults as the Go library `github.com/madappgang/passflow-go/auth`, though the Go options are `time.Duration` values and these are milliseconds.
+
+- A token's key is looked up by `kid` and the key type its algorithm requires. An unknown `kid` causes at most one refetch per `minRefreshInterval`, and a bad signature never causes one. The request with the unknown `kid` waits for that refetch, or joins one already running, and one verification never makes two fetches.
+- A set older than `maxAge` answers immediately and starts a background reload, unless one is running or `minRefreshInterval` has not passed since the last attempt. A request waits for a reload only when there is no set, or the set is past `maxStale`.
+- A reload counts only when all of it succeeds: status 200, a body within `maxBytes`, a JSON key set, and every usable key imported and checked. A usable key must be public, with no private member, RSA of at least 2048 bits with an odd exponent from 3 to 2^31 - 1, or P-256. Each key member must be canonical unpadded base64url. A key that carries private material fails the reload.
+- Anything short of a full success is one failed attempt, and a working set stays in place.
+- While reloads fail, a stale set is trusted until `maxStale` after the last successful fetch. Then every request gets a 503 until a reload succeeds.
+- A 503 never carries a challenge. A key rotation during an outage therefore does not look like a bad token.
+
+**Serverless and edge runtimes.** A runtime that freezes or cancels work after a response may never finish a background reload. The set is then refreshed by the waiting path once it is past `maxStale`, or by an unknown `kid`.
+
+**Rotation window.** A token signed by a key published less than `minRefreshInterval` after the previous fetch attempt is rejected as `key_unknown` until the gate opens, at most 30 seconds per instance with the defaults. Passflow signs with one key today, so only a deployment that rotates keys needs to call `await verifier.refresh()` from its rotation hook. It ignores the gate and reloads from a fetch that starts after the call, waiting out any fetch already running, so its success proves the set is newer than the call. It can therefore take up to twice `timeout`.
+
+## License
+
+Released under the MIT license, which is separate from the Passflow server's license.

package/dist/claims-BHJhnzch.d.cts

@@ -0,0 +1,51 @@
+/** The `passflow_tm` wire shape, camelCased. `tenantRoles` is decoded for raw access; `rolesOf` does not read it. */
+type TenantMembership = {
+  tenantId: string;
+  tenantName?: string;
+  tenantRoles?: string[];
+  rootGroupId?: string;
+  groups?: Record<string, string[]>;
+  groupNames?: Record<string, string>;
+};
+type PassflowClaims = {
+  sub: string;
+  iss: string;
+  aud: string[];
+  exp: number;
+  iat?: number;
+  /** Whole Unix seconds. Absent when the claim is absent, not a number or beyond ±2^53. */
+  authTime?: number;
+  /** `'0'` when the claim is absent or not a string. */
+  acr: string;
+  amr: string[];
+  scopes: string[];
+  sid?: string;
+  type: string;
+  tenants: Record<string, TenantMembership>;
+  /** The verifier's clock at verification, in Unix seconds. `requireFresh` measures from it. */
+  verifiedAt: number;
+  raw: Record<string, unknown>;
+};
+/**
+ * The structural part of a verifier. Declared here, with `verifiedBy`, so that provenance needs nothing
+ * from the verifier module.
+ */
+interface Verifier {
+  verify(token: string): Promise<PassflowClaims>;
+  refresh(): Promise<void>;
+}
+/**
+ * True only for the exact object `verifier.verify` returned. A spread or clone loses provenance, which
+ * costs one more verification and never a bypass. So does any wrapper or decorator object that delegates
+ * to `verifier.verify`: it is a different identity, and this verifier's adapter re-verifies claims it
+ * returns. Two verifiers built from the same configuration are different identities too.
+ */
+declare function verifiedBy(claims: PassflowClaims, verifier: Verifier): boolean;
+/**
+ * The roles a user holds in a tenant: `groups[rootGroupId]`, the rule the server's `CalcTenantRoles` and
+ * `@passflow/core`'s `parseMembership` apply. A missing tenant, root group or map gives an empty list.
+ * So does an empty `rootGroupId`, unlike the server: no role is granted from a group keyed by "".
+ * `tenantRoles` is a copy the server derives from the same root group, and is not consulted.
+ */
+declare function rolesOf(claims: PassflowClaims, tenantId: string): string[];
+export { verifiedBy as a, rolesOf as i, TenantMembership as n, Verifier as r, PassflowClaims as t };

package/dist/claims-BHJhnzch.d.mts

@@ -0,0 +1,51 @@
+/** The `passflow_tm` wire shape, camelCased. `tenantRoles` is decoded for raw access; `rolesOf` does not read it. */
+type TenantMembership = {
+  tenantId: string;
+  tenantName?: string;
+  tenantRoles?: string[];
+  rootGroupId?: string;
+  groups?: Record<string, string[]>;
+  groupNames?: Record<string, string>;
+};
+type PassflowClaims = {
+  sub: string;
+  iss: string;
+  aud: string[];
+  exp: number;
+  iat?: number;
+  /** Whole Unix seconds. Absent when the claim is absent, not a number or beyond ±2^53. */
+  authTime?: number;
+  /** `'0'` when the claim is absent or not a string. */
+  acr: string;
+  amr: string[];
+  scopes: string[];
+  sid?: string;
+  type: string;
+  tenants: Record<string, TenantMembership>;
+  /** The verifier's clock at verification, in Unix seconds. `requireFresh` measures from it. */
+  verifiedAt: number;
+  raw: Record<string, unknown>;
+};
+/**
+ * The structural part of a verifier. Declared here, with `verifiedBy`, so that provenance needs nothing
+ * from the verifier module.
+ */
+interface Verifier {
+  verify(token: string): Promise<PassflowClaims>;
+  refresh(): Promise<void>;
+}
+/**
+ * True only for the exact object `verifier.verify` returned. A spread or clone loses provenance, which
+ * costs one more verification and never a bypass. So does any wrapper or decorator object that delegates
+ * to `verifier.verify`: it is a different identity, and this verifier's adapter re-verifies claims it
+ * returns. Two verifiers built from the same configuration are different identities too.
+ */
+declare function verifiedBy(claims: PassflowClaims, verifier: Verifier): boolean;
+/**
+ * The roles a user holds in a tenant: `groups[rootGroupId]`, the rule the server's `CalcTenantRoles` and
+ * `@passflow/core`'s `parseMembership` apply. A missing tenant, root group or map gives an empty list.
+ * So does an empty `rootGroupId`, unlike the server: no role is granted from a group keyed by "".
+ * `tenantRoles` is a copy the server derives from the same root group, and is not consulted.
+ */
+declare function rolesOf(claims: PassflowClaims, tenantId: string): string[];
+export { verifiedBy as a, rolesOf as i, TenantMembership as n, Verifier as r, PassflowClaims as t };

package/dist/evaluate-BTuol-Oa.mjs

@@ -0,0 +1,348 @@
+// src/acr.ts
+const ACR_NONE = "0";
+const AAL1 = "1";
+const AAL2 = "2";
+const AAL3 = "3";
+const ACR_LEXICAL = /^[+-]?[0-9]+$/;
+const INT64_MAX = 9223372036854775807n;
+/**
+* The ordinal level of an `acr` value, by the rule the server's `strconv.Atoi` applies on a 64-bit
+* platform (`server_level` in the corpus): optional sign and any number of ASCII digits, the value
+* must fit a signed 64-bit integer; a lexical failure, an out-of-range value, a negative value or a
+* non-string is level 0.
+*
+* Internal. It returns `bigint` so that nothing on the decision path goes through a `Number`.
+*/
+function parseACRLevel(acr) {
+	if (typeof acr !== "string" || !ACR_LEXICAL.test(acr)) return 0n;
+	const level = BigInt(acr);
+	return level < 0n || level > INT64_MAX ? 0n : level;
+}
+/**
+* Whether a token's `acr` meets the required level. Both sides are compared as exact 64-bit integers,
+* and a required side that parses to level 0 is never satisfied: a wrong configuration string fails
+* closed here as well as at `requireACR` construction.
+*/
+function acrSatisfies(acr, min) {
+	const required = parseACRLevel(min);
+	return required !== 0n && parseACRLevel(acr) >= required;
+}
+/**
+* The level as a `number`, for display and logging. It is exact only up to 2^53, and nothing in this
+* library decides with it: use {@link acrSatisfies} to compare.
+*/
+function acrLevel(acr) {
+	return Number(parseACRLevel(acr));
+}
+// src/bearer.ts
+const BEARER_PREFIX = /^bearer(?:[ \t]+|$)/i;
+/**
+* The token from an `Authorization` header. The scheme is matched case-insensitively (RFC 9110). Any
+* other scheme, an absent header, and a `Bearer` with an empty or whitespace-only remainder all give
+* `undefined`.
+*/
+function extractBearer(authorization) {
+	if (typeof authorization !== "string") return;
+	const header = authorization.trim();
+	const prefix = BEARER_PREFIX.exec(header);
+	if (prefix === null) return;
+	const token = header.slice(prefix[0].length);
+	return token === "" ? void 0 : token;
+}
+// src/challenge.ts
+const MAX_AGE_ERROR = "[passflow] maxAgeSeconds must be a finite integer between 1 and Number.MAX_SAFE_INTEGER";
+const FORMAT_MAX_AGE_ERROR = "[passflow] maxAge must be undefined or a finite number no greater than Number.MAX_SAFE_INTEGER";
+const FORMAT_ACR_ERROR = "[passflow] acrValues must be undefined or a string";
+/**
+* The constructor rule for a freshness limit (`freshness.json#max_age_input`): a finite number,
+* truncated toward zero, at least 1 and a safe integer, or a `TypeError`. The bound means `String()`
+* always yields plain decimal, so a challenge can never carry `max_age=1e+21`, which the browser
+* SDK's `Number.parseInt` reads as 1. The returned value is both what is enforced and what the
+* challenge carries.
+*/
+function assertMaxAge(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(MAX_AGE_ERROR);
+	const seconds = Math.trunc(value);
+	if (seconds < 1 || !Number.isSafeInteger(seconds)) throw new TypeError(MAX_AGE_ERROR);
+	return seconds;
+}
+/**
+* The exact RFC 9470 `WWW-Authenticate` bytes the server's `SetInsufficientAuthChallenge` emits. This
+* is a formatter, not a constructor: a `maxAge` that truncates to zero or below is omitted, as the
+* server omits it, and it does not run {@link assertMaxAge}. A non-finite number, a non-number, or a
+* positive value above `Number.MAX_SAFE_INTEGER` is a `TypeError`.
+*
+* `acrValues` is a space-separated list of acr tokens, inserted unescaped exactly as the server does.
+*/
+function formatChallenge(c) {
+	let header = "Bearer error=\"insufficient_user_authentication\"";
+	if (c.acrValues !== void 0) {
+		if (typeof c.acrValues !== "string") throw new TypeError(FORMAT_ACR_ERROR);
+		if (c.acrValues !== "") header += `, acr_values="${c.acrValues}"`;
+	}
+	if (c.maxAge !== void 0) {
+		if (typeof c.maxAge !== "number" || !Number.isFinite(c.maxAge)) throw new TypeError(FORMAT_MAX_AGE_ERROR);
+		const seconds = Math.trunc(c.maxAge);
+		if (seconds > 0) {
+			if (!Number.isSafeInteger(seconds)) throw new TypeError(FORMAT_MAX_AGE_ERROR);
+			header += `, max_age=${String(seconds)}`;
+		}
+	}
+	return header;
+}
+// src/claims.ts
+const MAX_EXACT_SECONDS = 2 ** 53;
+const provenance = /* @__PURE__ */ new WeakMap();
+/** Internal: records that `verifier.verify` produced exactly this object. */
+function recordProvenance(claims, verifier) {
+	provenance.set(claims, verifier);
+}
+/**
+* True only for the exact object `verifier.verify` returned. A spread or clone loses provenance, which
+* costs one more verification and never a bypass. So does any wrapper or decorator object that delegates
+* to `verifier.verify`: it is a different identity, and this verifier's adapter re-verifies claims it
+* returns. Two verifiers built from the same configuration are different identities too.
+*/
+function verifiedBy(claims, verifier) {
+	return provenance.get(claims) === verifier && verifier !== void 0;
+}
+/**
+* Internal: a numeric date within ±2^53, the rule Go's `numericDate` applies. Beyond it a JSON number is no
+* longer an exact count of seconds, so the claim reads as absent.
+*/
+function isExactSeconds(value) {
+	return typeof value === "number" && Math.abs(value) <= MAX_EXACT_SECONDS;
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function stringsOf(value) {
+	return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+/** A wrong JSON type means the membership cannot be read. `null` reads as absent, as Go's decoder does. */
+function decodeMembership(value) {
+	if (!isPlainObject(value)) return;
+	const { tenant_id, tenant_name, tenant_roles, root_group_id, groups, group_names } = value;
+	const membership = { tenantId: "" };
+	if (tenant_id !== void 0 && tenant_id !== null) {
+		if (typeof tenant_id !== "string") return void 0;
+		membership.tenantId = tenant_id;
+	}
+	if (tenant_name !== void 0 && tenant_name !== null) {
+		if (typeof tenant_name !== "string") return void 0;
+		membership.tenantName = tenant_name;
+	}
+	if (tenant_roles !== void 0 && tenant_roles !== null) {
+		if (!isStringArray(tenant_roles)) return void 0;
+		membership.tenantRoles = tenant_roles;
+	}
+	if (root_group_id !== void 0 && root_group_id !== null) {
+		if (typeof root_group_id !== "string") return void 0;
+		membership.rootGroupId = root_group_id;
+	}
+	if (groups !== void 0 && groups !== null) {
+		if (!isPlainObject(groups)) return void 0;
+		const entries = Object.entries(groups).filter(([, roles]) => roles !== null);
+		if (!entries.every(([, roles]) => isStringArray(roles))) return void 0;
+		membership.groups = Object.fromEntries(entries);
+	}
+	if (group_names !== void 0 && group_names !== null) {
+		if (!isPlainObject(group_names)) return void 0;
+		const entries = Object.entries(group_names).filter(([, name]) => name !== null);
+		if (!entries.every(([, name]) => typeof name === "string")) return void 0;
+		membership.groupNames = Object.fromEntries(entries);
+	}
+	return membership;
+}
+/** A membership that fails to decode drops that tenant only: the shape is informational, the token stays valid. */
+function decodeTenants(value) {
+	if (!isPlainObject(value)) return {};
+	const tenants = [];
+	for (const [tenantId, raw] of Object.entries(value)) {
+		const membership = decodeMembership(raw);
+		if (membership !== void 0) tenants.push([tenantId, membership]);
+	}
+	return Object.fromEntries(tenants);
+}
+/** Fail-closed claim extraction from a payload whose signature and registered claims already passed. */
+function extractClaims(payload, verifiedAt) {
+	const { sub, iss, aud, exp, iat, auth_time: authTime, acr, amr, scopes, sid, type, passflow_tm: tenants } = payload;
+	const claims = {
+		sub: typeof sub === "string" ? sub : "",
+		iss: typeof iss === "string" ? iss : "",
+		aud: typeof aud === "string" ? [aud] : stringsOf(aud),
+		exp,
+		acr: typeof acr === "string" ? acr : "0",
+		amr: stringsOf(amr),
+		scopes: stringsOf(scopes),
+		type: typeof type === "string" ? type : "",
+		tenants: decodeTenants(tenants),
+		verifiedAt,
+		raw: payload
+	};
+	if (isExactSeconds(iat)) claims.iat = iat;
+	if (isExactSeconds(authTime)) claims.authTime = Math.trunc(authTime);
+	if (typeof sid === "string") claims.sid = sid;
+	return claims;
+}
+/**
+* The roles a user holds in a tenant: `groups[rootGroupId]`, the rule the server's `CalcTenantRoles` and
+* `@passflow/core`'s `parseMembership` apply. A missing tenant, root group or map gives an empty list.
+* So does an empty `rootGroupId`, unlike the server: no role is granted from a group keyed by "".
+* `tenantRoles` is a copy the server derives from the same root group, and is not consulted.
+*/
+function rolesOf(claims, tenantId) {
+	const { tenants } = claims;
+	if (!isPlainObject(tenants) || !Object.hasOwn(tenants, tenantId)) return [];
+	const { groups, rootGroupId } = tenants[tenantId];
+	if (!isPlainObject(groups) || !rootGroupId || !Object.hasOwn(groups, rootGroupId)) return [];
+	return [...groups[rootGroupId]];
+}
+// src/cors.ts
+const CHALLENGE_HEADER = "WWW-Authenticate";
+const CORS_EXPOSED_HEADERS = Object.freeze([CHALLENGE_HEADER]);
+/**
+* Appends `WWW-Authenticate` to an expose list unless it is already there, compared case-insensitively.
+* Everything else is kept as given, `*` and duplicates included: `*` is not a wildcard on a
+* credentialed request, so the explicit entry is what matters. This guarantees exactly one thing, that
+* the header appears as an explicit entry.
+*
+* Internal. Each adapter wraps it under the option name its CORS middleware uses.
+*/
+function withChallengeHeader(existing) {
+	const entries = typeof existing === "string" ? existing.split(",").map((entry) => entry.trim()).filter((entry) => entry !== "") : [...existing ?? []];
+	return entries.some((entry) => entry.toLowerCase() === "WWW-Authenticate".toLowerCase()) ? entries : [...entries, CHALLENGE_HEADER];
+}
+// src/errors.ts
+const MESSAGES = {
+	missing_token: "[passflow] no bearer token presented",
+	invalid_token: "[passflow] invalid token",
+	jwks_unavailable: "[passflow] key set unavailable"
+};
+/**
+* An authentication failure. The message is fixed per code and carries nothing from the token, the
+* request or the JWKS URL. A jose error is never attached as `cause`: jose's claim errors keep the
+* whole payload on `.payload`.
+*/
+var PassflowAuthError = class extends Error {
+	code;
+	reason;
+	status;
+	constructor(code, reason, options) {
+		super(reason === void 0 ? MESSAGES[code] : `${MESSAGES[code]}: ${reason}`, options);
+		this.name = "PassflowAuthError";
+		this.code = code;
+		this.status = code === "jwks_unavailable" ? 503 : 401;
+		if (reason !== void 0) this.reason = reason;
+	}
+};
+/**
+* A programming error, such as reading the claims before any middleware ran. It is deliberately not
+* a `PassflowAuthError`: those mean 401/503, which the browser SDK acts on, and this must reach the
+* framework's error handling as a 500.
+*/
+var PassflowUsageError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PassflowUsageError";
+	}
+};
+/**
+* True for a `PassflowAuthError`, including one from the other copy of this package when the ESM
+* and CJS builds are both loaded, where `instanceof` alone would say no.
+*/
+function isPassflowAuthError(e) {
+	if (e instanceof PassflowAuthError) return true;
+	if (!(e instanceof Error) || e.name !== "PassflowAuthError") return false;
+	const { code } = e;
+	return code === "missing_token" || code === "invalid_token" || code === "jwks_unavailable";
+}
+// src/evaluate.ts
+const CACHE_CONTROL = "Cache-Control";
+const NO_STORE = "no-store";
+const reject = (status, wwwAuthenticate) => ({
+	kind: "reject",
+	status,
+	headers: wwwAuthenticate === void 0 ? { [CACHE_CONTROL]: NO_STORE } : {
+		[CHALLENGE_HEADER]: wwwAuthenticate,
+		[CACHE_CONTROL]: NO_STORE
+	}
+});
+/**
+* Authentication failures never carry the step-up error: the browser SDK acts only on the step-up challenge,
+* and every other response, a plain 401 or a 503 included, reaches the caller's code unchanged.
+*/
+function rejectAuthentication(code) {
+	switch (code) {
+		case "missing_token": return reject(401, "Bearer");
+		case "invalid_token": return reject(401, "Bearer error=\"invalid_token\"");
+		case "jwks_unavailable": return reject(503);
+	}
+}
+/**
+* Validates a requirement and returns it with the effective freshness limit. Throws `TypeError`: this is a
+* programming error that should stop the process at route registration, not become a `Decision`.
+*
+* Internal: `requireACR` and `requireFresh` call it at construction.
+*/
+function assertRequirement(requirement) {
+	if (typeof requirement === "object" && requirement !== null) {
+		if (requirement.kind === "acr") {
+			if (parseACRLevel(requirement.min) === 0n) throw new TypeError("[passflow] the required ACR must parse to a level above 0");
+			return requirement;
+		}
+		if (requirement.kind === "fresh") return {
+			kind: "fresh",
+			maxAgeSeconds: assertMaxAge(requirement.maxAgeSeconds)
+		};
+	}
+	throw new TypeError("[passflow] a requirement is { kind: \"acr\", min } or { kind: \"fresh\", maxAgeSeconds }");
+}
+function isFresh(claims, maxAgeSeconds) {
+	const { authTime, verifiedAt } = claims;
+	if (!isExactSeconds(authTime)) return false;
+	return (typeof verifiedAt === "number" && Number.isFinite(verifiedAt) && verifiedAt > 0 ? Math.floor(verifiedAt) : Math.floor(Date.now() / 1e3)) - Math.trunc(authTime) <= maxAgeSeconds;
+}
+/**
+* Decides one requirement against claims. No claims means the middleware was composed wrongly, so the answer
+* is a 500 with no challenge: never a step-up, which the SDK would try to satisfy, and never a 401, because a
+* wiring bug must not be reported as a bad token. Throws `TypeError` on an invalid requirement.
+*/
+function evaluate(claims, requirement) {
+	const checked = assertRequirement(requirement);
+	if (claims === void 0 || claims === null) return reject(500);
+	if (checked.kind === "acr") return acrSatisfies(claims.acr, checked.min) ? { kind: "allow" } : reject(401, formatChallenge({ acrValues: checked.min }));
+	return isFresh(claims, checked.maxAgeSeconds) ? { kind: "allow" } : reject(401, formatChallenge({ maxAge: checked.maxAgeSeconds }));
+}
+/**
+* Authenticates a request. `existing` claims are reused only when `verifier` produced that exact object;
+* otherwise the presented header is verified with `verifier`, so a token outside this verifier's trust policy
+* is rejected as not valid here, never as insufficient. Never rejects: a failure is a `{ reject }` value.
+*/
+async function authenticate(verifier, authorization, existing) {
+	if (existing !== void 0 && existing !== null && verifiedBy(existing, verifier)) return { claims: existing };
+	const token = extractBearer(authorization);
+	if (token === void 0) return { reject: rejectAuthentication("missing_token") };
+	try {
+		return { claims: await verifier.verify(token) };
+	} catch (error) {
+		return { reject: isPassflowAuthError(error) ? rejectAuthentication(error.code) : reject(500) };
+	}
+}
+/**
+* Internal: one adapter step. Authenticates, then applies the requirement if there is one.
+*/
+async function guard(verifier, authorization, existing, requirement) {
+	const result = await authenticate(verifier, authorization, existing);
+	if ("reject" in result || requirement === void 0) return result;
+	const decision = evaluate(result.claims, requirement);
+	return decision.kind === "reject" ? { reject: decision } : result;
+}
+/** Internal: the adapters fail at construction when handed something that cannot verify. */
+function assertVerifier(verifier) {
+	if (typeof verifier !== "object" || verifier === null || typeof verifier.verify !== "function") throw new TypeError("[passflow] an adapter needs a verifier from createVerifier");
+}
+export { acrLevel as C, ACR_NONE as S, formatChallenge as _, guard as a, AAL2 as b, isPassflowAuthError as c, withChallengeHeader as d, extractClaims as f, assertMaxAge as g, verifiedBy as h, evaluate as i, CHALLENGE_HEADER as l, rolesOf as m, assertVerifier as n, PassflowAuthError as o, recordProvenance as p, authenticate as r, PassflowUsageError as s, assertRequirement as t, CORS_EXPOSED_HEADERS as u, extractBearer as v, acrSatisfies as w, AAL3 as x, AAL1 as y };