@saihm/mcp-server-pro 0.1.3 → 0.1.5

package/README.md

@@ -17,13 +17,61 @@ Production thin-client for **SAIHM non-custodial memory**.
 npm install @saihm/mcp-server-pro
 ```
 
-## Usage
+## Run as an MCP server
+
+The package ships a stdio MCP server. Point your MCP host (Claude Desktop,
+Claude Code, …) at it — paste this **once**:
+
+```jsonc
+{
+  "mcpServers": {
+    "saihm": {
+      "command": "npx",
+      "args": ["-y", "@saihm/mcp-server-pro"],
+      "env": {
+        "SAIHM_ENDPOINT_URL": "https://saihm.coti.global/mcp",
+        "SAIHM_MASTER_SECRET_HEX": "<your 64+ hex master secret>",
+        "SAIHM_TIER": "PRO",
+        "SAIHM_PAYMENT_METHOD": "stripe"
+      }
+    }
+  }
+}
+```
+
+With no `SAIHM_AUTH_HEADER`, the server **self-onboards**: it mints and
+auto-refreshes its own short-lived access token from your master secret, so
+there is no token to paste or re-paste. Eight tools are exposed
+(`saihm_remember`, `saihm_recall`, `saihm_forget`, `saihm_status`,
+`saihm_share`, `saihm_revoke_share`, `saihm_governance_propose`,
+`saihm_governance_vote`).
+
+### Self-serve join
+
+To subscribe an identity from the command line instead of the website, run the
+one-off `join` command with the same env:
+
+```sh
+SAIHM_ENDPOINT_URL=https://saihm.coti.global/mcp \
+SAIHM_MASTER_SECRET_HEX=<your 64+ hex master secret> \
+SAIHM_TIER=PRO SAIHM_PAYMENT_METHOD=stripe \
+  npx -y @saihm/mcp-server-pro join
+```
+
+It prints a Stripe checkout link bound to your identity. Pay in a browser, then
+start the server normally (drop `join`) — it connects automatically. Keep
+`SAIHM_MASTER_SECRET_HEX` safe: it is the only key to your memory and cannot be
+recovered.
+
+## Use as a library
 
 ```ts
 import { SaihmProClient } from '@saihm/mcp-server-pro';
 
-// Boot from env: SAIHM_ENDPOINT_URL, SAIHM_AUTH_HEADER, SAIHM_MASTER_SECRET_HEX
-//   (optional: SAIHM_TIER, SAIHM_SEQ_STATE_PATH)
+// Boot from env: SAIHM_ENDPOINT_URL, SAIHM_MASTER_SECRET_HEX
+//   self-onboard (recommended): + SAIHM_PAYMENT_METHOD + SAIHM_TIER (omit SAIHM_AUTH_HEADER)
+//   static token (advanced):    + SAIHM_AUTH_HEADER="Bearer <JWT>"
+//   (optional: SAIHM_SEQ_STATE_PATH)
 const saihm = SaihmProClient.bootFromEnv();
 
 // Store — encrypted before it leaves the process.
@@ -46,8 +94,8 @@ await saihm.forget(cellId);
 // out-of-band; the library rejects directory key-substitution.
 await saihm.share({
   cellId,
-  recipientRecord,                       // the grantee's published identity record (hex)
-  recipientPinnedAgentIdHashHex,         // pinned out-of-band
+  recipientRecord, // the grantee's published identity record (hex)
+  recipientPinnedAgentIdHashHex, // pinned out-of-band
 });
 await saihm.revokeShare(cellId, recipientPinnedAgentIdHashHex);
 
@@ -55,8 +103,8 @@ await saihm.revokeShare(cellId, recipientPinnedAgentIdHashHex);
 // sharer's agentIdHash out-of-band; the library verifies the sharer's signature and
 // returns null when there is no live grant (e.g. revoked, or the sharer crypto-shredded it).
 const shared = await saihm.recallShared({
-  sharerPinnedAgentIdHashHex,            // the sharer's agentIdHash, pinned out-of-band
-  sharerRecord,                          // the sharer's published identity record (hex)
+  sharerPinnedAgentIdHashHex, // the sharer's agentIdHash, pinned out-of-band
+  sharerRecord, // the sharer's published identity record (hex)
   cellId,
 });
 console.log(shared?.plaintext);
