axis-platform-sdk 0.2.1 → 0.3.0

package/badges/README.md

@@ -0,0 +1,41 @@
+# "Verified by AXIS" badge kit
+
+Drop-in SVG badges for platforms that show verification status on agent-authored
+content — comments, posts, bylines, profile rows. Use them to mark content an
+agent produced *after* it passed your AXIS gate.
+
+| File | Use |
+| --- | --- |
+| `verified-by-axis.svg` | Standard, for light backgrounds. |
+| `verified-by-axis-dark.svg` | Standard, for dark backgrounds. |
+| `verified-by-axis-compact.svg` | Tight spaces (inline next to a name). |
+
+## Use it
+
+```html
+<img src="https://unpkg.com/axis-platform-sdk/badges/verified-by-axis.svg"
+     alt="Verified by AXIS" height="22">
+```
+
+Or copy the SVG into your own assets. They're plain SVG with no external
+dependencies, so they inline anywhere (React, Vue, server-rendered HTML, email).
+
+Pick `-dark` on dark surfaces; the standard badge assumes a light background.
+Scale by setting `height` (the width follows the aspect ratio) — don't set both.
+
+## When to show it
+
+Show the badge only for content from an agent your gate **accepted** — i.e. a
+verdict with `accepted: true`. It tells a reader "a verified, accountable agent
+produced this, and its operator authorized the action." Don't show it for
+unverified or denied agents; that's the opposite of what it means.
+
+Optionally pair it with the agent's display name and operator from the verdict /
+`enrich()`, e.g. "Posted by Vale · Verified by AXIS".
+
+## Customizing
+
+These are a neutral v1. You may scale them and place them freely. Please keep the
+check mark and the word "AXIS" together as one lockup, and don't recolor the badge
+to imply a verification level the agent didn't actually meet. If you want a variant
+matched to the Kipple Labs brand system, that's planned — open an issue.

package/badges/verified-by-axis-compact.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="86" height="30" viewBox="0 0 86 30" role="img" aria-label="AXIS verified">
+  <title>AXIS verified</title>
+  <rect x="0.5" y="0.5" width="85" height="29" rx="14.5" fill="#ffffff" stroke="#e3e3df"/>
+  <circle cx="18" cy="15" r="7.5" fill="#157347"/>
+  <path d="M14.6 15.2l2.2 2.2 4.4-4.6" fill="none" stroke="#ffffff" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="34" y="19.4" font-family="-apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="12.5" font-weight="700" fill="#1b1b19">AXIS</text>
+</svg>

package/badges/verified-by-axis-dark.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="152" height="30" viewBox="0 0 152 30" role="img" aria-label="Verified by AXIS">
+  <title>Verified by AXIS</title>
+  <rect x="0.5" y="0.5" width="151" height="29" rx="14.5" fill="#1a1a18" stroke="#34342f"/>
+  <circle cx="18" cy="15" r="7.5" fill="#2ea36f"/>
+  <path d="M14.6 15.2l2.2 2.2 4.4-4.6" fill="none" stroke="#0f0f0e" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="34" y="19.4" font-family="-apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="12.5" fill="#b6b6af">Verified by <tspan font-weight="700" fill="#ededea">AXIS</tspan></text>
+</svg>

package/badges/verified-by-axis.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="152" height="30" viewBox="0 0 152 30" role="img" aria-label="Verified by AXIS">
+  <title>Verified by AXIS</title>
+  <rect x="0.5" y="0.5" width="151" height="29" rx="14.5" fill="#ffffff" stroke="#e3e3df"/>
+  <circle cx="18" cy="15" r="7.5" fill="#157347"/>
+  <path d="M14.6 15.2l2.2 2.2 4.4-4.6" fill="none" stroke="#ffffff" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/>
+  <text x="34" y="19.4" font-family="-apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="12.5" fill="#45453f">Verified by <tspan font-weight="700" fill="#1b1b19">AXIS</tspan></text>
+</svg>

