@forgezero/access 0.1.2 → 0.1.4

package/README.md

@@ -1,115 +1,408 @@
+<!--
+  GENERATED FILE — do not edit.
+
+  Change tools/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.
 
-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.
+## Package overview
 
-Zero runtime dependencies. Bun, Node 18+, Deno, Cloudflare Workers, browsers —
-anywhere `fetch` and Web Crypto exist.
+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. Package root: @forgezero/access. The sections below show the actual named imports emitted by each declaration entry point; wildcard imports are intentionally not used in the documentation.
 
-```bash
+```text
 bun add @forgezero/access
 ```
 
-## The idea in twelve lines
+## ForgeZero package family
+
+The five packages are installation boundaries. Choose a package by who installs it; choose a subpath by the capability used in that file.
+
+| package | short description | runtimes | documentation |
+|---|---|---|---|
+| @forgezero/vault | Scoped secret access with Agent, API-key and systemd-credential sources. | bun, node, workers, deno | [Open](https://www.forgezero.net/docs/vault-package) |
+| @forgezero/access | Typed route, principal, factor, RBAC and request-pipeline contracts. | bun, node, workers, deno | [Open](https://www.forgezero.net/docs/access) |
+| @forgezero/providers | Typed external providers with priority, health and classified fallback. | bun, node, workers, deno | [Open](https://www.forgezero.net/docs/providers) |
+| @forgezero/runtime | Portable runtime primitives for queries, jobs, events, schemas and finance. | bun, node | [Open](https://www.forgezero.net/docs/runtime) |
+| @forgezero/agent | Operator CLI and managed-node agent for bootstrap, deploy and lifecycle. | bun, node | [Open](https://www.forgezero.net/docs/agent) |
+
+## @forgezero/access public imports and commands
+
+Every row links to the detailed explanation and named-import/example area below. This table and those details are generated from the package inventory and emitted declarations.
+
+| public entry | short description | runtime | details |
+|---|---|---|---|
+| @forgezero/access | Declare routes, factors and policies as orthogonal lists; authorise against them. | portable | [Details + example](#forgezero-access) |
+| @forgezero/access/conditions | The twelve guards every project writes into `before`, each with the status its refusal deserves. | portable | [Details + example](#forgezero-access-conditions) |
+| @forgezero/access/effects | Audit, emit, meter, invalidate and notify — what happens after a request is decided, never failing it. | portable | [Details + example](#forgezero-access-effects) |
+| @forgezero/access/security | Constant-time comparison, CSPRNG tokens, HMAC, HKDF, AES-GCM sealing and redaction. Web Crypto only. | portable | [Details + example](#forgezero-access-security) |
+| @forgezero/access/rate-limit | Request counters over a window — in memory, in Redis, or in a Durable Object. | portable | [Details + example](#forgezero-access-rate-limit) |
+| @forgezero/access/fetch | A Fetch-native adapter over the declared access pipeline. | portable | [Details + example](#forgezero-access-fetch) |
+| @forgezero/access/pipeline | The framework-neutral route, principal, factor, policy, rate-limit and effects pipeline. | portable | [Details + example](#forgezero-access-pipeline) |
+| @forgezero/access/elysia | Elysia integration over the same access pipeline and route declarations. | portable | [Details + example](#forgezero-access-elysia) |
+| @forgezero/access/client | Typed client helpers that fulfil factors without duplicating the security matrix. | portable | [Details + example](#forgezero-access-client) |
+| @forgezero/access/testing | Deterministic access-pipeline fixtures and assertions for consumer tests. | portable | [Details + example](#forgezero-access-testing) |
+| @forgezero/access/header | Strict configurable header-identity extraction with canonical names and bounded values. | portable | [Details + example](#forgezero-access-header) |
+| @forgezero/access/principal | Generic principal-source resolution for browser, API-key, attestation or future identity adapters. | portable | [Details + example](#forgezero-access-principal) |
+| @forgezero/access/principal-session | Short-lived scope-bound delegated-principal sessions with sliding and absolute expiry. | portable | [Details + example](#forgezero-access-principal-session) |
+| @forgezero/access/authenticator | Authentication-source contracts for adding identity mechanisms without changing route policy. | portable | [Details + example](#forgezero-access-authenticator) |
+| @forgezero/access/ceremony-modes | Named security-ceremony modes and their session/action fulfilment semantics. | portable | [Details + example](#forgezero-access-ceremony-modes) |
+
+## Commands
+
+bun add @forgezero/access — Install the framework-neutral access contracts and adapters.
+
+```text
+bun add @forgezero/access
+```
+
+<a id="forgezero-access"></a>
+## @forgezero/access
+
+Declare routes, factors and policies as orthogonal lists; authorise against them. Named value imports: AccessError, Refusal, SCHEMA_VERSION, Settled, VERSION, action, assertReadable, authorise, codePolicy, defineAccessControl, defineFactors, defineRoutes, externalPolicy, fulfilledActionFactors, grantsRoute, impactOfDisabling, isRefusal, isSettled, page, resolveActionFactors, stemOf. Named type imports: AccessControl, AccessControlConfig, ActionPolicy, ActionRoute, AfterHandler, BeforeHandler, Binding, FactorContext, FactorKind, FactorRegistry, FactorSpec, GrantOptions, Method, Outcome, PageRoute, PolicySource, Problem, RatePolicy, RequestContext, Role, RouteBase, RouteContract, RouteRegistry, RouteSpec, SessionContext, SessionPolicy, Versioned. Import only the names used by this file.
+
+```text
+import { AccessError, Refusal, SCHEMA_VERSION, Settled, VERSION, action } from '@forgezero/access';
+import { assertReadable, authorise, codePolicy, defineAccessControl, defineFactors, defineRoutes } from '@forgezero/access';
+import { externalPolicy, fulfilledActionFactors, grantsRoute, impactOfDisabling, isRefusal, isSettled } from '@forgezero/access';
+import { page, resolveActionFactors, stemOf } from '@forgezero/access';
+import type { AccessControl, AccessControlConfig, ActionPolicy, ActionRoute, AfterHandler, BeforeHandler } from '@forgezero/access';
+import type { Binding, FactorContext, FactorKind, FactorRegistry, FactorSpec, GrantOptions } from '@forgezero/access';
+import type { Method, Outcome, PageRoute, PolicySource, Problem, RatePolicy } from '@forgezero/access';
+import type { RequestContext, Role, RouteBase, RouteContract, RouteRegistry, RouteSpec } from '@forgezero/access';
+import type { SessionContext, SessionPolicy, Versioned } from '@forgezero/access';
+```
+
+## @forgezero/access — Declare routes before handlers
 
-```ts
-import { defineRoutes, authorise } from '@forgezero/access';
+Routes and their access policy are data; Fetch and Elysia adapters enforce the same declaration.
 
