@passflow/node 0.0.0-bootstrap.0 → 0.0.0-stage

package/README.md

@@ -1,180 +1,3 @@
-# @passflow/node
+# Temporary Holding Version
 
-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.
+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.

package/package.json

@@ -1,106 +1,6 @@
 {
   "name": "@passflow/node",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Passflow authorization primitives for Node.js resource servers: token verification, ACR floors, auth_time freshness and RFC 9470 step-up challenges, with Express, Fastify and Hono adapters.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MadAppGang/passflow.git",
-    "directory": "sdk/node"
-  },
-  "type": "module",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=22.12"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    },
-    "./express": {
-      "import": {
-        "types": "./dist/express.d.mts",
-        "default": "./dist/express.mjs"
-      },
-      "require": {
-        "types": "./dist/express.d.cts",
-        "default": "./dist/express.cjs"
-      }
-    },
-    "./fastify": {
-      "import": {
-        "types": "./dist/fastify.d.mts",
-        "default": "./dist/fastify.mjs"
-      },
-      "require": {
-        "types": "./dist/fastify.d.cts",
-        "default": "./dist/fastify.cjs"
-      }
-    },
-    "./hono": {
-      "import": {
-        "types": "./dist/hono.d.mts",
-        "default": "./dist/hono.mjs"
-      },
-      "require": {
-        "types": "./dist/hono.d.cts",
-        "default": "./dist/hono.cjs"
-      }
-    },
-    "./package.json": "./package.json"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "jose": "^6.2.14"
-  },
-  "peerDependencies": {
-    "express": "^4.18.0 || ^5.0.0",
-    "fastify": "^5.0.0",
-    "hono": "^4.0.0"
-  },
-  "peerDependenciesMeta": {
-    "express": {
-      "optional": true
-    },
-    "fastify": {
-      "optional": true
-    },
-    "hono": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@arethetypeswrong/core": "0.18.5",
-    "@biomejs/biome": "1.9.4",
-    "@types/express": "5.0.6",
-    "@types/node": "^22.18.0",
-    "express": "5.3.0",
-    "fastify": "5.12.7",
-    "hono": "4.13.14",
-    "publint": "0.3.25",
-    "tsdown": "0.23.4",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "lint": "biome ci .",
-    "format": "biome format . --write",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
-  }
-}
+  "version": "0.0.0-stage",
+  "stub": true,
+  "description": "Temporary package placeholder for staged publishing"
+}

package/LICENSE

@@ -1,21 +0,0 @@
-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/dist/claims-BHJhnzch.d.cts

@@ -1,51 +0,0 @@
-/** 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

@@ -1,51 +0,0 @@
-/** 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 };