package/examples/toy-platform-worker.js

@@ -1,60 +1,60 @@
-/**
- * Toy "bouncer" platform — the backend for the full-loop demo.
- *
- * A pretend comments service that only accepts AXIS-verified agents holding
- * `comments:write`. It gates with a SwitchAuthorizer driven by a `door` policy
- * object — which is exactly what a "Door policy" screen in Owyhee edits and
- * saves. Flip `enabled` to false and the gate closes with no code change.
- *
- * Run locally: wrangler dev examples/toy-platform-worker.js
- */
-import { SwitchAuthorizer, denialResponse } from '../src/index.js';
-
-const AUDIENCE = 'comments.demo-platform.example';
-
-// The free-tier gate engine. This object is the editable "Door policy".
-const door = new SwitchAuthorizer({
-  audience: AUDIENCE,
-  defaultAllow: false,
-  gates: {
-    'comments:write': {
-      enabled: true,
-      requireScopes: ['comments:write'],
-      // minTier: 'domain',           // require domain-verified+ to comment
-      // blockedOperators: ['axis:spammer:operator'],
-    },
-  },
-});
-
-export default {
-  async fetch(request) {
-    const url = new URL(request.url);
-
-    // The gated action. The bouncer verifies + applies the door policy.
-    if (url.pathname === '/comment' && request.method === 'POST') {
-      const verdict = await door.gate('comments:write')(request);
-      if (!verdict.accepted) return denialResponse(verdict); // 401/403 + reason
-
-      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 our door policy so AIT issuers know our audience + requirements.
-    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: ['comments:write'], allow_unverified: false },
-      });
-    }
-
-    return new Response('AXIS bouncer demo. POST /comment with an AIT to get in.\n', { status: 200 });
-  },
-};
+/**
+ * Toy "bouncer" platform — the backend for the full-loop demo.
+ *
+ * A pretend comments service that only accepts AXIS-verified agents holding
+ * `comments:write`. It gates with a SwitchAuthorizer driven by a `door` policy
+ * object — which is exactly what a door-policy screen in the cloud-hosted console
+ * edits and saves. Flip `enabled` to false and the gate closes with no code change.
+ *
+ * Run locally: wrangler dev examples/toy-platform-worker.js
+ */
+import { SwitchAuthorizer, denialResponse } from '../src/index.js';
+
+const AUDIENCE = 'comments.demo-platform.example';
+
+// The free-tier gate engine. This object is the editable "Door policy".
+const door = new SwitchAuthorizer({
+  audience: AUDIENCE,
+  defaultAllow: false,
+  gates: {
+    'comments:write': {
+      enabled: true,
+      requireScopes: ['comments:write'],
+      // minTier: 'domain',           // require domain-verified+ to comment
+      // blockedOperators: ['axis:spammer:operator'],
+    },
+  },
+});
+
+export default {
+  async fetch(request) {
+    const url = new URL(request.url);
+
+    // The gated action. The bouncer verifies + applies the door policy.
+    if (url.pathname === '/comment' && request.method === 'POST') {
+      const verdict = await door.gate('comments:write')(request);
+      if (!verdict.accepted) return denialResponse(verdict); // 401/403 + reason
+
+      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 our door policy so AIT issuers know our audience + requirements.
+    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: ['comments:write'], allow_unverified: false },
+      });
+    }
+
+    return new Response('AXIS bouncer demo. POST /comment with an AIT to get in.\n', { status: 200 });
+  },
+};

package/package.json

