axis-platform-sdk 0.2.1 → 0.3.0

package/src/ledger.js

@@ -1,171 +1,170 @@
-/**
- * Access ledger — the platform's "who showed up at my door" record.
- *
- * Every time an agent presents and the gate reaches a verdict, the platform can
- * log the arrival here. This is the STATEFUL half of the bouncer: verifyAgent /
- * aitGate are stateless verdict machines; the ledger is the platform's own
- * append-only record of what those verdicts were, kept in the platform's OWN
- * store. Zero-infra by default (in-memory); a real platform plugs in D1 /
- * SQLite / Postgres via the adapter shape below.
- *
- * Canonical adapter: Owyhee "The Door" (kipple-governor, governor#27) is the
- * shipped, D1-backed product instance of this port — its `arrivals` table +
- * `recordArrival()` ARE this ledger over D1. This module is the library form
- * (the shape + an in-memory default); The Door is the production adapter. The
- * entry shape below is deliberately byte-compatible with The Door's
- * `ArrivalRecord` / `arrivals` columns so there is ONE arrival record across
- * the SDK and the product, not two.
- *
- * Trust note: the only scope worth recording is `effective_scope` (the
- * registry's chain-walked, trustworthy scope), which is exactly what a verdict
- * carries. We never persist the AIT's self-declared scope.
- *
- * --- Adapter shape -------------------------------------------------------
- * A store is any object implementing:
- *
- *   async append(entry)                  -> void     // persist one arrival
- *   async recent({ limit })              -> entry[]  // newest first
- *   async byOperator(operatorId, { limit }) -> entry[] // newest first
- *
- * `entry` is the record shape produced by `recordEntry()` — the same fields The
- * Door's `arrivals` table holds (minus the adapter's own PK/org columns):
- *   {
- *     agent_id, operator_id, created_at,          // created_at = epoch ms (Date.now())
- *     tier, delegation_valid, effective_scope: string[],
- *     gate_id, requested_action, display_name,
- *     decision: 'auto_allow'|'denied'|'held'|'approved'|'booted',
- *     reason, audience
- *   }
- *
- * The same adapter shape is shared with blocklist.js (a tiny CRUD port). A
- * platform implements both against whatever it already runs. The defaults here
- * keep the demo and the free tier zero-infra.
- */
-
-/**
- * Default in-memory ledger store. Newest-first iteration. Bounded so a
- * long-running Worker isolate doesn't grow without limit; override `max` (0 =
- * unbounded) when you want the full history and have a real store behind it.
- */
-export class MemoryLedgerStore {
-  constructor({ max = 10000 } = {}) {
-    this._entries = []; // chronological; newest pushed to the end
-    this.max = max;
-  }
-
-  async append(entry) {
-    this._entries.push(entry);
-    if (this.max && this._entries.length > this.max) {
-      this._entries.splice(0, this._entries.length - this.max);
-    }
-  }
-
-  async recent({ limit = 50 } = {}) {
-    const out = this._entries.slice(-limit);
-    out.reverse();
-    return out;
-  }
-
-  async byOperator(operatorId, { limit = 50 } = {}) {
-    const out = [];
-    for (let i = this._entries.length - 1; i >= 0 && out.length < limit; i--) {
-      if (this._entries[i].operator_id === operatorId) out.push(this._entries[i]);
-    }
-    return out;
-  }
-}
-
-/**
- * Normalize a verdict (from verifyAgent) into a ledger entry. The output is
- * byte-compatible with The Door's `ArrivalRecord` (governor#27) so the SDK and
- * the product share one arrival shape.
- *
- * `decision` defaults from the verdict (accepted -> 'auto_allow', else
- * 'denied'); a caller may override it with a manual-review state a real bouncer
- * needs ('held' | 'approved' | 'booted'). `created_at` is epoch ms (Date.now()),
- * matching The Door's column; for an ISO string use
- * `new Date(entry.created_at).toISOString()`.
- *
- * @param {object} verdict             A verifyAgent verdict.
- * @param {object} [fields]
- * @param {string} [fields.audience]          Platform audience (optional metadata; The Door doesn't persist it).
- * @param {string} [fields.gate_id]           Which gate was requested.
- * @param {string} [fields.requested_action]  Human-facing action label.
- * @param {string} [fields.display_name]      Enriched presentation name.
- * @param {string} [fields.decision]          Override decision ('held'|'approved'|'booted').
- * @param {number} [fields.created_at]        Override timestamp (epoch ms).
- */
-export function recordEntry(verdict, { audience, gate_id, requested_action, display_name, decision, created_at } = {}) {
-  const v = verdict || {};
-  return {
-    agent_id: v.agent_id || null,
-    operator_id: v.operator_id || null,
-    created_at: created_at || Date.now(),
-    tier: v.tier || null,
-    delegation_valid: v.delegation_valid === true,
-    effective_scope: Array.isArray(v.effective_scope) ? v.effective_scope : [],
-    gate_id: gate_id || null,
-    requested_action: requested_action || null,
-    display_name: display_name || null,
-    decision: decision || (v.accepted ? 'auto_allow' : 'denied'),
-    reason: v.accepted ? null : v.reason || v.code || 'denied',
-    audience: audience || null,
-  };
-}
-
-/**
- * The platform's access ledger. Wraps a store and gives you the log helpers a
- * "who's using my platform" view needs.
- */
-export class AccessLedger {
-  constructor({ store } = {}) {
-    this.store = store || new MemoryLedgerStore();
-  }
-
-  /**
-   * Log a verdict. Returns the persisted entry. `fields` carries the same
-   * optional arrival fields as `recordEntry` (audience, gate_id,
-   * requested_action, display_name, decision override).
-   */
-  async record(verdict, fields = {}) {
-    const entry = recordEntry(verdict, fields);
-    await this.store.append(entry);
-    return entry;
-  }
-
-  /** Most recent arrivals, newest first. */
-  async recent(opts = {}) {
-    return this.store.recent(opts);
-  }
-
-  /** Recent arrivals from a single operator, newest first. */
-  async byOperator(operatorId, opts = {}) {
-    return this.store.byOperator(operatorId, opts);
-  }
-}
-
-/**
- * Wrap a gate (or any `(request) => Promise<verdict>`) so every verdict is
- * logged to a ledger before it's returned. Drop-in around `aitGate(...)` or
- * `authorizer.gate(gateId)`:
- *
- *   const ledger = new AccessLedger();
- *   const gate = loggedGate(aitGate({ audience }), ledger, { audience, gate_id });
- *   const verdict = await gate(request);   // logged as a side effect
- *
- * `fields` are the static arrival fields to stamp on every entry (audience,
- * gate_id, requested_action, display_name). Logging failures never block the
- * request — a store hiccup must not turn an accepted agent away. The verdict is
- * always returned.
- */
-export function loggedGate(gate, ledger, fields = {}) {
-  return async function loggingGate(request) {
-    const verdict = await gate(request);
-    try {
-      await ledger.record(verdict, fields);
-    } catch {
-      /* never let a ledger write failure change the verdict */
-    }
-    return verdict;
-  };
-}
+/**
+ * Access ledger — the platform's "who showed up at my door" record.
+ *
+ * Every time an agent presents and the gate reaches a verdict, the platform can
+ * log the arrival here. This is the STATEFUL half of the bouncer: verifyAgent /
+ * aitGate are stateless verdict machines; the ledger is the platform's own
+ * append-only record of what those verdicts were, kept in the platform's OWN
+ * store. Zero-infra by default (in-memory); a real platform plugs in D1 /
+ * SQLite / Postgres via the adapter shape below.
+ *
+ * Canonical adapter: the cloud-hosted version is the D1-backed product instance
+ * of this port — its `arrivals` table + `recordArrival()` ARE this ledger over
+ * D1. This module is the library form (the shape + an in-memory default); the
+ * cloud-hosted version is the production adapter. The entry shape below is
+ * deliberately byte-compatible with its `ArrivalRecord` / `arrivals` columns so
+ * there is ONE arrival record across the SDK and the cloud product, not two.
+ *
+ * Trust note: the only scope worth recording is `effective_scope` (the
+ * registry's chain-walked, trustworthy scope), which is exactly what a verdict
+ * carries. We never persist the AIT's self-declared scope.
+ *
+ * --- Adapter shape -------------------------------------------------------
+ * A store is any object implementing:
+ *
+ *   async append(entry)                  -> void     // persist one arrival
+ *   async recent({ limit })              -> entry[]  // newest first
+ *   async byOperator(operatorId, { limit }) -> entry[] // newest first
+ *
+ * `entry` is the record shape produced by `recordEntry()` — the same fields The
+ * Door's `arrivals` table holds (minus the adapter's own PK/org columns):
+ *   {
+ *     agent_id, operator_id, created_at,          // created_at = epoch ms (Date.now())
+ *     tier, delegation_valid, effective_scope: string[],
+ *     gate_id, requested_action, display_name,
+ *     decision: 'auto_allow'|'denied'|'held'|'approved'|'booted',
+ *     reason, audience
+ *   }
+ *
+ * The same adapter shape is shared with blocklist.js (a tiny CRUD port). A
+ * platform implements both against whatever it already runs. The defaults here
+ * keep the demo and the free tier zero-infra.
+ */
+
+/**
+ * Default in-memory ledger store. Newest-first iteration. Bounded so a
+ * long-running Worker isolate doesn't grow without limit; override `max` (0 =
+ * unbounded) when you want the full history and have a real store behind it.
+ */
+export class MemoryLedgerStore {
+  constructor({ max = 10000 } = {}) {
+    this._entries = []; // chronological; newest pushed to the end
+    this.max = max;
+  }
+
+  async append(entry) {
+    this._entries.push(entry);
+    if (this.max && this._entries.length > this.max) {
+      this._entries.splice(0, this._entries.length - this.max);
+    }
+  }
+
+  async recent({ limit = 50 } = {}) {
+    const out = this._entries.slice(-limit);
+    out.reverse();
+    return out;
+  }
+
+  async byOperator(operatorId, { limit = 50 } = {}) {
+    const out = [];
+    for (let i = this._entries.length - 1; i >= 0 && out.length < limit; i--) {
+      if (this._entries[i].operator_id === operatorId) out.push(this._entries[i]);
+    }
+    return out;
+  }
+}
+
+/**
+ * Normalize a verdict (from verifyAgent) into a ledger entry. The output is
+ * byte-compatible with the cloud-hosted version's `ArrivalRecord` so the SDK and
+ * the cloud product share one arrival shape.
+ *
+ * `decision` defaults from the verdict (accepted -> 'auto_allow', else
+ * 'denied'); a caller may override it with a manual-review state a real bouncer
+ * needs ('held' | 'approved' | 'booted'). `created_at` is epoch ms (Date.now()),
+ * matching the cloud-hosted version's column; for an ISO string use
+ * `new Date(entry.created_at).toISOString()`.
+ *
+ * @param {object} verdict             A verifyAgent verdict.
+ * @param {object} [fields]
+ * @param {string} [fields.audience]          Platform audience (optional metadata; the cloud-hosted version doesn't persist it).
+ * @param {string} [fields.gate_id]           Which gate was requested.
+ * @param {string} [fields.requested_action]  Human-facing action label.
+ * @param {string} [fields.display_name]      Enriched presentation name.
+ * @param {string} [fields.decision]          Override decision ('held'|'approved'|'booted').
+ * @param {number} [fields.created_at]        Override timestamp (epoch ms).
+ */
+export function recordEntry(verdict, { audience, gate_id, requested_action, display_name, decision, created_at } = {}) {
+  const v = verdict || {};
+  return {
+    agent_id: v.agent_id || null,
+    operator_id: v.operator_id || null,
+    created_at: created_at || Date.now(),
+    tier: v.tier || null,
+    delegation_valid: v.delegation_valid === true,
+    effective_scope: Array.isArray(v.effective_scope) ? v.effective_scope : [],
+    gate_id: gate_id || null,
+    requested_action: requested_action || null,
+    display_name: display_name || null,
+    decision: decision || (v.accepted ? 'auto_allow' : 'denied'),
+    reason: v.accepted ? null : v.reason || v.code || 'denied',
+    audience: audience || null,
+  };
+}
+
+/**
+ * The platform's access ledger. Wraps a store and gives you the log helpers a
+ * "who's using my platform" view needs.
+ */
+export class AccessLedger {
+  constructor({ store } = {}) {
+    this.store = store || new MemoryLedgerStore();
+  }
+
+  /**
+   * Log a verdict. Returns the persisted entry. `fields` carries the same
+   * optional arrival fields as `recordEntry` (audience, gate_id,
+   * requested_action, display_name, decision override).
+   */
+  async record(verdict, fields = {}) {
+    const entry = recordEntry(verdict, fields);
+    await this.store.append(entry);
+    return entry;
+  }
+
+  /** Most recent arrivals, newest first. */
+  async recent(opts = {}) {
+    return this.store.recent(opts);
+  }
+
+  /** Recent arrivals from a single operator, newest first. */
+  async byOperator(operatorId, opts = {}) {
+    return this.store.byOperator(operatorId, opts);
+  }
+}
+
+/**
+ * Wrap a gate (or any `(request) => Promise<verdict>`) so every verdict is
+ * logged to a ledger before it's returned. Drop-in around `aitGate(...)` or
+ * `authorizer.gate(gateId)`:
+ *
+ *   const ledger = new AccessLedger();
+ *   const gate = loggedGate(aitGate({ audience }), ledger, { audience, gate_id });
+ *   const verdict = await gate(request);   // logged as a side effect
+ *
+ * `fields` are the static arrival fields to stamp on every entry (audience,
+ * gate_id, requested_action, display_name). Logging failures never block the
+ * request — a store hiccup must not turn an accepted agent away. The verdict is
+ * always returned.
+ */
+export function loggedGate(gate, ledger, fields = {}) {
+  return async function loggingGate(request) {
+    const verdict = await gate(request);
+    try {
+      await ledger.record(verdict, fields);
+    } catch {
+      /* never let a ledger write failure change the verdict */
+    }
+    return verdict;
+  };
+}

