@forgezero/access 0.1.1 → 0.1.3

package/README.md

@@ -1,75 +1,325 @@
+<!--
+  GENERATED FILE — do not edit.
+
+  Change scripts/generate-guides.ts or its typed sources, run `bun run guides`,
+  and commit the generator and rendered files together.
+-->
+
 # @forgezero/access
 
-**Who may call what, decided from one table instead of scattered `if` statements.**
+Declare your security posture as seven lists. Handlers hold business logic only.
+
+## Global package root and supported runtimes
+
+Anyone building a service on our request shape: one declared matrix of routes and factors, enforced by one pipeline whatever the framework. Imports no sibling at all, so it can be adopted on its own. Supported runtimes: bun, node, workers, deno. The global base/root import is @forgezero/access. Every public import or command is listed below; the documentation inventory is checked in both directions against package.json exports.
 
-You declare every route once — the session it needs, the roles that reach it, the
-factors it demands — and the same declaration authorises the request, renders the
-navigation and fails the build when the two disagree.
+```text
+import * as root from '@forgezero/access';
+```
+
+## Commands
 
-Zero runtime dependencies. Bun, Node 18+, Deno, Cloudflare Workers, browsers —
-anywhere `fetch` and Web Crypto exist.
+bun add @forgezero/access — Install the framework-neutral access contracts and adapters.
 
-```bash
+```text
 bun add @forgezero/access
 ```
 
-## The idea in twelve lines
+## @forgezero/access
+
+Declare routes, factors and policies as orthogonal lists; authorise against them.
+
+```text
+import * as api from '@forgezero/access';
+```
+
+## @forgezero/access/conditions
+
+The twelve guards every project writes into `before`, each with the status its refusal deserves.
+
+```text
+import * as api from '@forgezero/access/conditions';
+```
+
+## @forgezero/access/effects
+
+Audit, emit, meter, invalidate and notify — what happens after a request is decided, never failing it.
+
+```text
+import * as api from '@forgezero/access/effects';
+```
+
+## @forgezero/access/security
+
+Constant-time comparison, CSPRNG tokens, HMAC, HKDF, AES-GCM sealing and redaction. Web Crypto only.
+
+```text
+import * as api from '@forgezero/access/security';
+```
+
+## @forgezero/access/rate-limit
+
+Request counters over a window — in memory, in Redis, or in a Durable Object.
+
+```text
+import * as api from '@forgezero/access/rate-limit';
+```
+
+## @forgezero/access/fetch
+
+A Fetch-native adapter over the declared access pipeline.
+
+```text
+import * as api from '@forgezero/access/fetch';
+```
+
+## @forgezero/access/pipeline
 
-```ts
-import { defineRoutes, authorise } from '@forgezero/access';
+The framework-neutral route, principal, factor, policy, rate-limit and effects pipeline.
 