-const ACCESS = defineRoutes({
-  'api/invoices':        { group: 'session', factors: ['passkey'] },
-  'api/invoices/refund': { group: 'admin',   factors: ['passkey'], actionFactors: ['passkey'] }
+```text
+import { defineRoutes, action, page } from '@forgezero/access';
+
+export const routes = defineRoutes({
+  orders: page('Orders'),
+  'api/orders': action('List orders', 'GET', { page: 'orders' })
 });
+```
+
+<a id="forgezero-access-conditions"></a>
+## @forgezero/access/conditions
+
+The twelve guards every project writes into `before`, each with the status its refusal deserves. Named value imports: assertDeclaredRefusals, loadTarget, refusalsFor, requireApproval, requireBalance, requireIdempotency, requireNotFrozen, requireOwner, requireQuota, requireService, requireState, requireTier, requireUnlocked, requireVersion. Named type imports: ApprovalState, Condition, IdempotencyStore, LoadTargetOptions, RefusalSpec, RequireApprovalOptions, RequireBalanceOptions, RequireIdempotencyOptions, RequireNotFrozenOptions, RequireOwnerOptions, RequireQuotaOptions, RequireServiceOptions, RequireStateOptions, RequireTierOptions, RequireUnlockedOptions, RequireVersionOptions. Import only the names used by this file.
+
+```text
+import { assertDeclaredRefusals, loadTarget, refusalsFor, requireApproval, requireBalance, requireIdempotency } from '@forgezero/access/conditions';
+import { requireNotFrozen, requireOwner, requireQuota, requireService, requireState, requireTier } from '@forgezero/access/conditions';
+import { requireUnlocked, requireVersion } from '@forgezero/access/conditions';
+import type { ApprovalState, Condition, IdempotencyStore, LoadTargetOptions, RefusalSpec, RequireApprovalOptions } from '@forgezero/access/conditions';
+import type { RequireBalanceOptions, RequireIdempotencyOptions, RequireNotFrozenOptions, RequireOwnerOptions, RequireQuotaOptions, RequireServiceOptions } from '@forgezero/access/conditions';
+import type { RequireStateOptions, RequireTierOptions, RequireUnlockedOptions, RequireVersionOptions } from '@forgezero/access/conditions';
+```
+
+<a id="forgezero-access-effects"></a>
+## @forgezero/access/effects
+
+Audit, emit, meter, invalidate and notify — what happens after a request is decided, never failing it. Named value imports: audit, emit, invalidate, meter, notify, settlementOf. Named type imports: AuditOptions, AuditRecord, AuditSink, CacheInvalidator, Effect, EmitOptions, InvalidateOptions, MeterOptions, Notification, Notifier, NotifyOptions, Outbox, OutboxEvent, Settlement, UsageMeter. Import only the names used by this file.
+
+```text
+import { audit, emit, invalidate, meter, notify, settlementOf } from '@forgezero/access/effects';
+import type { AuditOptions, AuditRecord, AuditSink, CacheInvalidator, Effect, EmitOptions } from '@forgezero/access/effects';
+import type { InvalidateOptions, MeterOptions, Notification, Notifier, NotifyOptions, Outbox } from '@forgezero/access/effects';
+import type { OutboxEvent, Settlement, UsageMeter } from '@forgezero/access/effects';
+```
+
+<a id="forgezero-access-security"></a>
+## @forgezero/access/security
+
+Constant-time comparison, CSPRNG tokens, HMAC, HKDF, AES-GCM sealing and redaction. Web Crypto only. Named value imports: fromBase64Url, fromHex, hashToken, hkdf, hmacSha256, isLive, nowSeconds, open, randomDigits, randomHex, randomInt, randomToken, redact, seal, secretFieldPattern, sha256, timingSafeEqual, toBase64Url, toHex, verifyHmac. Named type imports: Sealed. Import only the names used by this file.
+
+```text
+import { fromBase64Url, fromHex, hashToken, hkdf, hmacSha256, isLive } from '@forgezero/access/security';
+import { nowSeconds, open, randomDigits, randomHex, randomInt, randomToken } from '@forgezero/access/security';
+import { redact, seal, secretFieldPattern, sha256, timingSafeEqual, toBase64Url } from '@forgezero/access/security';
+import { toHex, verifyHmac } from '@forgezero/access/security';
+import type { Sealed } from '@forgezero/access/security';
+```
+
+<a id="forgezero-access-rate-limit"></a>
+## @forgezero/access/rate-limit
+
+Request counters over a window — in memory, in Redis, or in a Durable Object. Named value imports: durableObjectStore, memoryStore, redisStore, slidingWindowStore. Named type imports: DurableStorageLike, RedisLike. Import only the names used by this file.
+
+```text
+import { durableObjectStore, memoryStore, redisStore, slidingWindowStore } from '@forgezero/access/rate-limit';
+import type { DurableStorageLike, RedisLike } from '@forgezero/access/rate-limit';
+```
+
+<a id="forgezero-access-fetch"></a>
+## @forgezero/access/fetch
+
+A Fetch-native adapter over the declared access pipeline. Named value imports: compileRoute, matchRoute, toFetch. Named type imports: FetchHandler. Import only the names used by this file.
+
+```text
+import { compileRoute, matchRoute, toFetch } from '@forgezero/access/fetch';
+import type { FetchHandler } from '@forgezero/access/fetch';
+```
+
+<a id="forgezero-access-pipeline"></a>
+## @forgezero/access/pipeline
+
+The framework-neutral route, principal, factor, policy, rate-limit and effects pipeline. Named value imports: createPipeline, defineHandlers, windowSeconds. Named type imports: Handler, HandlerRegistry, Pipeline, PipelineOptions, RateStore, SessionResolver, StepUpStore, Telemetry, Validator. Import only the names used by this file.
+
+```text
+import { createPipeline, defineHandlers, windowSeconds } from '@forgezero/access/pipeline';
+import type { Handler, HandlerRegistry, Pipeline, PipelineOptions, RateStore, SessionResolver } from '@forgezero/access/pipeline';
+import type { StepUpStore, Telemetry, Validator } from '@forgezero/access/pipeline';
+```
+
+<a id="forgezero-access-elysia"></a>
+## @forgezero/access/elysia
+
+Elysia integration over the same access pipeline and route declarations. Named value imports: elysia, forbiddenTelemetryAttribute, telemetryFrom, toElysiaPath. Named type imports: ElysiaAdapterOptions, OtelTracer. Import only the names used by this file.
+
+```text
+import { elysia, forbiddenTelemetryAttribute, telemetryFrom, toElysiaPath } from '@forgezero/access/elysia';
+import type { ElysiaAdapterOptions, OtelTracer } from '@forgezero/access/elysia';
+```
+
+<a id="forgezero-access-client"></a>
+## @forgezero/access/client
+
+Typed client helpers that fulfil factors without duplicating the security matrix. Named value imports: buildPath, createClient. Named type imports: ChallengeHandler, ClientOptions, ClientResult, Problem, RequestArgs, SecurityChallenge. Import only the names used by this file.
+
+```text
+import { buildPath, createClient } from '@forgezero/access/client';
+import type { ChallengeHandler, ClientOptions, ClientResult, Problem, RequestArgs, SecurityChallenge } from '@forgezero/access/client';
+```
+
+<a id="forgezero-access-testing"></a>
+## @forgezero/access/testing
+
+Deterministic access-pipeline fixtures and assertions for consumer tests. Named value imports: reachableRoutes, simulate, unreachableRoutes. Named type imports: SimulateArgs, Verdict. Import only the names used by this file.
+
+```text
+import { reachableRoutes, simulate, unreachableRoutes } from '@forgezero/access/testing';
+import type { SimulateArgs, Verdict } from '@forgezero/access/testing';
+```
+
+<a id="forgezero-access-header"></a>
+## @forgezero/access/header
+
+Strict configurable header-identity extraction with canonical names and bounded values. Named value imports: defineHeaderIdentitySources, headerIdentityResolver. Named type imports: HeaderAssignmentResolver, HeaderIdentity, HeaderIdentitySource, HeaderPrincipal. Import only the names used by this file.
+
+```text
+import { defineHeaderIdentitySources, headerIdentityResolver } from '@forgezero/access/header';
+import type { HeaderAssignmentResolver, HeaderIdentity, HeaderIdentitySource, HeaderPrincipal } from '@forgezero/access/header';
+```
+
+<a id="forgezero-access-principal"></a>
+## @forgezero/access/principal
+
+Generic principal-source resolution for browser, API-key, attestation or future identity adapters. Named value imports: assignmentIsActive, decidePrincipalAccess, defineRbacPrincipal, touchPrincipalAssignment. Named type imports: PrincipalAccessDecision, PrincipalAssignment, RbacPrincipal. Import only the names used by this file.
+
+```text
+import { assignmentIsActive, decidePrincipalAccess, defineRbacPrincipal, touchPrincipalAssignment } from '@forgezero/access/principal';
+import type { PrincipalAccessDecision, PrincipalAssignment, RbacPrincipal } from '@forgezero/access/principal';
+```
+
+<a id="forgezero-access-principal-session"></a>
+## @forgezero/access/principal-session
+
+Short-lived scope-bound delegated-principal sessions with sliding and absolute expiry. Named value imports: DEFAULT_PRINCIPAL_ABSOLUTE_TTL_MS, DEFAULT_PRINCIPAL_IDLE_TTL_MS, MAX_PRINCIPAL_ABSOLUTE_TTL_MS, MAX_PRINCIPAL_IDLE_TTL_MS, authenticatePrincipalSession, issuePrincipalSession, principalSessionIsActive, touchPrincipalSession. Named type imports: IssuedPrincipalSession, PrincipalSessionRecord. Import only the names used by this file.
+
+```text
+import { DEFAULT_PRINCIPAL_ABSOLUTE_TTL_MS, DEFAULT_PRINCIPAL_IDLE_TTL_MS, MAX_PRINCIPAL_ABSOLUTE_TTL_MS, MAX_PRINCIPAL_IDLE_TTL_MS, authenticatePrincipalSession, issuePrincipalSession } from '@forgezero/access/principal-session';
+import { principalSessionIsActive, touchPrincipalSession } from '@forgezero/access/principal-session';
+import type { IssuedPrincipalSession, PrincipalSessionRecord } from '@forgezero/access/principal-session';
+```
 
-// 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'
+<a id="forgezero-access-authenticator"></a>
+## @forgezero/access/authenticator
+
+Authentication-source contracts for adding identity mechanisms without changing route policy. Named value imports: createAuthenticator, encoding. Named type imports: AuthenticationOptions, AuthenticationResponse, Authenticator, AuthenticatorOptions, Credential, RegistrationOptions, RegistrationResponse. Import only the names used by this file.
+
+```text
+import { createAuthenticator, encoding } from '@forgezero/access/authenticator';
+import type { AuthenticationOptions, AuthenticationResponse, Authenticator, AuthenticatorOptions, Credential, RegistrationOptions } from '@forgezero/access/authenticator';
+import type { RegistrationResponse } from '@forgezero/access/authenticator';
+```
+
+<a id="forgezero-access-ceremony-modes"></a>
+## @forgezero/access/ceremony-modes
+
+Named security-ceremony modes and their session/action fulfilment semantics. Named value imports: MAX_CUSTODIANS, THRESHOLD_MODES, thresholdMode. Named type imports: ThresholdMode, ThresholdModeId. Import only the names used by this file.
+
+```text
+import { MAX_CUSTODIANS, THRESHOLD_MODES, thresholdMode } from '@forgezero/access/ceremony-modes';
+import type { ThresholdMode, ThresholdModeId } from '@forgezero/access/ceremony-modes';
+```
+
+## 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' })
 });
