@ouro.bot/cli 0.1.0-alpha.470 → 0.1.0-alpha.471

package/changelog.json

@@ -1,6 +1,14 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.471",
+      "changes": [
+        "`ouro account ensure` and `ouro connect mail` can now repair hosted Mail Control registry/vault drift with `--rotate-missing-mail-keys`, storing freshly returned one-time private keys in the owning agent vault without printing them.",
+        "Hosted Mail setup now detects missing private key material before writing partial runtime config, rotates only the missing native mailbox and/or delegated source keys, and preserves source separation for native agent mail versus delegated human mail.",
+        "Agent Mail setup and recovery docs now teach hosted key rotation explicitly, including that rotation repairs future mail access but cannot decrypt mail already encrypted to a lost private key."
+      ]
+    },
     {
       "version": "0.1.0-alpha.470",
       "changes": [

package/dist/heart/daemon/cli-exec.js

@@ -3055,12 +3055,43 @@ function requiredHostedKeyIds(body) {
         .map((record) => stringField(record, "keyId"))
         .filter((keyId) => keyId.length > 0);
 }
+function hostedMissingMailKeys(body, keys) {
+    const mailbox = isPlainRecord(body.mailbox) ? body.mailbox : undefined;
+    const sourceGrant = isPlainRecord(body.sourceGrant) ? body.sourceGrant : undefined;
+    const mailboxKeyId = mailbox ? stringField(mailbox, "keyId") : "";
+    const sourceKeyId = sourceGrant ? stringField(sourceGrant, "keyId") : "";
+    const missingMailbox = mailboxKeyId.length > 0 && !keys[mailboxKeyId];
+    const missingSourceGrant = sourceKeyId.length > 0 && !keys[sourceKeyId];
+    return {
+        keyIds: [
+            ...(missingMailbox ? [mailboxKeyId] : []),
+            ...(missingSourceGrant ? [sourceKeyId] : []),
+        ],
+        rotateMailbox: missingMailbox,
+        rotateSourceGrant: missingSourceGrant,
+    };
+}
 function assertHostedPrivateKeys(input) {
     for (const keyId of input.requiredKeyIds) {
         if (input.keys[keyId])
             continue;
-        throw new Error(`hosted Mail Control references private mail key ${keyId}, but it was not returned and is not present in ${input.agent}'s vault runtime/config. Repair requires a fresh Mail Control one-time key response or key rotation.`);
+        throw new Error(`hosted Mail Control references private mail key ${keyId}, but it was not returned and is not present in ${input.agent}'s vault runtime/config. Repair requires a fresh Mail Control one-time key response or rerunning setup with --rotate-missing-mail-keys.`);
+    }
+}
+async function requestHostedMailControl(input) {
+    const response = await input.fetchImpl(`${input.config.url}${input.path}`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${input.config.token}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(input.payload),
+    });
+    const body = await response.json();
+    if (!response.ok || body.ok === false) {
+        throw new Error(`hosted Mail Control ${input.label} failed (${response.status}): ${body.error ?? response.statusText}`);
     }
+    return body;
 }
 async function promptDelegatedMailSource(deps, input = {}) {
     if (input.noDelegatedSource)
@@ -3109,38 +3140,52 @@ async function ensureAgentMailroom(agent, input, deps, progressLabel) {
         if (hostedConfig) {
             progress.updateDetail("calling hosted Mail Control");
             const fetchImpl = deps.fetchImpl ?? fetch;
-            const response = await fetchImpl(`${hostedConfig.url}/v1/mailboxes/ensure`, {
-                method: "POST",
-                headers: {
-                    authorization: `Bearer ${hostedConfig.token}`,
-                    "content-type": "application/json",
-                },
-                body: JSON.stringify({
-                    agentId: agent,
-                    ...(input.ownerEmail ? { ownerEmail: input.ownerEmail } : {}),
-                    ...(input.source ? { source: input.source } : {}),
-                }),
+            const basePayload = {
+                agentId: agent,
+                ...(input.ownerEmail ? { ownerEmail: input.ownerEmail } : {}),
+                ...(input.source ? { source: input.source } : {}),
+            };
+            let body = await requestHostedMailControl({
+                fetchImpl,
+                config: hostedConfig,
+                path: "/v1/mailboxes/ensure",
+                payload: basePayload,
+                label: "ensure",
             });
-            const body = await response.json();
-            if (!response.ok || body.ok === false) {
-                throw new Error(`hosted Mail Control ensure failed (${response.status}): ${body.error ?? response.statusText}`);
-            }
-            const publicRegistry = requiredResponseRecord(body.publicRegistry, "publicRegistry");
-            const blobStore = requiredResponseRecord(body.blobStore, "blobStore");
-            mailboxAddress = typeof body.mailboxAddress === "string" && body.mailboxAddress.trim()
-                ? body.mailboxAddress.trim()
-                : requiredResponseText(requiredResponseRecord(body.mailbox, "mailbox"), "canonicalAddress", "mailboxAddress");
-            sourceAlias = typeof body.sourceAlias === "string" && body.sourceAlias.trim() ? body.sourceAlias.trim() : null;
-            const generatedPrivateKeys = responsePrivateKeys(body.generatedPrivateKeys);
+            let generatedPrivateKeys = responsePrivateKeys(body.generatedPrivateKeys);
             const privateKeys = {
                 ...mailroomPrivateKeys(existingMailroom),
                 ...generatedPrivateKeys,
             };
+            const missingKeys = hostedMissingMailKeys(body, privateKeys);
+            if (missingKeys.keyIds.length > 0 && input.rotateMissingMailKeys) {
+                progress.updateDetail("rotating missing hosted mail keys");
+                body = await requestHostedMailControl({
+                    fetchImpl,
+                    config: hostedConfig,
+                    path: "/v1/mailboxes/rotate-keys",
+                    payload: {
+                        ...basePayload,
+                        rotateMailbox: missingKeys.rotateMailbox,
+                        rotateSourceGrant: missingKeys.rotateSourceGrant,
+                        reason: "missing private mail keys in agent vault",
+                    },
+                    label: "key rotation",
+                });
+                generatedPrivateKeys = responsePrivateKeys(body.generatedPrivateKeys);
+                Object.assign(privateKeys, generatedPrivateKeys);
+            }
             assertHostedPrivateKeys({
                 agent,
                 keys: privateKeys,
                 requiredKeyIds: requiredHostedKeyIds(body),
             });
+            const publicRegistry = requiredResponseRecord(body.publicRegistry, "publicRegistry");
+            const blobStore = requiredResponseRecord(body.blobStore, "blobStore");
+            mailboxAddress = typeof body.mailboxAddress === "string" && body.mailboxAddress.trim()
+                ? body.mailboxAddress.trim()
+                : requiredResponseText(requiredResponseRecord(body.mailbox, "mailbox"), "canonicalAddress", "mailboxAddress");
+            sourceAlias = typeof body.sourceAlias === "string" && body.sourceAlias.trim() ? body.sourceAlias.trim() : null;
             mode = "hosted";
             registryPath = null;
             storePath = null;
@@ -3243,7 +3288,10 @@ async function executeConnectMail(agent, deps, input = {}) {
         ],
     });
     const setup = await promptDelegatedMailSource(deps, input);
-    const outcome = await ensureAgentMailroom(agent, setup, deps, "connect mail");
+    const outcome = await ensureAgentMailroom(agent, {
+        ...setup,
+        ...(input.rotateMissingMailKeys ? { rotateMissingMailKeys: true } : {}),
+    }, deps, "connect mail");
     return writeCapabilityOutcome(deps, {
         subtitle: `${agent}'s Mail sense is configured.`,
         summary: `Agent Mail is ready for ${agent}.`,
@@ -3309,7 +3357,10 @@ async function executeAccountEnsure(command, deps) {
         ],
     });
     const setup = await promptDelegatedMailSource(deps, command);
-    const outcome = await ensureAgentMailroom(command.agent, setup, deps, "account ensure");
+    const outcome = await ensureAgentMailroom(command.agent, {
+        ...setup,
+        ...(command.rotateMissingMailKeys ? { rotateMissingMailKeys: true } : {}),
+    }, deps, "account ensure");
     return writeCapabilityOutcome(deps, {
         subtitle: `${command.agent}'s work substrate account is configured.`,
         summary: `Ouro work substrate is ready for ${command.agent}.`,

package/dist/heart/daemon/cli-help.js

@@ -313,12 +313,12 @@ const SUBCOMMAND_HELP = {
     },
     "connect mail": {
         description: "Provision portable Agent Mail / Mailroom access and enable the Mail sense",
-        usage: "ouro connect mail [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source]",
+        usage: "ouro connect mail [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
         example: "ouro connect mail --agent slugger --owner-email ari@mendelow.me --source hey",
     },
     "account ensure": {
         description: "Idempotently prepare an agent's vault-backed work substrate account and private Mailroom mailbox",
-        usage: "ouro account ensure [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source]",
+        usage: "ouro account ensure [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
         example: "ouro account ensure --agent slugger --owner-email ari@mendelow.me --source hey",
     },
     "mail import-mbox": {

package/dist/heart/daemon/cli-parse.js

@@ -84,8 +84,8 @@ function usage() {
         "  ouro config model [--agent <name>] <model-name>",
         "  ouro config models [--agent <name>]",
         "  ouro auth [--agent <name>] [--provider <provider>]",
-        "  ouro account ensure [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source]",
-        "  ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source]",
+        "  ouro account ensure [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
+        "  ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
         "  ouro mail import-mbox --file <path> [--owner-email <email>] [--source <label>] [--agent <name>]",
         "  ouro auth verify [--agent <name>] [--provider <provider>]",
         "  ouro auth switch [--agent <name>] --provider <provider>",
@@ -817,6 +817,7 @@ function extractMailSourceFlags(args, usageText) {
     let ownerEmail;
     let source;
     let noDelegatedSource = false;
+    let rotateMissingMailKeys = false;
     let hasMailSourceFlags = false;
     for (let i = 0; i < args.length; i += 1) {
         const token = args[i];
@@ -839,6 +840,11 @@ function extractMailSourceFlags(args, usageText) {
             hasMailSourceFlags = true;
             continue;
         }
+        if (token === "--rotate-missing-mail-keys") {
+            rotateMissingMailKeys = true;
+            hasMailSourceFlags = true;
+            continue;
+        }
         rest.push(token);
     }
     if (noDelegatedSource && (ownerEmail !== undefined || source !== undefined)) {
@@ -852,11 +858,12 @@ function extractMailSourceFlags(args, usageText) {
         ...(ownerEmail !== undefined ? { ownerEmail } : {}),
         ...(source !== undefined ? { source } : {}),
         ...(noDelegatedSource ? { noDelegatedSource: true } : {}),
+        ...(rotateMissingMailKeys ? { rotateMissingMailKeys: true } : {}),
         hasMailSourceFlags,
     };
 }
 function parseConnectCommand(args) {
-    const usageText = "Usage: ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source]";
+    const usageText = "Usage: ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]";
     const { agent, rest: afterAgent } = extractAgentFlag(args);
     const mailFlags = extractMailSourceFlags(afterAgent, usageText);
     if (mailFlags.rest.length > 1)
@@ -872,6 +879,7 @@ function parseConnectCommand(args) {
         ...(mailFlags.ownerEmail !== undefined ? { ownerEmail: mailFlags.ownerEmail } : {}),
         ...(mailFlags.source !== undefined ? { source: mailFlags.source } : {}),
         ...(mailFlags.noDelegatedSource ? { noDelegatedSource: true } : {}),
+        ...(mailFlags.rotateMissingMailKeys ? { rotateMissingMailKeys: true } : {}),
     };
 }
 function parseMailCommand(args) {
@@ -912,7 +920,7 @@ function parseMailCommand(args) {
 }
 function parseAccountCommand(args) {
     const [sub, ...subArgs] = args;
-    const usageText = "Usage: ouro account ensure [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source]";
+    const usageText = "Usage: ouro account ensure [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]";
     if (sub !== "ensure") {
         throw new Error(usageText);
     }
@@ -926,6 +934,7 @@ function parseAccountCommand(args) {
         ...(mailFlags.ownerEmail !== undefined ? { ownerEmail: mailFlags.ownerEmail } : {}),
         ...(mailFlags.source !== undefined ? { source: mailFlags.source } : {}),
         ...(mailFlags.noDelegatedSource ? { noDelegatedSource: true } : {}),
+        ...(mailFlags.rotateMissingMailKeys ? { rotateMissingMailKeys: true } : {}),
     };
 }
 function parseProviderUseCommand(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.470",
+  "version": "0.1.0-alpha.471",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",