@truealter/sdk 0.5.0 → 0.5.1

package/dist/index.cjs

@@ -6,11 +6,11 @@ var utils = require('@noble/hashes/utils');
 var crypto$1 = require('crypto');
 var ed25519 = require('@noble/ed25519');
 var sha512 = require('@noble/hashes/sha512');
-var child_process = require('child_process');
-var os = require('os');
+var fs = require('fs');
 var path = require('path');
+var os = require('os');
+var child_process = require('child_process');
 var process$1 = require('process');
-var fs = require('fs');
 
 function _interopNamespace(e) {
   if (e && e.__esModule) return e;
@@ -36,6 +36,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;
 };
@@ -450,11 +456,19 @@ var X402Client = class {
   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
@@ -480,6 +494,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);
     }
@@ -952,9 +975,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];
@@ -967,6 +1027,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;
@@ -1626,6 +1743,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 = path.join(os.homedir(), ".config", "alter", "cf-access.env");
+  try {
+    const content = fs.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}`);
@@ -1634,6 +1771,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();
@@ -1652,9 +1790,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;
@@ -1688,7 +1826,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({
@@ -1720,7 +1863,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",
@@ -1728,16 +1872,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 = child_process.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 {
@@ -1768,6 +1911,17 @@ function wireClaudeCode(args) {
     reason: `claude mcp add exited ${String(run.status)}`
   };
 }
+function resolveBridgeScript() {
+  const { existsSync: existsSync4 } = __require("fs");
+  const { join: join3, dirname: dirname3 } = __require("path");
+  const siblingBridge = join3(dirname3(__filename), "..", "dist", "mcp-bridge.js");
+  if (existsSync4(siblingBridge)) return siblingBridge;
+  const srcBridge = join3(dirname3(__filename), "..", "mcp-bridge.js");
+  if (existsSync4(srcBridge)) return srcBridge;
+  const npmGlobalBridge = join3(dirname3(__filename), "mcp-bridge.js");
+  if (existsSync4(npmGlobalBridge)) return npmGlobalBridge;
+  return null;
+}
 function unwire() {
   const state = readWireState();
   const undone = [];

package/dist/index.d.cts

@@ -130,6 +130,7 @@ interface ProvenanceEnvelope {
 }
 interface ProvenancePayload {
     iss: string;
+    aud?: string | string[];
     iat: number;
     exp: number;
     purpose: string;
@@ -196,6 +197,13 @@ interface VerifyProvenanceOptions {
      * recommended for production use.
      */
     expectedIss?: string;
+    /**
+     * Expected `aud` claim. When provided and non-empty, the token's `aud`
+     * claim must contain this value (RFC 7519 §4.1.3). Pass an empty string
+     * to disable the check. Defaults to no check (undefined) for backward
+     * compatibility — callers SHOULD supply this in production environments.
+     */
+    expectedAud?: string;
 }
 /**
  * Verify a provenance JWS token against ALTER's published JWKS.
@@ -216,7 +224,15 @@ declare function verifyProvenance(envelope: ProvenanceEnvelope | string, opts?:
  *
  * ALTER signs each tool's input schema at startup and exposes the
  * signatures via the MCP `tools/list` `_meta.signatures` map. This helper
- * checks that each tool's schema hash matches the signed value.
+ * checks that each tool's schema hash matches the signed value, AND
+ * cryptographically verifies the ES256 JWS signature carried in
+ * `sig.signature` / `sig.kid` against the JWKS published at `jwksUrl`.
+ *
+ * H-9 remediation: previously only the schema hash was verified; the
+ * `sig.signature` and `sig.kid` fields were carried but never checked,
+ * allowing a hostile MCP server to substitute a fake tool schema whose
+ * hash matched a maliciously crafted `schema_hash` without needing the
+ * signing key.
  */
 interface SignedToolDefinition {
     name: string;
@@ -230,10 +246,22 @@ interface ToolSignatureMap {
         kid?: string | null;
     };
 }
-declare function verifyToolSignatures(tools: SignedToolDefinition[], signatures: ToolSignatureMap): Promise<{
+interface VerifyToolSignaturesOptions {
+    /**
+     * JWKS URL to verify ES256 signatures against. Must be https.
+     * Defaults to `https://api.truealter.com/.well-known/alter-keys.json`.
+     * When a tool's `signature` field is null/absent, the tool is marked
+     * valid-on-hash (legacy path) and a `warn_no_signature: true` flag is
+     * included in the result.
+     */
+    jwksUrl?: string;
+    fetch?: typeof fetch;
+}
+declare function verifyToolSignatures(tools: SignedToolDefinition[], signatures: ToolSignatureMap, opts?: VerifyToolSignaturesOptions): Promise<{
     tool: string;
     valid: boolean;
     reason?: string;
+    warn_no_signature?: boolean;
 }[]>;
 /**
  * Fetch the ALTER public key set. Cached in-process for five minutes.
@@ -369,12 +397,21 @@ interface X402ClientOptions {
     networks?: string[];
     /** Permitted assets. Defaults to `['USDC']`. */
     assets?: string[];