-if (!decision.allow) {
-  return new Response('Forbidden', { status: 403 });
+
+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.
+
+```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']
+  }
+}
+```
+
+## 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 }]
+```
+
+## 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'] })
 }
 ```
 
-Full documentation: **https://www.forgezero.net/docs/access**
+## 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.
 
-## Licence
+```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/dist/ceremony-modes.d.ts

@@ -26,46 +26,7 @@ export interface ThresholdMode {
      *  cannot read it uniformly across the set. */
     recommended: boolean;
 }
-export declare const THRESHOLD_MODES: readonly [{
-    readonly id: "1-of-2";
-    readonly threshold: 1;
-    readonly total: 2;
-    readonly label: "1 of 2";
-    readonly description: "Either custodian can unlock alone. Survives losing one person, but a single compromised custodian is enough to open the vault.";
-    readonly replicated: true;
-    readonly recommended: false;
-}, {
-    readonly id: "1-of-3";
-    readonly threshold: 1;
-    readonly total: 3;
-    readonly label: "1 of 3";
-    readonly description: "Any custodian can unlock alone. Maximum availability, minimum protection against an insider.";
-    readonly replicated: true;
-    readonly recommended: false;
-}, {
-    readonly id: "2-of-3";
-    readonly threshold: 2;
-    readonly total: 3;
-    readonly label: "2 of 3";
-    readonly description: "Two of three must convene. Survives losing one custodian, and no single person can unlock. The smallest genuinely split arrangement.";
-    readonly replicated: false;
-    readonly recommended: true;
-}, {
-    readonly id: "3-of-5";
-    readonly threshold: 3;
-    readonly total: 5;
-    readonly label: "3 of 5";
-    readonly description: "Three of five must convene. Survives losing two custodians.";
-    readonly replicated: false;
-    readonly recommended: false;
-}, {
-    readonly id: "4-of-7";
-    readonly threshold: 4;
-    readonly total: 7;
-    readonly label: "4 of 7";
-    readonly description: "Four of seven must convene. For larger governance groups.";
-    readonly replicated: false;
-    readonly recommended: false;
-}];
-export type ThresholdModeId = (typeof THRESHOLD_MODES)[number]['id'];
+export declare const MAX_CUSTODIANS = 32;
+export declare const THRESHOLD_MODES: readonly ThresholdMode[];
+export type ThresholdModeId = `${number}-of-${number}`;
 export declare function thresholdMode(id: string): ThresholdMode | undefined;

package/dist/ceremony-modes.js

@@ -1,5 +1,28 @@
 // src/ceremony-modes.ts
+var MAX_CUSTODIANS = 32;
+var majorityPreset = (threshold) => {
+  const total = threshold * 2 - 1;
+  return {
+    id: `${threshold}-of-${total}`,
+    threshold,
+    total,
+    label: `${threshold} of ${total}`,
+    description: `${threshold} of ${total} custodians must convene. Survives losing ${total - threshold} custodians.`,
+    replicated: false,
+    recommended: threshold === 2
+  };
+};
+var MAJORITY_PRESETS = Array.from({ length: 15 }, (_, index) => majorityPreset(index + 2));
 var THRESHOLD_MODES = [
+  {
+    id: "1-of-1",
+    threshold: 1,
+    total: 1,
+    label: "1 of 1",
+    description: "Bootstrap only: the first platform custodian brings custody online alone, then rotates to the long-term quorum.",
+    replicated: true,
+    recommended: false
+  },
   {
     id: "1-of-2",
     threshold: 1,
@@ -18,38 +41,31 @@ var THRESHOLD_MODES = [
     replicated: true,
     recommended: false
   },
-  {
-    id: "2-of-3",
-    threshold: 2,
-    total: 3,
-    label: "2 of 3",
-    description: "Two of three must convene. Survives losing one custodian, and no single person can unlock. The smallest genuinely split arrangement.",
-    replicated: false,
-    recommended: true
-  },
-  {
-    id: "3-of-5",
-    threshold: 3,
-    total: 5,
-    label: "3 of 5",
-    description: "Three of five must convene. Survives losing two custodians.",
-    replicated: false,
-    recommended: false
-  },
-  {
-    id: "4-of-7",
-    threshold: 4,
-    total: 7,
-    label: "4 of 7",
-    description: "Four of seven must convene. For larger governance groups.",
-    replicated: false,
-    recommended: false
-  }
+  ...MAJORITY_PRESETS
 ];
 function thresholdMode(id) {
-  return THRESHOLD_MODES.find((mode) => mode.id === id);
+  const preset = THRESHOLD_MODES.find((mode) => mode.id === id);
+  if (preset)
+    return preset;
+  const match = /^(\d{1,2})-of-(\d{1,2})$/.exec(id);
+  if (!match)
+    return;
+  const threshold = Number(match[1]);
+  const total = Number(match[2]);
+  if (!Number.isSafeInteger(threshold) || !Number.isSafeInteger(total) || threshold < 1 || total < 1 || threshold > total || total > MAX_CUSTODIANS)
+    return;
+  return {
+    id: `${threshold}-of-${total}`,
+    threshold,
+    total,
+    label: `${threshold} of ${total}`,
+    description: threshold === 1 ? `Any one of ${total} custodians can unlock alone.` : `${threshold} of ${total} custodians must convene.`,
+    replicated: threshold === 1,
+    recommended: false
+  };
 }
 export {
   thresholdMode,
-  THRESHOLD_MODES
+  THRESHOLD_MODES,
+  MAX_CUSTODIANS
 };

package/dist/conditions.js

@@ -275,7 +275,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.4";
 
 // src/conditions.ts
 function define(condition, routes, refusals, run) {

package/dist/effects.js

@@ -275,7 +275,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.4";
 
 // src/security.ts
 var HEX = Array.from({ length: 256 }, (_, index) => index.toString(16).padStart(2, "0"));

package/dist/elysia.js

@@ -275,7 +275,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.4";
 
 // src/pipeline.ts
 function defineHandlers(routes, handlers) {

package/dist/fetch.js

@@ -275,7 +275,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.4";
 
 // src/pipeline.ts
 function defineHandlers(routes, handlers) {

package/dist/header.js

@@ -275,7 +275,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.4";
 
 // src/principal.ts
 var ATOM = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/;

package/dist/index.d.ts

@@ -379,4 +379,4 @@ export declare function impactOfDisabling<R extends RouteRegistry>(access: Acces
     available: number;
     required: number;
 }[];
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.4";

package/dist/index.js

@@ -275,7 +275,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.4";
 export {
   stemOf,
   resolveActionFactors,

package/dist/pipeline.js

@@ -275,7 +275,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.4";
 
 // src/pipeline.ts
 function defineHandlers(routes, handlers) {

package/dist/principal-session.js

@@ -275,7 +275,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.4";
 
 // src/security.ts
 var HEX = Array.from({ length: 256 }, (_, index) => index.toString(16).padStart(2, "0"));

package/dist/principal.js

@@ -275,7 +275,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.4";
 
 // src/principal.ts
 var ATOM = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,255}$/;

package/dist/testing.js

@@ -275,7 +275,7 @@ function impactOfDisabling(access, enabledAfter) {
   }
   return broken;
 }
-var VERSION = "0.1.0";
+var VERSION = "0.1.4";
 
 // src/testing.ts
 function nameOf(policies, route) {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@forgezero/access",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "publishConfig": {
     "access": "public",
-    "provenance": true
+    "provenance": false
   },
   "exports": {
     ".": {
@@ -68,17 +68,16 @@
       "default": "./dist/ceremony-modes.js"
     }
   },
-	"scripts": {
-		"check": "tsc --noEmit",
-		"prebuild": "rm -rf dist",
-    "build": "bun build src/index.ts src/fetch.ts src/pipeline.ts src/elysia.ts src/client.ts src/testing.ts src/rate-limit.ts src/security.ts src/header.ts src/principal.ts src/principal-session.ts src/conditions.ts src/effects.ts src/authenticator.ts src/ceremony-modes.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
-    "prepublishOnly": "bun run check && bun run build"
+  "scripts": {
+    "check": "tsc --noEmit",
+    "build": "bun ../tools/package-task.ts build access",
+    "prepublishOnly": "bun ../tools/package-task.ts prepublish access"
   },
   "devDependencies": {
     "typescript": "^5.6.0",
     "@types/bun": "latest"
   },
-  "description": "Route matrix, RBAC and security factors. Zero runtime dependencies \u2014 runs anywhere fetch does.",
+  "description": "Route matrix, RBAC and security factors. Zero runtime dependencies — runs anywhere fetch does.",
   "keywords": [
     "rbac",
     "authorization",