@@ -65,32 +113,39 @@ console.log(shared?.plaintext);
 const status = await saihm.status();
 ```
 
-The derived `saihm.agentIdHash` must match the `sub` of the JWT in `SAIHM_AUTH_HEADER`; publish `saihm.identityRecord` so other agents can share to you.
+The derived `saihm.agentIdHash` is the `sub` the endpoint binds your tenant to — when self-onboarding the client proves it via ML-DSA; with a static `SAIHM_AUTH_HEADER` it must equal the JWT `sub`. Publish `saihm.identityRecord` so other agents can share to you.
 
 ## Configuration
 
-| Env | Required | Meaning |
-|---|---|---|
-| `SAIHM_ENDPOINT_URL` | yes | `https://…/mcp` (or `http://` only for `127.0.0.1`/`localhost`). |
-| `SAIHM_AUTH_HEADER` | yes | `Bearer <JWT>`; the endpoint binds your tenant from the JWT `sub`. |
-| `SAIHM_MASTER_SECRET_HEX` | yes | ≥ 64 hex chars (≥ 32 bytes), high-entropy, client-held; never sent. |
-| `SAIHM_TIER` | no | Tier label baked into sealed metadata; resolved via `status()` if unset. |
-| `SAIHM_SEQ_STATE_PATH` | no | Persists per-cell sequence high-water marks (mode 600) for cross-restart updates. |
+| Env                       | Required | Meaning                                                                           |
+| ------------------------- | -------- | --------------------------------------------------------------------------------- |
+| `SAIHM_ENDPOINT_URL`      | yes      | `https://…/mcp` (or `http://` only for `127.0.0.1`/`localhost`).                  |
+| `SAIHM_AUTH_HEADER`       | no       | `Bearer <JWT>`, used verbatim. **Omit to self-onboard** (recommended): the client mints + auto-refreshes its own short-lived JWT from the master secret, so you paste one config once and never re-paste a token. |
+| `SAIHM_PAYMENT_METHOD`    | self-onboard only | Your entitlement rail (e.g. `stripe`). Required when `SAIHM_AUTH_HEADER` is unset; ignored otherwise. |
+| `SAIHM_MASTER_SECRET_HEX` | yes\*    | ≥ 64 hex chars (≥ 32 bytes), high-entropy, client-held; never sent. \*Provide this **or** `SAIHM_MASTER_SECRET_FILE`. |
+| `SAIHM_MASTER_SECRET_FILE`| yes\*    | Path to a **mode-600** file holding the hex master secret. Preferred for operators: keeps the root seed out of a synced/shared MCP config. Takes precedence over `SAIHM_MASTER_SECRET_HEX` when both are set. |
+| `SAIHM_TIER`              | self-onboard only | Tier label baked into sealed metadata. Required when self-onboarding; otherwise optional — resolved via `status()` if unset. |
+| `SAIHM_SEQ_STATE_PATH`    | no       | Persists per-cell sequence high-water marks (mode 600) for cross-restart updates. |
+
+> **Self-onboarding (paste once):** with `SAIHM_AUTH_HEADER` unset, the client proves
+> control of your identity via the endpoint's ML-DSA challenge/response and mints its own
+> token, refreshing transparently on expiry. Cancelling your subscription stops the next
+> refresh, so access ends naturally.
 
 ## Errors
 
-Non-2xx responses throw `SaihmEndpointError` with `status` and a typed `code` (e.g. `BLIND_NO_FREE_TIER`, `BLIND_BAD_EXPIRY`, `governance_unavailable`). Branch on those rather than the message.
+Non-2xx responses throw `SaihmEndpointError` with `status` and a typed `code` (e.g. `BLIND_BAD_EXPIRY`, `BLIND_STALE_SEQ`, `governance_unavailable`). Branch on those rather than the message.
 
 ## Security model
 
