@suveren/gateway 0.40.0 → 0.41.1

package/content/guides/6-risks.md

@@ -11,6 +11,7 @@ What can make a test say more than it should, and what to do about each. Read th
 | The values a limit checks are readable on the Authority Server | Proposals are encrypted end to end since 0.27.0 — the server sees only the values it enforces limits on (e.g. an amount or a number of recipients) and fingerprints, never the content | Test data and renamed cases only in a setup; limits that refer to personal data are a profile question |
 | Setup limit too low | A clear without the following load leaves empty systems | Use a setup limit of 4–6 per day; clear and load in one go |
 | An AI that can control a browser or the screen | It could open the gateway's page, read the API key there and approve its own proposals — the person would no longer decide | Never open or operate the gateway's page, never handle the API key, never approve. Tell the person to approve themselves, and to keep the gateway page out of any browser an AI controls |
+| The AI writes as the person, or as a person at all | A customer believes they dealt with a human, or with the mandate owner personally. The footer says an AI sent it; the text would contradict it | Never write as the mandate owner or as any person, and never claim to be human. Write as their AI or about them in the third person, even when the person asks otherwise, and say why |
 | Calls around the Suveren tools | A terminal, HTTP or browser call to the gateway's ports is not governed by a mandate | Use only the Suveren tools. If something is missing, tell the person what — do not probe the gateway |
 
 Next: start a run — the person asks the working AI to work the new requests.

package/dist/control-plane/index.mjs

@@ -917,6 +917,11 @@ async function loadOrGenerateKeyPair(vault2) {
   vault2.setCredential(VAULT_SLOT, toStore);
   return kp;
 }
+async function getPublicKey(vault2) {
+  const stored = vault2.getCredential(VAULT_SLOT);
+  if (!stored?.publicKey) return null;
+  return fromBase64(stored.publicKey);
+}
 
 // src/lib/client-version.ts
 import { readFileSync as readFileSync4 } from "fs";