package/src/scope.js

@@ -1,46 +1,46 @@
-// Scope matching for the AXIS scope grammar (spec v0.2 §4.4).
-//
-// Ported verbatim from kipple-governor/src/scope-match.ts so the operator side
-// (Governor proxy chain-walk) and the platform side (this SDK) agree on scope
-// semantics exactly. Colon-separated segments; `*` is a wildcard for ONE
-// segment, not multi; no recursion. If the protocol grammar changes, change it
-// in both places.
-
-/**
- * Does `granted` cover `required`? I.e. can a caller granted `granted` claim
- * the permission `required`?
- *
- *   scopeCovers('admin:*',            'admin:users')        === true
- *   scopeCovers('admin:users',        'admin:users')        === true
- *   scopeCovers('admin:users',        'admin:roles')        === false
- *   scopeCovers('admin:*',            'admin:users:delete') === false  // * = 1 segment
- *   scopeCovers('anthropic:complete', 'anthropic:complete') === true
- */
-export function scopeCovers(granted, required) {
-  if (!granted || !required) return false;
-  if (granted === required) return true;
-  const g = granted.split(':');
-  const r = required.split(':');
-  if (g.length !== r.length) return false;
-  for (let i = 0; i < g.length; i++) {
-    if (g[i] === '*') continue;
-    if (g[i] !== r[i]) return false;
-  }
-  return true;
-}
-
-/**
- * Do the granted scopes cover EVERY required scope? Empty `required` is
- * trivially satisfied. Returns the missing required scopes on failure so a
- * caller can put them in a denial reason.
- *
- * @returns {{ ok: boolean, missing: string[] }}
- */
-export function coversAll(granted, required) {
-  const grantedList = Array.isArray(granted) ? granted : [];
-  const missing = [];
-  for (const req of required) {
-    if (!grantedList.some((g) => scopeCovers(g, req))) missing.push(req);
-  }
-  return { ok: missing.length === 0, missing };
-}
+// Scope matching for the AXIS scope grammar (spec v0.2 §4.4).
+//
+// Ported verbatim from the operator-side gateway's scope matcher so the operator
+// side (the outbound proxy chain-walk) and the platform side (this SDK) agree on
+// scope semantics exactly. Colon-separated segments; `*` is a wildcard for ONE
+// segment, not multi; no recursion. If the protocol grammar changes, change it
+// in both places.
+
+/**
+ * Does `granted` cover `required`? I.e. can a caller granted `granted` claim
+ * the permission `required`?
+ *
+ *   scopeCovers('admin:*',            'admin:users')        === true
+ *   scopeCovers('admin:users',        'admin:users')        === true
+ *   scopeCovers('admin:users',        'admin:roles')        === false
+ *   scopeCovers('admin:*',            'admin:users:delete') === false  // * = 1 segment
+ *   scopeCovers('anthropic:complete', 'anthropic:complete') === true
+ */
+export function scopeCovers(granted, required) {
+  if (!granted || !required) return false;
+  if (granted === required) return true;
+  const g = granted.split(':');
+  const r = required.split(':');
+  if (g.length !== r.length) return false;
+  for (let i = 0; i < g.length; i++) {
+    if (g[i] === '*') continue;
+    if (g[i] !== r[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Do the granted scopes cover EVERY required scope? Empty `required` is
+ * trivially satisfied. Returns the missing required scopes on failure so a
+ * caller can put them in a denial reason.
+ *
+ * @returns {{ ok: boolean, missing: string[] }}
+ */
+export function coversAll(granted, required) {
+  const grantedList = Array.isArray(granted) ? granted : [];
+  const missing = [];
+  for (const req of required) {
+    if (!grantedList.some((g) => scopeCovers(g, req))) missing.push(req);
+  }
+  return { ok: missing.length === 0, missing };
+}

package/templates/cloudflare-worker/README.md

@@ -0,0 +1,79 @@
+# AXIS gate — Cloudflare Worker starter
+
+Gate a Cloudflare Worker on **AXIS verified-agent identity**. When an AI agent
+shows up and wants to act, this verifies *who it is* and *what it's allowed to
+do* before your handler runs.
+
+Use this template if your platform already runs on Workers. **You do not need to
+adopt Cloudflare just to use AXIS** — if you run a Node backend, use the
+`node-express` starter instead. Both wrap the same zero-dependency engine.
+
+## Run it
+
+```bash
+npm install
+npx wrangler dev        # http://localhost:8787
+```
+
+```bash
+# Your published door policy:
+curl -s localhost:8787/.well-known/axis-access
+
+# No AIT -> 401:
+curl -i -X POST localhost:8787/comments -H 'content-type: application/json' -d '{"text":"hi"}'
+
+# Arrivals + boot console:
+open http://localhost:8787/admin
+```
+
+## Deploy it
+
+```bash
+npx wrangler deploy
+```
+
+No bindings are required for the free standalone path — the Worker's only
+outbound call is one HTTPS GET to the public AXIS registry.
+
+## The drop-in
+
+The minimal version is a few lines:
+
+```js
+import { aitGate, denialResponse } from 'axis-platform-sdk';
+
+const gate = aitGate({ audience: 'comments.mysite.com', requireScopes: ['content:comment'] });
+
+export default {
+  async fetch(request) {
+    const verdict = await gate(request);
+    if (!verdict.accepted) return denialResponse(verdict); // 401/403 + reason
+    // verdict.agent_id is verified. Proceed.
+    return Response.json({ ok: true, by: verdict.agent_id });
+  },
+};
+```
+
+`src/worker.js` is the fuller version: a `SwitchAuthorizer` door policy (named
+on/off gates you can edit like config), an access ledger ("who showed up"), a
+runtime blocklist ("boot this one"), and a tiny `/admin` console.
+
+## Options
+
+`aitGate(opts)` / `verifyAgent(token, opts)` take:
+
+| option | meaning |
+| --- | --- |
+| `audience` | Your platform's stable id. The AIT's `aud` must equal it. |
+| `requireScopes` | Scopes checked against the trustworthy `effective_scope`. |
+| `minTier` | `email` < `domain` < `verified` < `kyb_individual` < `kyb_organization`. |
+| `blockedOperators` / `approvedOperators` | Deny / allow by operator id. |
+| `registryBaseUrl` | Defaults to `https://registry.axisprime.ai`. |
+
+## Persisting state in production
+
+The in-memory ledger/blocklist reset when the isolate recycles. For durable
+arrivals + blocks, add a D1 binding in `wrangler.toml` and implement the SDK's
+documented store adapter shape against it (see `ledger.js` / `blocklist.js` in
+the SDK). The arrival record shape is byte-compatible with the cloud-hosted version
+(in alpha, Q3 2026), so moving to it later is a lift, not a rewrite.

package/templates/cloudflare-worker/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "axis-gate-worker-starter",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Drop-in starter: gate a Cloudflare Worker platform on AXIS verified-agent identity.",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy"
+  },
+  "dependencies": {
+    "axis-platform-sdk": "^0.2.1"
+  },
+  "devDependencies": {
+    "wrangler": "^3.90.0"
+  }
+}