@tomato414941/foundation 0.15.0 → 0.22.0

package/envelope.mjs

@@ -0,0 +1,57 @@
+import { createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes } from 'node:crypto';
+
+// How a secret is kept so that only those it was handed to can open it. Each secret has a key of its own (K);
+// its bytes are sealed with K, and K is sealed once per recipient with that recipient's public key: an
+// envelope. Whoever holds the private key opens the envelope and then the bytes; nobody else, and not the
+// server, which keeps only sealed bytes and envelopes. A recipient's private key is itself kept sealed by
+// a key that only one of its WebAuthn credentials yields (its PRF output), or in a file it keeps itself.
+//
+// Keys are X25519; sealing is AES-256-GCM; the envelope key comes from HKDF-SHA256 over the ephemeral
+// agreement. Every form is bytes: iv (12) + tag (16) + ciphertext, with the ephemeral public key (32) in
+// front for an envelope. A browser does the same with Web Crypto.
+const SPKI = Buffer.from('302a300506032b656e032100', 'hex'), PKCS8 = Buffer.from('302e020100300506032b656e04220420', 'hex');
+const ENVELOPE_INFO = 'foundation-envelope', WRAP_INFO = 'foundation-key';
+
+export function generateKey() {
+  const { privateKey, publicKey } = generateKeyPairSync('x25519');
+  return { privateKey: privateKey.export({ type: 'pkcs8', format: 'der' }).subarray(-32), publicKey: publicKey.export({ type: 'spki', format: 'der' }).subarray(-32) };
+}
+export const publicKeyOf = privateKey => createPublicKey(toPrivate(privateKey)).export({ type: 'spki', format: 'der' }).subarray(-32);
+const toPublic = raw => createPublicKey({ key: Buffer.concat([SPKI, raw]), type: 'spki', format: 'der' });
+const toPrivate = raw => createPrivateKey({ key: Buffer.concat([PKCS8, raw]), type: 'pkcs8', format: 'der' });
+
+function sealWith(key, bytes, aad) {
+  const iv = randomBytes(12), cipher = createCipheriv('aes-256-gcm', key, iv);
+  if (aad) cipher.setAAD(aad);
+  const content = Buffer.concat([cipher.update(bytes), cipher.final()]);
+  return Buffer.concat([iv, cipher.getAuthTag(), content]);
+}
+function openWith(key, sealed, aad) {
+  if (sealed.length < 28) throw new Error('sealed bytes are too short');
+  const decipher = createDecipheriv('aes-256-gcm', key, sealed.subarray(0, 12));
+  if (aad) decipher.setAAD(aad);
+  decipher.setAuthTag(sealed.subarray(12, 28));
+  return Buffer.concat([decipher.update(sealed.subarray(28)), decipher.final()]);
+}
+const agree = (privateKey, publicKey, info) => Buffer.from(hkdfSync('sha256', diffieHellman({ privateKey: toPrivate(privateKey), publicKey: toPublic(publicKey) }), '', info, 32));
+
+// The secret's own key, and its bytes sealed with it.
+export const newContentKey = () => randomBytes(32);
+export const sealContent = (contentKey, bytes) => sealWith(contentKey, bytes);
+export const openContent = (contentKey, sealed) => openWith(contentKey, sealed);
+
+// K sealed for one recipient: an ephemeral key agrees with the recipient's, and the recipient's public key
+// is bound in as associated data so an envelope opens only for whom it was made.
+export function seal(contentKey, recipientPublicKey) {
+  const ephemeral = generateKey();
+  return Buffer.concat([ephemeral.publicKey, sealWith(agree(ephemeral.privateKey, recipientPublicKey, ENVELOPE_INFO), contentKey, recipientPublicKey)]);
+}
+export function open(envelope, privateKey) {
+  if (envelope.length < 32 + 28) throw new Error('envelope is too short');
+  return openWith(agree(privateKey, envelope.subarray(0, 32), ENVELOPE_INFO), envelope.subarray(32), publicKeyOf(privateKey));
+}
+
+// A private key sealed with what a credential yields, so that credential alone unseals it.
+const wrapKey = yielded => Buffer.from(hkdfSync('sha256', yielded, '', WRAP_INFO, 32));
+export const wrap = (privateKey, yielded) => sealWith(wrapKey(yielded), privateKey);
+export const unwrap = (wrapped, yielded) => openWith(wrapKey(yielded), wrapped);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tomato414941/foundation",
-  "version": "0.15.0",
-  "description": "Foundation CLI: make a key, and hand what is kept to a command without it passing through the agent.",
+  "version": "0.22.0",
+  "description": "Foundation CLI: give this machine a WebAuthn credential, and hand what is kept to a command without it passing through the agent.",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -11,7 +11,9 @@
   },
   "files": [
     "runtime.mjs",
-    "env-name.mjs"
+    "env-name.mjs",
+    "webauthn.mjs",
+    "envelope.mjs"
   ],
   "repository": {
     "type": "git",

package/runtime.mjs

@@ -8,47 +8,58 @@ import { homedir, hostname, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
 import { validEnvName } from './env-name.mjs';
+import { createCredential, answer } from './webauthn.mjs';
+import { newContentKey, sealContent, seal, open as openEnvelope, openContent, generateKey } from './envelope.mjs';
 
 // This program does only what the agent running it cannot do for itself.
 //
 // Everything Foundation offers is plain HTTP, and an agent with the key can call it directly; a command
 // wrapper around those calls would only narrow what the agent is allowed to think of. Two things are left:
-//   connect  say which server, and make the key. It has to exist as a private file before anything can be asked, and whoever
-//            makes it must not print it.
+//   init     say which server, and make this machine's WebAuthn credential: the machine becomes a principal there, of
+//            nobody's. Its private key has to exist as a private file before anything can be asked, and nothing prints it.
+//   join     ask a person to make this machine their agent, so that it may act for them.
+//   token    prove this machine with its credential and print a bearer token that lasts an hour, for calling the API.
 //   exec     hand what is kept to a command, or keep a file it creates, without the bytes passing through
 //            the agent. If the agent fetched the values itself they would be in its context.
 // There is also `api`, which is for people and for scripts rather than for agents: it attaches the key to a
 // request and prints what comes back. One escape hatch, so that the API can grow without this program growing
 // a verb for every endpoint, and without deciding for an agent how it ought to use any of them.
-// The key file: what Foundation issued, kept private. Nothing here makes a key; Foundation does, once, when this
-// machine becomes a principal, and the file is the only place it lives afterwards.
+// The key file: this machine's WebAuthn credential - its id, whose it is, and its private key - kept private, and
+// the machine's own key for what is sealed for it (envelope.mjs). Both private halves are made here and never leave;
+// Foundation keeps only the public halves. A file may instead hold an access key Foundation issued - as handed out on the
+// web for a machine, or given to a lent machine - and, unless it is a lent machine's, it is replaced with a credential the
+// first time it is used.
 async function readKey(path, { missingOk = false } = {}) {
   let handle;
   try {
     handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
     const info = await handle.stat();
-    if (!info.isFile() || info.size > 512 || (info.mode & 0o077) || (process.getuid && info.uid !== process.getuid())) throw new Error('Runtime key file must be owned by the current user and private (mode 600).');
-    const token = (await handle.readFile('utf8')).trim();
-    if (!/^fdn_[A-Za-z0-9_-]{43}$/.test(token)) throw new Error('Invalid runtime key file.');
-    return token;
+    if (!info.isFile() || info.size > 4096 || (info.mode & 0o077) || (process.getuid && info.uid !== process.getuid())) throw new Error('Runtime key file must be owned by the current user and private (mode 600).');
+    const content = (await handle.readFile('utf8')).trim();
+    if (/^fdn_[A-Za-z0-9_-]{43}$/.test(content)) return { token: content };
+    let credential, own;
+    try { ({ webauthn_credential: credential, key: own } = JSON.parse(content)); } catch {}
+    if (typeof credential?.id !== 'string' || typeof credential.user !== 'string' || credential.private_key?.kty !== 'EC') throw new Error('Invalid runtime key file.');
+    if (own !== undefined && !/^[A-Za-z0-9_-]{43}$/.test(own?.private_key ?? '')) throw new Error('Invalid runtime key file.');
+    return { credential, own };
   } catch (error) {
-    if (error.code === 'ENOENT') { if (missingOk) return null; throw new Error('No key yet. Run: foundation connect'); }
+    if (error.code === 'ENOENT') { if (missingOk) return null; throw new Error('No key yet. Run: foundation init'); }
     if (error.code === 'ELOOP') throw new Error('Runtime key file must not be a symbolic link.');
     throw error;
   } finally { await handle?.close(); }
 }
-async function writeKey(path, token, privateDirectory) {
+async function writeKey(path, content, privateDirectory) {
   await mkdir(dirname(path), { recursive: true, mode: 0o700 });
   if (privateDirectory) {
     const directory = await stat(dirname(path));
     if ((directory.mode & 0o077) || (process.getuid && directory.uid !== process.getuid())) throw new Error('Foundation key directory must be owned by the current user and private (mode 700).');
   }
   const created = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 0o600);
-  try { await created.writeFile(token + '\n'); await created.sync(); } finally { await created.close(); }
+  try { await created.writeFile(content + '\n'); await created.sync(); } finally { await created.close(); }
 }
 
 const VERSION = createRequire(import.meta.url)('./package.json').version;
-// Which server this machine talks to is a setting, not part of the program: `connect <url>` writes it here,
+// Which server this machine talks to is a setting, not part of the program: `init <url>` writes it here,
 // and FOUNDATION_URL, when set, wins for that one run.
 const configPath = () => join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'foundation', 'config.json');
 async function savedUrl() {
@@ -63,7 +74,7 @@ async function saveUrl(origin) {
 }
 function serverUrl(value) {
   let url;
-  try { url = new URL(value); } catch { throw new Error('No Foundation server yet. Run: foundation connect <url>'); }
+  try { url = new URL(value); } catch { throw new Error('No Foundation server yet. Run: foundation init <url>'); }
   if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(url.hostname))) || url.username || url.password || url.pathname !== '/' || url.search || url.hash) throw new Error('The Foundation URL must be an HTTPS origin (HTTP is allowed only on localhost).');
   return url;
 }