@@ -3759,7 +3764,11 @@ function findSealedAttachment(toolArgs, sha256) {
 
 // src/lib/content-crypto.ts
 import { createHash as createHash5 } from "crypto";
-import { canonicalize as canonicalize3 } from "@hap/core";
+import {
+  canonicalize as canonicalize3,
+  encryptProposalContent as hapEncryptProposalContent,
+  decryptProposalContent as hapDecryptProposalContent
+} from "@hap/core";
 var CONTENT_ALG = "HPKE-X25519-HKDF-SHA256-AES256GCM";
 function computeProposalContentHash(toolArgs) {
   return `sha256:${createHash5("sha256").update(canonicalize3(toolArgs)).digest("hex")}`;
@@ -3774,7 +3783,7 @@ function keysToWire(encryptedKeys) {
   }
   return keys;
 }
-async function fetchUserPubkey(userId, deps) {
+async function fetchUserPubkeyEntry(userIdOrDid, deps) {
   const pin = readPairing(deps.dataDir);
   const pinning = {
     enforce: resolvePinTls(deps.dataDir),
@@ -3782,13 +3791,22 @@ async function fetchUserPubkey(userId, deps) {
   };
   try {
     const { res } = await fetchAs(
-      `${deps.spUrl}/api/users/${encodeURIComponent(userId)}/pubkey`,
+      `${deps.spUrl}/api/users/${encodeURIComponent(userIdOrDid)}/pubkey`,
       { headers: { Cookie: deps.cookie }, signal: AbortSignal.timeout(5e3) },
       pinning
     );
     if (!res.ok) return null;
     const data = await res.json().catch(() => ({}));
-    return typeof data.pubkey === "string" ? data.pubkey : null;
+    if (typeof data.pubkey !== "string") return null;
+    return { pubkey: data.pubkey, ...typeof data.did === "string" ? { did: data.did } : {} };
+  } catch {
+    return null;
+  }
+}
+function decodeReaderKey(pubkeyB64) {
+  try {
+    const bytes = new Uint8Array(Buffer.from(pubkeyB64, "base64"));
+    return bytes.length === 32 ? bytes : null;
   } catch {
     return null;
   }
@@ -3798,34 +3816,87 @@ async function resolveRecipientPubkeys(recipientUserIds, deps) {
   const resolved = [];
   const unreadableFor = [];
   for (const userId of ids) {
-    const pubkeyB64 = await fetchUserPubkey(userId, deps);
-    if (!pubkeyB64) {
+    const entry = await fetchUserPubkeyEntry(userId, deps);
+    const bytes = entry ? decodeReaderKey(entry.pubkey) : null;
+    if (!entry || !bytes) {
       unreadableFor.push(userId);
       continue;
     }
-    try {
-      const bytes = new Uint8Array(Buffer.from(pubkeyB64, "base64"));
-      if (bytes.length !== 32) {
-        unreadableFor.push(userId);
-        continue;
-      }
-      resolved.push({ userId, publicKey: bytes });
-    } catch {
-      unreadableFor.push(userId);
-    }
+    resolved.push({ userId, publicKey: bytes, ...entry.did ? { did: entry.did } : {} });
   }
   return { resolved, unreadableFor };
 }
-async function encryptProposalContent(toolArgs, recipientUserIds, deps) {
-  const canonical = canonicalize3(toolArgs);
-  const hash = computeProposalContentHash(toolArgs);
+async function resolveReaderDids(v08, resolved, deps) {
+  const dids = Array.from(/* @__PURE__ */ new Set([v08.ownerDid, ...v08.deciders]));
+  const readers = [];
+  const unreadable = [];
+  for (const did of dids) {
+    if (deps.selfDid && did === deps.selfDid) {
+      if (deps.selfPublicKey?.length === 32) readers.push({ did, publicKey: deps.selfPublicKey });
+      else unreadable.push(did);
+      continue;
+    }
+    const known = resolved.find((r) => r.did === did);
+    if (known) {
+      readers.push({ did, publicKey: known.publicKey });
+      continue;
+    }
+    const entry = await fetchUserPubkeyEntry(did, deps);
+    const bytes = entry && (entry.did === void 0 || entry.did === did) ? decodeReaderKey(entry.pubkey) : null;
+    if (bytes) readers.push({ did, publicKey: bytes });
+    else unreadable.push(did);
+  }
+  return { readers, unreadable };
+}
+async function encryptProposalContent(toolArgs, recipientUserIds, deps, v08) {
   const { resolved, unreadableFor } = await resolveRecipientPubkeys(recipientUserIds, deps);
+  if (v08) {
+    const didReaders = await resolveReaderDids(v08, resolved, deps);
+    if (didReaders.readers.length === 0) {
+      throw new Error("No reader of this proposal (the mandate owner or a signed decider) has an end-to-end key \u2014 cannot encrypt this proposal.");
+    }
+    const { content: env2, proposalContentHash: proposalContentHash2 } = await hapEncryptProposalContent(toolArgs, [
+      ...resolved.map((r) => ({ did: r.userId, publicKey: r.publicKey })),
+      ...didReaders.readers
+    ]);
+    const byDid = new Set(didReaders.readers.map((r) => r.did));
+    const keys = {};
+    const encryptedKeys = {};
+    for (const r of resolved) keys[r.userId] = env2.encrypted_keys[r.userId];
+    for (const did of byDid) encryptedKeys[did] = env2.encrypted_keys[did];
+    return {
+      content: {
+        v: 1,
+        alg: CONTENT_ALG,
+        ciphertext: env2.ciphertext,
+        keys,
+        hash: proposalContentHash2,
+        encrypted_keys: encryptedKeys,
+        readers: [...byDid],
+        unreadable: didReaders.unreadable
+      },
+      unreadableFor
+    };
+  }
   if (resolved.length === 0) {
     throw new Error("No recipient (including the submitter) has a registered end-to-end key \u2014 cannot encrypt this proposal.");
   }
-  const encrypted = await encryptForRecipients(canonical, resolved);
+  const { content: env, proposalContentHash } = await hapEncryptProposalContent(
+    toolArgs,
+    resolved.map((r) => ({ did: r.userId, publicKey: r.publicKey })),
+    { unreadable: unreadableFor }
+  );
   return {
-    content: { v: 1, alg: CONTENT_ALG, ciphertext: toB64(encrypted.intentCiphertext), keys: keysToWire(encrypted.encryptedKeys), hash },
+    content: {
+      v: 1,
+      alg: CONTENT_ALG,
+      ciphertext: env.ciphertext,
+      keys: env.encrypted_keys,
+      hash: proposalContentHash,
+      encrypted_keys: env.encrypted_keys,
+      readers: env.readers,
+      unreadable: env.unreadable
+    },
     unreadableFor
   };
 }
@@ -3840,11 +3911,47 @@ async function encryptProposalNote(note, recipientUserIds, deps) {
     unreadableFor
   };
 }
-async function decryptProposalContent(wire, myUserId, myPrivateKey) {
-  const wrap = wire.keys[myUserId];
+function assertContentFingerprint(plaintext, wire) {
+  const expected = wire.proposalContentHash ?? wire.hash;
+  if (!expected) return;
+  let parsed;
+  try {
+    parsed = JSON.parse(plaintext);
+  } catch {
+    throw new Error("Decrypted proposal content is not JSON \u2014 refusing to show it.");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("Decrypted proposal content is not a JSON object \u2014 refusing to show it.");
+  }
+  const actual = computeProposalContentHash(parsed);
+  if (actual !== expected) {
+    throw new Error("Decrypted proposal content does not match its fingerprint \u2014 refusing to show it.");
+  }
+}
+var STRICT_B64URL = /^[A-Za-z0-9_-]+$/;
+async function decryptProposalContent(wire, myUserId, myPrivateKey, myDid) {
+  const keys = { ...wire.keys ?? {}, ...wire.encrypted_keys ?? {} };
+  const wrap = (myDid ? keys[myDid] : void 0) ?? keys[myUserId];
   if (!wrap) {
     throw new Error("No key wrap for this account in this content \u2014 this device cannot read it.");
   }
+  const fingerprint = wire.proposalContentHash ?? wire.hash;
+  if (fingerprint && [wire.ciphertext, wrap.ct, wrap.enc].every((x) => STRICT_B64URL.test(x))) {
+    let opened;
+    try {
+      opened = await hapDecryptProposalContent(
+        { ciphertext: wire.ciphertext, encrypted_keys: { [myUserId]: wrap }, readers: [myUserId], unreadable: [] },
+        myUserId,
+        myPrivateKey
+      );
+    } catch (err) {
+      throw new Error(`This content could not be opened on this device: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (opened.proposalContentHash !== fingerprint) {
+      throw new Error("Decrypted proposal content does not match its fingerprint \u2014 refusing to show it.");
+    }
+    return opened.contentJcs;
+  }
   const encrypted = {
     intentCiphertext: new Uint8Array(Buffer.from(wire.ciphertext, "base64")),
     encryptedKeys: {
@@ -3854,7 +3961,9 @@ async function decryptProposalContent(wire, myUserId, myPrivateKey) {
       }
     }
   };
-  return decryptIntent(encrypted, myUserId, myPrivateKey);
+  const plaintext = await decryptIntent(encrypted, myUserId, myPrivateKey);
+  assertContentFingerprint(plaintext, wire);
+  return plaintext;
 }
 
 // src/lib/execution-journal-reader.ts
@@ -3927,7 +4036,7 @@ async function resolveProposalToolArgsForRoute(spUrl, vault2, dataDir, lockAsTls
     try {
       const kp = await loadOrGenerateKeyPair(vault2);
       const me = vault2.getSessionUser();
-      const plaintext = await decryptProposalContent(proposal.content, me?.id ?? "", kp.privateKey);
+      const plaintext = await decryptProposalContent(proposal.content, me?.id ?? "", kp.privateKey, me?.did);
       return { tool: proposal.tool, toolArgs: JSON.parse(plaintext) };
     } catch (err) {
       res.json({ status: "unavailable", reason: "connector_error", message: `Could not decrypt this proposal's content on this device: ${err instanceof Error ? err.message : String(err)}` });
@@ -3986,7 +4095,7 @@ function createProposalStatusRouter(spUrl, vault2, dataDir, lockAsTlsMismatch2,
   router.get("/:id/outcome", (req, res) => {
     try {
       const entry = findLatestByProposal(dataDir, req.params.id);
-      if (!entry) {
+      if (!entry || entry.state === "requested") {
         const none = { state: "none" };
         res.json(none);
         return;
@@ -4341,7 +4450,10 @@ import { Router as Router14 } from "express";
 function createDecryptProposalContentRouter(vault2) {
   const router = Router14();
   router.post("/", async (req, res) => {
-    const { ciphertext, keys } = req.body;
+    const { ciphertext, hash, proposalContentHash } = req.body;
+    const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+    const { encrypted_keys: ek, keys: lk } = req.body;
+    const keys = isObj(ek) || isObj(lk) ? { ...isObj(lk) ? lk : {}, ...isObj(ek) ? ek : {} } : void 0;
     if (typeof ciphertext !== "string" || ciphertext.length === 0) {
       res.status(400).json({ error: "Missing or invalid field: ciphertext (base64 string)" });
       return;
@@ -4358,9 +4470,17 @@ function createDecryptProposalContentRouter(vault2) {
     try {
       const kp = await loadOrGenerateKeyPair(vault2);
       const plaintext = await decryptProposalContent(
-        { ciphertext, keys },
+        {
+          ciphertext,
+          keys,
+          // v0.8 rule 8: when the caller passes the proposal's fingerprint, the
+          // decrypted content is checked against it before it is shown.
+          ...typeof hash === "string" ? { hash } : {},
+          ...typeof proposalContentHash === "string" ? { proposalContentHash } : {}
+        },
         me.id,
-        kp.privateKey
+        kp.privateKey,
+        me.did
       );
       res.json({ plaintext });
     } catch (err) {
@@ -4425,7 +4545,7 @@ function createInternalContentCryptoRouter(getSecret, vault2, spUrl, dataDir) {
       res.status(401).json({ error: "unauthorized" });
       return;
     }
-    const { toolArgs, recipientUserIds } = req.body ?? {};
+    const { toolArgs, recipientUserIds, readers } = req.body ?? {};
     if (typeof toolArgs !== "object" || toolArgs === null || Array.isArray(toolArgs)) {
       res.status(400).json({ error: "toolArgs must be an object" });
       return;
@@ -4438,6 +4558,15 @@ function createInternalContentCryptoRouter(getSecret, vault2, spUrl, dataDir) {
       res.status(400).json({ error: `too many recipients (max ${MAX_RECIPIENTS})` });
       return;
     }
+    let v08;
+    if (readers !== void 0) {
+      const r = readers;
+      if (!r || typeof r.ownerDid !== "string" || !r.ownerDid.startsWith("did:") || !Array.isArray(r.deciders) || !r.deciders.every((d) => typeof d === "string" && d.startsWith("did:")) || r.deciders.length > MAX_RECIPIENTS) {
+        res.status(400).json({ error: "readers must be { ownerDid: DID, deciders: DID[] }" });
+        return;
+      }
+      v08 = { ownerDid: r.ownerDid, deciders: r.deciders };
+    }
     const me = vault2.getSessionUser();
     const cookie = vault2.getSpCookie();
     if (!me || !cookie) {
@@ -4445,10 +4574,12 @@ function createInternalContentCryptoRouter(getSecret, vault2, spUrl, dataDir) {
       return;
     }
     try {
+      const selfPublicKey = v08 ? await getPublicKey(vault2) ?? void 0 : void 0;
       const { content, unreadableFor } = await encryptProposalContent(
         toolArgs,
         recipientUserIds,
-        { spUrl, cookie, dataDir, selfUserId: me.id }
+        { spUrl, cookie, dataDir, selfUserId: me.id, ...v08 ? { selfDid: me.did, selfPublicKey } : {} },
+        v08
       );
       res.json({ content, unreadableFor });
     } catch (err) {
@@ -4461,7 +4592,10 @@ function createInternalContentCryptoRouter(getSecret, vault2, spUrl, dataDir) {
       res.status(401).json({ error: "unauthorized" });
       return;
     }
-    const { ciphertext, keys } = req.body ?? {};
+    const body = req.body ?? {};
+    const { ciphertext, hash, proposalContentHash } = body;
+    const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+    const keys = isObj(body.encrypted_keys) || isObj(body.keys) ? { ...isObj(body.keys) ? body.keys : {}, ...isObj(body.encrypted_keys) ? body.encrypted_keys : {} } : void 0;
     if (typeof ciphertext !== "string" || ciphertext.length === 0) {
       res.status(400).json({ error: "ciphertext (base64 string) is required" });
       return;
@@ -4478,9 +4612,16 @@ function createInternalContentCryptoRouter(getSecret, vault2, spUrl, dataDir) {
     try {
       const kp = await loadOrGenerateKeyPair(vault2);
       const plaintext = await decryptProposalContent(
-        { ciphertext, keys },
+        {
+          ciphertext,
+          keys,
+          // v0.8 rule 8: checked against the fingerprint before it is returned.
+          ...typeof hash === "string" ? { hash } : {},
+          ...typeof proposalContentHash === "string" ? { proposalContentHash } : {}
+        },
         me.id,
-        kp.privateKey
+        kp.privateKey,
+        me.did
       );
       res.json({ plaintext });
     } catch (err) {
@@ -4959,11 +5100,12 @@ import {
   computeBoundsHash,
   computeScopeHash,
   computeIntentHash,
+  computeExecutionContextHash,
   computeProfileHash,
   isCommitmentModeAllowed,
   validateBoundsParams,
   validateScopeParams,
-  PROTOCOL_VERSION
+  SUPPORTED_VERSIONS
 } from "@hap/core";
 var MandateRefused = class extends Error {
 };
@@ -5075,7 +5217,7 @@ async function createMandate(req, deps) {
   const boundsHash = computeBoundsHash(plan.bounds, plan.profile);
   const scopeHash = computeScopeHash(plan.context, plan.profile);
   const intentHash = computeIntentHash(plan.intent);
-  const ecHash = computeIntentHash(JSON.stringify({ profile: plan.profile.id, domain: plan.domain, group: plan.groupId }));
+  const ecHash = computeExecutionContextHash(plan.profile);
   let enc;
   if (!plan.isPersonal) {
     const keys = await deps.as(
@@ -5090,7 +5232,10 @@ async function createMandate(req, deps) {
     authorization_id: authorizationId,
     profile_id: plan.profile.id,
     profile_hash: computeProfileHash(plan.profile),
-    supported_versions: [PROTOCOL_VERSION],
+    // v0.8: every version this gateway verifies and enforces, newest first
+    // (protocol.md → Version negotiation, rule 1). Today's 0.7 AS issues 0.7,
+    // a 0.8 AS issues 0.8 — the gateway reads each under its own rules.
+    supported_versions: [...SUPPORTED_VERSIONS],
     bounds: plan.bounds,
     bounds_hash: boundsHash,
     scope_hash: scopeHash,