@forgezero/access 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeZero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @forgezero/access
+
+**Who may call what, decided from one table instead of scattered `if` statements.**
+
+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.
+
+Zero runtime dependencies. Bun, Node 18+, Deno, Cloudflare Workers, browsers —
+anywhere `fetch` and Web Crypto exist.
+
+```bash
+bun add @forgezero/access
+```
+
+## The idea in twelve lines
+
+```ts
+import { defineRoutes, authorise } from '@forgezero/access';
+
+const ACCESS = defineRoutes({
+  'api/invoices':        { group: 'session', factors: ['passkey'] },
+  'api/invoices/refund': { group: 'admin',   factors: ['passkey'], actionFactors: ['passkey'] }
+});
+
+// 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 |
+
+Full documentation: **https://forgezero.net/docs/access**
+
+## Licence
+
+MIT. Part of [ForgeZero](https://forgezero.net) — secrets, attested compute and
+deploys — and usable entirely on its own, with no ForgeZero account.

package/dist/authenticator.d.ts

@@ -0,0 +1,118 @@
+/**
+ * A software WebAuthn authenticator, for tests.
+ *
+ * Passkeys are the wall every integration test hits. Registration and assertion
+ * need a real authenticator, so the usual answer is to stub the verifier — which
+ * removes the one thing worth testing and leaves every route behind it unproven.
+ * ForgeZero hit exactly that: the custodian ceremony, admin routes, tenant
+ * provisioning and the vault all sit behind a passkey, so none of them had ever
+ * been exercised end to end.
+ *
+ * This produces genuine credentials: real P-256 keys, real ES256 signatures over
+ * `authenticatorData || SHA-256(clientDataJSON)`, real CBOR attestation. A real
+ * verifier accepts them, and a tampered one is rejected — which is what makes it
+ * a test rather than a bypass.
+ *
+ * ## Deliberately NOT a security boundary
+ *
+ * The private key lives in memory and never leaves the process. Nothing here
+ * belongs in a production path, and nothing here weakens one: the server code
+ * under test is unchanged and unaware.
+ *
+ * ## PRF
+ *
+ * The PRF extension is what a custodian's share envelope is sealed with, so an
+ * authenticator without it cannot test custody at all. A real authenticator
+ * computes HMAC over a per-credential secret; so does this, which makes the
+ * output stable across assertions for one credential and unrelated between
+ * credentials — the two properties the envelope scheme depends on.
+ */
+type CborValue = number | string | Uint8Array | Map<CborValue, CborValue>;
+declare function cbor(value: CborValue): Uint8Array;
+/**
+ * Web Crypto returns ECDSA as raw `r || s`; WebAuthn verifiers expect DER.
+ *
+ * Skipping this conversion produces a signature that is the right length, looks
+ * plausible, and fails verification with no useful message — which is a long
+ * afternoon the first time.
+ */
+declare function toDer(raw: Uint8Array): Uint8Array;
+/** Matches @simplewebauthn's RegistrationResponseJSON closely enough to pass to it. */
+export interface RegistrationResponse {
+    id: string;
+    rawId: string;
+    type: 'public-key';
+    clientExtensionResults: Record<string, unknown>;
+    authenticatorAttachment?: 'platform' | 'cross-platform';
+    response: {
+        clientDataJSON: string;
+        attestationObject: string;
+        transports?: string[];
+    };
+}
+export interface AuthenticationResponse {
+    id: string;
+    rawId: string;
+    type: 'public-key';
+    clientExtensionResults: Record<string, unknown>;
+    response: {
+        clientDataJSON: string;
+        authenticatorData: string;
+        signature: string;
+        userHandle?: string;
+    };
+}
+export interface Credential {
+    id: string;
+    userHandle?: string;
+    signCount: number;
+}
+export interface AuthenticatorOptions {
+    rpId: string;
+    origin: string;
+    /** Off reproduces an authenticator that does not support PRF — worth testing. */
+    prf?: boolean;
+    /** Off makes `uv` false, so a route demanding user verification refuses. */
+    userVerified?: boolean;
+}
+/** Whatever `startRegistration` returned. Only these fields are read. */
+export interface RegistrationOptions {
+    challenge: string;
+    user?: {
+        id?: string;
+    };
+    rp?: {
+        id?: string;
+    };
+}
+export interface AuthenticationOptions {
+    challenge: string;
+    allowCredentials?: readonly {
+        id: string;
+    }[];
+}
+export declare function createAuthenticator(options: AuthenticatorOptions): {
+    /** Create a credential. The response is what a browser would post back. */
+    register(registration: RegistrationOptions): Promise<RegistrationResponse>;
+    /** Assert. Picks the allowed credential, or the only one when unconstrained. */
+    authenticate(authentication: AuthenticationOptions): Promise<AuthenticationResponse>;
+    /**
+     * PRF output for a salt — the key a custodian's share envelope is sealed
+     * with. Stable for one credential, unrelated between credentials, and
+     * unavailable when the device does not support the extension.
+     */
+    prf(salt: string | Uint8Array, credentialId?: string): Promise<Uint8Array>;
+    list: () => readonly Credential[];
+    /** Simulate a lost device, which is what the recovery path exists for. */
+    forget(credentialId?: string): void;
+};
+export type Authenticator = ReturnType<typeof createAuthenticator>;
+/** Exposed for tests that assert a tampered signature is actually rejected. */
+export declare const encoding: {
+    b64url: (bytes: Uint8Array) => string;
+    fromB64url: (value: string) => Uint8Array;
+    toDer: typeof toDer;
+    cbor: typeof cbor;
+    sha256: (bytes: Uint8Array) => Promise<Uint8Array>;
+};
+export {};

package/dist/authenticator.js

@@ -0,0 +1,186 @@
+// src/authenticator.ts
+function cborHead(major, value) {
+  if (value < 24)
+    return new Uint8Array([major << 5 | value]);
+  if (value < 256)
+    return new Uint8Array([major << 5 | 24, value]);
+  if (value < 65536)
+    return new Uint8Array([major << 5 | 25, value >> 8, value & 255]);
+  return new Uint8Array([
+    major << 5 | 26,
+    value >>> 24 & 255,
+    value >>> 16 & 255,
+    value >>> 8 & 255,
+    value & 255
+  ]);
+}
+var concat = (...parts) => {
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+};
+function cbor(value) {
+  if (typeof value === "number") {
+    return value < 0 ? cborHead(1, -value - 1) : cborHead(0, value);
+  }
+  if (typeof value === "string") {
+    const bytes = new TextEncoder().encode(value);
+    return concat(cborHead(3, bytes.length), bytes);
+  }
+  if (value instanceof Uint8Array)
+    return concat(cborHead(2, value.length), value);
+  const entries = [...value.entries()];
+  return concat(cborHead(5, entries.length), ...entries.map(([key, item]) => concat(cbor(key), cbor(item))));
+}
+function toDer(raw) {
+  const trim = (part) => {
+    let at = 0;
+    while (at < part.length - 1 && part[at] === 0)
+      at += 1;
+    const trimmed = part.slice(at);
+    return trimmed[0] & 128 ? concat(new Uint8Array([0]), trimmed) : trimmed;
+  };
+  const r = trim(raw.slice(0, 32));
+  const s = trim(raw.slice(32));
+  const body = concat(new Uint8Array([2, r.length]), r, new Uint8Array([2, s.length]), s);
+  return concat(new Uint8Array([48, body.length]), body);
+}
+var b64url = (bytes) => {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+var fromB64url = (value) => {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(padded + "=".repeat((4 - padded.length % 4) % 4));
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+};
+var sha256 = async (bytes) => new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+var AAGUID = new Uint8Array(16);
+function createAuthenticator(options) {
+  const { rpId, origin, prf = true, userVerified = true } = options;
+  const credentials = new Map;
+  const authData = async (credential, attested) => {
+    const rpIdHash = await sha256(new TextEncoder().encode(rpId));
+    let flags = 1;
+    if (userVerified)
+      flags |= 4;
+    if (attested)
+      flags |= 64;
+    const counter = new Uint8Array(4);
+    new DataView(counter.buffer).setUint32(0, credential?.signCount ?? 0, false);
+    if (!attested || !credential)
+      return concat(rpIdHash, new Uint8Array([flags]), counter);
+    const raw = await crypto.subtle.exportKey("raw", credential.keys.publicKey);
+    const point = new Uint8Array(raw);
+    const cose = cbor(new Map([
+      [1, 2],
+      [3, -7],
+      [-1, 1],
+      [-2, point.slice(1, 33)],
+      [-3, point.slice(33, 65)]
+    ]));
+    const idLength = new Uint8Array(2);
+    new DataView(idLength.buffer).setUint16(0, credential.id.length, false);
+    return concat(rpIdHash, new Uint8Array([flags]), counter, AAGUID, idLength, credential.id, cose);
+  };
+  const clientData = (type, challenge) => new TextEncoder().encode(JSON.stringify({ type, challenge, origin, crossOrigin: false }));
+  const sign = async (credential, data, clientDataJSON) => {
+    const signed = concat(data, await sha256(clientDataJSON));
+    const raw = new Uint8Array(await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, credential.keys.privateKey, signed));
+    return toDer(raw);
+  };
+  return {
+    async register(registration) {
+      const keys = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, false, [
+        "sign",
+        "verify"
+      ]);
+      const id = new Uint8Array(32);
+      crypto.getRandomValues(id);
+      const prfSecret = new Uint8Array(32);
+      crypto.getRandomValues(prfSecret);
+      const credential = {
+        id,
+        keys,
+        userHandle: registration.user?.id,
+        prfSecret,
+        signCount: 0
+      };
+      credentials.set(b64url(id), credential);
+      const clientDataJSON = clientData("webauthn.create", registration.challenge);
+      const attestation = cbor(new Map([
+        ["fmt", "none"],
+        ["attStmt", new Map],
+        ["authData", await authData(credential, true)]
+      ]));
+      return {
+        id: b64url(id),
+        rawId: b64url(id),
+        type: "public-key",
+        authenticatorAttachment: "platform",
+        clientExtensionResults: prf ? { prf: { enabled: true } } : {},
+        response: {
+          clientDataJSON: b64url(clientDataJSON),
+          attestationObject: b64url(attestation),
+          transports: ["internal", "hybrid"]
+        }
+      };
+    },
+    async authenticate(authentication) {
+      const allowed = authentication.allowCredentials?.[0]?.id;
+      const key = allowed ?? [...credentials.keys()][0];
+      const credential = key ? credentials.get(key) : undefined;
+      if (!credential)
+        throw new Error("This authenticator holds no credential for that request.");
+      credential.signCount += 1;
+      const clientDataJSON = clientData("webauthn.get", authentication.challenge);
+      const data = await authData(credential, false);
+      return {
+        id: b64url(credential.id),
+        rawId: b64url(credential.id),
+        type: "public-key",
+        clientExtensionResults: {},
+        response: {
+          clientDataJSON: b64url(clientDataJSON),
+          authenticatorData: b64url(data),
+          signature: b64url(await sign(credential, data, clientDataJSON)),
+          ...credential.userHandle ? { userHandle: credential.userHandle } : {}
+        }
+      };
+    },
+    async prf(salt, credentialId) {
+      if (!prf)
+        throw new Error("This authenticator does not support the PRF extension.");
+      const key = credentialId ?? [...credentials.keys()][0];
+      const credential = key ? credentials.get(key) : undefined;
+      if (!credential)
+        throw new Error("This authenticator holds no credential.");
+      const imported = await crypto.subtle.importKey("raw", credential.prfSecret, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+      const bytes = typeof salt === "string" ? new TextEncoder().encode(salt) : salt;
+      return new Uint8Array(await crypto.subtle.sign("HMAC", imported, bytes));
+    },
+    list: () => [...credentials.entries()].map(([id, credential]) => ({
+      id,
+      userHandle: credential.userHandle,
+      signCount: credential.signCount
+    })),
+    forget(credentialId) {
+      if (credentialId)
+        credentials.delete(credentialId);
+      else
+        credentials.clear();
+    }
+  };
+}
+var encoding = { b64url, fromB64url, toDer, cbor, sha256 };
+export {
+  encoding,
+  createAuthenticator
+};

package/dist/ceremony-modes.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Custodian threshold modes.
+ *
+ * A closed set chosen at ceremony time rather than free-form M and N. Two
+ * reasons: a typo like 7-of-3 is unrepresentable, and every mode here has been
+ * thought about — an operator picking numbers in a form has not.
+ */
+export interface ThresholdMode {
+    id: string;
+    /** M — how many custodians must convene to unlock. */
+    threshold: number;
+    /** N — how many shares exist in total. */
+    total: number;
+    label: string;
+    description: string;
+    /**
+     * True when a single custodian can unlock alone. Shamir needs threshold >= 2,
+     * so these modes REPLICATE the seed instead of splitting it: every custodian
+     * holds the whole thing. That is a real weakening — one compromised custodian
+     * is a compromised vault — and it is why these are marked rather than mixed
+     * in silently.
+     */
+    replicated: boolean;
+    /** Stated on EVERY mode, not just the recommended one: an optional field
+     *  disappears from the literal type where it is absent, and a consumer then
+     *  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 function thresholdMode(id: string): ThresholdMode | undefined;

package/dist/ceremony-modes.js

@@ -0,0 +1,55 @@
+// src/ceremony-modes.ts
+var THRESHOLD_MODES = [
+  {
+    id: "1-of-2",
+    threshold: 1,
+    total: 2,
+    label: "1 of 2",
+    description: "Either custodian can unlock alone. Survives losing one person, but a single compromised custodian is enough to open the vault.",
+    replicated: true,
+    recommended: false
+  },
+  {
+    id: "1-of-3",
+    threshold: 1,
+    total: 3,
+    label: "1 of 3",
+    description: "Any custodian can unlock alone. Maximum availability, minimum protection against an insider.",
+    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
+  }
+];
+function thresholdMode(id) {
+  return THRESHOLD_MODES.find((mode) => mode.id === id);
+}
+export {
+  thresholdMode,
+  THRESHOLD_MODES
+};

package/dist/client.d.ts

@@ -0,0 +1,76 @@
+import type { RouteRegistry } from './index';
+/**
+ * The typed client, and the other half of the 428 handshake.
+ *
+ * Generated from the same declarations the server enforces, so a route that
+ * changes its body shape changes the client's types in the same commit. There
+ * is no second source to drift from.
+ *
+ * ## Why the handshake lives here
+ *
+ * The server answers 428 with a one-time key and the factors it will accept.
+ * Something has to mint a proof and replay the original request with that key
+ * attached — and without it `stepUp` is a wall rather than a challenge. That
+ * was specified server-side for a long time with nobody implementing the other
+ * end.
+ *
+ * The replay MUST surface the action's own failure. Security passing while the
+ * write fails is otherwise completely silent: the caller sees a resolved
+ * promise, the record is unchanged, and nothing anywhere says why.
+ */
+export interface Problem {
+    code: string;
+    message: string;
+}
+export type ClientResult<T> = {
+    ok: true;
+    status: number;
+    data: T;
+} | {
+    ok: false;
+    status: number;
+    error: Problem;
+    errors?: readonly {
+        path: string;
+        message: string;
+    }[];
+};
+export interface SecurityChallenge {
+    scope: 'session' | 'action';
+    route: string;
+    factors: readonly string[];
+    required: number;
+    requestKey: string;
+}
+/**
+ * Turns a challenge into proofs. Supplied by the host, because how a passkey or
+ * a TOTP code is collected is a UI decision the client cannot make.
+ *
+ * Returning `undefined` means the human declined — a cancel, not an error, and
+ * the original 428 is surfaced unchanged.
+ */
+export interface ChallengeHandler {
+    (challenge: SecurityChallenge): Promise<{
+        factor: string;
+        proof: unknown;
+    }[] | undefined>;
+}
+export interface ClientOptions {
+    baseUrl: string;
+    onChallenge?: ChallengeHandler;
+    fetch?: typeof globalThis.fetch;
+    headers?: Record<string, string>;
+    /** Path that accepts a proof against a request key. */
+    fulfilPath?: string;
+}
+export interface RequestArgs {
+    params?: Record<string, string>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** `api/orders/[id]` + `{id:'7'}` → `/api/orders/7` */
+export declare function buildPath(routeKey: string, params?: Record<string, string>): string;
+export declare function createClient<R extends RouteRegistry>(routes: R, options: ClientOptions): { [K in keyof R as R[K] extends {
+    kind: "action";
+} ? K : never]: (args?: RequestArgs) => Promise<ClientResult<unknown>>; };