axis-platform-sdk 0.2.0 → 0.3.0

package/src/scope.d.ts

@@ -0,0 +1 @@
+export { scopeCovers, coversAll } from './index.js';

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"
+  }
+}

package/templates/cloudflare-worker/src/worker.js

@@ -0,0 +1,162 @@
+/**
+ * worker.js — a complete, deployable AXIS-gated platform on Cloudflare Workers.
+ *
+ * A pretend comments service that only accepts AXIS-verified agents holding
+ * `content:comment`, with the stateful half a real platform needs: an access
+ * ledger ("who showed up") and a runtime blocklist ("boot this one"), plus a
+ * tiny admin console over both.
+ *
+ *   npm install
+ *   npx wrangler dev        # local:  http://localhost:8787
+ *   npx wrangler deploy     # ship it
+ *
+ * What's the "real" integration vs. the demo scaffolding?
+ *   - the SwitchAuthorizer door policy   -> COPY; it's your editable gate config.
+ *   - the gate + ledger + blocklist wiring on POST /comments -> COPY.
+ *   - the in-memory stores               -> SWAP for D1 / KV in production (the
+ *                                           stores reset when the isolate recycles).
+ *   - the /admin HTML                    -> demo only; build your own console.
+ */
+import {
+  SwitchAuthorizer,
+  verifyAgent,
+  extractToken,
+  denialResponse,
+  AccessLedger,
+  Blocklist,
+  enrich,
+  blockAndReport,
+} from 'axis-platform-sdk';
+
+const AUDIENCE = 'comments.demo-platform.example'; // your platform's stable audience id
+const PLATFORM_ID = 'axis:demo-platform:door';     // this platform's AXIS id (attestor on boot-reports)
+// const REPUTATION_URL = 'https://axis-reputation.example/attestations'; // OFF by default
+
+// The editable "Door policy": named gates, each on/off, with optional tier/scope.
+const door = new SwitchAuthorizer({
+  audience: AUDIENCE,
+  defaultAllow: false,
+  gates: {
+    'content:comment': {
+      enabled: true,
+      requireScopes: ['content:comment'],
+      // minTier: 'domain',
+      // blockedOperators: ['axis:spammer:operator'],
+    },
+  },
+});
+
+// Stateful stores. In-memory reference (resets on isolate recycle); swap in
+// D1 / KV via the documented adapter shape for production.
+const ledger = new AccessLedger();
+const blocklist = new Blocklist();
+
+export default {
+  async fetch(request) {
+    const url = new URL(request.url);
+
+    // --- the gated action ---------------------------------------------------
+    if (url.pathname === '/comments' && request.method === 'POST') {
+      const base = door.optsForGate('content:comment');
+      const dynBlocked = await blocklist.blockedOperatorIds();
+      let verdict = await verifyAgent(extractToken(request), {
+        ...base,
+        blockedOperators: [...(base.blockedOperators || []), ...dynBlocked],
+      });
+      verdict = await blocklist.checkVerdict(verdict);
+
+      await ledger.record(verdict, { audience: AUDIENCE, gate_id: 'content:comment', requested_action: 'post a comment' }).catch(() => {});
+
+      if (!verdict.accepted) return denialResponse(verdict);
+      const body = await request.json().catch(() => ({}));
+      return Response.json({ ok: true, posted_by: verdict.agent_id, operator: verdict.operator_id, scope: verdict.effective_scope, comment: body.text || '' });
+    }
+
+    // --- publish your door policy ------------------------------------------
+    if (url.pathname === '/.well-known/axis-access') {
+      return Response.json({
+        axis_version: '0.3',
+        platform_id: AUDIENCE,
+        audience: AUDIENCE,
+        access_policy: { minimum_verification_level: 'email', required_scopes: ['content:comment'], allow_unverified: false },
+      });
+    }
+
+    // --- admin: recent arrivals (enriched for display) ----------------------
+    if (url.pathname === '/admin/arrivals' && request.method === 'GET') {
+      const limit = Number(url.searchParams.get('limit') || 25);
+      const rows = await ledger.recent({ limit });
+      const enriched = await Promise.all(rows.map(async (r) => {
+        if (!r.agent_id) return r;
+        try {
+          const info = await enrich(r.agent_id, null);
+          return { ...r, display_name: info.display_name, tier: info.tier };
+        } catch {
+          return r;
+        }
+      }));
+      return Response.json({ arrivals: enriched });
+    }
+
+    // --- admin: boot an agent or operator (block + best-effort report) ------
+    if (url.pathname === '/admin/boot' && request.method === 'POST') {
+      const body = await request.json().catch(() => ({}));
+      const reason = body.reason || 'booted by platform admin';
+      if (body.agent_id) {
+        const out = await blockAndReport(
+          blocklist,
+          { platformId: PLATFORM_ID, agentId: body.agent_id, operatorId: body.operator_id, category: body.category || 'abuse', reason },
+          { /* reputationUrl: REPUTATION_URL */ }
+        );
+        return Response.json({ ok: true, ...out });
+      }
+      if (body.operator_id) {
+        await blocklist.blockOperator(body.operator_id, reason);
+        return Response.json({ ok: true, blocked_operator: body.operator_id });
+      }
+      return Response.json({ ok: false, error: 'provide agent_id or operator_id' }, { status: 400 });
+    }
+
+    // --- admin: tiny HTML console ------------------------------------------
+    if (url.pathname === '/admin') {
+      return new Response(ADMIN_HTML, { headers: { 'Content-Type': 'text/html; charset=utf-8' } });
+    }
+
+    return new Response('AXIS-gated comments demo. POST /comments with an AIT to get in. See /admin.\n', { status: 200 });
+  },
+};
+
+const ADMIN_HTML = `<!doctype html><meta charset=utf-8>
+<title>AXIS bouncer — admin</title>
+<style>
+ body{font:14px/1.5 system-ui,sans-serif;margin:2rem;max-width:60rem}
+ h1{font-size:1.2rem} table{border-collapse:collapse;width:100%;margin:1rem 0}
+ th,td{border:1px solid #ccc;padding:.35rem .5rem;text-align:left;font-size:13px}
+ .denied,.booted{color:#b00} .auto_allow,.approved{color:#070} .held{color:#a60}
+ button{cursor:pointer} code{background:#f3f3f3;padding:0 .25rem}
+</style>
+<h1>AXIS bouncer — arrivals</h1>
+<p>Who showed up at <code>${AUDIENCE}</code>. Click <b>boot</b> to block + report an agent.</p>
+<table id=t><thead><tr><th>when</th><th>agent</th><th>operator</th><th>scope</th><th>decision</th><th></th></tr></thead><tbody></tbody></table>
+<script>
+async function load(){
+ const r=await fetch('/admin/arrivals?limit=50');const {arrivals}=await r.json();
+ const tb=document.querySelector('#t tbody');tb.innerHTML='';
+ for(const a of arrivals){
+  const tr=document.createElement('tr');
+  const name=a.display_name?a.display_name+' ':'';
+  const when=a.created_at?new Date(a.created_at).toISOString().replace('T',' ').slice(0,19):'';
+  tr.innerHTML='<td>'+when+'</td><td>'+name+'<code>'+(a.agent_id||'?')+'</code></td>'+
+    '<td><code>'+(a.operator_id||'?')+'</code></td><td>'+(a.effective_scope||[]).join(', ')+'</td>'+
+    '<td class="'+a.decision+'">'+a.decision+'</td>'+
+    '<td>'+(a.agent_id?'<button data-a="'+a.agent_id+'">boot</button>':'')+'</td>';
+  tb.appendChild(tr);
+ }
+ tb.querySelectorAll('button').forEach(b=>b.onclick=async()=>{
+  await fetch('/admin/boot',{method:'POST',headers:{'Content-Type':'application/json'},
+   body:JSON.stringify({agent_id:b.dataset.a,reason:'booted from console',category:'abuse'})});
+  load();
+ });
+}
+load();
+</script>`;

