npm - @saihm/mcp-server-pro - Versions diffs - 0.1.3 → 0.1.6 - Mend

@saihm/mcp-server-pro 0.1.3 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -11,19 +11,72 @@ Production thin-client for **SAIHM non-custodial memory**.
 > **Key loss is unrecoverable by design.** If you lose your master secret you lose your KEK, and no one — including SAIHM — can open your cells. Back it up securely.
+## See it run
+- **Live cross-model demos** — offline, ~1 min each, no account: <https://citw2.github.io/saihm-demos/>. Ground a memory you own in Claude, GPT, DeepSeek, Qwen, Kimi, or GLM, then prove you can erase it. `demo-claude-code` runs a stdio MCP server exactly like this one for Claude Code and Cursor.
+- **Token benchmark** — recalling a bounded set of memory cells instead of re-sending the transcript cut input tokens by **62.8%–85.9%** (up to ~86%) across a realistic multi-session task; open, offline, reproducible: <https://github.com/citw2/saihm-token-benchmark>.
 ## Install
 ```sh
 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 +99,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 +108,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 +118,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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,51 @@ 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 +217,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 +238,136 @@ 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 +381,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 +429,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 +466,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 +499,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 +581,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 +601,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 +644,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 ADDED Viewed

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

package/dist/server.js ADDED Viewed

@@ -0,0 +1,185 @@
+#!/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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@saihm/mcp-server-pro",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "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/smoke.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",