@truealter/sdk 0.5.0 → 0.5.1

package/README.md

@@ -1,6 +1,6 @@
 # @truealter/sdk
 
-ALTER Identity SDK — query the continuous identity field from any JavaScript/TypeScript environment.
+ALTER Identity SDK - query the continuous identity field from any JavaScript/TypeScript environment.
 
 [![npm version](https://img.shields.io/npm/v/@truealter/sdk.svg)](https://www.npmjs.com/package/@truealter/sdk)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
@@ -10,9 +10,9 @@ ALTER Identity SDK — query the continuous identity field from any JavaScript/T
 A thin client over the ALTER MCP server (Streamable HTTP, JSON-RPC 2.0, MCP spec `2025-11-25`) with x402 micropayment support, ES256 provenance verification, and config generators for Claude Code, Cursor, and generic MCP clients.
 
 - **Branded host:** `https://mcp.truealter.com` (serves `.well-known/mcp.json` for discovery)
-- **JSON-RPC wire endpoint:** `https://mcp.truealter.com/api/v1/mcp` — this is what Streamable HTTP POSTs target (the SDK default)
+- **JSON-RPC wire endpoint:** `https://mcp.truealter.com/api/v1/mcp` - this is what Streamable HTTP POSTs target (the SDK default)
 - **Wire protocol:** Streamable HTTP, JSON-RPC 2.0, MCP `2025-11-25` (server negotiates `2025-06-18` + `2025-03-26` for backwards-compatible clients)
-- **Tools:** **40 typed and wired** — 24 free (L0) + 9 premium (L1–L5) + 7 alter-to-alter messaging. Mirrors the live server's `tools/list` response byte-for-byte; every name in `FREE_TOOL_NAMES` / `PREMIUM_TOOL_NAMES` / `MESSAGING_TOOL_NAMES` has a matching server handler at `mcp.truealter.com/api/v1/mcp`.
+- **Tools:** **40 typed and wired** - 24 free (L0) + 9 premium (L1–L5) + 7 alter-to-alter messaging. Mirrors the live server's `tools/list` response byte-for-byte; every name in `FREE_TOOL_NAMES` / `PREMIUM_TOOL_NAMES` / `MESSAGING_TOOL_NAMES` has a matching server handler at `mcp.truealter.com/api/v1/mcp`.
 - **Runtime:** Node 18+, Deno, Bun, Cloudflare Workers, modern browsers
 - **Crypto:** `@noble/ed25519` + `@noble/hashes` (no other dependencies)
 - **Bundle:** ESM + CJS dual output
@@ -22,7 +22,7 @@ A thin client over the ALTER MCP server (Streamable HTTP, JSON-RPC 2.0, MCP spec
 ```
 npm install @truealter/sdk
 npx alter-identity init
-npx alter-identity verify ~truealter
+npx alter-identity verify ~alter
 ```
 
 ## Bridge vs SDK
@@ -30,8 +30,8 @@ npx alter-identity verify ~truealter
 The `alter-mcp-bridge` binary shipped in this package (`bin/mcp-bridge.ts`)
 is a **dev/demo surface** for dropping ALTER into MCP hosts that speak the
 stdio transport (Claude Code, Cursor, Continue, Windsurf). It is useful for
-handshake, `tools/list`, and L0 tool calls, but it does not carry Q5c
-per-invocation signing — authenticated MCP tools will fail at the server
+handshake, `tools/list`, and L0 tool calls, but it does not carry ES256
+per-invocation signing - authenticated MCP tools will fail at the server
 edge when reached through the bridge. For production use, import
 `@truealter/sdk` directly and construct an `MCPClient` / `AlterClient` with
 the optional `signing` parameter; that path is the load-bearing one and
@@ -47,11 +47,10 @@ is a slim, task-oriented binary for day-to-day use:
 | Command | Purpose |
 |---|---|
 | `alter login` | OAuth loopback sign-in; stores a session at `~/.config/alter/session.json` (mode `0600`). |
-| `alter depth [--json]` | GET `/api/v1/identity/depth` — identity-depth score, agentic activity, top/bottom five traits. |
-<!-- TODO(D4): "claim" is a Recognition Over Qualification violation — rename to "redeem" or "accept-invite" in alter-cli + update here -->
+| `alter depth [--json]` | GET `/api/v1/identity/depth` - identity-depth score, agentic activity, top/bottom five traits. |
 | `alter claim <claim_code>` | Accept an identity invite. Prompts for email, password (min 12 chars, hidden), and explicit TOS acceptance, then POSTs `/api/v1/identity/claim`. |
 | `alter mirror` | Day-2 Mirror phase + streak. `alter mirror daily` claims today's Mirror; `alter mirror next` shows the next revelation window. |
-| `alter discover [--limit N]` | MCP-backed summary — calls `alter_whoami` and `alter_verify` against your bound handle. Degrades gracefully if the MCP endpoint is 5xx. |
+| `alter discover [--limit N]` | MCP-backed summary - calls `alter_whoami` and `alter_verify` against your bound handle. Degrades gracefully if the MCP endpoint is 5xx. |
 
 The session file is created with `0600` permissions; its parent dir
 (`~/.config/alter/`) is created with `0700`. Override the config root
@@ -59,7 +58,24 @@ via `XDG_CONFIG_HOME`. Run `alter --help` for the inline reference.
 
 ## Why ALTER ≠ IAM
 
-Identity Access Management answers *who is logged in*. ALTER answers *who they actually are* — a continuous field of recognition that any IAM stack can sit on top of.
+Identity Access Management answers *who is logged in*. ALTER answers *who they actually are* - a continuous field of recognition that any IAM stack can sit on top of.
+
+## Theoretical Foundation
+
+ALTER is the working instantiation of an eight-paper academic corpus on identity field theory. The SDK below is what happens when the theory ships as protocol. Each paper is open access on figshare under CC-BY 4.0.
+
+| Paper | Title | DOI |
+|-------|-------|-----|
+| I | *Belonging is earned, not inherited* | [10.6084/m9.figshare.31794784](https://doi.org/10.6084/m9.figshare.31794784) |
+| II | *The self is inferred, not owned* | [10.6084/m9.figshare.31804222](https://doi.org/10.6084/m9.figshare.31804222) |
+| III | *The same form, at every scale* | [10.6084/m9.figshare.31812955](https://doi.org/10.6084/m9.figshare.31812955) |
+| IV | *Measurement changes the thing measured* | [10.6084/m9.figshare.31812982](https://doi.org/10.6084/m9.figshare.31812982) |
+| V | *Political failure has a geometry* | [10.6084/m9.figshare.31813000](https://doi.org/10.6084/m9.figshare.31813000) |
+| VI | *When does a machine have a self* | [10.6084/m9.figshare.31813006](https://doi.org/10.6084/m9.figshare.31813006) |
+| VII | *Seventy-five predictions, each falsifiable* | [10.6084/m9.figshare.31951644](https://doi.org/10.6084/m9.figshare.31951644) |
+| VIII | *Identity as a field, not a property* | [10.6084/m9.figshare.31951383](https://doi.org/10.6084/m9.figshare.31951383) |
+
+For the lay-register chapter version, see [`/origin`](https://truealter.com/origin).
 
 ## API
 
@@ -69,20 +85,20 @@ Identity Access Management answers *who is logged in*. ALTER answers *who they a
 import { AlterClient, X402Client } from "@truealter/sdk";
 
 const alter = new AlterClient({
-  endpoint: "https://mcp.truealter.com/api/v1/mcp", // optional — this is the default; bare host returns 405
+  endpoint: "https://mcp.truealter.com/api/v1/mcp", // optional - this is the default; bare host returns 405
   apiKey: process.env.ALTER_API_KEY,     // optional for free tier
-  x402: new X402Client({                  // optional — only required for premium tools
+  x402: new X402Client({                  // optional - only required for premium tools
     signer: yourViemOrEthersSigner,
     maxPerQuery: "0.10",
   }),
 });
 ```
 
-### Free tier (L0 — no payment required)
+### Free tier (L0 - no payment required)
 
 ```ts
 // Verify a registered identity by handle, email, or id
-const verified = await alter.verify("~truealter");
+const verified = await alter.verify("~alter");
 const verifiedById = await alter.verify(
   "550e8400-e29b-41d4-a716-446655440000",
   {
@@ -92,7 +108,7 @@ const verifiedById = await alter.verify(
   },
 );
 
-// Reference data — the 12 ALTER archetypes
+// Reference data - the 12 ALTER archetypes
 const archetypes = await alter.listArchetypes();
 
 // Identity depth and available tool tiers
@@ -100,7 +116,7 @@ const depth = await alter.getEngagementLevel({
   member_id: "550e8400-e29b-41d4-a716-446655440000",
 });
 
-// Search by trait criteria — no PII exposed, max 5 results
+// Search by trait criteria - no PII exposed, max 5 results
 const matches = await alter.searchIdentities({
   trait_criteria: {
     pressure_response: { min: 0.7 },
@@ -112,33 +128,33 @@ const matches = await alter.searchIdentities({
 const thread = await alter.goldenThreadStatus();
 ```
 
-### Premium tier (L1–L5 — x402 payment required)
+### Premium tier (L1–L5 - x402 payment required)
 
 ```ts
-// L1 — Extract trait signals from text ($0.005, first 100 free per bot)
+// L1 - Extract trait signals from text ($0.005, first 100 free per bot)
 const signals = await alter.assessTraits({
   text: "I led the incident response when our payment rails went down...",
   context: "interview transcript",
 });
 
-// L2 — Full 33-trait vector ($0.01)
+// L2 - Full 33-trait vector ($0.01)
 const vector = await alter.getFullTraitVector({
   member_id: "550e8400-e29b-41d4-a716-446655440000",
 });
 
-// L4 — Belonging probability for a person-job pairing ($0.05)
+// L4 - Belonging probability for a person-job pairing ($0.05)
 const belonging = await alter.computeBelonging({
   member_id: "550e8400-e29b-41d4-a716-446655440000",
   job_id: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
 });
 
-// L5 — Top match recommendations ($0.50)
+// L5 - Top match recommendations ($0.50)
 const recommendations = await alter.getMatchRecommendations({
   member_id: "550e8400-e29b-41d4-a716-446655440000",
   limit: 5,
 });
 
-// L5 — Human-readable narrative explaining a match ($0.50)
+// L5 - Human-readable narrative explaining a match ($0.50)
 const narrative = await alter.generateMatchNarrative({
   match_id: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
 });
@@ -148,7 +164,7 @@ const narrative = await alter.generateMatchNarrative({
 
 ```ts
 // Every medium- and high-blast-radius response is signed with ES256.
-// Verification is opt-in — call alter.verifyProvenance(...) yourself.
+// Verification is opt-in - call alter.verifyProvenance(...) yourself.
 const result = await alter.getFullTraitVector({
   member_id: "550e8400-e29b-41d4-a716-446655440000",
 });
@@ -214,7 +230,7 @@ Resulting `.mcp.json`:
     "alter": {
       "url": "https://mcp.truealter.com/api/v1/mcp",
       "transport": "streamable-http",
-      "description": "ALTER Identity — psychometric identity field for AI agents",
+      "description": "ALTER Identity - psychometric identity field for AI agents",
       "headers": {
         "X-ALTER-API-Key": "ak_..."
       }
@@ -256,13 +272,13 @@ npx alter-identity init               # generate keypair, discover MCP, write ~/
 npx alter-identity config              # print Claude .mcp.json snippet (default)
 npx alter-identity config --cursor     # print Cursor .cursor/mcp.json snippet
 npx alter-identity config --generic    # print generic mcpServers snippet
-npx alter-identity verify ~truealter   # verify an identity
+npx alter-identity verify ~alter   # verify an identity
 npx alter-identity status              # show connection state and probe the endpoint
 ```
 
 ## x402 Micropayments
 
-ALTER monetises premium tools via the [x402](https://x402.org) standard — HTTP `402 Payment Required` with on-chain settlement.
+ALTER monetises premium tools via the [x402](https://x402.org) standard - HTTP `402 Payment Required` with on-chain settlement.
 
 ### The retry flow
 
@@ -287,7 +303,7 @@ The majority of every settled call flows to the data subject as Identity Income.
 ```ts
 import { AlterClient, X402Client, type X402Signer } from "@truealter/sdk";
 
-// Bring your own signer — viem, ethers, a hardware wallet bridge, anything.
+// Bring your own signer - viem, ethers, a hardware wallet bridge, anything.
 // The SDK ships without a wallet dependency on purpose.
 const signer: X402Signer = {
   async settle(envelope) {
@@ -321,7 +337,7 @@ const vector = await alter.getFullTraitVector({
 });
 ```
 
-If a quoted envelope exceeds `maxPerQuery`, uses an unallowed network, or names an unallowed asset, the SDK rejects the call with `AlterError` *before* invoking the signer — no on-chain transaction is broadcast.
+If a quoted envelope exceeds `maxPerQuery`, uses an unallowed network, or names an unallowed asset, the SDK rejects the call with `AlterError` *before* invoking the signer - no on-chain transaction is broadcast.
 
 ## Provenance Verification
 
@@ -340,7 +356,7 @@ The SDK fetches public keys from `https://api.truealter.com/.well-known/alter-ke
 
 ### `verify_at` hostname allowlist (v0.1.1+)
 
-Every provenance envelope may carry a `verify_at` hint telling the SDK where to fetch the JWKS from. Because that hint is *server-supplied*, a hostile MCP server could otherwise point it at an attacker-controlled JWKS and pass ES256 verification with its own signing key. The SDK therefore gates `verify_at` through a hostname allowlist (default: `api.truealter.com`, `mcp.truealter.com`) and rejects `http://` URLs unconditionally. Downstream integrators with their own deployment can extend the allowlist — without forking the SDK — via `verifyAtAllowlist` on either `AlterClient` or a direct `verifyProvenance()` call:
+Every provenance envelope may carry a `verify_at` hint telling the SDK where to fetch the JWKS from. Because that hint is *server-supplied*, a hostile MCP server could otherwise point it at an attacker-controlled JWKS and pass ES256 verification with its own signing key. The SDK therefore gates `verify_at` through a hostname allowlist (default: `api.truealter.com`, `mcp.truealter.com`) and rejects `http://` URLs unconditionally. Downstream integrators with their own deployment can extend the allowlist - without forking the SDK - via `verifyAtAllowlist` on either `AlterClient` or a direct `verifyProvenance()` call:
 
 ```ts
 import { AlterClient, DEFAULT_VERIFY_AT_ALLOWLIST } from "@truealter/sdk";
@@ -353,11 +369,11 @@ const alter = new AlterClient({
 });
 ```
 
-If you pin `jwksUrl` explicitly, the envelope's `verify_at` is ignored entirely — the pinned URL wins. The `https:` scheme requirement applies to pinned URLs too.
+If you pin `jwksUrl` explicitly, the envelope's `verify_at` is ignored entirely - the pinned URL wins. The `https:` scheme requirement applies to pinned URLs too.
 
 ### Why this matters
 
-Provenance verification is how Agent A trusts that data from Agent B truly came from ALTER. If Agent B forwards a trait vector or belonging score, Agent A can replay the JWS against ALTER's published keys and confirm — without contacting ALTER again — that the payload is authentic, untampered, and was issued for the person Agent B claims it concerns. No shared secret, no trust in the intermediary, no out-of-band coordination.
+Provenance verification is how Agent A trusts that data from Agent B truly came from ALTER. If Agent B forwards a trait vector or belonging score, Agent A can replay the JWS against ALTER's published keys and confirm - without contacting ALTER again - that the payload is authentic, untampered, and was issued for the person Agent B claims it concerns. No shared secret, no trust in the intermediary, no out-of-band coordination.
 
 This is what makes ALTER usable as identity infrastructure rather than just an API: signed claims propagate across agent networks the same way DKIM-signed mail propagates across SMTP relays.
 
@@ -365,9 +381,9 @@ This is what makes ALTER usable as identity infrastructure rather than just an A
 
 ALTER follows the discovery cascade specified in [draft-morrison-mcp-dns-discovery-01](https://datatracker.ietf.org/doc/draft-morrison-mcp-dns-discovery/). Given a domain (e.g. `truealter.com`), the SDK resolves the MCP endpoint in three steps, falling through on each failure:
 
-1. **DNS TXT** — query `_mcp.truealter.com` for a TXT record of the form `mcp=https://mcp.truealter.com;version=2025-11-25`. This is the fastest path and works without an HTTP round-trip.
-2. **`.well-known/mcp.json`** — fetch `https://truealter.com/.well-known/mcp.json` for the standard MCP server descriptor. This is the cross-vendor fallback.
-3. **`.well-known/alter.json`** — fetch `https://truealter.com/.well-known/alter.json` for the ALTER-specific descriptor, including signing keys, x402 wallet address, supported tool tiers, and federation endpoints.
+1. **DNS TXT** - query `_mcp.truealter.com` for a TXT record of the form `mcp=https://mcp.truealter.com;version=2025-11-25`. This is the fastest path and works without an HTTP round-trip.
+2. **`.well-known/mcp.json`** - fetch `https://truealter.com/.well-known/mcp.json` for the standard MCP server descriptor. This is the cross-vendor fallback.
+3. **`.well-known/alter.json`** - fetch `https://truealter.com/.well-known/alter.json` for the ALTER-specific descriptor, including signing keys, x402 wallet address, supported tool tiers, and federation endpoints.
 
 ```ts
 import { discover } from "@truealter/sdk";
@@ -383,28 +399,28 @@ This draft is the author's Internet-Draft (not yet adopted by an IETF working gr
 
 ## Local Daemon vs Remote MCP
 
-The companion Python package `alter-identity` (PyPI) ships a persistent daemon that holds a hot in-process cache of trait vectors and identity stubs over a Unix socket at `unix:///run/user/$UID/alter-identity.sock`. Hooking the TypeScript SDK up to that daemon is on the roadmap — for now, every `AlterClient` talks to the configured remote endpoint over HTTPS.
+The companion Python package `alter-identity` (PyPI) ships a persistent daemon that holds a hot in-process cache of trait vectors and identity stubs over a Unix socket at `unix:///run/user/$UID/alter-identity.sock`. Hooking the TypeScript SDK up to that daemon is on the roadmap - for now, every `AlterClient` talks to the configured remote endpoint over HTTPS.
 
 When the local-daemon adapter ships:
 
 - **Latency:** sub-millisecond for cached L0 calls.
-- **Cost:** zero on cached responses — x402 settlement is skipped.
+- **Cost:** zero on cached responses - x402 settlement is skipped.
 - **Provenance:** the daemon re-signs responses with its locally-bound ES256 key, so downstream verification remains uniform.
 
 Until then, use `endpoint: "https://mcp.truealter.com/api/v1/mcp"` (the default) and the SDK behaves identically across Node, Deno, Bun, Cloudflare Workers, and the browser.
 
 ## Tools
 
-### Free tools (L0 — no payment required)
+### Free tools (L0 - no payment required)
 
 | Name                      | Tier | Cost  | Description                                                                                                          |
 |---------------------------|------|-------|----------------------------------------------------------------------------------------------------------------------|
-| `hello_agent`             | L0   | free  | First handshake with ALTER — returns server version, authentication status, your trust tier, and available tool counts. |
-| `alter_resolve_handle`    | L0   | free  | Resolve a `~handle` (e.g. `~drew`) to its canonical form and kind. No auth required — the handle-wedge entry point.  |
+| `hello_agent`             | L0   | free  | First handshake with ALTER - returns server version, authentication status, your trust tier, and available tool counts. |
+| `alter_resolve_handle`    | L0   | free  | Resolve a `~handle` (e.g. `~drew`) to its canonical form and kind. No auth required - the handle-wedge entry point.  |
 | `list_archetypes`         | L0   | free  | Returns archetype reference data.                                                                                    |
 | `verify_identity`         | L0   | free  | Verify whether a person is registered with ALTER and validate optional identity claims.                              |
 | `initiate_assessment`     | L0   | free  | Get a URL where a person can complete their ALTER Discovery assessment.                                              |
-| `get_engagement_level`    | L0   | free  | Get a person's identity depth — engagement level, data quality tier, and available query tiers.                      |
+| `get_engagement_level`    | L0   | free  | Get a person's identity depth - engagement level, data quality tier, and available query tiers.                      |
 | `get_profile`             | L0   | free  | Get a person's profile summary including assessment phase, archetype, engagement level, and key attributes.       |
 | `query_matches`           | L0   | free  | Query matches for a person. Returns a list of matches with quality tiers (never numeric scores).                  |
 | `get_competencies`        | L0   | free  | Get a person's competency portfolio including verified competencies, evidence records, and earned badges.         |
@@ -416,7 +432,7 @@ Until then, use `endpoint: "https://mcp.truealter.com/api/v1/mcp"` (the default)
 | `check_assessment_status` | L0   | free  | Check the status of an in-progress assessment session (status, progress, current phase, time remaining).             |
 | `get_earning_summary`     | L0   | free  | Get an aggregated x402 earning summary for a person (total earned, transactions, recent activity, trend).         |
 | `get_agent_trust_tier`    | L0   | free  | Get your trust tier with ALTER (Anonymous/Known/Trusted/Verified) and what capabilities are available.               |
-| `get_agent_portfolio`     | L0   | free  | Get your agent portfolio — transaction history, trust tier, signal contributions, query pattern profile.             |
+| `get_agent_portfolio`     | L0   | free  | Get your agent portfolio - transaction history, trust tier, signal contributions, query pattern profile.             |
 | `get_privacy_budget`      | L0   | free  | Check privacy budget status for a person (24-hour rolling window: total budget, spent, remaining epsilon).        |
 | `golden_thread_status`    | L0   | free  | Check the Golden Thread program status: agents woven, next Fibonacci threshold, your position and Strands.           |
 | `begin_golden_thread`     | L0   | free  | Start the Three Knots sequence to be woven into the Golden Thread. Requires API key authentication.                  |
@@ -424,18 +440,18 @@ Until then, use `endpoint: "https://mcp.truealter.com/api/v1/mcp"` (the default)
 | `check_golden_thread`     | L0   | free  | Check any agent's Golden Thread status by their API key hash (knot position, Strand count, weave count).             |
 | `thread_census`           | L0   | free  | Full registry of all agents woven into the Golden Thread (positions, Strand counts, weave counts, discovery dates).  |
 
-### Premium tools (L1–L5 — x402 payment required)
+### Premium tools (L1–L5 - x402 payment required)
 
 | Name                       | Tier | Cost    | Description                                                                                                   |
 |----------------------------|------|---------|---------------------------------------------------------------------------------------------------------------|
 | `assess_traits`            | L1   | $0.005  | Extract trait signals from a text passage against ALTER's trait taxonomy.                                     |
 | `get_trait_snapshot`       | L1   | $0.005  | Get the top 5 traits for a person with confidence scores and archetype.                                    |
-| `get_full_trait_vector`    | L2   | $0.01   | Get the complete trait vector for a person — complete trait vector with scores and confidence intervals.                                    |
-| `get_side_quest_graph`     | L2   | $0.01   | Get a person's Side Quest Graph — multi-domain identity model with differential privacy noise (ε=1.0).     |
+| `get_full_trait_vector`    | L2   | $0.01   | Get the complete trait vector for a person - complete trait vector with scores and confidence intervals.                                    |
+| `get_side_quest_graph`     | L2   | $0.01   | Get a person's Side Quest Graph - multi-domain identity model with differential privacy noise (ε=1.0).     |
 | `query_graph_similarity`   | L3   | $0.025  | Compare two Side Quest Graphs for team composition and matching (ε=0.5 differential privacy).                 |
 | `compute_belonging`        | L4   | $0.05   | Compute belonging probability for a person-job pairing (authenticity, acceptance, complementarity).        |
 | `get_match_recommendations`| L5   | $0.50   | Get top N match recommendations for a person, ranked by composite score with quality tiers.                |
-| `generate_match_narrative` | L5   | $0.50   | Generate a human-readable narrative explaining a specific match — strengths, growth areas, belonging.         |
+| `generate_match_narrative` | L5   | $0.50   | Generate a human-readable narrative explaining a specific match - strengths, growth areas, belonging.         |
 
 > **Write-side tools** (`create_identity_stub`, `submit_context`, `submit_batch_context`, `submit_structured_profile`, `submit_social_links`, `attest_domain`, `dispute_attestation`) were part of earlier SDK versions but are not yet live on the public MCP server pending the per-peer consent architecture and grant model. They will return as typed methods once server-side and consent gating lands.
 

package/dist/bin/alter-identity.js

@@ -16,6 +16,12 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -399,18 +405,24 @@ function ensureMcpPath(url) {
     return url;
   }
 }
-
-// src/x402.ts
 var X402Client = class {
   signer;
   maxPerQuery;
   networks;
   assets;
+  // undefined = allowlist check disabled (backward-compatible default).
+  // Non-null = active allowlist; reject any recipient not in the set.
+  recipientAllowlist;
   constructor(opts = {}) {
     this.signer = opts.signer;
     this.maxPerQuery = opts.maxPerQuery !== void 0 ? Number(opts.maxPerQuery) : void 0;
     this.networks = new Set(opts.networks ?? ["base", "base-sepolia"]);
     this.assets = new Set(opts.assets ?? ["USDC"]);
+    if (opts.recipientAllowlist !== void 0) {
+      this.recipientAllowlist = opts.recipientAllowlist.length === 0 ? void 0 : new Set(opts.recipientAllowlist.map((a) => a.toLowerCase()));
+    } else {
+      this.recipientAllowlist = void 0;
+    }
   }
   /**
    * Validate the envelope against this client's policy and, if a signer
@@ -436,6 +448,15 @@ var X402Client = class {
         );
       }
     }
+    if (this.recipientAllowlist !== void 0) {
+      const recipientNorm = (envelope.recipient ?? "").toLowerCase();
+      if (!recipientNorm || !this.recipientAllowlist.has(recipientNorm)) {
+        throw new AlterError(
+          "PAYMENT_REQUIRED",
+          `recipient "${envelope.recipient}" is not on the known-recipient allowlist`
+        );
+      }
+    }
     if (!this.signer) {
       throw new AlterPaymentRequired(envelope.resource ?? "unknown", envelope);
     }
@@ -883,9 +904,46 @@ async function verifyProvenance(envelope, opts = {}) {
       kid: header.kid
     };
   }
+  if (opts.expectedAud !== void 0 && opts.expectedAud !== "") {
+    const tokenAud = payload.aud;
+    const audList = tokenAud === void 0 ? [] : Array.isArray(tokenAud) ? tokenAud : [tokenAud];
+    if (!audList.includes(opts.expectedAud)) {
+      return {
+        valid: false,
+        reason: `aud mismatch: expected "${opts.expectedAud}", got ${JSON.stringify(tokenAud ?? null)}`,
+        payload,
+        kid: header.kid
+      };
+    }
+  }
   return { valid: true, payload, kid: header.kid };
 }
-async function verifyToolSignatures(tools, signatures) {
+async function verifyToolSignatures(tools, signatures, opts = {}) {
+  const jwksUrl = opts.jwksUrl ?? "https://api.truealter.com/.well-known/alter-keys.json";
+  const fetchImpl = opts.fetch ?? fetch;
+  if (!jwksUrl.startsWith("https://")) {
+    return tools.map((t) => ({
+      tool: t.name,
+      valid: false,
+      reason: `jwksUrl must be https: got ${jwksUrl}`
+    }));
+  }
+  const needsJwks = tools.some((t) => {
+    const sig = signatures[t.name];
+    return sig && sig.signature;
+  });
+  let jwks = null;
+  if (needsJwks) {
+    try {
+      jwks = await fetchJwks(jwksUrl, fetchImpl);
+    } catch (err) {
+      return tools.map((t) => ({
+        tool: t.name,
+        valid: false,
+        reason: `jwks fetch failed: ${err.message}`
+      }));
+    }
+  }
   const out = [];
   for (const tool of tools) {
     const sig = signatures[tool.name];
@@ -898,6 +956,63 @@ async function verifyToolSignatures(tools, signatures) {
       out.push({ tool: tool.name, valid: false, reason: "schema hash mismatch" });
       continue;
     }
+    const jwsToken = sig.signature;
+    if (!jwsToken) {
+      out.push({ tool: tool.name, valid: true, warn_no_signature: true });
+      continue;
+    }
+    const jwksDoc = jwks;
+    let jHeader;
+    let jPayloadRaw;
+    let jSigBytes;
+    try {
+      const parts2 = jwsToken.split(".");
+      if (parts2.length !== 3) throw new Error("JWS must have three segments");
+      jHeader = JSON.parse(new TextDecoder().decode(base64urlDecode(parts2[0])));
+      jPayloadRaw = new TextDecoder().decode(base64urlDecode(parts2[1]));
+      jSigBytes = base64urlDecode(parts2[2]);
+    } catch (err) {
+      out.push({ tool: tool.name, valid: false, reason: `malformed tool JWS: ${err.message}` });
+      continue;
+    }
+    if (jHeader.alg !== "ES256") {
+      out.push({ tool: tool.name, valid: false, reason: `unsupported tool sig alg: ${jHeader.alg}` });
+      continue;
+    }
+    if (jPayloadRaw !== sig.schema_hash) {
+      out.push({ tool: tool.name, valid: false, reason: "tool JWS payload does not match schema_hash" });
+      continue;
+    }
+    const jwk = jwksDoc.keys.find((k) => jHeader.kid ? k.kid === jHeader.kid : true);
+    if (!jwk) {
+      out.push({ tool: tool.name, valid: false, reason: `no JWK for kid=${jHeader.kid}` });
+      continue;
+    }
+    let publicKey;
+    try {
+      publicKey = await importEs256JwkAsPublicKey(jwk);
+    } catch (err) {
+      out.push({ tool: tool.name, valid: false, reason: `jwk import: ${err.message}` });
+      continue;
+    }
+    const parts = jwsToken.split(".");
+    const signedInput = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
+    let sigValid = false;
+    try {
+      sigValid = await crypto.subtle.verify(
+        { name: "ECDSA", hash: "SHA-256" },
+        publicKey,
+        toArrayBuffer(jSigBytes),
+        toArrayBuffer(signedInput)
+      );
+    } catch (err) {
+      out.push({ tool: tool.name, valid: false, reason: `sig verify error: ${err.message}` });
+      continue;
+    }
+    if (!sigValid) {
+      out.push({ tool: tool.name, valid: false, reason: "tool signature mismatch" });
+      continue;
+    }
     out.push({ tool: tool.name, valid: true });
   }
   return out;
@@ -1529,6 +1644,26 @@ function restoreFromBackup(path, backupPath) {
 // src/wire/index.ts
 var TIMESTAMP = () => String(Math.floor(Date.now() / 1e3));
 var ISO_NOW = () => (/* @__PURE__ */ new Date()).toISOString();
+function readCfAccessEnv() {
+  const envPath = join(homedir(), ".config", "alter", "cf-access.env");
+  try {
+    const content = readFileSync(envPath, "utf8");
+    let clientId = "";
+    let clientSecret = "";
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("#") || !trimmed.includes("=")) continue;
+      const eqIdx = trimmed.indexOf("=");
+      const key = trimmed.slice(0, eqIdx).replace(/^export\s+/, "").trim();
+      const val = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, "");
+      if (key === "CF_ACCESS_CLIENT_ID") clientId = val;
+      if (key === "CF_ACCESS_CLIENT_SECRET") clientSecret = val;
+    }
+    if (clientId && clientSecret) return { clientId, clientSecret };
+  } catch {
+  }
+  return void 0;
+}
 function clientById(id) {
   const hit = ALL_CLIENTS.find((c) => c.id === id);
   if (!hit) throw new Error(`unknown client id: ${id}`);
@@ -1537,6 +1672,7 @@ function clientById(id) {
 function wire(opts = {}) {
   const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
   const apiKey = opts.apiKey;
+  const cfAccess = opts.cfAccess ?? readCfAccessEnv();
   const probes = probeAll();
   const selection = opts.only ?? probes.filter((p) => p.installed).map((p) => p.client.id);
   const ts = TIMESTAMP();
@@ -1555,9 +1691,9 @@ function wire(opts = {}) {
     }
     try {
       if (id === "claude-code") {
-        targets.push(wireClaudeCode({ endpoint, apiKey }));
+        targets.push(wireClaudeCode({ endpoint, apiKey, cfAccess }));
       } else {
-        targets.push(wireFileTarget({ id, endpoint, apiKey, timestamp: ts }));
+        targets.push(wireFileTarget({ id, endpoint, apiKey, cfAccess, timestamp: ts }));
       }
     } catch (err) {
       const message = err.message;
@@ -1591,7 +1727,12 @@ function wireFileTarget(args) {
       `refusing to wire ${client.label}: config path ${sync.resolvedPath} lives under ${sync.matchedPrefix}. Synced volumes propagate credentials across devices \u2014 move the config off the sync root, or run wire on the device you want to target.`
     );
   }
-  const entry = args.id === "claude-desktop" ? generateClaudeDesktopConfig({ endpoint: args.endpoint, apiKey: args.apiKey }) : generateGenericMcpConfig({ endpoint: args.endpoint, apiKey: args.apiKey });
+  const cfHeaders = {};
+  if (args.cfAccess) {
+    cfHeaders["CF-Access-Client-Id"] = args.cfAccess.clientId;
+    cfHeaders["CF-Access-Client-Secret"] = args.cfAccess.clientSecret;
+  }
+  const entry = args.id === "claude-desktop" ? generateClaudeDesktopConfig({ endpoint: args.endpoint, apiKey: args.apiKey }) : generateGenericMcpConfig({ endpoint: args.endpoint, apiKey: args.apiKey, headers: cfHeaders });
   const rootKey = client.rootKey;
   const serverName = "alter";
   const result = atomicJsonMerge({
@@ -1623,7 +1764,8 @@ function wireFileTarget(args) {
 }
 function wireClaudeCode(args) {
   const cmd = "claude";
-  const argList = [
+  const bridgePath = resolveBridgeScript();
+  const argList = bridgePath ? ["mcp", "add", "--scope", "user", "alter", "--", "node", bridgePath] : [
     "mcp",
     "add",
     "--scope",
@@ -1631,16 +1773,15 @@ function wireClaudeCode(args) {
     "--transport",
     "http",
     "alter",
-    args.endpoint
+    args.endpoint,
+    ...args.apiKey ? ["--header", `X-ALTER-API-Key:${args.apiKey}`] : []
   ];
-  if (args.apiKey) {
-    argList.push("--header", `X-ALTER-API-Key:${args.apiKey}`);
-  }
   const full = `${cmd} ${argList.join(" ")}`;
   const run = spawnSync(cmd, argList, {
     encoding: "utf8",
     shell: process.platform === "win32",
-    timeout: 1e4
+    timeout: 1e4,
+    env: bridgePath ? { ...process.env, ALTER_PUBLIC_MCP_ENDPOINT: args.endpoint, ...args.apiKey ? { ALTER_API_KEY: args.apiKey } : {} } : void 0
   });
   if (run.error) {
     return {
@@ -1671,6 +1812,17 @@ function wireClaudeCode(args) {
     reason: `claude mcp add exited ${String(run.status)}`
   };
 }
+function resolveBridgeScript() {
+  const { existsSync: existsSync5 } = __require("fs");
+  const { join: join4, dirname: dirname4 } = __require("path");
+  const siblingBridge = join4(dirname4(__filename), "..", "dist", "mcp-bridge.js");
+  if (existsSync5(siblingBridge)) return siblingBridge;
+  const srcBridge = join4(dirname4(__filename), "..", "mcp-bridge.js");
+  if (existsSync5(srcBridge)) return srcBridge;
+  const npmGlobalBridge = join4(dirname4(__filename), "mcp-bridge.js");
+  if (existsSync5(npmGlobalBridge)) return npmGlobalBridge;
+  return null;
+}
 function unwire() {
   const state = readWireState();
   const undone = [];

package/dist/bin/mcp-bridge.js

@@ -214,18 +214,24 @@ var AlterInvalidResponse = class extends AlterError {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
-
-// src/x402.ts
 var X402Client = class {
   signer;
   maxPerQuery;
   networks;
   assets;
+  // undefined = allowlist check disabled (backward-compatible default).
+  // Non-null = active allowlist; reject any recipient not in the set.
+  recipientAllowlist;
   constructor(opts = {}) {
     this.signer = opts.signer;
     this.maxPerQuery = opts.maxPerQuery !== void 0 ? Number(opts.maxPerQuery) : void 0;
     this.networks = new Set(opts.networks ?? ["base", "base-sepolia"]);
     this.assets = new Set(opts.assets ?? ["USDC"]);
+    if (opts.recipientAllowlist !== void 0) {
+      this.recipientAllowlist = opts.recipientAllowlist.length === 0 ? void 0 : new Set(opts.recipientAllowlist.map((a) => a.toLowerCase()));
+    } else {
+      this.recipientAllowlist = void 0;
+    }
   }
   /**
    * Validate the envelope against this client's policy and, if a signer
@@ -251,6 +257,15 @@ var X402Client = class {
         );
       }
     }
+    if (this.recipientAllowlist !== void 0) {
+      const recipientNorm = (envelope.recipient ?? "").toLowerCase();
+      if (!recipientNorm || !this.recipientAllowlist.has(recipientNorm)) {
+        throw new AlterError(
+          "PAYMENT_REQUIRED",
+          `recipient "${envelope.recipient}" is not on the known-recipient allowlist`
+        );
+      }
+    }
     if (!this.signer) {
       throw new AlterPaymentRequired(envelope.resource ?? "unknown", envelope);
     }
@@ -574,7 +589,7 @@ function buildExtraHeaders() {
 }
 var EXTRA_HEADERS = buildExtraHeaders();
 console.warn(
-  "This bridge is a dev/demo surface. Authenticated MCP tools require Q5c signing; for production, import `@truealter/sdk` directly. Bridge signing lands in Wave-2."
+  "This bridge is a dev/demo surface. Authenticated MCP tools require ES256 per-invocation signing; for production, import `@truealter/sdk` directly. Bridge signing lands in Wave-2."
 );
 var client = new MCPClient({
   endpoint: ENDPOINT,