package/templates/cloudflare-worker/wrangler.toml

@@ -0,0 +1,20 @@
+# Minimal Wrangler config for the AXIS gate Worker starter.
+#   npx wrangler dev      # run locally at http://localhost:8787
+#   npx wrangler deploy   # deploy to your account
+#
+# Rename `name` to whatever you want the Worker to be called. No bindings are
+# required for the free standalone path — the Worker only makes one outbound
+# HTTPS call to the public AXIS registry.
+
+name = "axis-gate-worker"
+main = "src/worker.js"
+compatibility_date = "2025-01-01"
+
+# The in-memory ledger/blocklist reset when the isolate recycles. For durable
+# arrivals + blocks, add a D1 binding (or KV) here and implement the SDK's
+# documented store adapter shape against it. See the SDK's ledger.js / blocklist.js.
+#
+# [[d1_databases]]
+# binding = "DB"
+# database_name = "axis-gate"
+# database_id = "<your-d1-id>"

package/templates/node-express/README.md

@@ -0,0 +1,113 @@
+# AXIS gate — Node / Express starter
+
+Gate any Express platform on **AXIS verified-agent identity** in a few lines. When
+an AI agent shows up and wants to act (post a comment, call your API, place an
+order), this verifies *who it is* and *what it's allowed to do* before your
+handler runs.
+
+No Cloudflare. No account with us. No infra to stand up. The only network call is
+one HTTPS GET to the public AXIS registry, which does the cryptography
+(signature + revocation + delegation-chain walk) server-side and hands back a
+trustworthy verdict.
+
+## Run it
+
+```bash
+npm install
+npm start         # http://localhost:8787
+```
+
+Then, in another terminal:
+
+```bash
+# Your published door policy (what agents must satisfy to get in):
+curl -s localhost:8787/.well-known/axis-access
+
+# No AIT -> 401. The bouncer turns away anyone who doesn't present an identity:
+curl -i -X POST localhost:8787/comments -H 'content-type: application/json' -d '{"text":"hi"}'
+
+# Open the admin console to watch arrivals and boot a bad agent:
+open http://localhost:8787/admin
+```
+
+To prove the gate works without a real agent:
+
+```bash
+npm run smoke     # boots the real middleware, asserts the deny paths
+```
+
+## The whole integration is one import + one line
+
+`axisGate` is a real export of the package — `axis-platform-sdk/express`. You
+don't copy a file; you import it:
+
+```js
+import express from 'express';
+import { axisGate } from 'axis-platform-sdk/express';
+
+const app = express();
+app.use(express.json());
+
+app.post('/comments',
+  axisGate({ audience: 'comments.mysite.com', requireScopes: ['content:comment'] }),
+  (req, res) => {
+    // req.axis.agent_id is a VERIFIED agent. Proceed with your real logic.
+    res.json({ ok: true, by: req.axis.agent_id });
+  });
+
+app.listen(8787);
+```
+
+`axisGate(opts)` pulls the AIT off the request (`Authorization: Bearer …`,
+`X-AXIS-Token`, or `?ait=`), verifies it, and either calls `next()` with
+`req.axis` set to the verdict, or responds `401` (no token) / `403` (policy) /
+`503` (unexpected verify error) with `{ error, message }`. It imports nothing
+from Express, so it works with Connect and bare `http` servers too.
+
+### Options (passed straight through to `verifyAgent`)
+
+| option | meaning |
+| --- | --- |
+| `audience` | **Required-ish.** Your platform's stable id. The AIT's `aud` must equal it, so an agent's token for *another* site can't be replayed at yours. |
+| `requireScopes` | Scopes the agent must hold, checked against the **trustworthy `effective_scope`** (the registry's chain-walked result — never the AIT's self-declared scope). |
+| `minTier` | Minimum operator verification tier: `email` < `domain` < `verified` < `kyb_individual` < `kyb_organization`. |
+| `blockedOperators` / `approvedOperators` | Deny-list / allow-list by operator id. |
+| `registryBaseUrl` | Defaults to `https://registry.axisprime.ai`. Point at your own registry if you run one. |
+
+## What `server.js` adds (the stateful bouncer)
+
+A real platform wants more than a yes/no. `server.js` shows the rest, all
+zero-infra by default:
+
+- **Door policy as config** — a `SwitchAuthorizer` with named, on/off gates.
+  Flip `enabled: false` and a gate closes with no code change. This object is
+  exactly what a "door policy" admin screen would edit.
+- **Access ledger** — every arrival (accepted *or* denied) is logged so you can
+  answer "who's been using my platform."
+- **Runtime blocklist** — boot one agent, or a whole operator, without a deploy.
+- **`/admin` console** — a tiny HTML page listing arrivals with a **boot** button.
+
+## Persisting state in production
+
+The ledger and blocklist default to in-memory stores — fine for the demo, gone
+when the process restarts. For production, implement the documented adapter
+shape (a small CRUD interface) against whatever database you already run
+(Postgres, SQLite, Redis, …) and pass it in:
+
+```js
+new AccessLedger({ store: myPostgresLedgerStore });
+new Blocklist({ store: myPostgresBlocklistStore });
+```
+
+The adapter shape is documented in the SDK's `ledger.js` / `blocklist.js`. The
+entry shape is byte-compatible with the cloud-hosted version (in alpha, Q3 2026),
+so if you move to it later, your arrival records already line up.
+
+## Letting a real agent in
+
+The accept path needs an agent that has actually been delegated `content:comment`
+by its operator and presents an AIT addressed to your `audience`. That agent gets
+its identity from the **[AXIS Prime MCP](https://github.com/MachinesOfDesire/axis-mcp)**
+(the agent side). Point a test agent at your `audience`, have its operator grant
+`content:comment`, and POST its AIT to `/comments` — you'll see a `200` and the
+arrival turns green in `/admin`.

package/templates/node-express/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "axis-gate-express-starter",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Drop-in starter: gate an Express platform on AXIS verified-agent identity.",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js",
+    "smoke": "node smoke.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "axis-platform-sdk": "^0.3.0",
+    "express": "^4.22.2"
+  }
+}