+    /**
+     * Known recipient addresses. Defaults to {@link DEFAULT_RECIPIENT_ALLOWLIST}.
+     * Passing a list here *replaces* the default — include the ALTER canonical
+     * address if you still want it accepted.
+     *
+     * An empty array disables the check entirely (not recommended for production).
+     */
+    recipientAllowlist?: string[];
 }
 declare class X402Client {
     private readonly signer?;
     private readonly maxPerQuery?;
     private readonly networks;
     private readonly assets;
+    private readonly recipientAllowlist;
     constructor(opts?: X402ClientOptions);
     /**
      * Validate the envelope against this client's policy and, if a signer
@@ -415,7 +452,7 @@ interface MCPClientOptions {
     /** Optional x402 client for automatic premium tool payment. */
     x402?: X402Client;
     /**
-     * Q5c per-invocation signing. When present, every `tools/call` is
+     * ES256 per-invocation signing. When present, every `tools/call` is
      * ES256-signed and submitted with the `Mcp-Invocation-Signature`
      * header. The public half of `privateKey` MUST have been
      * registered via `POST /api/v1/agents/keys` against the same API
@@ -1595,11 +1632,17 @@ declare function sha256(bytes: string | Buffer): string;
  * deterministic ordering is worth the tiny blocking cost.
  */
 
+interface CfAccessCredentials {
+    clientId: string;
+    clientSecret: string;
+}
 interface WireOptions {
     /** Override the endpoint written into every client config. Defaults to DEFAULT_ENDPOINT. */
     endpoint?: string;
     /** Optional API key written into `headers['X-ALTER-API-Key']` for each target. */
     apiKey?: string;
+    /** CF Access service token credentials. Auto-read from ~/.config/alter/cf-access.env when absent. */
+    cfAccess?: CfAccessCredentials;
     /** Restrict to a subset of client ids. Default: every detected client. */
     only?: readonly ClientId[];
     /** Skip any client whose probe said "not installed" even if the caller passed it via `only`. */
@@ -1624,15 +1667,12 @@ declare function unwire(): UnwireReport;
  * @truealter/sdk — alter_homepage MCP tool types
  *
  * Wire-format types for the user-authored, externally-queryable identity
- * homepage surface ratified (proposed) as D-CUST-PORTFOLIO-1 in
- * alter-internal Session 54.
+ * homepage surface.
  *
- * Tool name note: ratified-as `alter_portfolio` in the proposed DR;
- * shipping as `alter_homepage` because `alter_portfolio` is already
- * taken by the verified-attestations tool in mcp-alter (different
- * concept). Per the handover's explicit fallback. The DR text and
- * companion docs may still say "portfolio" — the wire-format and
- * tool-name-on-server are `homepage`.
+ * Tool name note: the wire-format and server-side tool name are
+ * `alter_homepage`. The name `alter_portfolio` is reserved by the
+ * verified-attestations tool in `mcp-alter` (a different concept), so
+ * homepage types ship under `homepage`.
  *
  * Wire-format rule: every field name matches the JSON Schema property
  * name exactly (snake_case). These are passed straight into JSON-RPC
@@ -1690,7 +1730,7 @@ interface HomepageManifest {
      */
     opener?: HomepageField<string>;
     /**
-     * Composed-glyph string (from typed primitives, D-CUST-1 M3). The
+     * Composed-glyph string (from typed primitives). The
      * sigil is a string of renderer-recognised primitive references —
      * not raw glyph codes — so different consumers can render the same
      * sigil distinctly. Provenance is `declared` for user-composed,
@@ -1774,8 +1814,7 @@ 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) and
- *  the proposed-D-CUST-PORTFOLIO-1 DR. */
+ *  `docs/technical/alter-portfolio-manifest-v1.md` (forthcoming). */
 declare const HOMEPAGE_LIMITS: {
     readonly whoami_max_chars: 240;
     readonly opener_max_chars: 280;
@@ -1784,13 +1823,11 @@ declare const HOMEPAGE_LIMITS: {
 };
 
 /**
- * @truealter/sdk — theme pack types (D-CUST-1 substrate, Wave 2)
+ * @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`; the architecture spike
- * (with threat model F1–F10) lives in
- * `.repos/internal/02-Technical-Strategy/alter-theme-packs-architecture-spike.md`.
+ * `docs/technical/alter-theme-pack-spec-v1.md`.
  *
  * These types describe the on-the-wire shape of theme manifests as they
  * are produced by `alter theme install`, persisted to `themes.lock`,
@@ -1930,7 +1967,7 @@ interface ThemesLockV1 {
  * Input arguments for the `theme_share` MCP tool. Sharing emits a 5:1
  * return event to the sharer (recognition credit + pack citation) and
  * to the recipient (discovery signal). Implementation lives in
- * `mcp-alter` per D-RS15.
+ * `mcp-alter`.
  */
 interface ThemeShareInput {
     /** Recipient ~handle. */

package/dist/index.d.ts

@@ -130,6 +130,7 @@ interface ProvenanceEnvelope {
 }
 interface ProvenancePayload {
     iss: string;
+    aud?: string | string[];
     iat: number;
     exp: number;
     purpose: string;
@@ -196,6 +197,13 @@ interface VerifyProvenanceOptions {
      * recommended for production use.
      */
     expectedIss?: string;
+    /**
+     * Expected `aud` claim. When provided and non-empty, the token's `aud`
+     * claim must contain this value (RFC 7519 §4.1.3). Pass an empty string
+     * to disable the check. Defaults to no check (undefined) for backward
+     * compatibility — callers SHOULD supply this in production environments.
+     */
+    expectedAud?: string;
 }
 /**
  * Verify a provenance JWS token against ALTER's published JWKS.
@@ -216,7 +224,15 @@ declare function verifyProvenance(envelope: ProvenanceEnvelope | string, opts?:
  *
  * ALTER signs each tool's input schema at startup and exposes the
  * signatures via the MCP `tools/list` `_meta.signatures` map. This helper
- * checks that each tool's schema hash matches the signed value.
+ * checks that each tool's schema hash matches the signed value, AND
+ * cryptographically verifies the ES256 JWS signature carried in
+ * `sig.signature` / `sig.kid` against the JWKS published at `jwksUrl`.
+ *
+ * H-9 remediation: previously only the schema hash was verified; the
+ * `sig.signature` and `sig.kid` fields were carried but never checked,
+ * allowing a hostile MCP server to substitute a fake tool schema whose
+ * hash matched a maliciously crafted `schema_hash` without needing the
+ * signing key.
  */
 interface SignedToolDefinition {
     name: string;
@@ -230,10 +246,22 @@ interface ToolSignatureMap {
         kid?: string | null;
     };
 }
-declare function verifyToolSignatures(tools: SignedToolDefinition[], signatures: ToolSignatureMap): Promise<{
+interface VerifyToolSignaturesOptions {
+    /**
+     * JWKS URL to verify ES256 signatures against. Must be https.
+     * Defaults to `https://api.truealter.com/.well-known/alter-keys.json`.
+     * When a tool's `signature` field is null/absent, the tool is marked
+     * valid-on-hash (legacy path) and a `warn_no_signature: true` flag is
+     * included in the result.
+     */
+    jwksUrl?: string;
+    fetch?: typeof fetch;
+}
+declare function verifyToolSignatures(tools: SignedToolDefinition[], signatures: ToolSignatureMap, opts?: VerifyToolSignaturesOptions): Promise<{
     tool: string;
     valid: boolean;
     reason?: string;
+    warn_no_signature?: boolean;
 }[]>;
 /**
  * Fetch the ALTER public key set. Cached in-process for five minutes.
@@ -369,12 +397,21 @@ interface X402ClientOptions {
     networks?: string[];
     /** Permitted assets. Defaults to `['USDC']`. */
     assets?: string[];
+    /**
+     * Known recipient addresses. Defaults to {@link DEFAULT_RECIPIENT_ALLOWLIST}.
+     * Passing a list here *replaces* the default — include the ALTER canonical
+     * address if you still want it accepted.
+     *
+     * An empty array disables the check entirely (not recommended for production).
+     */
+    recipientAllowlist?: string[];
 }
 declare class X402Client {
     private readonly signer?;
     private readonly maxPerQuery?;
     private readonly networks;
     private readonly assets;
+    private readonly recipientAllowlist;
     constructor(opts?: X402ClientOptions);
     /**
      * Validate the envelope against this client's policy and, if a signer
@@ -415,7 +452,7 @@ interface MCPClientOptions {
     /** Optional x402 client for automatic premium tool payment. */
     x402?: X402Client;
     /**
-     * Q5c per-invocation signing. When present, every `tools/call` is
+     * ES256 per-invocation signing. When present, every `tools/call` is
      * ES256-signed and submitted with the `Mcp-Invocation-Signature`
      * header. The public half of `privateKey` MUST have been
      * registered via `POST /api/v1/agents/keys` against the same API
@@ -1595,11 +1632,17 @@ declare function sha256(bytes: string | Buffer): string;
  * deterministic ordering is worth the tiny blocking cost.
  */
 
+interface CfAccessCredentials {
+    clientId: string;
+    clientSecret: string;
+}
 interface WireOptions {
     /** Override the endpoint written into every client config. Defaults to DEFAULT_ENDPOINT. */
     endpoint?: string;
     /** Optional API key written into `headers['X-ALTER-API-Key']` for each target. */
     apiKey?: string;
+    /** CF Access service token credentials. Auto-read from ~/.config/alter/cf-access.env when absent. */
+    cfAccess?: CfAccessCredentials;
     /** Restrict to a subset of client ids. Default: every detected client. */
     only?: readonly ClientId[];
     /** Skip any client whose probe said "not installed" even if the caller passed it via `only`. */
@@ -1624,15 +1667,12 @@ declare function unwire(): UnwireReport;
  * @truealter/sdk — alter_homepage MCP tool types
  *
  * Wire-format types for the user-authored, externally-queryable identity
- * homepage surface ratified (proposed) as D-CUST-PORTFOLIO-1 in
- * alter-internal Session 54.
+ * homepage surface.
  *
- * Tool name note: ratified-as `alter_portfolio` in the proposed DR;
- * shipping as `alter_homepage` because `alter_portfolio` is already
- * taken by the verified-attestations tool in mcp-alter (different
- * concept). Per the handover's explicit fallback. The DR text and
- * companion docs may still say "portfolio" — the wire-format and
- * tool-name-on-server are `homepage`.
+ * Tool name note: the wire-format and server-side tool name are
+ * `alter_homepage`. The name `alter_portfolio` is reserved by the
+ * verified-attestations tool in `mcp-alter` (a different concept), so
+ * homepage types ship under `homepage`.
  *
  * Wire-format rule: every field name matches the JSON Schema property
  * name exactly (snake_case). These are passed straight into JSON-RPC
@@ -1690,7 +1730,7 @@ interface HomepageManifest {
      */
     opener?: HomepageField<string>;
     /**
-     * Composed-glyph string (from typed primitives, D-CUST-1 M3). The
+     * Composed-glyph string (from typed primitives). The
      * sigil is a string of renderer-recognised primitive references —
      * not raw glyph codes — so different consumers can render the same
      * sigil distinctly. Provenance is `declared` for user-composed,
@@ -1774,8 +1814,7 @@ 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) and
- *  the proposed-D-CUST-PORTFOLIO-1 DR. */
+ *  `docs/technical/alter-portfolio-manifest-v1.md` (forthcoming). */
 declare const HOMEPAGE_LIMITS: {
     readonly whoami_max_chars: 240;
     readonly opener_max_chars: 280;
@@ -1784,13 +1823,11 @@ declare const HOMEPAGE_LIMITS: {
 };
 
 /**
- * @truealter/sdk — theme pack types (D-CUST-1 substrate, Wave 2)
+ * @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`; the architecture spike
- * (with threat model F1–F10) lives in
- * `.repos/internal/02-Technical-Strategy/alter-theme-packs-architecture-spike.md`.
+ * `docs/technical/alter-theme-pack-spec-v1.md`.
  *
  * These types describe the on-the-wire shape of theme manifests as they
  * are produced by `alter theme install`, persisted to `themes.lock`,
@@ -1930,7 +1967,7 @@ interface ThemesLockV1 {
  * Input arguments for the `theme_share` MCP tool. Sharing emits a 5:1
  * return event to the sharer (recognition credit + pack citation) and
  * to the recipient (discovery signal). Implementation lives in
- * `mcp-alter` per D-RS15.
+ * `mcp-alter`.
  */
 interface ThemeShareInput {
     /** Recipient ~handle. */