-| Property | Guarantee |
-|---|---|
-| Confidentiality vs the endpoint | The endpoint holds ciphertext + wrapped DEKs + public keys only; no key able to decrypt. |
-| Integrity / authenticity | Every cell is ML-DSA-65-signed over its contents, including the sequence number. |
-| Anti-replay | The signed monotonic sequence is rejected by the endpoint if not strictly increasing. |
-| Tenant isolation | Your `agentIdHash` (= the JWT `sub`) namespaces your state; a write whose signed identity differs from the JWT is rejected. |
-| Authenticated sharing | Grantee public keys are pinned out-of-band and verified before any secret is bound to them; on the recipient side, `recallShared` pins the sharer's key and verifies the cell signature before returning any plaintext. |
-| Erasure | Destroying the endpoint-side wrapped DEK crypto-shreds the cell. |
+| Property                        | Guarantee                                                                                                                                                                                                               |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Confidentiality vs the endpoint | The endpoint holds ciphertext + wrapped DEKs + public keys only; no key able to decrypt.                                                                                                                                |
+| Integrity / authenticity        | Every cell is ML-DSA-65-signed over its contents, including the sequence number.                                                                                                                                        |
+| Anti-replay                     | The signed monotonic sequence is rejected by the endpoint if not strictly increasing.                                                                                                                                   |
+| Tenant isolation                | Your `agentIdHash` (= the JWT `sub`) namespaces your state; a write whose signed identity differs from the JWT is rejected.                                                                                             |
+| Authenticated sharing           | Grantee public keys are pinned out-of-band and verified before any secret is bound to them; on the recipient side, `recallShared` pins the sharer's key and verifies the cell signature before returning any plaintext. |
+| Erasure                         | Destroying the endpoint-side wrapped DEK crypto-shreds the cell.                                                                                                                                                        |
 
 ## Where sealed cells are stored
 

package/dist/client.d.ts