-const ACCESS = defineRoutes({
-  'api/invoices':        { group: 'session', factors: ['passkey'] },
-  'api/invoices/refund': { group: 'admin',   factors: ['passkey'], actionFactors: ['passkey'] }
+```text
+import * as api from '@forgezero/access/pipeline';
+```
+
+## @forgezero/access/elysia
+
+Elysia integration over the same access pipeline and route declarations.
+
+```text
+import * as api from '@forgezero/access/elysia';
+```
+
+## @forgezero/access/client
+
+Typed client helpers that fulfil factors without duplicating the security matrix.
+
+```text
+import * as api from '@forgezero/access/client';
+```
+
+## @forgezero/access/testing
+
+Deterministic access-pipeline fixtures and assertions for consumer tests.
+
+```text
+import * as api from '@forgezero/access/testing';
+```
+
+## @forgezero/access/header
+
+Strict configurable header-identity extraction with canonical names and bounded values.
+
+```text
+import * as api from '@forgezero/access/header';
+```
+
+## @forgezero/access/principal
+
+Generic principal-source resolution for browser, API-key, attestation or future identity adapters.
+
+```text
+import * as api from '@forgezero/access/principal';
+```
+
+## @forgezero/access/principal-session
+
+Short-lived scope-bound delegated-principal sessions with sliding and absolute expiry.
+
+```text
+import * as api from '@forgezero/access/principal-session';
+```
+
+## @forgezero/access/authenticator
+
+Authentication-source contracts for adding identity mechanisms without changing route policy.
+
+```text
+import * as api from '@forgezero/access/authenticator';
+```
+
+## @forgezero/access/ceremony-modes
+
+Named security-ceremony modes and their session/action fulfilment semantics.
+
+```text
+import * as api from '@forgezero/access/ceremony-modes';
+```
+
+## Declare routes before handlers
+
+Routes and their access policy are data; Fetch and Elysia adapters enforce the same declaration.
+
+```text
+import { defineRoutes, action, page } from '@forgezero/access';
+
+export const routes = defineRoutes({
+  orders: page('Orders'),
+  'api/orders': action('List orders', 'GET', { page: 'orders' })
 });
+```
+
+## 1. Install
+
+Zero runtime dependencies. The core is fetch types plus plain JSON Schema, so it runs on Bun, Node 18+, Cloudflare Workers, Deno and every edge runtime.
+
+```text
+bun add @forgezero/access
+```
+
+## 2. Declare routes and who may reach them
+
+Routes carry their contract — label, method, and the shapes they accept and return. WHO may reach them is a separate list, because the two change for different reasons and on different schedules.
+
+```text
+import { defineRoutes, defineAccessControl, page, action } from '@forgezero/access';
+
+export const ROUTES = defineRoutes({
+  orders:                    page('Orders'),
+  'api/orders':              action('List', 'GET',  { page: 'orders' }),
+  'api/orders/[id]/refund':  action('Refund', 'POST', { page: 'orders' })
+});
+
+export const ACCESS = defineAccessControl({
+  factors: FACTORS,
+  routes: ROUTES,
+  sessionPolicies: {
+    member: { factors: ['passkey'], routes: ['orders', 'api/orders'] },
+    admin:  { factors: ['passkey'], routes: ['api/orders/[id]/refund'] }
+  }
+});
+```
+
+## 3. Mount it
+
+One line per runtime. The pipeline is written once and shared, so an adapter never re-decides anything.
+
+```text
+// anywhere fetch exists — Workers, Deno, Node, Bun
+import { toFetch } from '@forgezero/access/fetch';
+export default { fetch: toFetch({ access: ACCESS, handlers: HANDLERS }) };
+
+// Elysia
+import { elysia } from '@forgezero/access/elysia';
+app.use(elysia({ access: ACCESS, handlers: HANDLERS, Elysia }));
+```
+
+## Every route needs a session policy, or the build fails
+
+Exactly one policy must cover each route. A route nobody classified is a route whose security nobody decided — and adding a route is precisely when that happens. This is the rule that catches omission rather than typos, and it is why forgetting is not possible rather than merely discouraged.
 
-// A ROLE IS A SET OF ROUTE KEYS. There is no second permission vocabulary to
-// keep in sync, and a role naming a route that no longer exists is a type error.
-const FINANCE = ['api/invoices', 'api/invoices/refund'] as const;
+```text
+SESSION_INCOMPLETE: No session policy covers: api/orders/export.
+Every route needs exactly one.
+```
+
+## Fresh proof for dangerous actions
 
-authorise(ACCESS, 'api/invoices/refund', session);   // → allowed | Refusal
+actionFactorsRequired is a COUNT: 1 is any-one, the list length is all-of, and anything between is M-of-N with no special case. The proof binds to the record your before-handler loaded, so a key minted to refund order A cannot refund order B.
+
+```text
+actionPolicies: {
+  sensitive: {
+    factors: ['passkey', 'telegram', 'totp'],
+    required: 2,          // any 2 of the 3
+    target: 'orders',
+    routes: ['api/orders/[id]/refund']
+  }
+}
 ```
 
-## What it gives you that a middleware does not
+## A session factor NEVER satisfies an action factor
+
+fulfilledActionFactors() returns an empty array, always. A five-minute verified-at timestamp looks equivalent and is not: a timestamp IS a persisted factor, so a left-open laptop or a stolen cookie replays the privileged action. Returning nothing makes that impossible by construction rather than by policy.
+
+## Disabling a factor tells you what it breaks, first
+
+The effective pool is the route factors intersected with the factors you have enabled. If that falls below the required count the route becomes UNAVAILABLE — never quietly weakened to whatever remains. Ask before saving rather than discovering it during an incident.
+
+```text
+impactOfDisabling(ACCESS, ['passkey'])
+// [{ route: 'api/orders/[id]/refund', available: 1, required: 2 }]
+```
 
-**Two layers, and the second never trusts the first.** A session factor is proved
-once and persists — it answers *who is this*. An action factor is proved per call
-and never persists — it answers *is this a human, now, for this record*. A
-five-minute "recently verified" timestamp looks equivalent and is not: a
-timestamp **is** a persisted factor, so a left-open laptop replays the privileged
-action. `fulfilledActionFactors()` returns `[]` — always, by design.
+## Test it without a server
 
-**A refusal that says what happened.** `401` no session · `403` role lacks the
-route · `404` route exists but not in this stage · `409` a condition refused ·
-`423` locked, a human must act · `428` a factor is missing, and the headers name
-which. Every one is distinct because "403" for all of them is how a support
-queue fills up.
+simulate() reports which policy decided, which a browser 403 never tells you. reachableRoutes() answers what a role can actually do — worth running, because stem inheritance grants more than a grant list reads like.
 
-**Twelve guards already written.** `requireBalance`, `requireApproval`,
-`requireQuota`, `requireFreshness` and the rest — the conditions every project
-writes by hand, each already carrying the right status code.
+```text
+import { simulate, reachableRoutes } from '@forgezero/access/testing';
 
-**Testable with no server.** `@forgezero/access/testing` builds sessions and
-asserts the decision directly, so the truth table is a unit test rather than an
-integration suite.
+simulate(ACCESS, { route: 'api/settings', roles, as: 'member' });
+// { allowed: false, status: 403, reason: 'ACCESS_DENIED', sessionPolicy: 'admin' }
+
+reachableRoutes(ACCESS, roles, ['member']);
+// holding 'orders' also grants api/orders/[id]/refund — stems inherit
+```
+
+## Conditions: the guards, already written
+
+Every project writes the same dozen checks into its before-handlers. These are those checks, each declaring the status it refuses with. requireOwner answers 404 rather than 403 on purpose — a 403 confirms the record exists, which turns sequential identifiers into an enumeration oracle.
+
+```text
+import { loadTarget, requireOwner, requireState, requireBalance }
+  from '@forgezero/access/conditions';
+
+beforeHandlers: {
+  load:    loadTarget({ routes: ['api/orders/[id]/refund'], load: findOrder }),
+  mine:    requireOwner({ routes: ['api/orders/[id]/refund'], owner: o => o.userKey }),
+  payable: requireState({ routes: ['api/orders/[id]/refund'],
+                          status: o => o.status, allowed: ['paid'] })
+}
+```
 
-## Subpaths
+## A refusal keeps its own status
 
-| import | what it is |
-|---|---|
-| `@forgezero/access` | the matrix, roles, `authorise`, `Refusal` |
-| `/conditions` | the twelve guards, each with its own status |
-| `/effects` | audit, emit, meter, invalidate, notify — after the decision |
-| `/security` | constant-time compare, CSPRNG tokens, HMAC, HKDF, AES-GCM sealing |
-| `/rate-limit` | counters over a window — memory, Redis, or a Durable Object |
-| `/elysia` · `/fetch` | adapters |
-| `/client` | the browser half, including the 428 replay |
-| `/testing` | decide without a server |
-| `/pipeline` · `/authenticator` | the resolver, and WebAuthn |
+A condition throws a Refusal carrying the status the client deserves, so "already refunded" is a 409 the UI can explain rather than a 500 that tells the client to retry. An idempotent replay throws Settled instead and returns the original answer — because a retrying client needs to learn the transfer succeeded, which no error code can tell it.
 
-Full documentation: **https://www.forgezero.net/docs/access**
+```text
+throw new Refusal(409, 'STATE_INVALID', 'Already refunded.', { status: 'refunded' });
 
-## Licence
+// idempotent replay — the ORIGINAL result, not an error
+throw new Settled({ ok: true, id: 'ref_1' }, 201);
+```
+
+## Undeclared refusals fail the build
+
+Each condition knows which statuses it can produce, so the set a route can answer is derivable. Add a quota check to a route whose contract never mentions 409 and the build stops — rather than a client rendering "an unexpected error" for the one refusal a user could have acted on.
+
+```text
+assertDeclaredRefusals({ routes: ROUTES, conditions: CONDITIONS });
+// Undeclared refusals:
+//   api/wallet/withdraw can 409 (requireQuota) but does not declare it
+```
+
+## Effects: what happens once it is decided
+
+Audit, emit, meter, invalidate and notify. None can fail the request — a dead audit sink must not turn a completed transfer into a 500. Audit records denials as well as successes, because a run of 403s from one session is the signal an incident is reconstructed from. Every payload is redacted first.
+
+```text
+import { audit, emit, meter } from '@forgezero/access/effects';
+
+afterHandlers: {
+  trail: audit({ routes: [...], sink }),
+  event: emit({ routes: [...], outbox, type: 'order.refunded',
+                payload: (ctx, result) => ({ id: result.id }) }),
+  usage: meter({ routes: [...], meter, unit: 'request' })  // successes only
+}
+```
+
+## Response codes, and what each means
+
+A 428 is not a rejection: it names the missing proof and the same request succeeds on replay. A 404 for a route outside its stage is deliberate — a 403 would confirm the route exists.
+
+```text
+401  no session
+403  session is fine, the role lacks this route
+404  route exists but not in this stage, realm or feature
+409  a condition refused — state, balance, quota or approval
+412  the record changed since you read it
+422  the request did not match what the route accepts
+423  locked — a human must act, unlike 503
+428  a factor is missing — headers name which
+429  rate limited
+```
 
-MIT. Part of [ForgeZero](https://www.forgezero.net) — secrets, attested compute and
-deploys — and usable entirely on its own, with no ForgeZero account.
+Full rendered documentation: https://www.forgezero.net/docs/access

package/dist/conditions.js

@@ -60,13 +60,16 @@ function defineFactors(factors) {
   return factors;
 }
 function page(label, options = {}) {
-  return { kind: "page", label, ...options };
+  return { kind: "page", label, accessGroup: "default", ...options };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, ...options };
+  return { kind: "action", label, method, accessGroup: "default", ...options };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
+      throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
+    }
     const isApi = key.startsWith("api/");
     if (isApi !== (route.kind === "action")) {
       throw new AccessError("ROUTE_KIND_MISMATCH", `"${key}": routes under api/ must be actions, and actions must be under api/.`);
@@ -242,11 +245,11 @@ function authorise(args) {
     return { allow: false, status: 404, code: "NOT_FOUND" };
   }
   const policy = access.sessionPolicyFor(routeKey);
-  if (!policy || policy.factors.length === 0)
+  if ((policy?.factors.length ?? 0) === 0)
     return { allow: true };
   if (!session)
     return { allow: false, status: 401, code: "AUTH_REQUIRED" };
-  const missing = policy.factors.filter((factor) => !session.factors.includes(factor));
+  const missing = (policy?.factors ?? []).filter((factor) => !session.factors.includes(factor));
   if (missing.length > 0) {
     return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
   }

package/dist/effects.js

@@ -60,13 +60,16 @@ function defineFactors(factors) {
   return factors;
 }
 function page(label, options = {}) {
-  return { kind: "page", label, ...options };
+  return { kind: "page", label, accessGroup: "default", ...options };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, ...options };
+  return { kind: "action", label, method, accessGroup: "default", ...options };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
+      throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
+    }
     const isApi = key.startsWith("api/");
     if (isApi !== (route.kind === "action")) {
       throw new AccessError("ROUTE_KIND_MISMATCH", `"${key}": routes under api/ must be actions, and actions must be under api/.`);
@@ -242,11 +245,11 @@ function authorise(args) {
     return { allow: false, status: 404, code: "NOT_FOUND" };
   }
   const policy = access.sessionPolicyFor(routeKey);
-  if (!policy || policy.factors.length === 0)
+  if ((policy?.factors.length ?? 0) === 0)
     return { allow: true };
   if (!session)
     return { allow: false, status: 401, code: "AUTH_REQUIRED" };
-  const missing = policy.factors.filter((factor) => !session.factors.includes(factor));
+  const missing = (policy?.factors ?? []).filter((factor) => !session.factors.includes(factor));
   if (missing.length > 0) {
     return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
   }

package/dist/elysia.js

@@ -60,13 +60,16 @@ function defineFactors(factors) {
   return factors;
 }
 function page(label, options = {}) {
-  return { kind: "page", label, ...options };
+  return { kind: "page", label, accessGroup: "default", ...options };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, ...options };
+  return { kind: "action", label, method, accessGroup: "default", ...options };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
+      throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
+    }
     const isApi = key.startsWith("api/");
     if (isApi !== (route.kind === "action")) {
       throw new AccessError("ROUTE_KIND_MISMATCH", `"${key}": routes under api/ must be actions, and actions must be under api/.`);
@@ -242,11 +245,11 @@ function authorise(args) {
     return { allow: false, status: 404, code: "NOT_FOUND" };
   }
   const policy = access.sessionPolicyFor(routeKey);
-  if (!policy || policy.factors.length === 0)
+  if ((policy?.factors.length ?? 0) === 0)
     return { allow: true };
   if (!session)
     return { allow: false, status: 401, code: "AUTH_REQUIRED" };
-  const missing = policy.factors.filter((factor) => !session.factors.includes(factor));
+  const missing = (policy?.factors ?? []).filter((factor) => !session.factors.includes(factor));
   if (missing.length > 0) {
     return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
   }

package/dist/fetch.js

@@ -60,13 +60,16 @@ function defineFactors(factors) {
   return factors;
 }
 function page(label, options = {}) {
-  return { kind: "page", label, ...options };
+  return { kind: "page", label, accessGroup: "default", ...options };
 }
 function action(label, method, options = {}) {
-  return { kind: "action", label, method, ...options };
+  return { kind: "action", label, method, accessGroup: "default", ...options };
 }
 function defineRoutes(routes) {
   for (const [key, route] of Object.entries(routes)) {
+    if (!/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(route.accessGroup)) {
+      throw new AccessError("ROUTE_ACCESS_INVALID", `"${key}": accessGroup must be a bounded name.`);
+    }
     const isApi = key.startsWith("api/");
     if (isApi !== (route.kind === "action")) {
       throw new AccessError("ROUTE_KIND_MISMATCH", `"${key}": routes under api/ must be actions, and actions must be under api/.`);
@@ -242,11 +245,11 @@ function authorise(args) {
     return { allow: false, status: 404, code: "NOT_FOUND" };
   }
   const policy = access.sessionPolicyFor(routeKey);
-  if (!policy || policy.factors.length === 0)
+  if ((policy?.factors.length ?? 0) === 0)
     return { allow: true };
   if (!session)
     return { allow: false, status: 401, code: "AUTH_REQUIRED" };
-  const missing = policy.factors.filter((factor) => !session.factors.includes(factor));
+  const missing = (policy?.factors ?? []).filter((factor) => !session.factors.includes(factor));
   if (missing.length > 0) {
     return { allow: false, status: 428, code: "SECURITY_REQUIRED", missing };
   }

package/dist/header.d.ts

@@ -0,0 +1,41 @@
+import { type PrincipalAssignment, type RbacPrincipal } from './principal';
+export interface HeaderIdentity {
+    subject: string;
+    /** Authentication facts established by the source, never RBAC assignments. */
+    claims?: Readonly<Record<string, string>>;
+}
+/** A header is transport; this verifier is the authentication boundary. */
+export interface HeaderIdentitySource {
+    key: string;
+    header: string;
+    verify(input: {
+        value: string;
+        request: Request;
+        source: string;
+    }): Promise<HeaderIdentity | undefined>;
+}
+export interface HeaderPrincipal extends RbacPrincipal {
+    kind: 'header-identity';
+    /** Stable RBAC principal key. Safe to persist in a membership row. */
+    principalKey: string;
+    source: string;
+    subject: string;
+    claims: Readonly<Record<string, string>>;
+}
+/**
+ * The host owns assignments. It may read a database, configuration service or
+ * code policy; the credential itself never supplies roles. This is called for
+ * every request so assignment, disablement and revocation take effect at once.
+ */
+export interface HeaderAssignmentResolver {
+    (input: {
+        principalKey: string;
+        source: string;
+        subject: string;
+        claims: Readonly<Record<string, string>>;
+        request: Request;
+    }): Promise<readonly PrincipalAssignment[]>;
+}
+export declare function defineHeaderIdentitySources<const T extends readonly HeaderIdentitySource[]>(sources: T): T;
+/** Resolve exactly one authenticated header source and its fresh RBAC assignment. */
+export declare function headerIdentityResolver(sourcesInput: readonly HeaderIdentitySource[], resolveAssignments: HeaderAssignmentResolver): (request: Request) => Promise<HeaderPrincipal | undefined>;