@truealter/sdk 0.5.1 → 0.5.3

package/README.md

@@ -12,7 +12,7 @@ A thin client over the ALTER MCP server (Streamable HTTP, JSON-RPC 2.0, MCP spec
 - **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)
 - **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:** **34 publicly advertised**, 26 free (L0) + 8 premium (L1-L5), kept in sync with ALTER's live MCP server at every publish.
 - **Runtime:** Node 18+, Deno, Bun, Cloudflare Workers, modern browsers
 - **Crypto:** `@noble/ed25519` + `@noble/hashes` (no other dependencies)
 - **Bundle:** ESM + CJS dual output
@@ -34,27 +34,20 @@ 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
-carries the provenance envelope end-to-end. Bridge signing lands in Wave-2
-alongside the CLI wallet/consent verbs.
+the optional `signing` parameter; that path is the primary one and
+carries the provenance envelope end-to-end. Bridge signing is planned for a
+future release.
 
 ## CLI
 
 The package ships two binaries. `alter-identity` is the full SDK-feature
-binary (`init`, `verify`, `whoami`, wire/unwire, signing, etc). `alter`
-is a slim, task-oriented binary for day-to-day use:
+binary (`init`, `verify`, `whoami`, wire/unwire, signing, etc).
+`alter-mcp-bridge` is the stdio bridge described above. The day-to-day
+`alter` command line is distributed separately as
+[`@truealter/cli`](https://www.npmjs.com/package/@truealter/cli) - it is
+not part of this package.
 
-| 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. |
-| `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. |
-
-The session file is created with `0600` permissions; its parent dir
-(`~/.config/alter/`) is created with `0700`. Override the config root
-via `XDG_CONFIG_HOME`. Run `alter --help` for the inline reference.
+Run `alter-identity --help` for the inline reference.
 
 ## Why ALTER ≠ IAM
 
@@ -94,6 +87,90 @@ const alter = new AlterClient({
 });
 ```
 
+### Minimum-version preflight (required)
+
+ALTER's backend publishes a per-client minimum-version floor. The SDK
+preflights this floor lazily on the first network call: no explicit
+call is required for the common case. If the running SDK is below the
+floor for `alter-identity`, the SDK throws `BelowFloorError` with the
+upgrade command attached.
+
+The floor document is signed by the backend with a floor-only Ed25519
+private key. The SDK ships only the corresponding public keys
+(`KNOWN_FLOOR_PUBLIC_KEYS`, a `key_id` to SPKI-PEM map): no signing
+secret ships in the client, and a compromised client cannot forge floor
+documents. The `key_id` is the first 8 hex chars of SHA-256 of the raw
+32-byte Ed25519 public key, so clients select the right key during a
+rotation. An unknown `key_id` or an invalid signature is treated as a
+cache miss (refetch), never as a pass.
+
+```ts
+import { AlterClient, BelowFloorError, checkMinVersion } from "@truealter/sdk";
+
+// Optional: run the preflight explicitly to surface the upgrade
+// prompt at startup, before any real work happens:
+try {
+  await checkMinVersion();
+} catch (err) {
+  if (err instanceof BelowFloorError) {
+    console.error(`upgrade required: ${err.upgrade_cmd}`);
+    process.exit(1);
+  }
+  throw err;
+}
+
+// The constructor installs the same hook lazily: it fires on your
+// first request automatically:
+const alter = new AlterClient();
+try {
+  await alter.verify("~alter");
+} catch (err) {
+  if (err instanceof BelowFloorError) {
+    // Re-thrown on every subsequent call until you upgrade.
+    console.error(`upgrade: ${err.upgrade_cmd}`);
+  }
+}
+```
+
+`BelowFloorError` carries the canonical envelope fields as enumerable
+properties so consumers can branch without re-parsing:
+
+| Property         | Type   | Example                              |
+| ---------------- | ------ | ------------------------------------ |
+| `code`           | string | `"client_below_floor"`               |
+| `client_version` | string | `"0.5.2"`                            |
+| `min_version`    | string | `"0.6.0"`                            |
+| `upgrade_cmd`    | string | `"npm install -g @truealter/sdk"`    |
+| `channel`        | string | `"npm"`                              |
+| `envelope`       | object | full `{ error: {...} }` envelope     |
+
+**Opt-out (discouraged).** Pass `unsafe_skipVersionCheck: true` to skip
+the client-side preflight. The server-side floor gate still rejects
+below-floor clients with HTTP 426 regardless: disabling the SDK-side
+preflight only swaps a clean typed error for an opaque network failure
+on every subsequent call.
+
+```ts
+const alter = new AlterClient({ unsafe_skipVersionCheck: true });
+```
+
+Worked example: see [`examples/min-version-check/`](./examples/min-version-check/).
+
+### Identity headers
+
+Every outbound request from `AlterClient` / `MCPClient` carries three
+identity headers that the server-side floor middleware consults:
+
+| Header                     | Value (this SDK)   |
+| -------------------------- | ------------------ |
+| `X-Alter-Client-Id`        | `alter-identity`   |
+| `X-Alter-Client-Version`   | the running `SDK_VERSION` |
+| `X-Alter-Client-Channel`   | `npm`              |
+
+These are MANDATORY on every authenticated backend endpoint per
+D-MIN-VERSION-FLOOR-1 §3. The User-Agent header remains informational
+and is NEVER used for floor enforcement.
+
 ### Free tier (L0 - no payment required)
 
 ```ts
@@ -128,33 +205,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.01, 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.10)
 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.60)
 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 ($1.00)
 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 ($1.00)
 const narrative = await alter.generateMatchNarrative({
   match_id: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
 });
@@ -186,9 +263,9 @@ if (tampered.length) throw new Error(`tampered tools: ${tampered.map((t) => t.to
 ```ts
 import { discover } from "@truealter/sdk";
 
-// Three-step discovery cascade: DNS TXT → mcp.json → alter.json
+// Three-step discovery cascade: DNS TXT to mcp.json to alter.json
 const descriptor = await discover("truealter.com");
-// → { url: "https://mcp.truealter.com/api/v1/mcp", transport, source, publicKey, x402Contract, capability }
+// returns { url: "https://mcp.truealter.com/api/v1/mcp", transport, source, publicKey, x402Contract, capability }
 ```
 
 ### Low-level MCPClient
@@ -288,11 +365,11 @@ ALTER monetises premium tools via the [x402](https://x402.org) standard - HTTP `
 4. Server validates the proof, executes the tool, signs the response with ES256, returns it.
 5. AlterRouter executes the split on-chain in the same transaction. The data subject receives Identity Income directly; ALTER receives only its protocol cut. No custodian, no broker.
 
-The SDK handles steps 2–4 automatically when an `X402Client` with a configured `signer` is passed in.
+The SDK handles steps 2-4 automatically when an `X402Client` with a configured `signer` is passed in.
 
 ### Tier structure
 
-x402 micropayments at L0–L5 trust tiers. Per-call pricing visible after `alter login`.
+x402 micropayments at L0-L5 trust tiers. Per-call pricing visible after `alter login`.
 
 ### Identity income split
 
@@ -388,7 +465,7 @@ ALTER follows the discovery cascade specified in [draft-morrison-mcp-dns-discove
 ```ts
 import { discover } from "@truealter/sdk";
 
-// Cascading discovery (DNS TXT → mcp.json → alter.json)
+// Cascading discovery (DNS TXT to mcp.json to alter.json)
 const descriptor = await discover("truealter.com");
 
 // Skip the DNS step (e.g. in browsers or Cloudflare Workers)
@@ -397,18 +474,6 @@ const httpsOnly = await discover("truealter.com", { skipDns: true });
 
 This draft is the author's Internet-Draft (not yet adopted by an IETF working group); until adoption, the cascade order may change. Pin the SDK version to a specific minor release if you depend on this behaviour.
 
-## 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.
-
-When the local-daemon adapter ships:
-
-- **Latency:** sub-millisecond for cached L0 calls.
-- **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)
@@ -416,7 +481,7 @@ Until then, use `endpoint: "https://mcp.truealter.com/api/v1/mcp"` (the default)
 | 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.  |
+| `alter_resolve_handle`    | L0   | free  | Resolve a `~handle` (e.g. `~example`) 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.                                              |
@@ -440,18 +505,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).     |
-| `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.         |
+| `assess_traits`            | L1   | $0.01   | Extract trait signals from a text passage against ALTER's trait taxonomy.                                     |
+| `get_trait_snapshot`       | L1   | $0.01   | Get the top 5 traits for a person with confidence scores and archetype.                                    |
+| `get_full_trait_vector`    | L2   | $0.10   | Get the complete trait vector for a person - complete trait vector with scores and confidence intervals.                                    |
+| `get_side_quest_graph`     | L2   | $0.10   | Get a person's Side Quest Graph - multi-domain identity model with differential privacy noise (ε=1.0).     |
+| `query_graph_similarity`   | L3   | $0.30   | Compare two Side Quest Graphs for team composition and matching (ε=0.5 differential privacy).                 |
+| `compute_belonging`        | L4   | $0.60   | Compute belonging probability for a person-job pairing (authenticity, acceptance, complementarity).        |
+| `get_match_recommendations`| L5   | $1.00   | Get top N match recommendations for a person, ranked by composite score with quality tiers.                |
+| `generate_match_narrative` | L5   | $1.00   | 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.