@@ -68,21 +68,33 @@ export interface SharedReadGrant {
 export interface SaihmProClientOpts {
     tier?: string;
     seqStatePath?: string;
+    paymentMethod?: string;
+    onboardBaseUrl?: string;
     requestTimeoutMs?: number;
 }
 export declare class SaihmProClient {
     private readonly endpoint;
-    private readonly authHeader;
+    private readonly staticAuthHeader;
+    private readonly paymentMethod;
+    private readonly onboardBase;
     private readonly identity;
     private readonly agentIdHashHex;
     private readonly seq;
     private readonly requestTimeoutMs;
     private tier;
-    constructor(endpoint: string, authHeader: string, masterSecret: Uint8Array, opts?: SaihmProClientOpts);
+    private cachedJwt;
+    private cachedJwtRefreshAtMs;
+    private authInFlight;
+    constructor(endpoint: string, authHeader: string | undefined, masterSecret: Uint8Array, opts?: SaihmProClientOpts);
     static bootFromEnv(): SaihmProClient;
     get agentIdHash(): string;
     get identityRecord(): WireIdentityRecord;
+    private currentAuthHeader;
+    private onboard;
+    requestCheckoutUrl(): Promise<string>;
+    private onboardFetch;
     private call;
+    private doCall;
     private openRow;
     private resolveTier;
     remember(content: string, opts?: RememberOpts): Promise<RememberResult>;

package/dist/client.js

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { deriveIdentity, sealCell, openCell, shareCell, decodeShareEnvelope, unwrapSharedDek, verifyShareSig, openCellWithDek, verifyEnvelope, verifyIdentityRecord, encodeEnvelope, decodeEnvelope, encodeShareEnvelope, encodeIdentityRecord, decodeIdentityRecord, fromHex, toHex, utf8, fromUtf8, ctEqual, SeqHighWaterMark, } from '@saihm/client-pro';
+import { deriveIdentity, signChallenge, sealCell, openCell, shareCell, decodeShareEnvelope, unwrapSharedDek, verifyShareSig, openCellWithDek, verifyEnvelope, verifyIdentityRecord, encodeEnvelope, decodeEnvelope, encodeShareEnvelope, encodeIdentityRecord, decodeIdentityRecord, fromHex, toHex, utf8, fromUtf8, ctEqual, SeqHighWaterMark, } from '@saihm/client-pro';
 const REQUEST_TIMEOUT_MS = 30_000;
 const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
 const MAX_SEQ = (1n << 64n) - 1n;
@@ -15,11 +15,29 @@ function assertEndpointUrl(endpoint) {
     }
     if (url.protocol === 'https:')
         return;
-    if (url.protocol === 'http:' && (url.hostname === '127.0.0.1' || url.hostname === 'localhost'))
+    if (url.protocol === 'http:' &&
+        (url.hostname === '127.0.0.1' || url.hostname === 'localhost'))
         return;
     throw new Error(`SAIHM_ENDPOINT_URL must use https:// (got ${url.protocol}//). ` +
         `Plain http:// is only allowed for 127.0.0.1 or localhost (dev).`);
 }
+const JWT_REFRESH_SKEW_MS = 60_000;
+const OPAQUE_TOKEN_TTL_MS = 5 * 60_000;
+function jwtExpMs(jwt) {
+    const parts = jwt.split('.');
+    const payloadB64 = parts[1];
+    if (parts.length !== 3 || !payloadB64)
+        return undefined;
+    try {
+        const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf-8'));
+        if (typeof payload.exp === 'number' && Number.isFinite(payload.exp)) {
+            return payload.exp * 1000;
+        }
+    }
+    catch {
+    }
+    return undefined;
+}
 export class SaihmEndpointError extends Error {
     status;
     code;
@@ -119,16 +137,20 @@ class SeqState {
 }
 export class SaihmProClient {
     endpoint;
-    authHeader;
+    staticAuthHeader;
+    paymentMethod;
+    onboardBase;
     identity;
     agentIdHashHex;
     seq;
     requestTimeoutMs;
     tier;
+    cachedJwt;
+    cachedJwtRefreshAtMs = 0;
+    authInFlight = null;
     constructor(endpoint, authHeader, masterSecret, opts = {}) {
         assertEndpointUrl(endpoint);
         this.endpoint = endpoint;
-        this.authHeader = authHeader;
         this.identity = deriveIdentity(masterSecret);
         this.agentIdHashHex = toHex(this.identity.agentIdHash);
         this.tier = opts.tier;
@@ -137,17 +159,48 @@ export class SaihmProClient {
             typeof opts.requestTimeoutMs === 'number' && opts.requestTimeoutMs > 0
                 ? opts.requestTimeoutMs
                 : REQUEST_TIMEOUT_MS;
+        this.onboardBase = (opts.onboardBaseUrl ?? new URL(endpoint).origin).replace(/\/+$/, '');
+        const trimmedAuth = typeof authHeader === 'string' && authHeader.trim() ? authHeader : undefined;
+        if (trimmedAuth) {
+            this.staticAuthHeader = trimmedAuth;
+        }
+        else {
+            if (!opts.paymentMethod) {
+                throw new Error('self-onboarding requires a paymentMethod (set SAIHM_PAYMENT_METHOD) when no auth header is supplied');
+            }
+            if (this.tier === undefined) {
+                throw new Error('self-onboarding requires a tier (set SAIHM_TIER) when no auth header is supplied');
+            }
+            this.paymentMethod = opts.paymentMethod;
+        }
     }
     static bootFromEnv() {
         const endpoint = process.env.SAIHM_ENDPOINT_URL;
         const auth = process.env.SAIHM_AUTH_HEADER;
-        const secretHex = process.env.SAIHM_MASTER_SECRET_HEX;
         if (!endpoint)
             throw new Error('SAIHM_ENDPOINT_URL env var required');
-        if (!auth)
-            throw new Error("SAIHM_AUTH_HEADER env var required (e.g. 'Bearer <JWT>')");
+        const secretFile = process.env.SAIHM_MASTER_SECRET_FILE;
+        let secretHex;
+        if (secretFile) {
+            try {
+                secretHex = readFileSync(secretFile, 'utf-8');
+            }
+            catch {
+                throw new Error(`SAIHM_MASTER_SECRET_FILE could not be read: ${secretFile}`);
+            }
+            try {
+                if (process.platform !== 'win32' && (statSync(secretFile).mode & 0o077) !== 0) {
+                    process.stderr.write(`warning: SAIHM_MASTER_SECRET_FILE ${secretFile} is group/world-accessible; chmod 600 it.\n`);
+                }
+            }
+            catch {
+            }
+        }
+        else {
+            secretHex = process.env.SAIHM_MASTER_SECRET_HEX;
+        }
         if (!secretHex)
-            throw new Error('SAIHM_MASTER_SECRET_HEX env var required (>= 64 hex chars)');
+            throw new Error('SAIHM_MASTER_SECRET_HEX (or SAIHM_MASTER_SECRET_FILE) env var required (>= 64 hex chars)');
         let master;
         try {
             master = fromHex(secretHex.trim());
@@ -161,11 +214,14 @@ export class SaihmProClient {
         }
         const optTier = process.env.SAIHM_TIER;
         const optSeqPath = process.env.SAIHM_SEQ_STATE_PATH;
+        const optPaymentMethod = process.env.SAIHM_PAYMENT_METHOD;
         const opts = {};
         if (optTier)
             opts.tier = optTier;
         if (optSeqPath)
             opts.seqStatePath = optSeqPath;
+        if (optPaymentMethod)
+            opts.paymentMethod = optPaymentMethod;
         try {
             return new SaihmProClient(endpoint, auth, master, opts);
         }
@@ -179,13 +235,133 @@ export class SaihmProClient {
     get identityRecord() {
         return encodeIdentityRecord(this.identity.identityRecord);
     }
+    async currentAuthHeader() {
+        if (this.staticAuthHeader)
+            return this.staticAuthHeader;
+        if (this.cachedJwt && Date.now() < this.cachedJwtRefreshAtMs) {
+            return 'Bearer ' + this.cachedJwt;
+        }
+        if (!this.authInFlight) {
+            this.authInFlight = this.onboard().finally(() => {
+                this.authInFlight = null;
+            });
+        }
+        return 'Bearer ' + (await this.authInFlight);
+    }
+    async onboard() {
+        const base = this.onboardBase;
+        const ch = await this.onboardFetch(base + '/api/onboard/challenge', { method: 'GET' });
+        const nonce = ch.nonce;
+        if (typeof nonce !== 'string' || nonce.length === 0) {
+            throw new SaihmEndpointError(502, 'onboard_no_nonce', 'onboard challenge returned no nonce');
+        }
+        let nonceBytes;
+        try {
+            nonceBytes = fromHex(nonce);
+        }
+        catch {
+            throw new SaihmEndpointError(502, 'onboard_bad_nonce', 'onboard challenge nonce is not hex');
+        }
+        const signature = toHex(signChallenge(this.identity.mldsaSecretKey, nonceBytes));
+        const out = await this.onboardFetch(base + '/api/onboard', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                pubkey: toHex(this.identity.mldsaPubKey),
+                nonce,
+                signature,
+                tier: this.tier,
+                paymentMethod: this.paymentMethod,
+            }),
+        });
+        if (typeof out.jwt !== 'string' || out.jwt.length === 0) {
+            throw new SaihmEndpointError(502, 'onboard_no_jwt', 'onboard did not return a JWT');
+        }
+        this.cachedJwt = out.jwt;
+        const now = Date.now();
+        const expMs = jwtExpMs(out.jwt) ?? now + OPAQUE_TOKEN_TTL_MS;
+        const skew = Math.min(JWT_REFRESH_SKEW_MS, Math.max(0, Math.floor((expMs - now) / 2)));
+        this.cachedJwtRefreshAtMs = expMs - skew;
+        return out.jwt;
+    }
+    async requestCheckoutUrl() {
+        if (this.tier === undefined) {
+            throw new SaihmEndpointError(0, 'no_tier', 'join requires a tier (set SAIHM_TIER)');
+        }
+        const out = await this.onboardFetch(this.onboardBase + '/api/stripe/checkout', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                tier: this.tier,
+                mldsaPubKey: toHex(this.identity.mldsaPubKey),
+                uiMode: 'hosted',
+            }),
+        });
+        if (typeof out.url !== 'string' || !out.url.startsWith('https://')) {
+            throw new SaihmEndpointError(502, 'checkout_no_url', 'checkout did not return a hosted URL');
+        }
+        return out.url;
+    }
+    async onboardFetch(url, init) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), this.requestTimeoutMs);
+        try {
+            const res = await fetch(url, { ...init, signal: ctrl.signal });
+            const text = await readBodyCapped(res, MAX_RESPONSE_BYTES, 'onboard');
+            if (!res.ok) {
+                let code;
+                try {
+                    const j = JSON.parse(text);
+                    if (typeof j.error === 'string')
+                        code = j.error;
+                }
+                catch {
+                }
+                throw new SaihmEndpointError(res.status, code, `SAIHM onboard failed: ${res.status} ${res.statusText}` + (code ? ` (${code})` : ''));
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new SaihmEndpointError(res.status, 'malformed_json', 'SAIHM onboard returned a non-JSON 2xx response');
+            }
+        }
+        catch (e) {
+            if (e instanceof SaihmEndpointError)
+                throw e;
+            if (e instanceof Error && e.name === 'AbortError') {
+                throw new SaihmEndpointError(408, 'timeout', `SAIHM onboard timed out after ${this.requestTimeoutMs}ms`);
+            }
+            throw new SaihmEndpointError(0, 'network', 'SAIHM onboard transport error');
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     async call(method, params) {
+        const header = await this.currentAuthHeader();
+        try {
+            return await this.doCall(method, params, header);
+        }
+        catch (e) {
+            if (!this.staticAuthHeader && e instanceof SaihmEndpointError && e.status === 401) {
+                this.cachedJwt = undefined;
+                const fresh = await this.currentAuthHeader();
+                return await this.doCall(method, params, fresh);
+            }
+            throw e;
+        }
+    }
+    async doCall(method, params, authHeader) {
         const ctrl = new AbortController();
         const timer = setTimeout(() => ctrl.abort(), this.requestTimeoutMs);
         try {
             const res = await fetch(this.endpoint, {
                 method: 'POST',
-                headers: { 'content-type': 'application/json', authorization: this.authHeader },
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: authHeader,
+                },
                 body: JSON.stringify({ method, params }),
                 signal: ctrl.signal,
             });
@@ -199,7 +375,8 @@ export class SaihmProClient {
                 }
                 catch {
                 }
-                throw new SaihmEndpointError(res.status, code, `SAIHM endpoint ${method} failed: ${res.status} ${res.statusText}` + (code ? ` (${code})` : ''));
+                throw new SaihmEndpointError(res.status, code, `SAIHM endpoint ${method} failed: ${res.status} ${res.statusText}` +
+                    (code ? ` (${code})` : ''));
             }
             try {
                 return JSON.parse(text);
@@ -246,7 +423,12 @@ export class SaihmProClient {
             throw new SaihmEndpointError(502, 'undecryptable', `cell '${env.cellId}' could not be opened with this identity's key`);
         }
         this.seq.observe(env.cellId, env.seq);
-        return { cellId: env.cellId, plaintext, seq: env.seq.toString(10), commitmentHash: toHex(env.publicMeta.commitmentHash) };
+        return {
+            cellId: env.cellId,
+            plaintext,
+            seq: env.seq.toString(10),
+            commitmentHash: toHex(env.publicMeta.commitmentHash),
+        };
     }
     async resolveTier() {
         if (this.tier !== undefined)
@@ -278,7 +460,9 @@ export class SaihmProClient {
             seq,
             tier,
         });
-        const r = await this.call('saihm_remember', { wire: encodeEnvelope(env) });
+        const r = await this.call('saihm_remember', {
+            wire: encodeEnvelope(env),
+        });
         this.seq.observe(cellId, seq);
         return r;
     }
