@forgezero/access 0.1.0

package/dist/client.js

@@ -0,0 +1,107 @@
+// src/client.ts
+function buildPath(routeKey, params = {}) {
+  return "/" + routeKey.split("/").map((segment) => {
+    const named = /^\[(?:\.\.\.)?(\w+)\]$/.exec(segment);
+    if (!named)
+      return segment;
+    const value = params[named[1]];
+    if (value === undefined) {
+      throw new Error(`Missing route parameter "${named[1]}" for ${routeKey}`);
+    }
+    return encodeURIComponent(value);
+  }).join("/");
+}
+function withQuery(path, query) {
+  if (!query)
+    return path;
+  const search = new URLSearchParams;
+  for (const [name, value] of Object.entries(query)) {
+    if (value !== undefined && value !== null)
+      search.set(name, String(value));
+  }
+  const encoded = search.toString();
+  return encoded ? `${path}?${encoded}` : path;
+}
+function createClient(routes, options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const fulfilPath = options.fulfilPath ?? "/api/security/fulfil";
+  async function send(routeKey, method, args, requestKey) {
+    const path = withQuery(buildPath(routeKey, args.params), args.query);
+    const response = await doFetch(options.baseUrl + path, {
+      method,
+      credentials: "include",
+      headers: {
+        "content-type": "application/json",
+        ...options.headers,
+        ...args.headers,
+        ...requestKey ? { "x-security-request-key": requestKey } : {}
+      },
+      body: args.body === undefined ? undefined : JSON.stringify(args.body)
+    });
+    const payload = await response.json().catch(() => {
+      return;
+    });
+    if (response.ok) {
+      return { ok: true, status: response.status, data: payload };
+    }
+    if (response.status === 428) {
+      const key = response.headers.get("x-security-request-key");
+      if (key) {
+        return {
+          ok: false,
+          status: 428,
+          error: payload?.error ?? { code: "SECURITY_REQUIRED", message: "Security check required." },
+          errors: payload?.security ? [{ path: "", message: JSON.stringify({ ...payload.security, requestKey: key }) }] : undefined
+        };
+      }
+    }
+    return {
+      ok: false,
+      status: response.status,
+      error: payload?.error ?? { code: "REQUEST_FAILED", message: response.statusText },
+      errors: payload?.errors
+    };
+  }
+  async function call(routeKey, method, args) {
+    const first = await send(routeKey, method, args);
+    if (first.ok || first.status !== 428 || !options.onChallenge)
+      return first;
+    const encoded = first.errors?.[0]?.message;
+    if (!encoded)
+      return first;
+    const challenge = JSON.parse(encoded);
+    const proofs = await options.onChallenge(challenge);
+    if (!proofs?.length)
+      return first;
+    const fulfilled = await doFetch(options.baseUrl + fulfilPath, {
+      method: "POST",
+      credentials: "include",
+      headers: { "content-type": "application/json", ...options.headers },
+      body: JSON.stringify({ requestKey: challenge.requestKey, proofs })
+    });
+    if (!fulfilled.ok) {
+      const payload = await fulfilled.json().catch(() => {
+        return;
+      });
+      return {
+        ok: false,
+        status: fulfilled.status,
+        error: payload?.error ?? { code: "SECURITY_FAILED", message: "The security check was not accepted." }
+      };
+    }
+    return send(routeKey, method, args, challenge.requestKey);
+  }
+  const api = {};
+  for (const key of Object.keys(routes)) {
+    const route = routes[key];
+    if (route.kind !== "action")
+      continue;
+    const method = route.method;
+    api[key] = (args = {}) => call(key, method, args);
+  }
+  return api;
+}
+export {
+  createClient,
+  buildPath
+};

package/dist/conditions.d.ts