@@ -99,23 +110,27 @@ async function outputBytes(path) {
 const HELP = `Usage: foundation <command> [options]
 
 Commands:
-  connect [<url>] [--name <name>]      Make this machine's key and ask the owner to approve it.
+  init [<url>] [--name <name>]         Make this machine's credential: it becomes a principal of its own.
                                        With <url>, remember that Foundation server for later commands.
+  join                                 Ask a person to make this machine their agent.
+  token                                Print a bearer token for the API, valid for an hour.
   api <METHOD> </path> [--json <body>] [--from <file>] [--type <media-type>]
-                                       Send one request to the Foundation API with the key attached.
+                                       Send one request to the Foundation API as this machine.
   exec <ENV>=<name> [...] -- <command> [args...]
                                        Run a command with saved values in its environment.
   exec --inputs '<json>' -- <command>  The same, with files, structured inputs, or a connection for a service by id.
   exec --output '<json>' -- <command>  Also save a file the command writes.
+  keep <name> --from <file>            Save a file as a secret, sealed here for whoever may open it.
+  read <name>                          Print a secret this machine was handed an envelope for.
   version                              Print the version.
 
 API specification:
   foundation api GET /openapi.json      Read the server's OpenAPI specification; no key required.
 
 Environment:
-  FOUNDATION_URL               The server for this run (otherwise the one saved by connect).
+  FOUNDATION_URL               The server for this run (otherwise the one saved by init).
   FOUNDATION_AGENT             Your name, such as claude or codex; gives each agent its own key file.
-  FOUNDATION_RUNTIME_KEY_FILE  Where the key file is.
+  FOUNDATION_RUNTIME_KEY_FILE  Where the key file (this machine's credential) is.
 `;
 
 async function main() {
@@ -157,12 +172,14 @@ async function main() {
       if (names.some(item => item.as === output.as)) throw new Error('Output needs a different environment variable from every input.');
     }
   }
-  let call, connectTo, name;
-  if (action === 'connect') {
+  let call, serverGiven, name;
+  if (action === 'init') {
     const parsed = parseArgs({ args, options: { name: { type: 'string' } }, strict: true, allowPositionals: true });
-    if (parsed.positionals.length > 1) throw new Error('Usage: connect [<url>] [--name <name>]');
-    connectTo = parsed.positionals[0];
+    if (parsed.positionals.length > 1) throw new Error('Usage: init [<url>] [--name <name>]');
+    serverGiven = parsed.positionals[0];
     name = parsed.values.name;
+  } else if (action === 'join') {
+    if (args.length) throw new Error('Usage: join');
   } else if (action === 'api') {
     const parsed = parseArgs({ args, options: { json: { type: 'string' }, from: { type: 'string' }, type: { type: 'string' } }, strict: true, allowPositionals: true });
     if (parsed.positionals.length !== 2 || !/^(GET|POST|PUT|DELETE|PATCH)$/.test(parsed.positionals[0]) || !parsed.positionals[1].startsWith('/')) {
@@ -174,13 +191,34 @@ async function main() {
     const content = parsed.values.from !== undefined ? await readFile(parsed.values.from) : parsed.values.json !== undefined ? Buffer.from(parsed.values.json) : method === 'GET' ? undefined : Buffer.from('{}');
     call = { method, target: parsed.positionals[1], body: content,
       type: parsed.values.type || (parsed.values.from !== undefined ? 'application/octet-stream' : 'application/json') };
+  } else if (action === 'keep') {
+    const parsed = parseArgs({ args, options: { from: { type: 'string' } }, strict: true, allowPositionals: true });
+    if (parsed.positionals.length !== 1 || parsed.values.from === undefined) throw new Error('Usage: keep <name> --from <file>');
+    const content = await readFile(parsed.values.from);
+    if (!content.length || content.length > 1024 * 1024) throw new Error('A secret must contain 1 byte to 1MB.');
+    call = { name: parsed.positionals[0], body: content };
+  } else if (action === 'read') {
+    if (args.length !== 1) throw new Error('Usage: read <name>');
+    call = { name: args[0] };
+  } else if (action === 'token') {
+    if (args.length) throw new Error('Usage: token');
   } else if (!(action === 'exec' && (names.length || output) && command.length)) {
-    throw new Error('Usage: connect [<url>] [--name <name>] | exec [<ENV>=<name> ... | --inputs <json>] [--output <json>] -- <command> [args...] | api <method> </path> [--json <body>] [--from <file>]');
+    throw new Error('Usage: init [<url>] [--name <name>] | join | token | exec [<ENV>=<name> ... | --inputs <json>] [--output <json>] -- <command> [args...] | keep <name> --from <file> | read <name> | api <method> </path> [--json <body>] [--from <file>]');
   }
-  const url = serverUrl(connectTo ?? configured);
+  const url = serverUrl(serverGiven ?? configured);
   const keyPath = process.env.FOUNDATION_RUNTIME_KEY_FILE || join(homedir(), '.local', 'state', 'foundation', createHash('sha256').update(url.origin).digest('hex').slice(0, 24) + (agentName ? '-' + agentName.toLowerCase().replace(/[^a-z0-9]+/g, '-') : '') + '.key');
   const publicSpec = action === 'api' && call.method === 'GET' && call.target === '/openapi.json';
-  let token = publicSpec ? null : await readKey(keyPath, { missingOk: action === 'connect' });
+  let key = publicSpec ? null : await readKey(keyPath, { missingOk: action === 'init' }), token = key?.token ?? null;
+  // The credential proves this machine for an hour at a time: the challenge is answered for the server actually reached.
+  async function prove() {
+    const begin = await fetch(url.origin + '/v1/session', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ kind: 'webauthn' }), redirect: 'error', signal: AbortSignal.timeout(30_000) });
+    const { options } = await begin.json();
+    const response = await fetch(url.origin + '/v1/session', { method: 'PUT', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ kind: 'webauthn', credential: answer(options, key.credential, url.origin), session: 'token' }), redirect: 'error', signal: AbortSignal.timeout(30_000) });
+    const proven = await response.json();
+    if (!response.ok || typeof proven.token !== 'string') throw new Error('Foundation did not accept this machine\'s credential (' + response.status + ', ' + (proven.error?.code || 'unknown') + ').');
+    return proven.token;
+  }
   async function send(target, payload, { accept, method = 'POST', type = 'application/json' } = {}) {
     const response = await fetch(url.origin + target, { method, headers: { authorization: 'Bearer ' + token, ...(payload === undefined ? {} : { 'content-type': type }) },
       body: payload === undefined ? undefined : type === 'application/json' ? JSON.stringify(payload) : payload, redirect: 'error', signal: AbortSignal.timeout(30_000) });
@@ -188,7 +226,35 @@ async function main() {
     if (!response.ok && !accept?.(data)) throw new Error('Foundation request failed (' + response.status + ', ' + (data.error?.code || 'unknown') + '). ' + (data.error?.message || 'Check the connection and runtime permission.'));
     return data;
   }
-  // One request, with the key attached and the answer printed as it came. Nothing here knows the endpoints.
+  // A key file holding an issued access key: register a WebAuthn credential with it, and keep the credential instead.
+  // A lent machine's key stays as it is; it ends with the machine.
+  async function upgrade(label) {
+    const me = await send('/v1/principals/me', undefined, { method: 'GET' });
+    if (me.key?.environment) return;
+    const { options } = await send('/v1/principals/' + encodeURIComponent(me.principal.id) + '/credentials', { kind: 'webauthn' });
+    const made = createCredential(options, url.origin);
+    await send('/v1/principals/' + encodeURIComponent(me.principal.id) + '/credentials', { kind: 'webauthn', name: label, credential: made.response }, { method: 'PUT' });
+    await writeKey(keyPath, JSON.stringify({ webauthn_credential: made.credential }), !process.env.FOUNDATION_RUNTIME_KEY_FILE);
+    key = { credential: made.credential };
+  }
+  // This machine's own key, made and published once it is a principal here: what is sealed for it opens with this.
+  // A key published elsewhere for this principal stays as it is; then nothing sealed for it opens here.
+  async function publishKey() {
+    if (key.own) return;
+    const made = generateKey();
+    const published = await send('/v1/principals/me/key', { public_key: made.publicKey.toString('base64url') }, { method: 'PUT', accept: data => data.error?.code === 'key_exists' });
+    if (published.error) return;
+    key.own = { private_key: made.privateKey.toString('base64url') };
+    await writeKey(keyPath, JSON.stringify({ webauthn_credential: key.credential, key: key.own }), !process.env.FOUNDATION_RUNTIME_KEY_FILE);
+  }
+  if (key?.token && action !== 'init') { await upgrade(hostname() + ' の ' + (agentName || 'AI')); }
+  // A credential this server no longer knows leaves initialising again; anything else needs it.
+  if (key?.credential) {
+    try { token = await prove(); await publishKey(); }
+    catch (error) { if (action !== 'init') throw error; key = null; token = null; }
+  }
+  if (action === 'token') { console.log(token); return; }
+  // One request, as this machine, and the answer printed as it came. Nothing here knows the endpoints.
   if (action === 'api') {
     if (!publicSpec && !/[?&]as=/.test(call.target)) {
       const me = await send('/v1/principals/me', undefined, { method: 'GET', accept: () => true });
@@ -202,25 +268,52 @@ async function main() {
     if (!response.ok) process.exitCode = 1;
     return;
   }
-  // Asking the owner to approve this key. The key itself is never printed: it stays in the file.
-  // A key the owner already approved has nothing to ask; connecting again only changes which server is remembered.
-  if (action === 'connect') {
-    // A key someone already accepted has nothing to ask; connecting again only changes which server is remembered.
-    // No key, or one this server does not know: become a principal there first, and keep what it issues.
+  // Becoming a principal here: a key this server knows has nothing to make; initialising again only changes which
+  // server is remembered. The key itself is never printed: it stays in the file.
+  if (action === 'init') {
     const wanted = name ?? hostname() + ' の ' + (agentName || 'AI');
     let me = null;
     if (token) me = await send('/v1/principals/me', undefined, { method: 'GET', accept: data => data.error?.code === 'not_approved' });
     if (!token || me?.error) {
-      const response = await fetch(url.origin + '/v1/principals', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name: wanted }), redirect: 'error', signal: AbortSignal.timeout(30_000) });
-      const made = await response.json();
-      if (!response.ok || !/^fdn_[A-Za-z0-9_-]{43}$/.test(made.token ?? '')) throw new Error('Foundation did not issue a key (' + response.status + ', ' + (made.error?.code || 'unknown') + ').');
-      await writeKey(keyPath, made.token, !process.env.FOUNDATION_RUNTIME_KEY_FILE);
-      token = made.token; me = null;
-    }
-    const answer = me?.acts_for?.length ? null : await send('/v1/requests', { authorization_details: [{ type: 'relation', relation: 'actor' }] });
-    if (connectTo !== undefined) await saveUrl(url.origin);
-    console.log(answer === null ? 'Already approved on ' + url.origin + '.' : JSON.stringify(answer, null, 2));
-    console.log('\nKey file: ' + keyPath + '\nServer: ' + url.origin + (connectTo !== undefined ? ' (saved to ' + configPath() + ')' : '') + '\nEverything else is HTTP: Authorization: Bearer <the contents of that file>');
+      // No key, or one this server does not know: a WebAuthn credential made here, proven by nobody, makes this machine a
+      // principal there, of nobody's - the same call a browser's passkey makes.
+      key = null; me = null;
+      const post = (method, payload) => fetch(url.origin + '/v1/principals', { method, headers: { 'content-type': 'application/json' }, body: JSON.stringify(payload), redirect: 'error', signal: AbortSignal.timeout(30_000) });
+      const begun = await post('POST', { kind: 'webauthn', name: wanted });
+      const { options, error } = await begun.json();
+      if (!begun.ok) throw new Error('Foundation did not begin a credential (' + begun.status + ', ' + (error?.code || 'unknown') + ').');
+      const made = createCredential(options, url.origin);
+      const done = await post('PUT', { kind: 'webauthn', name: wanted, principal_name: wanted, credential: made.response, session: 'token' });
+      const became = await done.json();
+      if (!done.ok || typeof became.token !== 'string') throw new Error('Foundation did not accept this machine\'s credential (' + done.status + ', ' + (became.error?.code || 'unknown') + ').');
+      key = { credential: made.credential }; token = became.token;
+      await writeKey(keyPath, JSON.stringify({ webauthn_credential: key.credential }), !process.env.FOUNDATION_RUNTIME_KEY_FILE);
+      await publishKey();
+    } else if (key?.token) { await upgrade(wanted); token = await prove(); await publishKey(); }
+    if (serverGiven !== undefined) await saveUrl(url.origin);
+    if (!me) me = await send('/v1/principals/me', undefined, { method: 'GET' });
+    console.log(JSON.stringify({ principal: me.principal, acts_for: me.acts_for ?? [] }, null, 2));
+    console.log('\nKey file: ' + keyPath + '\nServer: ' + url.origin + (serverGiven !== undefined ? ' (saved to ' + configPath() + ')' : '') + '\nTo act for someone: foundation join\nEverything else is HTTP: Authorization: Bearer $(foundation token)');
+    return;
+  }
+  // Asking a person to make this machine their agent. One they already approved has nothing to ask.
+  if (action === 'join') {
+    const me = await send('/v1/principals/me', undefined, { method: 'GET', accept: data => data.error?.code === 'not_approved' });
+    if (me.acts_for?.length) { console.log('Already approved on ' + url.origin + '.'); return; }
+    const answer = await send('/v1/requests', { authorization_details: [{ type: 'relation', relation: 'agent' }] });
+    console.log(JSON.stringify(answer, null, 2));
+    return;
+  }
+  // Reading a secret this machine was handed an envelope for: its own, or one shown to it along a line.
+  if (action === 'read') {
+    if (!key.own) throw new Error('This machine has no key of its own here, so nothing sealed for it can be opened.');
+    const own = await send('/v1/resources?kind=secret&name=' + encodeURIComponent(call.name), undefined, { method: 'GET', accept: () => true });
+    const resource = own.resource ?? (await send('/v1/resources?shown=me', undefined, { method: 'GET' })).resources.find(item => item.kind === 'secret' && item.name === call.name);
+    if (!resource) throw new Error('No secret named ' + JSON.stringify(call.name) + ' is kept by this machine or shown to it.');
+    const kept = await send('/v1/resources/' + resource.id + '/content', undefined, { method: 'GET' });
+    if (!kept.envelope) throw new Error('No envelope was made for this machine: it may read about this secret, but was not handed its key.');
+    const contentKey = openEnvelope(Buffer.from(kept.envelope, 'base64url'), Buffer.from(key.own.private_key, 'base64url'));
+    process.stdout.write(openContent(contentKey, Buffer.from(kept.content, 'base64url')));
     return;
   }
   // Nothing runs before someone has accepted this key: a key that acts for nobody reaches only its own empty resources,
