@seasonkoh/webaz 0.1.18 → 0.1.20

package/dist/pwa/verifiability-index.js

@@ -0,0 +1,63 @@
+/**
+ * RFC-011 §⑤ 可验证索引 —— 一份"什么可验 + 怎么验"的总表(护照/锚/AP2/订单链散在四处,这里统一)。
+ * 诚实分级(不可过度声明):
+ *   - 护照 / 外部锚:公开可验(任何第三方离线 ecrecover / 验签),强。
+ *   - AP2 Mandate:签名输出,可验。
+ *   - 订单事件链:HMAC 是 actor 私钥 → 第三方【无法】验签;可验的是【哈希链连续性】(防篡改),且 party-gated。
+ * 只【链接 + 说明】how-to,不嵌密钥(密钥 live 发布在 did.json / protocol-status issuers),doc=code 不漂移。
+ */
+import { SOFTWARE_VERSION, CONTRACT_VERSION } from '../version.js';
+const BASE = 'https://webaz.xyz';
+export function buildVerifiabilityIndex() {
+    return {
+        contract_version: CONTRACT_VERSION,
+        software_version: SOFTWARE_VERSION,
+        note: 'RFC-011 §⑤. Each artifact lists what it proves, the scheme, how to verify, and its verifiability LEVEL — do not over-trust beyond the stated level. Issuer keys are published live (not embedded here): /.well-known/did.json + /.well-known/webaz-protocol.json#issuers.',
+        levels: {
+            public_signature: 'any third party verifies offline (ecrecover / sig-check) without calling WebAZ',
+            public_endpoint: 'verifiable via a public WebAZ endpoint (no auth)',
+            integrity_chain: 'tamper-evidence via a hash-chain (verify continuity); NOT a third-party-verifiable signature',
+            party_gated: 'full data only to order parties; others get integrity, not contents',
+        },
+        artifacts: [
+            {
+                artifact: 'agent_passport',
+                proves: 'an agent\'s custodian fingerprint + risk/engagement/behavior, signed by the WebAZ issuer key',
+                scheme: 'eip191 (EIP-191 personal_sign)',
+                level: 'public_signature',
+                offline: true,
+                how_to_verify: 'GET /api/me/agents/:apiKeyPrefix/passport → ecrecover(passport.canonical, passport.signature) == issuer address from /.well-known/did.json (CAIP-10) / /.well-known/webaz-protocol.json#issuers; check active_since/revoked_at window.',
+                endpoint: `${BASE}/api/me/agents/:apiKeyPrefix/passport`,
+                keys: `${BASE}/.well-known/did.json`,
+            },
+            {
+                artifact: 'external_anchor',
+                proves: 'a real-world item\'s ownership/authenticity anchor + independent verifier attestations',
+                scheme: 'signature (server-verifiable)',
+                level: 'public_endpoint',
+                offline: false,
+                how_to_verify: `GET ${BASE}/api/external-anchors/:id/verify-sig (public); cross-check verifier attestations via /api/external-anchors/:id.`,
+                endpoint: `${BASE}/api/external-anchors/:id/verify-sig`,
+            },
+            {
+                artifact: 'ap2_mandate',
+                proves: 'a buyer\'s signed Intent/Cart/Payment Mandate (AP2) emitted alongside the webaz price/order format',
+                scheme: 'AP2 signed mandate',
+                level: 'public_signature',
+                offline: true,
+                how_to_verify: 'verify the AP2 mandate signature per the AP2 spec; emitted by webaz_verify_price + webaz_place_order (dual-output).',
+                endpoint: 'returned inline by verify_price / place_order',
+            },
+            {
+                artifact: 'order_event_chain',
+                proves: 'the order/dispute transition history is append-only + tamper-evident (each event hash chains to the previous)',
+                scheme: 'sha256 hash-chain (event_hash / prev_event_hash). NOTE: the per-event `signature` is an HMAC with the actor\'s api_key — NOT third-party verifiable; the verifiable property is the HASH-CHAIN continuity.',
+                level: 'integrity_chain',
+                offline: true,
+                party_gated: true,
+                how_to_verify: `For an order you are party to: GET ${BASE}/api/orders/:id/chain (returns chain + verification). Or stream events via ${BASE}/api/agent/events (§⑥): check each event\'s prev_event_hash == the previous event\'s event_hash. Continuity proves no insert/delete/reorder.`,
+                endpoint: `${BASE}/api/orders/:id/chain`,
+            },
+        ],
+    };
+}

package/dist/version.js

@@ -0,0 +1,32 @@
+/**
+ * Single source of truth for WebAZ version axes — RFC-011 §④ (version hygiene).
+ *
+ * TWO DISTINCT AXES. Do not conflate them — conflating is exactly the dirt this file kills
+ * (the old hardcoded MCP `SERVER_VERSION='0.1.8'` + Server handshake `version:'0.1.0'` drifted
+ *  away from the real package version 0.1.19; this makes that structurally impossible).
+ *
+ * 1. SOFTWARE_VERSION — npm / release semver of THIS codebase (MCP client+server + PWA).
+ *    Read from package.json at runtime so it can NEVER drift. Bumps on every release.
+ *    Resolves from both dev (tsx src/version.ts → ../package.json) and prod/published
+ *    (node dist/version.js → ../package.json), since package.json sits at the package root
+ *    and is always included in the npm tarball.
+ *
+ * 2. CONTRACT_VERSION — the agent-native INTEGRATION CONTRACT version (manifest `schema_version`).
+ *    A deliberate integer that integrators' agents key off. Bump ONLY on a *breaking* change to
+ *    the data contract they read (entity shape / boundary / verifiable-field semantics).
+ *    INDEPENDENT of software releases — a patch/feature release does NOT bump it; a breaking
+ *    contract change DOES, even within the same software version. Governs RFC-011's contract.
+ *
+ * Both are surfaced to integrators in /.well-known/webaz-protocol.json so an agent can read
+ * "contract vN running software x.y.z" and decide compatibility.
+ */
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+/** npm/release semver — single source = package.json. Never hardcode a copy of this. */
+export const SOFTWARE_VERSION = pkg.version;
+/** Integration-contract version. Bump on ANY integrator-observable contract-surface change
+ *  (capability matrix §② / entity dictionary §①); the CONTRACT_CHANGES `kind` classifies whether
+ *  it is breaking. Additive changes (kind:'added') are safe for agents to ignore. Guarded by
+ *  tests/test-contract-fingerprint.ts + docs/CONTRACT-LOCK.json. */
+export const CONTRACT_VERSION = 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seasonkoh/webaz",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "[PRE-LAUNCH] Agent-native decentralized commerce protocol. Humans and AI agents trade on the same protocol via MCP tools. ⚠️ Repository currently private until W8 public launch — GitHub links may return 404. See https://webaz.xyz for status.",
   "main": "dist/mcp.js",
   "bin": {
@@ -20,6 +20,7 @@
     "enforcement": "tsx src/cron-enforcement.ts",
     "pwa": "tsx src/pwa/server.ts",
     "schema:verify": "tsx scripts/schema-verify.ts",
+    "contract:verify": "tsx tests/test-contract-fingerprint.ts",
     "license:check": "tsx scripts/license-invariant-check.ts",
     "meta-rules:check": "tsx scripts/meta-rules-invariant-check.ts",
     "params:check": "tsx scripts/meta-rule-locked-params-check.ts"