@truealter/sdk 0.5.3 → 0.5.8

package/dist/index.d.ts

@@ -437,7 +437,7 @@ interface MCPClientInfo {
     version: string;
 }
 interface MCPClientOptions {
-    /** Streamable HTTP endpoint. Default: https://mcp.truealter.com */
+    /** Streamable HTTP endpoint. Default: https://mcp.truealter.com/api/v1/mcp (public discovery). Member bridge runtime sets api.truealter.com via env or explicit option. */
     endpoint?: string;
     /** Optional API key for the `X-ALTER-API-Key` header. */
     apiKey?: string;
@@ -474,7 +474,7 @@ interface MCPClientOptions {
     /**
      * Optional hook invoked once, lazily, before the first network call
      * (the first `initialize()` or any direct `rpc()`). Used by
-     * {@link AlterClient} to run the D-MIN-VERSION-FLOOR-1 preflight on
+     * {@link AlterClient} to run the version-floor preflight on
      * first request: not on import, not in the constructor. A throw
      * from the hook propagates to the caller of the first `tools/call`
      * (or `initialize()`).
@@ -486,7 +486,7 @@ interface MCPSigningOptions {
     kid: string;
     /** ES256 P-256 private key: 32-byte scalar or PEM. */
     privateKey: Uint8Array | string;
-    /** The caller's bound ~handle. */
+    /** The caller's bound handle. */
     handle: string;
 }
 interface MCPCallOptions {
@@ -545,7 +545,7 @@ declare class MCPClient {
     private initialised;
     constructor(opts?: MCPClientOptions);
     /**
-     * Run the lazy preflight hook (D-MIN-VERSION-FLOOR-1) exactly once.
+     * Run the lazy version-floor preflight hook exactly once.
      * Idempotent and serialised: concurrent callers share the same
      * promise. Throws from the hook propagate to every concurrent caller.
      */
@@ -1212,7 +1212,8 @@ declare const TOOL_BLAST_RADIUS: Record<ToolName, "low" | "medium" | "high">;
  * This is the entry point most consumers will use. It bundles
  * {@link MCPClient}, {@link X402Client}, discovery, and provenance
  * verification into a single ergonomic surface that mirrors the 32
- * tools exposed at https://mcp.truealter.com/api/v1/mcp.
+ * tools exposed at https://mcp.truealter.com/api/v1/mcp (public/discovery)
+ * and https://api.truealter.com/api/v1/mcp (member bearer-first runtime).
  *
  * Free tier methods require no authentication. Premium methods accept
  * an `X402Client` (or fall back to throwing {@link AlterPaymentRequired}
@@ -1237,8 +1238,13 @@ interface AlterClientOptions extends Omit<MCPClientOptions, 'x402'> {
      */
     skipDiscovery?: boolean;
     /**
-     * URL of the JWKS document used for provenance verification. Defaults
-     * to `https://api.truealter.com/.well-known/alter-keys.json`.
+     * URL of the JWKS document used for provenance verification.
+     *
+     * When unset, the JWKS host is derived from the configured API surface
+     * ({@link resolveJwksUrl}: `apiBase` > `ALTER_API` env > the `endpoint`
+     * origin > the canonical `api.truealter.com`), so the trust anchor
+     * tracks whatever surface the client is actually pointed at rather than
+     * a single hardcoded host.
      *
      * When set, this URL is used verbatim for every `verifyProvenance`
      * call and *overrides* any `verify_at` hint on the server response:
@@ -1258,7 +1264,7 @@ interface AlterClientOptions extends Omit<MCPClientOptions, 'x402'> {
      */
     verifyAtAllowlist?: readonly string[];
     /**
-     * Skip the D-MIN-VERSION-FLOOR-1 client-side preflight (the lazy
+     * Skip the client-side version-floor preflight (the lazy
      * `checkMinVersion()` invocation on first request). Deliberately named
      * to discourage casual use: the server-side floor gate (Phase 1
      * middleware) still rejects below-floor clients with HTTP 426
@@ -1402,7 +1408,15 @@ declare class AlterClient {
         valid: boolean;
         reason?: string;
     }[]>;
-    /** Fetch the published JWKS for ALTER's signing key (cached 5 min). */
+    /**
+     * Fetch the published JWKS for ALTER's signing key (cached 5 min).
+     *
+     * The JWKS URL is derived from the configured API surface
+     * ({@link resolveJwksUrl}: explicit `jwksUrl` > `apiBase` > `ALTER_API` >
+     * the configured `endpoint` origin > the canonical host) rather than a
+     * single hardcoded host, so the trust anchor tracks the surface the
+     * client is actually pointed at.
+     */
     fetchPublicKeys(): Promise<unknown>;
 }
 
@@ -1477,9 +1491,9 @@ interface SignInvocationOptions {
 declare function signInvocation(toolName: string, toolArgs: Record<string, unknown>, options: SignInvocationOptions): string;
 
 /**
- * floor-preflight: SDK-side D-MIN-VERSION-FLOOR-1 Phase 4 enforcement.
+ * floor-preflight: SDK-side client version-floor enforcement.
  *
- * Sister to `alter-cli`'s `src/lib/floor-preflight.ts` (Phase 2). This is
+ * Sister to the CLI client's own floor-preflight. This is
  * the `@truealter/sdk` implementation: it fires lazily on the first
  * authenticated network call from {@link AlterClient}, hits the public
  * floor endpoint, verifies the Ed25519 signature against the published
@@ -1505,8 +1519,8 @@ declare function signInvocation(toolName: string, toolArgs: Record<string, unkno
  * corresponding public key (SPKI PEM) in {@link KNOWN_FLOOR_PUBLIC_KEYS},
  * keyed by `key_id`. No signing secret ships in the client: this is
  * asymmetric: the public key cannot forge signatures. MUST stay
- * byte-compatible with `backend/app/core/floor_signing.py` and the
- * canonical TypeScript client (`alter-cli` `src/lib/floor-preflight.ts`):
+ * byte-compatible with the ALTER backend floor-signing implementation
+ * and the canonical TypeScript CLI client:
  *   - Algorithm: Ed25519 (RFC 8032). Deterministic: same key + payload
  *     always yields the same signature.
  *   - `key_id`  = first 8 hex chars of SHA-256(raw 32-byte public key).
@@ -1534,8 +1548,8 @@ declare const CLIENT_CHANNEL = "npm";
 /**
  * Compute the 8-char `key_id` for an Ed25519 public key (SPKI PEM).
  *
- * Matches the backend `key_id_for_public_key(pub)` in
- * `backend/app/core/floor_signing.py`:
+ * Matches the backend `key_id_for_public_key(pub)` in the ALTER
+ * backend floor-signing implementation:
  *   raw = pub.public_bytes(Encoding.Raw, PublicFormat.Raw)  # 32 bytes
  *   sha256(raw).hexdigest()[:8]
  *
@@ -1552,7 +1566,7 @@ declare function computeKeyId(publicKeyPem: string): string;
  * stripped via the `,`/`:` separators; non-ASCII passes through as raw UTF-8
  * (Node's `JSON.stringify` never `\uXXXX`-escapes non-ASCII, matching the
  * backend's `ensure_ascii=False`). The result is the byte-exact input to
- * Ed25519 signing (backend) and verification (this SDK and alter-cli) on
+ * Ed25519 signing (backend) and verification (this SDK and the CLI client) on
  * both sides.
  */
 declare function canonicalJson(obj: unknown): string;
@@ -1562,12 +1576,12 @@ declare function canonicalJson(obj: unknown): string;
  * `key_id` = first 8 hex chars of SHA-256(raw 32-byte Ed25519 public key).
  * Use `computeKeyId(spkiPem)` to re-derive and validate the map key.
  *
- * Backend may rotate via D-MSG11 dual-key path: clients keep N keys and
+ * Backend may rotate via a dual-key path: clients keep N keys and
  * select via `key_id`. Add new keys additively; remove old keys only after
  * all deployed clients have received the new key.
  *
  * Current keys (mirrors `KNOWN_FLOOR_PUBLIC_KEYS` in the canonical
- * `alter-cli` client):
+ * CLI client):
  *   8aa59e05: dev/non-prod key (local + e2e + staging). Safe to ship publicly;
  *              this is the PUBLIC key only, never the private key.
  *   640f7d9a: prod key. Added 2026-06-05. key_id = first 8 hex of
@@ -1707,7 +1721,7 @@ declare function compareSemver(a: string, b: string): number;
  * canonical JSON of `{ floors, served_at }`: `signature` + `key_id` +
  * `cache_ttl_seconds` are excluded from the signed bytes.
  *
- * MUST stay byte-compatible with the backend (`backend/app/core/floor_signing.py`):
+ * MUST stay byte-compatible with the ALTER backend floor-signing implementation:
  *   - Algorithm: Ed25519 (RFC 8032). Deterministic: same key + payload = same sig.
  *   - Payload: `canonicalJson({floors, served_at})`: sorted-keys + compact.
  *   - `key_id`: first 8 hex chars of SHA-256(raw 32-byte Ed25519 public key).
@@ -1715,7 +1729,7 @@ declare function compareSemver(a: string, b: string): number;
  *
  * The `keys` parameter maps `key_id -> SPKI PEM string`; defaults to
  * `KNOWN_FLOOR_PUBLIC_KEYS`. Returns false on unknown key_id (triggers refetch
- * per D-MSG11 rotation path).
+ * per the key-rotation path).
  */
 declare function verifyFloorSignature(doc: FloorDocument, keys?: Record<string, string>): boolean;
 
@@ -1747,8 +1761,8 @@ declare function generateGenericMcpConfig(opts?: GenerateMcpConfigOptions): Gene
 /**
  * Claude Code MCP config helper.
  *
- * Claude Code reads MCP servers from `.mcp.json` (project) or
- * `~/.claude/mcp.json` (user). The shape matches `mcpServers`.
+ * Claude Code reads MCP servers from the project-level `.mcp.json` or
+ * the user-level Claude Code config. The shape matches `mcpServers`.
  */
 
 declare function generateClaudeConfig(opts?: GenerateMcpConfigOptions): GenericMcpConfig;
@@ -1766,10 +1780,11 @@ declare function generateCursorConfig(opts?: GenerateMcpConfigOptions): GenericM
  * Claude Desktop MCP config helper.
  *
  * Claude Desktop speaks stdio only: it does not currently dial
- * Streamable-HTTP MCP servers directly. The canonical bridge is our
- * own `alter-mcp-bridge` binary, which is published alongside this CLI
- * in the same npm package. Desktop hosts then spawn the bridge as a
- * child process and read JSON-RPC over stdin/stdout.
+ * Streamable-HTTP MCP servers directly. The canonical bridge is the
+ * `alter` CLI's `mcp-bridge` subcommand. The SDK no longer publishes a
+ * standalone bridge binary; the CLI launches the bridge by file path.
+ * Desktop hosts spawn `alter mcp-bridge` as a child process and read
+ * JSON-RPC over stdin/stdout.
  *
  * Config file path varies by platform and is resolved in
  * `src/wire/paths.ts`. This adapter only produces the config *shape*.
@@ -1790,9 +1805,9 @@ interface GenerateClaudeDesktopOptions {
     apiKey?: string;
     /** Identifier used by Claude Desktop for this server. Default: `alter`. */
     serverName?: string;
-    /** Override the bridge command (e.g. `npx alter-mcp-bridge`). Default: bare `alter-mcp-bridge`. */
+    /** Override the bridge command (e.g. `npx`). Default: the `alter` CLI. */
     bridgeCommand?: string;
-    /** Extra args appended after the default bridge args. */
+    /** Extra args appended after the default `mcp-bridge` subcommand arg. */
     extraArgs?: string[];
 }
 declare function generateClaudeDesktopConfig(opts?: GenerateClaudeDesktopOptions): ClaudeDesktopConfig;
@@ -1943,6 +1958,15 @@ interface WireOptions {
     only?: readonly ClientId[];
     /** Skip any client whose probe said "not installed" even if the caller passed it via `only`. */
     skipMissing?: boolean;
+    /**
+     * Absolute path to the `alter` CLI launcher entry (its `dist/index.js`).
+     * When set, Claude Code is wired to run `node <launcherPath> mcp-bridge`,
+     * which injects the ES256 signing credential (ALTER_SIGNING_KEY /
+     * ALTER_SIGNING_KID) from the OS secure store before spawning the bridge,
+     * so MCP tool calls are signed. When absent (standalone SDK use without the
+     * CLI), wiring falls back to `node <bridge>`: anonymous / L0, no signing.
+     */
+    launcherPath?: string;
 }
 interface WireReport {
     state: WireState;
@@ -1980,13 +2004,13 @@ declare const TIER_PRICES: Record<string, number>;
 /** Publicly advertised tool counts. Mirrors canonical-facts.json public_advertised. */
 declare const ADVERTISED_TOOL_COUNTS: {
     /** Free (L0) tools visible to anonymous / agent-class callers. */
-    readonly free: 26;
+    readonly free: 27;
     /** Premium (L1-L5) tools requiring x402 payment. */
-    readonly premium: 8;
+    readonly premium: 9;
     /** Messaging tools (member-self-only; excluded from external advertisement). */
     readonly messaging: 0;
     /** Total publicly advertised (free + premium). */
-    readonly total: 34;
+    readonly total: 36;
 };
 /** x402 settlement revenue split. Weaver = the data subject earning Identity Income. */
 declare const REVENUE_SPLIT: {
@@ -2164,8 +2188,8 @@ interface HomepageOutput {
  */
 type HomepageCallerVertical = "workplace" | "education" | "personal" | "civic" | "agent" | "unknown";
 /** Maximum sizes from the spec. SDK consumers can use these to validate
- *  input before sending. Mirrored from
- *  `docs/technical/alter-portfolio-manifest-v1.md` (forthcoming). */
+ *  input before sending. Mirrored from the ALTER portfolio manifest spec v1
+ *  (forthcoming). */
 declare const HOMEPAGE_LIMITS: {
     readonly whoami_max_chars: 240;
     readonly opener_max_chars: 280;
@@ -2178,8 +2202,7 @@ declare const HOMEPAGE_LIMITS: {
  * @truealter/sdk: theme pack types
  *
  * Wire-format types for ALTER theme packs and `themes.lock` composition
- * manifests. The full specification lives in
- * `docs/technical/alter-theme-pack-spec-v1.md`.
+ * manifests. The full specification lives in the ALTER theme pack spec v1.
  *
  * These types describe the on-the-wire shape of theme manifests as they
  * are produced by `alter theme install`, persisted to `themes.lock`,
@@ -2205,7 +2228,7 @@ interface ThemeMeta {
     name: string;
     /** SemVer-shaped recommended; informational only. Resolution uses pack_id. */
     version: string;
-    /** MUST be a ~handle whose D-ID8 public key signs the pack. */
+    /** MUST be a ~handle whose signing public key signs the pack. */
     author: string;
     /** ≤ 240 characters after NFC. */
     description: string;
@@ -2267,7 +2290,7 @@ interface ThemeManifestV1 {
 }
 /**
  * The `.sig` file accompanying every pack. Verification logic lives in
- * `alter-cli/src/theme/sign.ts`; this is the wire-format type only.
+ * the CLI client; this is the wire-format type only.
  */
 interface ThemeSignatureManifest {
     /** SHA-256 multihash of the canonical-form pack. */
@@ -2303,7 +2326,7 @@ interface ThemeLockEntry {
  */
 interface ThemesLockV1 {
     schema_version: 1;
-    /** e.g. "alter-cli/0.5.0", informational only. */
+    /** Free-form producer tag, e.g. "@truealter/cli/1.0.0", informational only. */
     generated_by: string;
     /** RFC 3339 UTC timestamp at lockfile-write time. */
     generated_at: string;
@@ -2342,7 +2365,7 @@ interface ThemeShareOutput {
         message: string;
     };
 }
-/** v1 schema constants. Mirror the spec at docs/technical/alter-theme-pack-spec-v1.md. */
+/** v1 schema constants. Mirror the ALTER theme pack spec v1. */
 declare const THEME_LIMITS: {
     readonly meta_name_pattern: RegExp;
     readonly meta_description_max_chars: 240;

package/dist/index.js

@@ -15,8 +15,13 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -404,7 +409,7 @@ function ensureMcpPath(url) {
 
 // src/meta.ts
 var SDK_NAME = "@truealter/sdk";
-var SDK_VERSION = "0.5.3" ;
+var SDK_VERSION = "0.5.8" ;
 
 // src/floor-preflight.ts
 var MIN_VERSION_ENDPOINT = "/v1/clients/min-version";
@@ -832,7 +837,7 @@ var MCPClient = class {
     this.preflightHook = opts.preflightHook;
   }
   /**
-   * Run the lazy preflight hook (D-MIN-VERSION-FLOOR-1) exactly once.
+   * Run the lazy version-floor preflight hook exactly once.
    * Idempotent and serialised: concurrent callers share the same
    * promise. Throws from the hook propagate to every concurrent caller.
    */
@@ -954,7 +959,14 @@ var MCPClient = class {
           method: "POST",
           headers: this.buildHeaders(signatureHeader),
           body: JSON.stringify(payload),
-          signal: controller.signal
+          signal: controller.signal,
+          // Prevent fetch from silently following 3xx redirects. When
+          // Cloudflare Access credentials are absent or expired the edge
+          // returns HTTP 302 → CF Access login page (text/html). Without
+          // this option undici follows the redirect, lands on a 200 HTML
+          // body, and resp.json() throws the opaque "invalid JSON body"
+          // error that was surfaced as "MCP <method>: invalid JSON body".
+          redirect: "manual"
         });
       } catch (err) {
         clearTimeout(timer);
@@ -971,6 +983,19 @@ var MCPClient = class {
       clearTimeout(timer);
       const sessionHeader = resp.headers.get("Mcp-Session-Id");
       if (sessionHeader) this.sessionId = sessionHeader;
+      if (resp.status >= 300 && resp.status < 400) {
+        const location = resp.headers.get("Location") ?? "";
+        const isAuthRedirect = location.includes("cloudflareaccess.com") || location.includes("/cdn-cgi/access/") || !location.startsWith("/") && !location.startsWith(new URL(this.endpoint).origin);
+        if (isAuthRedirect) {
+          throw new AlterAuthError(
+            `MCP ${method}: Cloudflare Access blocked the request (session expired or credentials missing). Run \`alter login\` to re-authenticate.`,
+            302
+          );
+        }
+        throw new AlterNetworkError(
+          `MCP ${method}: unexpected redirect ${resp.status} to ${location || "(no Location)"}`
+        );
+      }
       if (resp.status === 401 || resp.status === 403) {
         throw new AlterAuthError(`HTTP ${resp.status} on ${method}`, resp.status);
       }
@@ -995,11 +1020,56 @@ var MCPClient = class {
         const body2 = await safeText(resp);
         throw new AlterError("NETWORK", `HTTP ${resp.status} on ${method}: ${body2.slice(0, 200)}`);
       }
+      const contentType = resp.headers.get("Content-Type") ?? "";
+      const isHtml = contentType.includes("text/html");
+      const isSse = contentType.includes("text/event-stream");
+      if (isHtml || isSse) {
+        if (isSse) {
+          const rawText = await safeText(resp);
+          const dataLine = rawText.split("\n").find((l) => l.startsWith("data:"));
+          if (dataLine) {
+            const jsonPart = dataLine.slice("data:".length).trim();
+            try {
+              const parsed = JSON.parse(jsonPart);
+              if (parsed.error) {
+                const code = parsed.error.code;
+                const message = parsed.error.message ?? `MCP ${method} error`;
+                throw new AlterToolError(this.guessToolName(payload), message, code);
+              }
+              return parsed.result;
+            } catch (parseErr) {
+              if (parseErr instanceof AlterError) throw parseErr;
+              throw new AlterInvalidResponse(
+                `MCP ${method}: could not parse SSE data frame as JSON`,
+                parseErr
+              );
+            }
+          }
+          throw new AlterInvalidResponse(
+            `MCP ${method}: received text/event-stream response with no data: frame`
+          );
+        }
+        const excerpt = (await safeText(resp)).slice(0, 300);
+        const looksLikeLoginPage = excerpt.toLowerCase().includes("cloudflareaccess") || excerpt.toLowerCase().includes("access denied") || excerpt.toLowerCase().includes("<title>");
+        if (looksLikeLoginPage) {
+          throw new AlterAuthError(
+            `MCP ${method}: received an HTML login page instead of JSON (Content-Type: ${contentType}). Run \`alter login\` to re-authenticate.`,
+            200
+          );
+        }
+        throw new AlterInvalidResponse(
+          `MCP ${method}: unexpected Content-Type "${contentType}" (expected application/json). Body excerpt: ${excerpt.slice(0, 120)}`
+        );
+      }
       let body;
       try {
         body = await resp.json();
       } catch (err) {
-        throw new AlterInvalidResponse(`MCP ${method}: invalid JSON body`, err);
+        const hint = contentType ? ` (Content-Type: ${contentType})` : "";
+        throw new AlterInvalidResponse(
+          `MCP ${method}: failed to parse JSON response${hint}. The server may have returned a non-JSON body. Run \`alter login\` if the session is expired.`,
+          err
+        );
       }
       if (body.error) {
         const code = body.error.code;
@@ -1020,7 +1090,7 @@ var MCPClient = class {
     const headers = {
       ...this.extraHeaders ?? {},
       "Content-Type": "application/json",
-      Accept: "application/json",
+      Accept: "application/json, text/event-stream",
       "User-Agent": `${this.clientInfo.name}/${this.clientInfo.version}`,
       "X-Alter-Client-Id": "alter-identity",
       "X-Alter-Client-Version": SDK_VERSION,
@@ -1497,7 +1567,23 @@ function canonicalJson2(value) {
 
 // src/client.ts
 var DEFAULT_ENDPOINT = "https://mcp.truealter.com/api/v1/mcp";
+var MEMBER_BRIDGE_ENDPOINT = "https://api.truealter.com/api/v1/mcp";
 var DEFAULT_DOMAIN = "truealter.com";
+var CANONICAL_API_BASE = "https://api.truealter.com";
+var JWKS_WELL_KNOWN_PATH = "/.well-known/alter-keys.json";
+function resolveJwksUrl(opts = {}) {
+  if (opts.jwksUrl) return opts.jwksUrl;
+  const base = opts.apiBase ?? (typeof process !== "undefined" ? process.env?.ALTER_API : void 0) ?? originOf(opts.endpoint) ?? CANONICAL_API_BASE;
+  return `${base.replace(/\/+$/, "")}${JWKS_WELL_KNOWN_PATH}`;
+}
+function originOf(url) {
+  if (!url) return void 0;
+  try {
+    return new URL(url).origin;
+  } catch {
+    return void 0;
+  }
+}
 var AlterClient = class {
   mcp;
   x402;
@@ -1656,7 +1742,7 @@ var AlterClient = class {
   // ── Alter-to-Alter Messaging ─────────────────────────────────────────
   // Wave 1: cross-handle direct messages between authenticated tilde
   // handles. Default closed: recipient must have granted the sender via
-  // alter_message_grant. Spec: docs/technical/Alter-to-Alter Messaging.md.
+  // alter_message_grant. Spec: the ALTER Alter-to-Alter Messaging spec.
   /** Send a direct message to another tilde handle. */
   async messageSend(args) {
     return this.mcp.callTool("alter_message_send", args);
@@ -1695,6 +1781,10 @@ var AlterClient = class {
     if (!envelope) return { valid: false, reason: "no provenance envelope" };
     const inner = envelope.provenance ?? envelope;
     return verifyProvenance(inner, {
+      // Pass an explicit jwksUrl only when the caller pinned one. Leaving it
+      // undefined preserves the envelope `verify_at` (allowlist-gated)
+      // resolution path inside verifyProvenance; the allowlist is the
+      // trust-anchor gate there, not a bare hardcoded host.
       jwksUrl: this.options.jwksUrl,
       verifyAtAllowlist: this.options.verifyAtAllowlist
     });
@@ -1707,9 +1797,21 @@ var AlterClient = class {
   async verifyToolSignatures(tools, signatures) {
     return verifyToolSignatures(tools, signatures);
   }
-  /** Fetch the published JWKS for ALTER's signing key (cached 5 min). */
+  /**
+   * Fetch the published JWKS for ALTER's signing key (cached 5 min).
+   *
+   * The JWKS URL is derived from the configured API surface
+   * ({@link resolveJwksUrl}: explicit `jwksUrl` > `apiBase` > `ALTER_API` >
+   * the configured `endpoint` origin > the canonical host) rather than a
+   * single hardcoded host, so the trust anchor tracks the surface the
+   * client is actually pointed at.
+   */
   async fetchPublicKeys() {
-    const url = this.options.jwksUrl ?? "https://api.truealter.com/.well-known/alter-keys.json";
+    const url = resolveJwksUrl({
+      jwksUrl: this.options.jwksUrl,
+      apiBase: this.options.apiBase,
+      endpoint: this.options.endpoint
+    });
     return fetchPublicKeys(url);
   }
 };
@@ -1744,17 +1846,20 @@ function generateCursorConfig(opts = {}) {
 // src/adapters/claude-desktop.ts
 function generateClaudeDesktopConfig(opts = {}) {
   const serverName = opts.serverName ?? "alter";
-  const bridgeCommand = opts.bridgeCommand ?? "alter-mcp-bridge";
+  const bridgeCommand = opts.bridgeCommand ?? "alter";
   const env2 = {};
-  env2.ALTER_MCP_ENDPOINT = opts.endpoint ?? DEFAULT_ENDPOINT;
+  env2.ALTER_MCP_ENDPOINT = opts.endpoint ?? MEMBER_BRIDGE_ENDPOINT;
   if (opts.apiKey) env2.ALTER_API_KEY = opts.apiKey;
   const entry = {
     command: bridgeCommand,
+    // The `mcp-bridge` subcommand is always the first arg now that the bridge
+    // is invoked through the `alter` CLI, not a bare bridge binary.
+    args: ["mcp-bridge"],
     env: env2,
     description: "ALTER Identity: psychometric identity field for AI agents"
   };
   if (opts.extraArgs && opts.extraArgs.length > 0) {
-    entry.args = [...opts.extraArgs];
+    entry.args = [...entry.args, ...opts.extraArgs];
   }
   return { mcpServers: { [serverName]: entry } };
 }
@@ -2032,6 +2137,7 @@ function wire(opts = {}) {
   const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
   const apiKey = opts.apiKey;
   const cfAccess = opts.cfAccess ?? readCfAccessEnv();
+  const launcherPath = opts.launcherPath;
   const probes = probeAll();
   const selection = opts.only ?? probes.filter((p) => p.installed).map((p) => p.client.id);
   const ts = TIMESTAMP();
@@ -2050,7 +2156,7 @@ function wire(opts = {}) {
     }
     try {
       if (id === "claude-code") {
-        targets.push(wireClaudeCode({ endpoint, apiKey, cfAccess }));
+        targets.push(wireClaudeCode({ endpoint, apiKey, cfAccess, launcherPath }));
       } else {
         targets.push(wireFileTarget({ id, endpoint, apiKey, cfAccess, timestamp: ts }));
       }
@@ -2121,10 +2227,28 @@ function wireFileTarget(args) {
     postSha256: result.postSha256
   };
 }
-function wireClaudeCode(args) {
-  const cmd = "claude";
-  const bridgePath = resolveBridgeScript();
-  const argList = bridgePath ? ["mcp", "add", "--scope", "user", "alter", "--", "node", bridgePath] : [
+function redactSecret(text, secret) {
+  if (!secret) return text;
+  return text.split(secret).join("***redacted***");
+}
+function buildClaudeCodeAddArgs(args) {
+  if (args.subprocessArgv) {
+    return [
+      "mcp",
+      "add",
+      "--scope",
+      "user",
+      "alter",
+      "--env",
+      `ALTER_MCP_ENDPOINT=${MEMBER_BRIDGE_ENDPOINT}`,
+      "--env",
+      `ALTER_PUBLIC_MCP_ENDPOINT=${MEMBER_BRIDGE_ENDPOINT}`,
+      ...args.apiKey ? ["--env", `ALTER_API_KEY=${args.apiKey}`] : [],
+      "--",
+      ...args.subprocessArgv
+    ];
+  }
+  return [
     "mcp",
     "add",
     "--scope",
@@ -2135,12 +2259,28 @@ function wireClaudeCode(args) {
     args.endpoint,
     ...args.apiKey ? ["--header", `X-ALTER-API-Key:${args.apiKey}`] : []
   ];
-  const full = `${cmd} ${argList.join(" ")}`;
+}
+function wireClaudeCode(args) {
+  const cmd = "claude";
+  const bridgePath = resolveBridgeScript();
+  const launcher = args.launcherPath && existsSync(args.launcherPath) ? args.launcherPath : null;
+  const subprocessArgv = launcher ? ["node", launcher, "mcp-bridge"] : bridgePath ? ["node", bridgePath] : null;
+  const argList = buildClaudeCodeAddArgs({
+    apiKey: args.apiKey,
+    subprocessArgv,
+    endpoint: args.endpoint
+  });
+  const full = redactSecret(`${cmd} ${argList.join(" ")}`, args.apiKey);
   const run = spawnSync(cmd, argList, {
     encoding: "utf8",
     shell: process.platform === "win32",
     timeout: 1e4,
-    env: bridgePath ? { ...process.env, ALTER_PUBLIC_MCP_ENDPOINT: args.endpoint, ...args.apiKey ? { ALTER_API_KEY: args.apiKey } : {} } : void 0
+    env: subprocessArgv ? {
+      ...process.env,
+      ALTER_MCP_ENDPOINT: MEMBER_BRIDGE_ENDPOINT,
+      ALTER_PUBLIC_MCP_ENDPOINT: MEMBER_BRIDGE_ENDPOINT,
+      ...args.apiKey ? { ALTER_API_KEY: args.apiKey } : {}
+    } : void 0
   });
   if (run.error) {
     return {
@@ -2173,6 +2313,10 @@ function wireClaudeCode(args) {
 }
 function resolveBridgeScript() {
   const here = dirname(fileURLToPath(import.meta.url));
+  const distBinBridge = join(here, "bin", "mcp-bridge.js");
+  if (existsSync(distBinBridge)) return distBinBridge;
+  const nestedDistBinBridge = join(here, "..", "dist", "bin", "mcp-bridge.js");
+  if (existsSync(nestedDistBinBridge)) return nestedDistBinBridge;
   const siblingBridge = join(here, "..", "dist", "mcp-bridge.js");
   if (existsSync(siblingBridge)) return siblingBridge;
   const srcBridge = join(here, "..", "mcp-bridge.js");
@@ -2462,13 +2606,13 @@ var TIER_PRICES = {
 };
 var ADVERTISED_TOOL_COUNTS = {
   /** Free (L0) tools visible to anonymous / agent-class callers. */
-  free: 26,
+  free: 27,
   /** Premium (L1-L5) tools requiring x402 payment. */
-  premium: 8,
+  premium: 9,
   /** Messaging tools (member-self-only; excluded from external advertisement). */
   messaging: 0,
   /** Total publicly advertised (free + premium). */
-  total: 34
+  total: 36
 };
 var REVENUE_SPLIT = {
   weaver: 0.75,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@truealter/sdk",
-  "version": "0.5.3",
-  "description": "ALTER Identity SDK: query the continuous identity field from any JavaScript/TypeScript environment",
+  "version": "0.5.8",
+  "description": "~Alter Identity SDK: query the continuous identity field from any JavaScript/TypeScript environment",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -14,10 +14,6 @@
       "require": "./dist/index.cjs"
     }
   },
-  "bin": {
-    "alter-identity": "./dist/bin/alter-identity.js",
-    "alter-mcp-bridge": "./dist/bin/mcp-bridge.js"
-  },
   "files": [
     "dist/",
     "README.md",
@@ -47,6 +43,7 @@
     "vitest": "^4.1.3"
   },
   "overrides": {
+    "esbuild": ">=0.28.1",
     "postcss": ">=8.5.10"
   },
   "keywords": [