@@ -232,13 +325,49 @@ async function main() {
   if (!own && !current.acts_for?.length) throw new Error('Foundation request failed (401, not_approved). This key acts for nobody yet' + (current.requests?.[0] ? '; it is waiting for approval at ' + current.requests[0].verification_uri : '') + '.');
   // Whose resources a run reaches: the one this key acts for, the one named when it acts for several, or its own.
   const acting = current.acts_for ?? [];
-  const holder = process.env.FOUNDATION_AS || (acting.length === 1 ? acting[0] : null);
-  if (!holder && acting.length > 1) throw new Error('This key acts for several principals. Set FOUNDATION_AS=<principal id> to say which one this run is for.');
-  const forHolder = target => holder ? target + (target.includes('?') ? '&' : '?') + 'as=' + encodeURIComponent(holder) : target;
+  const owner = process.env.FOUNDATION_AS || (acting.length === 1 ? acting[0] : null);
+  if (!owner && acting.length > 1) throw new Error('This key acts for several principals. Set FOUNDATION_AS=<principal id> to say which one this run is for.');
+  const forHolder = target => owner ? target + (target.includes('?') ? '&' : '?') + 'as=' + encodeURIComponent(owner) : target;
+  // A secret is sealed here, with a key of its own, for each of the owner's recipients: the server keeps what it
+  // cannot open. This machine is not among them; it places the bytes and does not read them back.
+  const sealedFor = async bytes => {
+    const { recipients } = await send('/v1/principals/' + encodeURIComponent(owner || 'me') + '/recipients', undefined, { method: 'GET' });
+    if (!Array.isArray(recipients) || !recipients.length) throw new Error('Nobody can open a secret kept for this owner yet: the owner needs a key, or Foundation needs to act for them.');
+    const contentKey = newContentKey();
+    return { content: sealContent(contentKey, bytes).toString('base64url'), envelopes: Object.fromEntries(recipients.map(item => [item.principal_id, seal(contentKey, Buffer.from(item.public_key, 'base64url')).toString('base64url')])) };
+  };
+  if (action === 'keep') {
+    const saved = await send(forHolder('/v1/resources?kind=secret&name=' + encodeURIComponent(call.name)), await sealedFor(call.body), { method: 'PUT' });
+    try { await send('/v1/principals/me/relations', { relation: 'editor', object_type: 'resource', object_id: saved.resource.id }, { method: 'DELETE' }); } catch {}
+    console.log(JSON.stringify(saved));
+    return;
+  }
+  // A secret this machine was handed an envelope for is opened here, with its own key: the server keeps what it cannot
+  // open, and nobody else has to be able to open it for this machine to use it. Everything else - a connection, a secret
+  // not handed to this machine - is asked of the server, which hands over only what Foundation may open for the owner.
+  const handed = { environment: {}, files: [] };
+  let asked = names;
+  if (key.own && names.some(item => typeof item.name === 'string')) {
+    const shown = owner ? (await send('/v1/resources?shown=me', undefined, { method: 'GET', accept: () => true })).resources ?? [] : [];
+    asked = [];
+    for (const item of names) {
+      let resource = null;
+      if (typeof item.name === 'string') {
+        resource = owner ? shown.find(row => row.kind === 'secret' && row.name === item.name && row.owner_id === owner)
+          : (await send('/v1/resources?kind=secret&name=' + encodeURIComponent(item.name), undefined, { method: 'GET', accept: () => true })).resource;
+      }
+      const kept = resource ? await send('/v1/resources/' + resource.id + '/content', undefined, { method: 'GET', accept: () => true }) : null;
+      if (!kept?.envelope) { asked.push(item); continue; }
+      const bytes = openContent(openEnvelope(Buffer.from(kept.envelope, 'base64url'), Buffer.from(key.own.private_key, 'base64url')), Buffer.from(kept.content, 'base64url'));
+      if (item.filename !== undefined) handed.files.push({ env: item.as, filename: item.filename, content: bytes.toString('base64'), encoding: 'base64' });
+      else handed.environment[item.as] = bytes.toString('utf8');
+    }
+  }
   let injection;
-  if (names.length) ({ injection } = await send(forHolder('/v1/injections'), { names }));
+  if (asked.length) ({ injection } = await send(forHolder('/v1/injections'), { names: asked }));
   else injection = { environment: {}, files: [] };
   if (!injection || typeof injection.environment !== 'object' || !Array.isArray(injection.files)) throw new Error('Foundation returned an invalid injection.');
+  injection = { environment: { ...injection.environment, ...handed.environment }, files: [...injection.files, ...handed.files] };
   // What each of them sets is the server's to say; this applies it and refuses anything it may not set.
   const environment = { ...process.env };
   delete environment.FOUNDATION_RUNTIME_KEY_FILE;
@@ -266,7 +395,7 @@ async function main() {
       }
     }
   };