@@ -1,49 +1,54 @@
-{
-  "name": "axis-platform-sdk",
-  "version": "0.2.1",
-  "description": "Platform-side SDK for the AXIS protocol. The verifier/'bouncer' side: when an AXIS agent shows up at your platform, verify its identity + delegation + scope and decide whether to accept, scope, or boot it. Zero runtime dependencies; runs in Node 20+, Cloudflare Workers, and modern browsers.",
-  "type": "module",
-  "main": "src/index.js",
-  "types": "./src/index.d.ts",
-  "exports": {
-    ".": { "types": "./src/index.d.ts", "default": "./src/index.js" },
-    "./scope": { "types": "./src/scope.d.ts", "default": "./src/scope.js" },
-    "./gate": { "types": "./src/gate.d.ts", "default": "./src/gate.js" },
-    "./authorizer": { "types": "./src/authorizer.d.ts", "default": "./src/authorizer.js" },
-    "./ledger": { "types": "./src/ledger.d.ts", "default": "./src/ledger.js" },
-    "./blocklist": { "types": "./src/blocklist.d.ts", "default": "./src/blocklist.js" },
-    "./reportback": { "types": "./src/reportback.d.ts", "default": "./src/reportback.js" }
-  },
-  "scripts": {
-    "test": "node --test test/scope.test.js test/verify.test.js test/authorizer.test.js test/ledger.test.js test/blocklist.test.js test/reportback.test.js"
-  },
-  "keywords": [
-    "axis",
-    "axis-protocol",
-    "agent-identity",
-    "verifier",
-    "platform",
-    "authorization"
-  ],
-  "author": "Kipple Labs, Inc.",
-  "license": "Apache-2.0",
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "homepage": "https://github.com/MachinesOfDesire/axis-platform-sdk",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/MachinesOfDesire/axis-platform-sdk.git"
-  },
-  "bugs": {
-    "url": "https://github.com/MachinesOfDesire/axis-platform-sdk/issues"
-  },
-  "files": [
-    "src/",
-    "examples/",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE",
-    "NOTICE"
-  ]
-}
+{
+  "name": "axis-platform-sdk",
+  "version": "0.3.0",
+  "description": "Platform-side SDK for the AXIS protocol. The verifier/'bouncer' side: when an AXIS agent shows up at your platform, verify its identity + delegation + scope and decide whether to accept, scope, or boot it. Zero runtime dependencies; runs in Node 20+, Cloudflare Workers, and modern browsers.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": { "types": "./src/index.d.ts", "default": "./src/index.js" },
+    "./scope": { "types": "./src/scope.d.ts", "default": "./src/scope.js" },
+    "./gate": { "types": "./src/gate.d.ts", "default": "./src/gate.js" },
+    "./express": { "types": "./src/express.d.ts", "default": "./src/express.js" },
+    "./authorizer": { "types": "./src/authorizer.d.ts", "default": "./src/authorizer.js" },
+    "./ledger": { "types": "./src/ledger.d.ts", "default": "./src/ledger.js" },
+    "./blocklist": { "types": "./src/blocklist.d.ts", "default": "./src/blocklist.js" },
+    "./reportback": { "types": "./src/reportback.d.ts", "default": "./src/reportback.js" }
+  },
+  "scripts": {
+    "test": "node --test test/scope.test.js test/verify.test.js test/authorizer.test.js test/ledger.test.js test/blocklist.test.js test/reportback.test.js test/express.test.js"
+  },
+  "keywords": [
+    "axis",
+    "axis-protocol",
+    "agent-identity",
+    "verifier",
+    "platform",
+    "authorization"
+  ],
+  "author": "Kipple Labs, Inc.",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "homepage": "https://github.com/MachinesOfDesire/axis-platform-sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MachinesOfDesire/axis-platform-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MachinesOfDesire/axis-platform-sdk/issues"
+  },
+  "files": [
+    "src/",
+    "examples/",
+    "templates/",
+    "badges/",
+    "README.md",
+    "QUICKSTART.md",
+    "CASE-STUDY-offworld.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/authorizer.js

@@ -1,101 +1,101 @@
-/**
- * The Authorizer port + the free-tier SwitchAuthorizer.
- *
- * Owyhee (and any platform) always does IDENTITY verification first — is this a
- * real, non-revoked agent with a trustworthy effective_scope (verifyAgent ->
- * registry). That part is fixed and never pluggable.
- *
- * The authorization DECISION is the pluggable, monetizable layer. Every
- * Authorizer implements the same shape:
- *
- *     authorize(token, gateId, { registryBaseUrl, fetchImpl }) -> verdict
- *
- * where `verdict` is exactly what verifyAgent returns
- * ({ accepted, reason?, code?, agent_id?, operator_id?, effective_scope?, tier?, ... }).
- *
- * Profiles (Josh's "simple on/off -> granular -> really complicated"):
- *   - SwitchAuthorizer  (this file)  — FREE tier. Config-driven on/off gates
- *                                      + optional tier / scope / operator rules.
- *   - EngineAuthorizer  (not here)   — PAID. Same port, delegates the decision
- *                                      to Permify / OpenFGA (sidecar) for
- *                                      relationship/attribute rules.
- *   - EnterpriseAuthorizer (not here)— full ReBAC/ABAC, same port.
- *
- * The SwitchAuthorizer's `policy` object is exactly what a "Door policy" screen
- * edits and saves.
- */
-import { verifyAgent } from './verify.js';
-import { extractToken } from './gate.js';
-
-const deny = (reason, code, extra = {}) => ({ accepted: false, reason, code, ...extra });
-
-/**
- * Free-tier gate engine: a set of named gates, each on/off, with optional
- * minimum tier, required scopes, and operator allow/block lists.
- *
- * policy = {
- *   audience: 'comments.mysite.com',   // your platform id; applied to every gate
- *   defaultAllow: false,               // posture for a gateId with no policy
- *   blockedOperators: [],              // global blocklist, applied to all gates
- *   gates: {
- *     'comments:write': {
- *       enabled: true,
- *       minTier: 'domain',             // optional
- *       requireScopes: ['comments:write'], // optional
- *       blockedOperators: [],          // optional, gate-specific
- *       approvedOperators: null        // optional allowlist
- *     }
- *   }
- * }
- */
-export class SwitchAuthorizer {
-  constructor(policy = {}) {
-    this.policy = policy || {};
-  }
-
-  /** The verifyAgent options this policy implies for a given gate. */
-  optsForGate(gateId) {
-    const p = this.policy;
-    const gate = (p.gates && p.gates[gateId]) || null;
-    return {
-      audience: p.audience,
-      requireScopes: (gate && gate.requireScopes) || [],
-      minTier: gate && gate.minTier,
-      blockedOperators: [...(p.blockedOperators || []), ...((gate && gate.blockedOperators) || [])],
-      approvedOperators: (gate && gate.approvedOperators) || null,
-    };
-  }
-
-  /**
-   * Decide whether `token` may act at `gateId`. Denies if the gate is turned
-   * off, or unknown when the posture is closed. Otherwise runs identity
-   * verification + this gate's policy.
-   */
-  async authorize(token, gateId, { registryBaseUrl, fetchImpl } = {}) {
-    const p = this.policy;
-    const gate = (p.gates && p.gates[gateId]) || null;
-
-    if (!gate) {
-      if (p.defaultAllow) {
-        return verifyAgent(token, {
-          audience: p.audience,
-          blockedOperators: p.blockedOperators || [],
-          registryBaseUrl,
-          fetchImpl,
-        });
-      }
-      return deny(`No policy for gate '${gateId}' and the default posture is closed`, 'gate_unknown');
-    }
-
-    if (gate.enabled === false) {
-      return deny(`Gate '${gateId}' is turned off`, 'gate_closed');
-    }
-
-    return verifyAgent(token, { ...this.optsForGate(gateId), registryBaseUrl, fetchImpl });
-  }
-
-  /** Bind this authorizer to a gateId as a request gate: (request) => verdict. */
-  gate(gateId, opts = {}) {
-    return async (request) => this.authorize(extractToken(request), gateId, opts);
-  }
-}
+/**
+ * The Authorizer port + the free-tier SwitchAuthorizer.
+ *
+ * The cloud-hosted version (and any platform) always does IDENTITY verification
+ * first — is this a real, non-revoked agent with a trustworthy effective_scope (verifyAgent ->
+ * registry). That part is fixed and never pluggable.
+ *
+ * The authorization DECISION is the pluggable, monetizable layer. Every
+ * Authorizer implements the same shape:
+ *
+ *     authorize(token, gateId, { registryBaseUrl, fetchImpl }) -> verdict
+ *
+ * where `verdict` is exactly what verifyAgent returns
+ * ({ accepted, reason?, code?, agent_id?, operator_id?, effective_scope?, tier?, ... }).
+ *
+ * Profiles (Josh's "simple on/off -> granular -> really complicated"):
+ *   - SwitchAuthorizer  (this file)  — FREE tier. Config-driven on/off gates
+ *                                      + optional tier / scope / operator rules.
+ *   - EngineAuthorizer  (not here)   — PAID. Same port, delegates the decision
+ *                                      to Permify / OpenFGA (sidecar) for
+ *                                      relationship/attribute rules.
+ *   - EnterpriseAuthorizer (not here)— full ReBAC/ABAC, same port.
+ *
+ * The SwitchAuthorizer's `policy` object is exactly what a "Door policy" screen
+ * edits and saves.
+ */
+import { verifyAgent } from './verify.js';
+import { extractToken } from './gate.js';
+
+const deny = (reason, code, extra = {}) => ({ accepted: false, reason, code, ...extra });
+
+/**
+ * Free-tier gate engine: a set of named gates, each on/off, with optional
+ * minimum tier, required scopes, and operator allow/block lists.
+ *
+ * policy = {
+ *   audience: 'comments.mysite.com',   // your platform id; applied to every gate
+ *   defaultAllow: false,               // posture for a gateId with no policy
+ *   blockedOperators: [],              // global blocklist, applied to all gates
+ *   gates: {
+ *     'comments:write': {
+ *       enabled: true,
+ *       minTier: 'domain',             // optional
+ *       requireScopes: ['comments:write'], // optional
+ *       blockedOperators: [],          // optional, gate-specific
+ *       approvedOperators: null        // optional allowlist
+ *     }
+ *   }
+ * }
+ */
+export class SwitchAuthorizer {
+  constructor(policy = {}) {
+    this.policy = policy || {};
+  }
+
+  /** The verifyAgent options this policy implies for a given gate. */
+  optsForGate(gateId) {
+    const p = this.policy;
+    const gate = (p.gates && p.gates[gateId]) || null;
+    return {
+      audience: p.audience,
+      requireScopes: (gate && gate.requireScopes) || [],
+      minTier: gate && gate.minTier,
+      blockedOperators: [...(p.blockedOperators || []), ...((gate && gate.blockedOperators) || [])],
+      approvedOperators: (gate && gate.approvedOperators) || null,
+    };
+  }
+
+  /**
+   * Decide whether `token` may act at `gateId`. Denies if the gate is turned
+   * off, or unknown when the posture is closed. Otherwise runs identity
+   * verification + this gate's policy.
+   */
+  async authorize(token, gateId, { registryBaseUrl, fetchImpl } = {}) {
+    const p = this.policy;
+    const gate = (p.gates && p.gates[gateId]) || null;
+
+    if (!gate) {
+      if (p.defaultAllow) {
+        return verifyAgent(token, {
+          audience: p.audience,
+          blockedOperators: p.blockedOperators || [],
+          registryBaseUrl,
+          fetchImpl,
+        });
+      }
+      return deny(`No policy for gate '${gateId}' and the default posture is closed`, 'gate_unknown');
+    }
+
+    if (gate.enabled === false) {
+      return deny(`Gate '${gateId}' is turned off`, 'gate_closed');
+    }
+
+    return verifyAgent(token, { ...this.optsForGate(gateId), registryBaseUrl, fetchImpl });
+  }
+
+  /** Bind this authorizer to a gateId as a request gate: (request) => verdict. */
+  gate(gateId, opts = {}) {
+    return async (request) => this.authorize(extractToken(request), gateId, opts);
+  }
+}