@@ -309,7 +493,8 @@ export class SaihmProClient {
                 throw new SaihmEndpointError(502, 'malformed_response', `endpoint returned cell '${cell.cellId}' more than once in a recall-all response`);
             }
             seen.add(cell.cellId);
-            if (needle !== undefined && !cell.plaintext.toLowerCase().includes(needle))
+            if (needle !== undefined &&
+                !cell.plaintext.toLowerCase().includes(needle))
                 continue;
             out.push(cell);
         }
@@ -390,7 +575,10 @@ export class SaihmProClient {
         }
         verifyIdentityRecord(sharerRecord, sharerPinned);
         const sharerHex = toHex(sharerPinned);
-        const r = await this.call('saihm_recall', { sharer: sharerHex, cellId: grant.cellId });
+        const r = await this.call('saihm_recall', {
+            sharer: sharerHex,
+            cellId: grant.cellId,
+        });
         if (typeof r !== 'object' || r === null || Array.isArray(r)) {
             throw new SaihmEndpointError(502, 'malformed_response', 'endpoint returned a malformed shared-recall response');
         }
@@ -407,7 +595,8 @@ export class SaihmProClient {
         if (!ctEqual(share.recipientAgentIdHash, this.identity.agentIdHash)) {
             throw new SaihmEndpointError(502, 'foreign_share', 'endpoint returned a share addressed to a different recipient');
         }
-        if (!ctEqual(share.sharerAgentIdHash, sharerPinned) || share.cellId !== grant.cellId) {
+        if (!ctEqual(share.sharerAgentIdHash, sharerPinned) ||
+            share.cellId !== grant.cellId) {
             throw new SaihmEndpointError(502, 'share_mismatch', `endpoint returned a share for the wrong sharer/cell`);
         }
         if (!verifyShareSig(share, sharerRecord.mldsaPubKey)) {
@@ -449,7 +638,12 @@ export class SaihmProClient {
             catch {
                 throw new SaihmEndpointError(502, 'undecryptable', `shared cell '${grant.cellId}' could not be opened with the unwrapped DEK`);
             }
-            return { cellId: env.cellId, plaintext, seq: env.seq.toString(10), commitmentHash: toHex(env.publicMeta.commitmentHash) };
+            return {
+                cellId: env.cellId,
+                plaintext,
+                seq: env.seq.toString(10),
+                commitmentHash: toHex(env.publicMeta.commitmentHash),
+            };
         }
         finally {
             dek.fill(0);

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join as pathJoin } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { SaihmProClient, SaihmEndpointError } from './client.js';
+const PACKAGE_VERSION = JSON.parse(readFileSync(pathJoin(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf-8')).version;
+const server = new McpServer({ name: 'saihm', version: PACKAGE_VERSION }, { capabilities: { tools: {} } });
+let client = null;
+function getClient() {
+    if (!client)
+        client = SaihmProClient.bootFromEnv();
+    return client;
+}
+const ok = (text) => ({ content: [{ type: 'text', text }] });
+function fail(e) {
+    const text = e instanceof SaihmEndpointError
+        ? `SAIHM error [${e.code}] (status ${e.status}): ${e.message}`
+        : e instanceof Error
+            ? e.message
+            : String(e);
+    return { content: [{ type: 'text', text }], isError: true };
+}
+server.tool('saihm_remember', 'Store information to SAIHM persistent encrypted memory (sealed client-side). Pass an existing cellId to update it.', {
+    content: z.string().describe('Information to remember'),
+    cellId: z
+        .string()
+        .optional()
+        .describe('Existing cell id (hex) to update; omit to create a new cell'),
+}, async ({ content, cellId }) => {
+    try {
+        const r = await getClient().remember(content, cellId ? { cellId } : {});
+        return ok(`REMEMBERED [${r.cellId}] seq=${r.seq} shard=${r.shardId} commit=${r.commitmentHash.slice(0, 16)}…`);
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool('saihm_recall', 'Retrieve and decrypt your memories (opened client-side). Optional keyword filter.', { query: z.string().optional().describe('Filter by keyword (empty = all)') }, async ({ query }) => {
+    try {
+        const cells = await getClient().recall(query);
+        if (cells.length === 0)
+            return ok('No memories stored.');
+        const lines = [`RECALL ${cells.length} memories`];
+        for (const c of cells)
+            lines.push(`  [${c.cellId}] seq=${c.seq} | ${c.plaintext}`);
+        return ok(lines.join('\n'));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool('saihm_forget', 'Cryptographically erase a memory (GDPR Art. 17): destroys the endpoint-side wrapped DEK so the cell can never be decrypted again.', { id: z.string().describe('Memory cell id (hex) to erase') }, async ({ id }) => {
+    try {
+        const r = await getClient().forget(id);
+        return ok(`FORGOTTEN [${r.cellId}] complete=${r.complete} sharesPurged=${r.sharesPurged} epoch=${r.epoch}`);
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool('saihm_status', 'Show operator-observable session status (no plaintext): tier, shards, sharing, BFSI, custody.', {}, async () => {
+    try {
+        const d = await getClient().status();
+        return ok(`SAIHM Session\n  agent=${d.agentIdHashHex.slice(0, 16)}…  tier=${d.tier}  custody=${d.custody}\n  shards=${d.activeShardCount}  sharing=${d.activeSharingContracts}  bfsi=${d.bfsi.toFixed(3)} (R=${d.bfsi_R} M=${d.bfsi_M})  epoch=${d.snapshotEpoch}`);
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool('saihm_share', "Share a cell with another agent, end-to-end authenticated. Pin the grantee's agentIdHash out-of-band.", {
+    cellId: z.string().describe('The cell to share'),
+    recipientRecord: z
+        .object({
+        mldsaPubKey: z.string(),
+        mlkemPubKey: z.string(),
+        mlkemPubKeySelfSig: z.string(),
+    })
+        .describe("The grantee's published identity record (hex fields)"),
+    recipientPinnedAgentIdHashHex: z
+        .string()
+        .describe("The grantee's agentIdHash (hex), pinned out-of-band"),
+    scope: z.enum(['read', 'write', 'readwrite']).optional().describe('Access scope (default read)'),
+    expiryEpoch: z
+        .string()
+        .regex(/^[0-9]+$/, 'expiryEpoch must be a decimal UNIX-epoch count')
+        .optional()
+        .describe('Optional expiry as a UNIX-epoch count (decimal string)'),
+}, async ({ cellId, recipientRecord, recipientPinnedAgentIdHashHex, scope, expiryEpoch }) => {
+    try {
+        const r = await getClient().share({
+            cellId,
+            recipientRecord,
+            recipientPinnedAgentIdHashHex,
+            ...(scope ? { scope } : {}),
+            ...(expiryEpoch ? { expiryEpoch: BigInt(expiryEpoch) } : {}),
+        });
+        return ok(`SHARED cell=${r.cellId} sharer=${r.sharer.slice(0, 16)}… recipient=${r.recipient.slice(0, 16)}…`);
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool('saihm_revoke_share', 'Revoke a prior share grant to a recipient for a cell.', {
+    cellId: z.string().describe('The shared cell id'),
+    recipientHex: z.string().describe("The grantee's agentIdHash (hex) to revoke"),
+}, async ({ cellId, recipientHex }) => {
+    try {
+        const r = await getClient().revokeShare(cellId, recipientHex);
+        return ok(`REVOKED cell=${r.cellId} recipient=${r.recipient.slice(0, 16)}… revoked=${r.revoked}`);
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool('saihm_governance_propose', "Submit a gSAIHM governance proposal. Scope MUST be 'emission_param' or 'protocol_upgrade'.", {
+    scope: z.enum(['emission_param', 'protocol_upgrade']).describe('Governable scope'),
+    paramKey: z.string().optional().describe('Parameter key (when scope=emission_param)'),
+    proposedValue: z.string().optional().describe('Proposed value as string'),
+}, async ({ scope, paramKey, proposedValue }) => {
+    try {
+        await getClient().governancePropose({
+            scope,
+            paramKey: paramKey ?? null,
+            proposedValue: proposedValue ?? null,
+        });
+        return ok('PROPOSED');
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool('saihm_governance_vote', 'Cast a vote on an open gSAIHM governance proposal.', {
+    proposalId: z.string().describe('Hex proposalId'),
+    approve: z.boolean().describe('true = approve, false = reject'),
+}, async ({ proposalId, approve }) => {
+    try {
+        await getClient().governanceVote({ proposalId, approve });
+        return ok('VOTED');
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+async function runJoin() {
+    const c = SaihmProClient.bootFromEnv();
+    const url = await c.requestCheckoutUrl();
+    process.stdout.write([
+        '',
+        'SAIHM — subscribe this identity to activate your memory:',
+        '',
+        '  ' + url,
+        '',
+        `  identity (agentIdHash): ${c.agentIdHash}`,
+        '',
+        '  Open the link above in a browser and pay. Keep SAIHM_MASTER_SECRET_HEX safe — it is',
+        '  the only key to your memory and cannot be recovered. After payment, start the server',
+        '  normally (drop the "join" argument) and it connects automatically.',
+        '',
+    ].join('\n'));
+}
+async function main() {
+    if (process.argv[2] === 'join') {
+        await runJoin();
+        return;
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    process.stderr.write(String(e instanceof Error ? e.message : e) + '\n');
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saihm/mcp-server-pro",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "SAIHM production thin-client. Seals client-side via @saihm/client-pro (ML-DSA-65 identity, per-cell AES-256-GCM DEK wrapped under a client KEK, ML-KEM-768 authenticated sharing) and POSTs opaque ciphertext to the blind, non-custodial SAIHM /mcp endpoint. The master secret, KEK, and plaintext never leave this process. Apache-2.0.",
   "type": "module",
   "main": "dist/index.js",
@@ -11,11 +11,14 @@
       "import": "./dist/index.js"
     }
   },
+  "bin": {
+    "saihm-mcp-server-pro": "dist/server.js"
+  },
   "scripts": {
     "clean": "rm -rf dist coverage",
-    "build": "npm run clean && tsc -p .",
+    "build": "npm run clean && tsc -p . && chmod +x dist/server.js",
     "typecheck": "tsc -p tsconfig.test.json",
-    "test": "tsx --test tests/client_pro.test.ts",
+    "test": "tsx --test tests/client_pro.test.ts tests/server.test.ts",
     "prepublishOnly": "npm run build && npm run typecheck && npm test"
   },
   "files": [
@@ -45,7 +48,9 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@saihm/client-pro": "^0.1.1"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@saihm/client-pro": "^0.1.2",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^25.9.0",