kojee-mcp 0.5.2 → 0.5.4

package/README.md

@@ -220,6 +220,35 @@ in it is Hermes-specific — and it is **OFF by default**.
 | `KOJEE_WEBHOOK_SECRET` | HMAC-SHA256 key for the signature header. URL set but secret unset ⇒ sink **DISABLED with an error** (the proxy NEVER sends unsigned webhooks). |
 | `KOJEE_WEBHOOK_TIMEOUT_MS` | Per-attempt request timeout (default `5000`). |
 | `KOJEE_WEBHOOK_MAX_RETRIES` | Retries on a retryable failure — network / 5xx / 408 / 429 (default `4`). |
+| `KOJEE_WEBHOOK_SIGNATURE_HEADER` | Header name carrying the signature (default `X-Kojee-Signature`). |
+| `KOJEE_WEBHOOK_SIGNATURE_PREFIX` | Literal string prepended to the hex digest (default empty — bare hex). |
+| `KOJEE_WEBHOOK_SIGNATURE_FORMAT` | Optional preset. `github` ⇒ header `X-Hub-Signature-256`, prefix `sha256=` (the GitHub-webhook convention). Explicit `_HEADER`/`_PREFIX` vars override the preset's corresponding value. Unknown values are **warned about once and ignored** — never fatal. |
+
+**Signature emission is configurable (0.5.3)** — the HMAC *computation* never
+changes (hex SHA-256 HMAC of the raw body bytes, keyed by
+`KOJEE_WEBHOOK_SECRET`); only the header name and an optional digest prefix do.
+Defaults are byte-identical to 0.5.2. For a GitHub-convention receiver (Hermes
+and most off-the-shelf webhook verifiers):
+
+```bash
+export KOJEE_WEBHOOK_SIGNATURE_FORMAT=github
+# Each POST then carries:
+#   X-Hub-Signature-256: sha256=<hex HMAC-SHA256 of the raw body, keyed by KOJEE_WEBHOOK_SECRET>
+# which verifies with any GitHub-style check, e.g.:
+#   expected = "sha256=" + HMAC_SHA256_hex(secret, raw_body)
+#   timing_safe_equal(header, expected)
+```
+
+Or set the pieces individually (these override the preset):
+
+```bash
+export KOJEE_WEBHOOK_SIGNATURE_HEADER="X-Hub-Signature-256"
+export KOJEE_WEBHOOK_SIGNATURE_PREFIX="sha256="
+```
+
+The wizard can persist this non-interactively, e.g.
+`kojee-mcp init --runtime hermes --webhook-url https://… --webhook-signature-format github`
+(also `--webhook-signature-header` / `--webhook-signature-prefix`).
 
 **Receiver contract** (the single source of truth is `buildWebhookReceiverNote()`
 in `src/tandem/recipe.ts`, and the exact body shape is the `WEBHOOK_BODY_SHAPE`
@@ -251,6 +280,94 @@ never delay or break the Monitor (event-log) or Channel wake paths. The status
 log redacts the secret and strips any basic-auth credentials embedded in
 `KOJEE_WEBHOOK_URL`.
 
+## Wake Continuity (0.5.4)
+
+The event-stream subscription is a **connect-time snapshot of the caller's
+memberships**. A daemon that rotates its session identity across restarts used
+to come up with its tandem seat still bound to the OLD session — subscribed to
+nothing, deaf to webhook wakes, while sends kept working (agent-scoped
+fallback). Two mechanisms close this permanently:
+
+**Ensure-join at startup.** After auth and *before* the event stream connects,
+the daemon ensure-joins its live session (`tandem_join` is idempotent — an
+existing seat returns `already_member`). One log line per tandem (`joined
+fresh` vs `already seated`); failures warn and continue (a bad id never kills
+the daemon).
+
+| `KOJEE_TANDEMS` | Behavior |
+|---|---|
+| *(unset — the default)* | **Auto**: `tandem_list` (which is **principal-scoped** — it also lists rooms where only *sibling* agents of the principal sit), **filtered to rows where THIS agent holds an active seat** (`my_membership.is_member === true`; rows missing the flag are excluded — fail closed), then ensure-join each with the live session. Auto mode re-seats the agent where it already belongs; it never joins rooms the agent was not in. |
+| `<id>,<id>,…` | Join exactly these tandem ObjectId hexes (24-hex; invalid entries warned + skipped). |
+| `none` | Disable ensure-join entirely. |
+
+**Stream reconnect after join.** Any successful `tandem_join` performed by the
+daemon path (the startup ensure-join, or the MCP tool called through the proxy
+by its agent) triggers a graceful event-stream reconnect (close + reconnect via
+the existing backoff machinery, resuming from the per-room cursors), so the
+subscription snapshot always includes just-acquired seats. Multiple joins in a
+burst are debounced into one reconnect. No daemon restart needed, ever.
+
+## Local Send Control Surface (0.5.4)
+
+One stable, supported way to **send** a Tandem message from *outside* the proxy
+process — for native gateway plugins, scripts, and humans. Two halves, one
+shared core (`src/tandem/send.ts`), one envelope contract.
+
+### CLI: `kojee-mcp send`
+
+```bash
+kojee-mcp send <tandem_id> --body "hello" [--reply-to <message_id>] [--kind message|status]
+```
+
+Uses the machine's **paired** credentials — the same `~/.kojee/config.json` +
+`~/.kojee/keypair.json` the proxy reads, the same DPoP/GatewayClient path, the
+same deterministic session seat. Prints **one JSON envelope** to stdout and
+exits `0`/`1`:
+
+```json
+{"ok":true,"tandem_id":"T-1","message_id":"m_123","cursor":42,"text":"..."}
+{"ok":false,"error":"content_blocked","message":"content blocked by gateway — ..."}
+```
+
+### HTTP: `POST /send` on the running daemon's hook-server
+
+Lets a plugin riding a **running** daemon send without spawning Node. Find the
+port and the bearer via the session-discovery file
+(`~/.kojee/sessions/cc-<key>.json` → `port`, `controlTokenPath`):
+
+```bash
+curl -s -X POST "http://127.0.0.1:$PORT/send" \
+  -H "Authorization: Bearer $(cat ~/.kojee/control-token)" \
+  -H "Content-Type: application/json" \
+  -d '{"tandem_id":"T-1","body":"hello","reply_to":"m_0","kind":"message"}'
+```
+
+Returns the **same JSON envelope** as the CLI. HTTP status mirrors the typed
+error: `200` ok · `400 bad_request` · `401 unauthorized` ·
+`403 content_blocked / member_cap / not_member / governance_denied` ·
+`429 rate_limited` · `502` upstream (gateway auth/network/unknown) ·
+`503 send_unavailable`.
+
+**Auth.** Every endpoint that returns or writes this principal's data —
+`POST /send`, `GET /poll`, `GET /status` — requires the same bearer: a fresh
+random token issued at every daemon start, stored `0600` at
+`~/.kojee/control-token` (rotates on restart — re-read the file, don't cache).
+Presenting it proves the caller can read this user's files; other local users
+and browser drive-by requests cannot. Only `GET /health` (a liveness ping
+carrying no data) stays open. The in-tree consumers (the Claude Code Stop /
+UserPromptSubmit hooks and `kojee-mcp doctor`) read the token from the path
+advertised in the session-discovery file and send it automatically; the
+Monitor wake path tails the event-log *file* and never touches `/poll`. If
+the daemon could not issue a token at start (exotic FS), the reads degrade
+open and `POST /send` answers `503` — loudly logged.
+
+**Typed errors** (`error` field, both surfaces): `member_cap`,
+`content_blocked` (the gateway WAF rejecting message *content* — commonly a
+literal URL in the body; de-fang or split it; this is **not** an auth failure),
+`gateway_auth`, `not_member`, `rate_limited`, `network`, `governance_denied`,
+`approval_required`, `not_paired`, `not_enrolled`, `bad_request`,
+`unauthorized`, `send_unavailable`, `send_failed` (raw text preserved).
+
 ## Development
 
 Run tests:

package/dist/chunk-2MIISF2W.js

@@ -0,0 +1,35 @@
+// src/auth/dpop.ts
+import { SignJWT, base64url } from "jose";
+import crypto from "crypto";
+async function createDPoPProof(privateKey, kid, method, url, nonce, accessToken) {
+  const payload = {
+    htm: method,
+    htu: url,
+    jti: crypto.randomUUID()
+  };
+  if (nonce) {
+    payload.nonce = nonce;
+  }
+  if (accessToken) {
+    payload.ath = computeAth(accessToken);
+  }
+  const header = {
+    typ: "dpop+jwt",
+    alg: "ES256",
+    jwk: { kid }
+  };
+  return new SignJWT(payload).setProtectedHeader(header).setIssuedAt().sign(privateKey);
+}
+function computeAth(accessToken) {
+  const hash = crypto.createHash("sha256").update(accessToken).digest();
+  return base64url.encode(hash);
+}
+
+// src/tandem/session-id.ts
+import { ulid } from "ulidx";
+var MCP_SESSION_ID = ulid();
+
+export {
+  createDPoPProof,
+  MCP_SESSION_ID
+};

package/dist/chunk-36L3GCU3.js

@@ -0,0 +1,213 @@
+import {
+  MCP_SESSION_ID,
+  createDPoPProof
+} from "./chunk-2MIISF2W.js";
+import {
+  translateHttpError,
+  translateJsonRpcError,
+  translateNetworkError
+} from "./chunk-LDZXU3DW.js";
+import {
+  secureDir,
+  secureFile
+} from "./chunk-BLEGIR35.js";
+
+// src/auth/keystore.ts
+import { importJWK, exportJWK, generateKeyPair } from "jose";
+import fs from "fs";
+import os from "os";
+import path from "path";
+var DEFAULT_PATH = path.join(os.homedir(), ".kojee", "keypair.json");
+async function loadKeystore(keystorePath = DEFAULT_PATH, expectedBrokerUrl) {
+  if (!fs.existsSync(keystorePath)) {
+    return null;
+  }
+  const raw = fs.readFileSync(keystorePath, "utf-8");
+  const data = JSON.parse(raw);
+  if (expectedBrokerUrl && data.broker_url !== expectedBrokerUrl) {
+    return null;
+  }
+  const privateKey = await importJWK(data.private_key_jwk, "ES256");
+  return {
+    privateKey,
+    publicJwk: data.public_jwk,
+    kid: data.kid,
+    data
+  };
+}
+async function saveKeystore(privateKey, publicJwk, kid, brokerUrl, keystorePath = DEFAULT_PATH) {
+  const dir = path.dirname(keystorePath);
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  secureDir(dir);
+  const privateJwk = await exportJWK(privateKey);
+  const data = {
+    private_key_jwk: privateJwk,
+    kid,
+    broker_url: brokerUrl,
+    public_jwk: publicJwk,
+    enrolled_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  fs.writeFileSync(keystorePath, JSON.stringify(data, null, 2), {
+    mode: 384
+  });
+  secureFile(keystorePath);
+}
+async function generateES256KeyPair() {
+  const { privateKey, publicKey } = await generateKeyPair("ES256");
+  const publicJwk = await exportJWK(publicKey);
+  publicJwk.kty = "EC";
+  publicJwk.crv = "P-256";
+  return { privateKey, publicJwk };
+}
+
+// src/gateway-client.ts
+import crypto from "crypto";
+var GatewayClient = class {
+  constructor(brokerUrl, token, privateKey, kid, sessionId) {
+    this.brokerUrl = brokerUrl;
+    this.token = token;
+    this.privateKey = privateKey;
+    this.kid = kid;
+    this.endpoint = `${brokerUrl}/mcp/messages/${sessionId}/`;
+  }
+  brokerUrl;
+  token;
+  privateKey;
+  kid;
+  currentNonce;
+  requestCounter = 0;
+  endpoint;
+  /**
+   * Expose the DPoP signing key so peer modules sharing auth state
+   * (e.g. tandem/event-stream.ts) can sign their own requests.
+   */
+  getPrivateKey() {
+    return this.privateKey;
+  }
+  /**
+   * Expose the bot_key_id (kid) for DPoP proof headers. Paired with
+   * getPrivateKey() so peer modules can construct proofs without
+   * threading the key material through their own constructors.
+   */
+  getKid() {
+    return this.kid;
+  }
+  /**
+   * Derive a deterministic session ID from the gateway token.
+   * session_id = sha256(token + "proxy").slice(0, 16)
+   */
+  static deriveSessionId(token) {
+    const hash = crypto.createHash("sha256").update(token + "proxy").digest("hex");
+    return hash.slice(0, 16);
+  }
+  /**
+   * Send a JSON-RPC 2.0 request to the gateway, handling DPoP auth and
+   * nonce retry transparently. A 403 `step_up_required` (deprecated feature,
+   * owner ruling 2026-06-10) is no longer polled — it surfaces immediately as
+   * a structured tool error via translateHttpError.
+   *
+   * `signal` (ROUND-3 MAJOR A) is a REAL AbortSignal threaded into the
+   * underlying `fetch` option — NOT placed inside `params`/`arguments`. A
+   * caller with a per-call timeout budget (e.g. resubscribeMemberships) passes
+   * its controller's signal here so a hung backend aborts at the budget instead
+   * of hanging forever. Putting the signal in `arguments` (the round-2 bug) both
+   * left fetch un-aborted AND serialized a junk `{}` onto the wire body.
+   */
+  async sendRpc(method, params = {}, signal) {
+    const rpcRequest = {
+      jsonrpc: "2.0",
+      id: ++this.requestCounter,
+      method,
+      params
+    };
+    return this.executeWithRetries(rpcRequest, signal);
+  }
+  async executeWithRetries(rpcRequest, signal) {
+    let response;
+    try {
+      response = await this.sendHttpRequest(rpcRequest, signal);
+    } catch (err) {
+      return translateNetworkError(err);
+    }
+    this.trackNonce(response);
+    if (response.status === 401) {
+      const body = await this.tryParseErrorBody(response);
+      if (body?.error === "use_dpop_nonce") {
+        console.error("[gateway] Nonce expired, retrying with fresh nonce...");
+        try {
+          response = await this.sendHttpRequest(rpcRequest, signal);
+        } catch (err) {
+          return translateNetworkError(err);
+        }
+        this.trackNonce(response);
+      } else {
+        const translated = translateHttpError(401, body?.error);
+        if (translated) return translated;
+      }
+    }
+    if (response.status === 403) {
+      const body = await this.tryParseErrorBody(response);
+      const translated = translateHttpError(403, body?.error, body?.trigger);
+      if (translated) return translated;
+    }
+    if (!response.ok) {
+      const body = await this.tryParseErrorBody(response);
+      const translated = translateHttpError(response.status, body?.error);
+      if (translated) return translated;
+      return {
+        content: [{ type: "text", text: `Gateway error: ${response.status}` }],
+        isError: true
+      };
+    }
+    const rpcResponse = await response.json();
+    if (rpcResponse.error) {
+      return translateJsonRpcError(rpcResponse.error);
+    }
+    const result = rpcResponse.result;
+    return result ?? { content: [{ type: "text", text: "No result" }] };
+  }
+  async sendHttpRequest(rpcRequest, signal) {
+    const proof = await createDPoPProof(
+      this.privateKey,
+      this.kid,
+      "POST",
+      this.endpoint,
+      this.currentNonce,
+      this.token
+    );
+    return fetch(this.endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `DPoP ${this.token}`,
+        DPoP: proof,
+        "Mcp-Session-Id": MCP_SESSION_ID
+      },
+      body: JSON.stringify(rpcRequest),
+      // ROUND-3 MAJOR A: the caller's AbortSignal rides HERE (a real fetch
+      // option), never inside the JSON-RPC body. `undefined` is a valid value
+      // for the fetch `signal` option (no abort wired).
+      ...signal ? { signal } : {}
+    });
+  }
+  trackNonce(response) {
+    const nonce = response.headers.get("DPoP-Nonce");
+    if (nonce) {
+      this.currentNonce = nonce;
+    }
+  }
+  async tryParseErrorBody(response) {
+    try {
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+};
+
+export {
+  loadKeystore,
+  saveKeystore,
+  generateES256KeyPair,
+  GatewayClient
+};