-  const recovery = () => 'Foundation could not confirm the output was saved. The private output file is retained for recovery: ' + outputPath + '\nRetry with foundation api PUT "/v1/resources?kind=secret&name=<URL-encoded-name>" --from <file>, then remove that recovery file.';
+  const recovery = () => 'Foundation could not confirm the output was saved. The private output file is retained for recovery: ' + outputPath + '\nRetry with foundation keep <name> --from <file>, then remove that recovery file.';
   process.once('exit', cleanup);
   for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.once(signal, () => {
     interrupted = true;
@@ -305,9 +434,9 @@ async function main() {
       retainOutput = true;
       // The command wrote it; the agent never saw it, and keeps it that way: the line drawn for the one who kept it is declined.
       let saved;
-      try { saved = await send(forHolder('/v1/resources?kind=secret&name=' + encodeURIComponent(output.name)), bytes, { method: 'PUT', type: 'application/octet-stream' }); }
+      try { saved = await send(forHolder('/v1/resources?kind=secret&name=' + encodeURIComponent(output.name)), await sealedFor(bytes), { method: 'PUT' }); }
       catch { throw new Error(recovery()); }
-      try { await send('/v1/relations', { relation: 'editor', object_type: 'resource', object_id: saved.resource.id }, { method: 'DELETE' }); } catch {}
+      try { await send('/v1/principals/me/relations', { relation: 'editor', object_type: 'resource', object_id: saved.resource.id }, { method: 'DELETE' }); } catch {}
       retainOutput = false;
       console.error('Saved output as ' + JSON.stringify(output.name) + '.');
     }

package/webauthn.mjs

@@ -0,0 +1,44 @@
+import { createHash, generateKeyPairSync, createPrivateKey, randomBytes, sign } from 'node:crypto';
+
+// A WebAuthn authenticator in software, for wherever there is no browser: it makes a credential and answers challenges
+// with it, writing what a browser writes. The origin it signs is the one it is actually talking to, so a challenge
+// relayed from elsewhere is refused there. It reports the user present - the principal running it asked - and never
+// verified, since it checks no face, fingerprint or PIN.
+const b64 = bytes => Buffer.from(bytes).toString('base64url');
+const sha256 = data => createHash('sha256').update(data).digest();
+const PRESENT = 0x01, ATTESTED = 0x40;
+
+// Just enough CBOR (RFC 8949) for an attestation object and a COSE key: maps, byte and text strings, small integers.
+function cbor(value) {
+  const head = (major, length) => length < 24 ? Buffer.from([major << 5 | length])
+    : length < 256 ? Buffer.from([major << 5 | 24, length]) : Buffer.from([major << 5 | 25, length >> 8, length & 255]);
+  if (Number.isInteger(value)) return value >= 0 ? head(0, value) : head(1, -1 - value);
+  if (Buffer.isBuffer(value)) return Buffer.concat([head(2, value.length), value]);
+  if (typeof value === 'string') { const text = Buffer.from(value); return Buffer.concat([head(3, text.length), text]); }
+  const entries = value instanceof Map ? [...value] : Object.entries(value);
+  return Buffer.concat([head(5, entries.length), ...entries.flatMap(([key, item]) => [cbor(key), cbor(item)])]);
+}
+const counter = count => { const bytes = Buffer.alloc(4); bytes.writeUInt32BE(count); return bytes; };
+const clientData = (type, challenge, origin) => Buffer.from(JSON.stringify({ type, challenge, origin, crossOrigin: false }));
+
+// Makes a credential for the options a server gave. Returns what to send back, and what to keep: the credential's id, its
+// private key, and whose it is.
+export function createCredential(options, origin) {
+  const { privateKey, publicKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' });
+  const point = publicKey.export({ format: 'jwk' }), id = randomBytes(32);
+  const cose = cbor(new Map([[1, 2], [3, -7], [-1, 1], [-2, Buffer.from(point.x, 'base64url')], [-3, Buffer.from(point.y, 'base64url')]]));
+  const authData = Buffer.concat([sha256(options.rp.id), Buffer.from([PRESENT | ATTESTED]), counter(0), Buffer.alloc(16),
+    Buffer.from([id.length >> 8, id.length & 255]), id, cose]);
+  const response = { id: b64(id), rawId: b64(id), type: 'public-key', clientExtensionResults: {},
+    response: { clientDataJSON: b64(clientData('webauthn.create', options.challenge, origin)), attestationObject: b64(cbor({ fmt: 'none', attStmt: {}, authData })), transports: [] } };
+  return { response, credential: { id: b64(id), user: options.user.id, private_key: privateKey.export({ format: 'jwk' }) } };
+}
+
+// Answers a sign-in challenge with a kept credential.
+export function answer(options, credential, origin) {
+  const data = clientData('webauthn.get', options.challenge, origin);
+  const authData = Buffer.concat([sha256(options.rpId), Buffer.from([PRESENT]), counter(0)]);
+  const signature = sign('sha256', Buffer.concat([authData, sha256(data)]), createPrivateKey({ key: credential.private_key, format: 'jwk' }));
+  return { id: credential.id, rawId: credential.id, type: 'public-key', clientExtensionResults: {},
+    response: { clientDataJSON: b64(data), authenticatorData: b64(authData), signature: b64(signature), userHandle: credential.user } };
+}