@@ -0,0 +1,280 @@
+import { type BeforeHandler, type RequestContext } from './index';
+/**
+ * Conditions — the reusable `before` catalog.
+ *
+ * Every project rewrites the same twelve guards: load the record or 404, check
+ * it belongs to the caller, check its status allows this transition, check the
+ * balance, check the idempotency key, check the version. Written per route they
+ * drift; written per project they drift between projects. Written once here
+ * they are one thing to get right, and every project that adopts them inherits
+ * the fixes.
+ *
+ * ## What a condition is
+ *
+ * A `BeforeHandler` that either merges state or throws a `Refusal` carrying the
+ * status the client deserves. It never returns a response and never decides
+ * business outcomes — it decides whether the handler is allowed to run at all.
+ *
+ * ## Why they declare their refusals
+ *
+ * Each carries `refusals`, so the set of statuses a route can produce is
+ * derivable rather than hand-maintained. `assertDeclaredRefusals` uses it to
+ * fail the build when a route's `response` map omits a status its own
+ * conditions can throw — the drift that produces a client crashing on a 409 it
+ * was never told about.
+ *
+ * ## Order matters and is not enforced here
+ *
+ * `loadTarget` must precede anything reading the record. The pipeline runs the
+ * chain in declaration order and merges state as it goes, so the ordering lives
+ * in the declaration list where it is visible, not in a dependency graph nobody
+ * reads.
+ */
+export interface RefusalSpec {
+    status: number;
+    code: string;
+    /** One clause, present tense: what has to be true for this to fire. */
+    when: string;
+}
+export interface Condition<K extends string> extends BeforeHandler<K> {
+    /** Stable name — appears in flow documentation and telemetry. */
+    condition: string;
+    refusals: readonly RefusalSpec[];
+}
+type State = Record<string, unknown>;
+type Routes<K extends string> = {
+    routes: readonly K[];
+};
+export interface LoadTargetOptions<K extends string> extends Routes<K> {
+    /** State key the record lands under. Defaults to `target`. */
+    as?: string;
+    /** Where the identifier comes from. Defaults to a `id` path parameter. */
+    id?: (context: RequestContext) => string | undefined;
+    load: (id: string, context: RequestContext) => Promise<unknown> | unknown;
+    /** Refusal code. Defaults to NOT_FOUND — see the note on 404 below. */
+    code?: string;
+}
+/**
+ * Load the record this request acts on, or 404.
+ *
+ * First in almost every chain, for two reasons beyond the obvious. Step 8 binds
+ * a step-up proof to a specific record, which requires the record; and a
+ * condition that reads the database twice — once to check, once in the handler —
+ * is a TOCTOU window somebody will eventually land in.
+ */
+export declare function loadTarget<K extends string>(options: LoadTargetOptions<K>): Condition<K>;
+export interface RequireOwnerOptions<K extends string> extends Routes<K> {
+    of?: string;
+    owner: (record: never) => string | undefined;
+    /** Defaults to the session user. A tenant app passes the realm instead. */
+    subject?: (context: RequestContext) => string | undefined;
+}
+/**
+ * The record belongs to the caller — otherwise 404, deliberately not 403.
+ *
+ * A 403 confirms the record exists, which turns any sequential identifier into
+ * an enumeration oracle: an attacker walks the range and learns exactly which
+ * accounts, orders or entries are real. Answering 404 makes "not yours" and
+ * "not there" indistinguishable, which is the only honest answer to give
+ * somebody who should not know either way.
+ */
+export declare function requireOwner<K extends string>(options: RequireOwnerOptions<K>): Condition<K>;
+export interface RequireStateOptions<K extends string> extends Routes<K> {
+    of?: string;
+    status: (record: never) => string;
+    allowed: readonly string[];
+    code?: string;
+}
+/**
+ * The record is in a status this transition accepts, or 409.
+ *
+ * The guard that stops a withdrawal being approved twice, an invoice being
+ * settled after it was voided, a ceremony activating from a state it never
+ * reached. Checking status inside the handler works right up to the second
+ * concurrent request, and this at least fails them both loudly and with the
+ * allowed set in the payload so the UI can explain itself.
+ */
+export declare function requireState<K extends string>(options: RequireStateOptions<K>): Condition<K>;
+export interface RequireVersionOptions<K extends string> extends Routes<K> {
+    of?: string;
+    version: (record: never) => string | number;
+    /** Defaults to `If-Match`, falling back to a `version` body field. */
+    expected?: (context: RequestContext) => string | number | undefined;
+}
+/**
+ * Optimistic concurrency — 412 when the record moved under the caller.
+ *
+ * Last-write-wins is not a decision anybody makes on purpose; it is what you get
+ * by not making one. Two operators editing the same policy silently lose one of
+ * the edits, and nothing anywhere records that it happened.
+ */
+export declare function requireVersion<K extends string>(options: RequireVersionOptions<K>): Condition<K>;
+export interface IdempotencyStore {
+    /**
+     * Claim the key. `fresh` means proceed; `replay` carries the stored answer;
+     * `pending` means an identical request is still running.
+     *
+     * Must be atomic — a get-then-set implementation reintroduces exactly the
+     * double-spend this exists to prevent.
+     */
+    claim(key: string, route: string): Promise<{
+        state: 'fresh';
+    } | {
+        state: 'replay';
+        value: unknown;
+        status: number;
+    } | {
+        state: 'pending';
+    }>;
+}
+export interface RequireIdempotencyOptions<K extends string> extends Routes<K> {
+    store: IdempotencyStore;
+    /** Defaults to the `Idempotency-Key` header. */
+    key?: (context: RequestContext) => string | undefined;
+    /** True refuses a request without a key. Correct for anything that moves money. */
+    strict?: boolean;
+}
+/**
+ * At-most-once, for requests that must not happen twice.
+ *
+ * A retry after a timeout is not a client bug — it is what every HTTP client and
+ * every mobile network does. Without a claim the second attempt places a second
+ * order, and the user sees one confirmation for two withdrawals.
+ *
+ * A replay throws `Settled`, so the caller gets the ORIGINAL answer rather than
+ * an error. A 409 would be defensible and useless: a retrying client still would
+ * not learn the transfer succeeded.
+ */
+export declare function requireIdempotency<K extends string>(options: RequireIdempotencyOptions<K>): Condition<K>;
+export interface RequireUnlockedOptions<K extends string> extends Routes<K> {
+    unlocked: () => boolean | Promise<boolean>;
+}
+/**
+ * The vault is unlocked, or 423.
+ *
+ * 423 rather than 503 because the distinction is actionable: 503 says wait, 423
+ * says a human must unlock something. A client that retries a 423 forever is a
+ * client nobody told the difference.
+ */
+export declare function requireUnlocked<K extends string>(options: RequireUnlockedOptions<K>): Condition<K>;
+export interface RequireServiceOptions<K extends string> extends Routes<K> {
+    service: string;
+    /** Satisfied by a `@forgezero/providers` registry health check. */
+    healthy: (service: string) => boolean | Promise<boolean>;
+}
+/**
+ * A provider for this service is reachable, or 503 — checked before the handler
+ * does work it will have to undo.
+ *
+ * The failure this prevents is subtle: a route that writes a record and then
+ * sends an email leaves the record behind when every relay is down, and the
+ * user retries into a duplicate.
+ */
+export declare function requireService<K extends string>(options: RequireServiceOptions<K>): Condition<K>;
+export interface RequireNotFrozenOptions<K extends string> extends Routes<K> {
+    /** Return a reason to freeze; undefined to allow. */
+    frozen: (context: RequestContext, state: State) => Promise<string | undefined> | string | undefined;
+}
+/**
+ * Nothing has administratively halted this subject, or 423.
+ *
+ * Separate from status because it is orthogonal: an order can be perfectly valid
+ * and still not permitted to move because the account is under review, the asset
+ * is halted, or an operator pulled the switch. Folding it into a status enum
+ * means every state machine grows a `frozen` member and every transition has to
+ * remember it.
+ */
+export declare function requireNotFrozen<K extends string>(options: RequireNotFrozenOptions<K>): Condition<K>;
+export interface RequireTierOptions<K extends string> extends Routes<K> {
+    atLeast: number;
+    tier: (context: RequestContext, state: State) => Promise<number> | number;
+    /** Names the ladder, so the client knows where to send the user. */
+    ladder?: string;
+    code?: string;
+}
+/**
+ * The subject has reached a level, or 403 naming the gap.
+ *
+ * One mechanism, two uses that are the same shape: a plan tier gating a feature,
+ * and a verification tier gating an amount. Both are "a monotonic level the
+ * subject must have reached", and both need the CURRENT level in the refusal or
+ * the UI cannot render anything better than "denied".
+ */
+export declare function requireTier<K extends string>(options: RequireTierOptions<K>): Condition<K>;
+export interface RequireBalanceOptions<K extends string> extends Routes<K> {
+    /** Minor units. Never a float — see the note below. */
+    amount: (context: RequestContext, state: State) => Promise<bigint> | bigint;
+    available: (context: RequestContext, state: State) => Promise<bigint> | bigint;
+    asset?: (context: RequestContext, state: State) => string | undefined;
+}
+/**
+ * Enough available balance, or 409.
+ *
+ * `bigint` minor units, not `number`. A double cannot hold 0.1 + 0.2, and it
+ * cannot hold satoshi precision above ~90 million BTC-equivalents at all; the
+ * rounding shows up as a ledger that fails to balance by a few units a month
+ * and nobody can say why. Refusing a float at the type level is cheaper than
+ * finding that later.
+ *
+ * This checks AVAILABLE — free of holds — not total. A balance check against
+ * total lets two concurrent withdrawals each pass and the second overdraws.
+ */
+export declare function requireBalance<K extends string>(options: RequireBalanceOptions<K>): Condition<K>;
+export interface RequireQuotaOptions<K extends string> extends Routes<K> {
+    /** `24h`, `30d` — documentation for the client, the store owns the window. */
+    window: string;
+    cap: (context: RequestContext, state: State) => Promise<bigint> | bigint;
+    amount: (context: RequestContext, state: State) => Promise<bigint> | bigint;
+    used: (context: RequestContext, state: State) => Promise<bigint> | bigint;
+    code?: string;
+}
+/**
+ * A value cap over a window, which is NOT a rate limit.
+ *
+ * Rate limiting counts requests and protects the service; a quota counts value
+ * and protects the account. One withdrawal of the entire balance passes every
+ * rate limit ever written. They also fail differently — 429 means slow down,
+ * this means the answer will be the same until the window rolls — so they get
+ * different codes and the reset time is in the payload.
+ */
+export declare function requireQuota<K extends string>(options: RequireQuotaOptions<K>): Condition<K>;
+export interface ApprovalState {
+    status: 'pending' | 'approved' | 'rejected';
+    approvals?: number;
+    required?: number;
+    reason?: string;
+}
+export interface RequireApprovalOptions<K extends string> extends Routes<K> {
+    approval: (context: RequestContext, state: State) => Promise<ApprovalState> | ApprovalState;
+}
+/**
+ * Somebody ELSE approved this — which is not what action factors check.
+ *
+ * Action factors make the actor prove themselves freshly. This makes a second
+ * party sign off, and no amount of the first kind substitutes for the second:
+ * that is the entire point of four-eyes on a large withdrawal or a custodian
+ * change. Two mechanisms because they answer different questions, and merging
+ * them would let a sufficiently authenticated operator approve their own move.
+ */
+export declare function requireApproval<K extends string>(options: RequireApprovalOptions<K>): Condition<K>;
+/**
+ * Every status a route's conditions can throw is declared in its contract.
+ *
+ * The drift this catches: somebody adds `requireQuota` to a withdrawal route,
+ * the generated client never learns 409 is possible, and the UI renders "an
+ * unexpected error occurred" for the one refusal a user can actually act on.
+ * Cheap to check, invisible until a customer hits it.
+ */
+export declare function assertDeclaredRefusals(args: {
+    routes: Record<string, {
+        response?: Record<number, unknown>;
+    }>;
+    conditions: readonly Condition<string>[];
+    /** Statuses handled centrally rather than per route. */
+    ignore?: readonly number[];
+}): void;
+/** Every refusal a route can produce, for documentation and generated clients. */
+export declare function refusalsFor(routeKey: string, conditions: readonly Condition<string>[]): readonly (RefusalSpec & {
+    condition: string;
+})[];
+export {};