@forgezero/access 0.1.2 → 0.1.3

package/README.md

@@ -1,115 +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.
+
+```text
+import * as root from '@forgezero/access';
+```
+
+## Commands
+
+bun add @forgezero/access — Install the framework-neutral access contracts and adapters.
+
+```text
+bun add @forgezero/access
+```
+
+## @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
+
+The framework-neutral route, principal, factor, policy, rate-limit and effects pipeline.
+
+```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' })
+});
+```
 
-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.
+## 1. Install
 
-Zero runtime dependencies. Bun, Node 18+, Deno, Cloudflare Workers, browsers —
-anywhere `fetch` and Web Crypto exist.
+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.
 
-```bash
+```text
 bun add @forgezero/access
 ```
 
-## The idea in twelve lines
+## 2. Declare routes and who may reach them
 
-```ts
-import { defineRoutes, authorise } from '@forgezero/access';
+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.
 
-const ACCESS = defineRoutes({
-  'api/invoices':        { group: 'session', factors: ['passkey'] },
-  'api/invoices/refund': { group: 'admin',   factors: ['passkey'], actionFactors: ['passkey'] }
+```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' })
 });
 
-// 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;
-
-authorise(ACCESS, 'api/invoices/refund', session);   // → allowed | Refusal
-```
-
-## What it gives you that a middleware does not
-
-**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.
-
-**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.
-
-**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.
-
-**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.
-
-## Subpaths
-
-| 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 |
-| `/header` | verified header identities with fresh, host-owned RBAC assignments |
-| `/principal` | generic multi-assignment principals, route groups, methods and expiry |
-| `/principal-session` | short-lived server sessions bound to an opaque client identity |
-
-Header identities are a separate principal, not a browser session. A source
-verifier authenticates one configured header and returns only a stable subject;
-the host resolves that subject's role assignments on every request. Roles are
-never accepted from the header value, and a header principal cannot satisfy a
-session or fresh-action factor. Multiple source adapters can coexist, but a
-request presenting more than one source is refused as ambiguous.
-
-`accessGroup` is the single open, host-defined route classification used by
-generic principal assignments—`public`, `user`, `admin`, `custody`,
-`orchestration`, or any future product vocabulary. Session policies remain the
-generic package's authentication boundary; ForgeZero additionally requires its
-`public` group to use anonymous authentication and rejects contradictions at
-boot. The package does not hard-code a purpose or identity type.
-
-```ts
-import { headerIdentityResolver } from '@forgezero/access/header';
-import { decidePrincipalAccess } from '@forgezero/access/principal';
-
-const resolveHeader = headerIdentityResolver(
-  [{
-    key: 'partner-sso',
-    header: 'x-partner-identity',
-    verify: ({ value, request }) => verifyPartnerAssertion(value, request)
-  }],
-  // Read the current admin/custodian assignment. Do not cache it in the token.
-  ({ principalKey }) => memberships.assignments(principalKey)
-);
-
-const principal = await resolveHeader(request);
-const decision = decidePrincipalAccess({
-  access, principal, roles: await policy.roles(), routeKey: 'api/orders/write', method: 'POST'
+export const ACCESS = defineAccessControl({
+  factors: FACTORS,
+  routes: ROUTES,
+  sessionPolicies: {
+    member: { factors: ['passkey'], routes: ['orders', 'api/orders'] },
+    admin:  { factors: ['passkey'], routes: ['api/orders/[id]/refund'] }
+  }
 });
-if (!decision.allow) {
-  return new Response('Forbidden', { status: 403 });
+```
+
+## 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.
+
+```text
+SESSION_INCOMPLETE: No session policy covers: api/orders/export.
+Every route needs exactly one.
+```
+
+## Fresh proof for dangerous actions
+
+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']
+  }
 }
 ```
 
-Full documentation: **https://www.forgezero.net/docs/access**
+## A session factor NEVER satisfies an action factor
 
-## Licence
+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 }]
+```
+
+## Test it without a server
+
+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.
+
+```text
+import { simulate, reachableRoutes } from '@forgezero/access/testing';
+
+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'] })
+}
+```
+
+## A refusal keeps its own status
+
+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.
+
+```text
+throw new Refusal(409, 'STATE_INVALID', 'Already refunded.', { status: 'refunded' });
+
+// 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/access",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "publishConfig": {
     "access": "public",