@tomato414941/foundation 0.3.0 → 0.5.0

package/guide.mjs

@@ -19,24 +19,28 @@ function connectorLines(connectors) {
 }
 
 export function guide(connectors) {
-  return ['Foundation keeps user-controlled values and objects, and runs explicitly requested built-in functions.',
-    'A saved name identifies bytes. It does not select a service, a connection, a function, or an environment variable.',
-    'Storage never invokes a provider: a value saved from a function is an independent snapshot, not a live connection.', '',
+  return ['Foundation holds, for each principal, grants and objects, and runs explicitly requested built-in functions.',
+    'A grant is what its holder let Foundation do at a provider: a credential they handed over (given), a consent they gave',
+    'at the service (authorized), or a role they made for Foundation to assume (delegated). An object is bytes they placed here.',
+    'Reading never reaches a provider. Delivering a grant derives what it yields now: a given one its bytes, the others what',
+    'their connector obtains. A name is the holder\'s word for a thing; it decides no service, function or variable.', '',
     'Everything below is HTTP with your approved key: Authorization: Bearer fdn_...',
     'Nothing here needs a shell. With one, use foundation api to attach the key and foundation exec to deliver values',
     'to a command. api prints responses: use function save options when output should not enter your context.',
     'Never ask the owner to paste passwords, keys or tokens into chat. Use a storage request or OAuth URL instead.', '',
     'WHO YOU ARE',
     '   Everything that comes to Foundation is a principal: a person, an AI, an app. You are one, and your key is what',
-    '   proves it: a secret of your own making, 43 URL-safe base64 characters after `fdn_`. Generate one, keep it private,',
-    '   and never print it. If you can write a private file, keep it there; otherwise keep it wherever your secrets go.',
+    '   proves it. Foundation issues it, once, and shows it once: keep it private and never print it. If you can write a',
+    '   private file, keep it there; otherwise keep it wherever your secrets go.',
+    '   POST /v1/principals  {"name": "<what to call you>"}   with no credential at all. Makes you, and answers with token.',
     '   What you may reach follows from lines between principals: whoever you act for (actor), whoever made you (owner).',
     '   POST /v1/requests  {"kind": "actor", "input": {"name": "<what to call you>"}}   with your key as the bearer.',
     '     Asks whoever opens it to let you act for them. Returns verification_uri and confirmation_code. Give the person',
-    '     both; they open the URL and type the code. Until they do you act for nobody: everything below answers as',
-    '     your own, empty, holdings. Retry GET /v1/principals/me every few seconds and look at acts_for. Do not hammer it.',
+    '     both; they open the URL and type the code. Until they do you act for nobody. Retry GET /v1/principals/me every',
+    '     few seconds and look at acts_for. Do not hammer it.',
     '   GET /v1/principals/me    who you are: principal, acts_for (whom you act for), owners, credentials, your open requests.',
-    '     Acting for exactly one principal, their holdings are what the calls below reach. For several, name one: ?as=<id>.',
+    '     Every call below reaches your own holdings unless you name whose: ?as=<id of one you act for>. The foundation CLI',
+    '     and the MCP tool add ?as= for you when you act for exactly one; over raw HTTP, add it yourself.',
     '   PATCH /v1/principals/me {"name"}    DELETE /v1/principals/me    a new name; leaving (your key stops working).',
     '   GET /v1/requests/<id>   one of your requests and what happened at its page (events).   DELETE cancels it.',
     '   GET /v1/relations   every line you are on.   GET /v1/records   what was done in your name or to you.',
@@ -44,28 +48,36 @@ export function guide(connectors) {
     '   POST /v1/relations {"subject":"<principal id>","relation":"viewer"|"editor","object_type":"holding","object_id":"<id>"}   DELETE takes it back.',
     '   GET /v1/holdings   what others have shown you.   GET /v1/holdings/<id>   one thing, whoever holds it.',
     '   GET /v1/holdings/<id>/content   reads it; PUT writes it, as editor. Lines point at the id, so renaming changes nothing.', '',
-    'WHAT IS KEPT',
-    '   PUT /v1/holdings?kind=secret&name=<name>    body: raw bytes, up to 1MB. The same exact name replaces that value; the answer carries its id.',
+    'GRANTS (what the holder let Foundation use)',
+    '   PUT /v1/holdings?kind=grant&name=<name>[&provider=<id>&tags=<a,b>]    body: raw bytes, up to 1MB. A given grant:',
+    '     the same exact name replaces that value; the answer carries its id. provider names the service it belongs to',
+    '     (a short lowercase id: aws, stripe, github, ...); tags are the holder\'s words for grouping (a project, an',
+    '     environment). Both may be changed later. Set them when you know them: the owner sorts by them.',
     '     What you keep for the holder you may read back (an editor line is drawn for you). What the holder kept, or a',
-    '     connection handed over, you may deliver into a command but not read, unless the holder draws you a line.',
+    '     service authorized, you may deliver into a command but not read, unless the holder draws you a line.',
     '     Do not print delivered values into your context.',
-    '   GET /v1/holdings?kind=secret    ids, names, sizes and timestamps, not contents. &prefix=<literal prefix> narrows by text, not directory.',
-    '   GET /v1/holdings?kind=secret&name=<name>   the one thing by name: its id and metadata. 404 if no such name.',
-    '   GET /v1/holdings/<id>/content    bytes, as written; 403 forbidden without a line to it.   PUT writes them.',
-    '   PATCH /v1/holdings/<id> {"name"}    a new name for the same thing.   DELETE /v1/holdings/<id>   removes it.',
+    '   GET /v1/holdings?kind=grant    every grant: id, name, method (given / authorized / delegated), provider, tags, status;',
+    '     for a connected one also its service, facts and the variables it yields. &method= &provider= &tag= &prefix= narrow it.',
+    '   GET /v1/holdings?kind=grant&name=<name>   one given grant by name: its id and metadata. 404 if no such name.',
+    '   GET /v1/holdings/<id>/content    a given grant\'s bytes, as written; 403 forbidden without a line to it. PUT writes them.',
+    '     A connected grant has no content to read (405): what it yields is derived when delivered.',
+    '   PATCH /v1/holdings/<id> {"name","provider","tags"}    new words for the same thing.   DELETE /v1/holdings/<id>   removes a given one.',
     '   URL-encode the name. A name is any text, which is why it travels as a query and not as a path. Names are 1-200 characters without control characters; case, spaces, slashes and punctuation',
     '   remain literal. No normalization, hierarchy, service ownership or automatic renewal is inferred.',
     '   The owner can read, rename or delete any saved value. Stored copies survive OAuth disconnection.', '',
     'HANDING IT TO A COMMAND',
-    '   POST /v1/deliveries  {"names": [{"name": "build token", "as": "GH_TOKEN"}]}',
-    '     Each item is {name, as, filename?}. as is required: it names the environment variable, independently of name.',
+    '   POST /v1/deliveries  {"names": [{"name": "build token", "as": "GH_TOKEN"}, {"name": "<id of a connected grant>"}]}',
+    '     Each item is {name, as, filename?}. name is a given grant\'s name or any grant\'s id. For a given grant, as is',
+    '     required: it names the environment variable. A connected grant yields its connector\'s variables (see outputs);',
+    '     as may rename the one variable of a connector that has exactly one. Delivering a connected grant asks the service',
+    '     for a fresh credential when needed; expires_at says how long what came back is good.',
     '     filename makes the bytes a temporary file instead; as holds its local path. Use this for binary or multiline data.',
     '     Up to 16 inputs. Variables and filenames must be distinct; reserved system variables are refused.',
-    '     Returns delivery: {environment, files}. No provider check or refresh occurs; expiry of stored bytes is unknown.',
-    '     Calling this into an agent context exposes values. Use exec when the intent is to run a local command.', '',
+    '     Returns delivery: {environment, files}. Calling this into an agent context exposes values. Use exec when the intent',
+    '     is to run a local command.', '',
     'FILLING THE STORE',
     '',
-    '1. Put it there yourself. Anything you obtained or wrote: PUT /v1/holdings?kind=secret&name=<name>, above.',
+    '1. Put it there yourself. Anything you obtained or wrote: PUT /v1/holdings?kind=grant&name=<name>, above.',
     '',
     '2. ASKING THE OWNER, for what only they can fetch -- an API token, a key, a certificate they must go and create.',
     '   POST /v1/requests  {"kind":"store", "input":{"fields":[{...}]}, "purpose":"...", "steps":["..."], "valid_minutes":30}',
@@ -86,21 +98,18 @@ export function guide(connectors) {
     '   Give the owner the verification_uri (there is no code). When they finish, it is simply kept.',
     '   Ask for what the owner already holds. Never take it through the conversation and put it there yourself.',
     '',
-    '3. CONNECTING A SERVICE for later explicit credential processing. OAuth renewal state stays with the connection,',
-    '   separate from ordinary saved values. Connecting does not create named values.',
+    '3. CONNECTING A SERVICE, so that Foundation may obtain credentials there itself. What renews them stays with the',
+    '   grant, never in a value you can read. Connecting creates one grant, listed with the others.',
     ...connectorLines(connectors),
     '   POST /v1/requests  {"kind":"connect", "input":{"connector":"<id>"}, "purpose":"...", "valid_minutes":30}   Give the owner the verification_uri.',
+    '   A connector whose flow is "role" (aws.role) has the owner make a role for Foundation in their own console and',
+    '   paste its name; nothing of theirs is kept but that name, and each delivery obtains an hour of credentials.',
     '   Poll GET /v1/requests/<id> every few seconds until done; result.connection_id identifies the connection.',
-    '   GET /v1/connections   connection IDs, labels, provider details and available output identifiers.', '',
+    '   GET /v1/connections   the connected grants: ids, labels, service details and the variables each yields.',
+    '   To use one, deliver it (above) or bind it in http.request (below). Disconnecting removes the grant; what was',
+    '   already handed out stays where it went. Revoke at the provider if needed.', '',
     'FUNCTIONS',
-    '   GET /v1/functions   catalog of built-in operations and their invocation endpoints; no arbitrary-code runtime.',
-    '   POST /v1/functions/connection.credentials',
-    '     {"connection_id": "<id>", "save": {"<output identifier>": "<chosen saved name>"}}',
-    '     Checks or renews that connection and saves only the outputs you explicitly name. Returns saved metadata and',
-    '     actual expiry, without credential values. Existing values at those exact names are replaced atomically.',
-    '     Omit save to receive delivery directly. Prefer save when invoking from an AI tool; then use exec or http.request.',
-    '     Saving creates independent copies: subsequent reads never refresh them; invoke this function again when needed.',
-    '     Disconnecting stops future processing, not copies already saved or handed out. Revoke at the provider if needed.', '',
+    '   GET /v1/functions   catalog of built-in operations and their invocation endpoints; no arbitrary-code runtime.', '',
     'WHEN IT DOES NOT WORK',
     '   GET /v1/requests/<id>   one of your requests, and what happened at its page (events).',
     '   GET /v1/requests?status=pending   your requests. Several may be open at once (up to 10).',
@@ -124,12 +133,14 @@ export function guide(connectors) {
     'HTTPS REQUEST FUNCTION',
     '   POST /v1/functions/http.request  {"url": "https://api.example.com/v1/items", "method": "POST",',
     '     "headers": {"authorization": "Bearer {{foundation:token}}"}, "bindings": {"token": "build token"}, "body": "..."}',
-    '     Each placeholder identifies an input slot. bindings maps slots to exact saved names (including braces or spaces).',
-    '     Without bindings, a slot is itself a saved name. Inputs only in headers/body, never in the URL. Up to 8 inputs.',
-    '     body_encoding "base64" sends bytes without substitution. Input values are read as stored, never refreshed.',
+    '     Each placeholder identifies an input slot. bindings maps slots to grants: a given grant\'s exact name (including',
+    '     braces or spaces), or a connected grant\'s id (<id>#<VARIABLE> when it yields several). Without bindings, a slot',
+    '     is itself a name. Inputs only in headers/body, never in the URL. Up to 8 inputs. A bound connected grant is',
+    '     derived first, so its service may be asked for a fresh credential.',
+    '     body_encoding "base64" sends bytes without substitution.',
     '     Returns {response: {status, headers, body, body_encoding}}. Common echoes of input secrets are redacted;',
     '     do not treat redaction as protection against arbitrary transformations by an untrusted destination.',
-    '     Optional save: "<name>" stores the response body and returns only response status/headers and saved metadata.',
+    '     Optional save: "<name>" keeps the response body as a given grant and returns only status/headers and saved metadata.',
     '     Redirects are returned, not followed.',
     '     HTTPS on 443, public hostnames only, never this server or private networks. 1MB each way, 20 seconds, 30/minute.',
     '     No workflow, schedule or implicit execution: the caller chooses each invocation and each saved output.', '',
@@ -149,7 +160,7 @@ export function guide(connectors) {
     '     Use this instead of POST /v1/deliveries whenever the point is to run something.',
     `   foundation exec --output '{"name":"login config","as":"AUTH_FILE","filename":"auth.json"}' -- <command>`,
     '     Creates one empty private file and sets as to its path. Tell the command to write its authentication result there.',
-    '     After exit 0, saves the file bytes under the exact name, then removes the temporary file.',
+    '     After exit 0, keeps the file bytes as a given grant under the exact name, then removes the temporary file.',
     '     An existing value at that name is replaced. Output must be a private regular file containing 1 byte to 1MB.',
     '     May be combined with inputs, using a different environment variable. A failed command never saves its output.',
     '     If upload cannot be confirmed, exits with an error and reports the retained private file for recovery; inputs are',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomato414941/foundation",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Foundation CLI: make a key, and hand what is kept to a command without it passing through the agent.",
   "type": "module",
   "engines": {

package/runtime.mjs

@@ -3,7 +3,7 @@ import { open, mkdir, stat, lstat, mkdtemp, writeFile, chmod, readFile, rename }
 import { parseArgs } from 'node:util';
 import { rmSync, readdirSync, constants } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash } from 'node:crypto';
 import { homedir, hostname, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
@@ -21,21 +21,9 @@ import { guide } from './guide.mjs';
 // 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.
-async function runtimeKey(path, create, privateDirectory) {
-  if (create) {
-    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).');
-    }
-    let created;
-    try {
-      created = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
-      await created.writeFile('fdn_' + randomBytes(32).toString('base64url') + '\n');
-      await created.sync();
-    } catch (error) { if (error.code !== 'EEXIST') throw error; }
-    finally { await created?.close(); }
-  }
+// 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.
+async function readKey(path, { missingOk = false } = {}) {
   let handle;
   try {
     handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
@@ -45,11 +33,20 @@ async function runtimeKey(path, create, privateDirectory) {
     if (!/^fdn_[A-Za-z0-9_-]{43}$/.test(token)) throw new Error('Invalid runtime key file.');
     return token;
   } catch (error) {
-    if (error.code === 'ENOENT') 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 connect'); }
     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) {
+  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(); }
+}
 
 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,
@@ -110,7 +107,7 @@ Commands:
                                        Send one request to the Foundation API with the key attached.
   exec <ENV>=<name> [...] -- <command> [args...]
                                        Run a command with saved values in its environment.
-  exec --inputs '<json>' -- <command>  The same, with files or structured inputs.
+  exec --inputs '<json>' -- <command>  The same, with files, structured inputs, or a connected grant by id.
   exec --output '<json>' -- <command>  Also save a file the command writes.
   guide                                The API guide: what Foundation keeps, and how to ask it for things.
   version                              Print the version.
@@ -153,8 +150,10 @@ async function main() {
       if (at < 1) throw new Error('Specify the environment variable explicitly: ENV=name');
       return { name: value.slice(at + 1), as: value.slice(0, at) };
     });
-    if (!Array.isArray(names) || names.length > 16 || names.some(item => !item || typeof item.name !== 'string' || !item.name || !validEnvName(item.as))) throw new Error('Each input needs a name and a non-reserved environment variable in as.');
-    if (new Set(names.map(item => item.as)).size !== names.length) throw new Error('Each input needs a different environment variable.');
+    // A connected grant names its own variables, so an input may leave `as` out; a given one must say where it goes.
+    if (!Array.isArray(names) || names.length > 16 || names.some(item => !item || typeof item.name !== 'string' || !item.name || (item.as !== undefined && !validEnvName(item.as)))) throw new Error('Each input needs a name and, when given, a non-reserved environment variable in as.');
+    const chosen = names.map(item => item.as).filter(value => value !== undefined);
+    if (new Set(chosen).size !== chosen.length) throw new Error('Each input needs a different environment variable.');
     if (parsed.values.output !== undefined) {
       try { output = JSON.parse(parsed.values.output); } catch { throw new Error('--output must be a JSON object {name, as, filename}.'); }
       if (!output || Array.isArray(output) || typeof output !== 'object' || Object.keys(output).some(key => !['name', 'as', 'filename'].includes(key))) throw new Error('--output must be a JSON object {name, as, filename}.');
@@ -185,7 +184,7 @@ async function main() {
   }
   const url = serverUrl(connectTo ?? 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 token = await runtimeKey(keyPath, action === 'connect', !process.env.FOUNDATION_RUNTIME_KEY_FILE);
+  let token = await readKey(keyPath, { missingOk: action === 'connect' });
   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) });
@@ -195,6 +194,10 @@ async function main() {
   }
   // One request, with the key attached and the answer printed as it came. Nothing here knows the endpoints.
   if (action === 'api') {
+    if (!/[?&]as=/.test(call.target)) {
+      const me = await send('/v1/principals/me', undefined, { method: 'GET', accept: () => true });
+      if (me.acts_for?.length === 1) call.target += (call.target.includes('?') ? '&' : '?') + 'as=' + encodeURIComponent(me.acts_for[0].id);
+    }
     const response = await fetch(url.origin + call.target, { method: call.method, headers: { authorization: 'Bearer ' + token, ...(call.body === undefined ? {} : { 'content-type': call.type }) },
       ...(call.body === undefined ? {} : { body: call.body }), redirect: 'error', signal: AbortSignal.timeout(30_000) });
     const bytes = Buffer.from(await response.arrayBuffer());
@@ -207,9 +210,18 @@ async function main() {
   // 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.
+    const wanted = name ?? hostname() + ' の ' + (agentName || 'AI');
     let me = null;
-    try { me = await send('/v1/principals/me', undefined, { method: 'GET' }); } catch {}
-    const answer = me?.acts_for?.length ? null : await send('/v1/requests', { kind: 'actor', input: { name: name ?? hostname() + ' の ' + (agentName || 'AI') } });
+    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', { kind: 'actor', input: { name: wanted } });
     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>');
@@ -219,8 +231,12 @@ async function main() {
   // and the person it asked has yet to answer.
   const current = await send('/v1/principals/me', undefined, { method: 'GET' });
   if (!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 holdings a run reaches: the one this key acts for, or the one named when it acts for several.
+  const holder = process.env.FOUNDATION_AS || (current.acts_for.length === 1 ? current.acts_for[0].id : null);
+  if (!holder) 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 => target + (target.includes('?') ? '&' : '?') + 'as=' + encodeURIComponent(holder);
   let delivery;
-  if (names.length) ({ delivery } = await send('/v1/deliveries', { names }));
+  if (names.length) ({ delivery } = await send(forHolder('/v1/deliveries'), { names }));
   else delivery = { environment: {}, files: [] };
   if (!delivery || typeof delivery.environment !== 'object' || !Array.isArray(delivery.files)) throw new Error('Foundation returned an invalid delivery.');
   // What each of them sets is the server's to say; this applies it and refuses anything it may not set.
@@ -250,7 +266,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/holdings?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 api PUT "/v1/holdings?kind=grant&name=<URL-encoded-name>" --from <file>, then remove that recovery file.';
   process.once('exit', cleanup);
   for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.once(signal, () => {
     interrupted = true;
@@ -289,7 +305,7 @@ 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('/v1/holdings?kind=secret&name=' + encodeURIComponent(output.name), bytes, { method: 'PUT', type: 'application/octet-stream' }); }
+      try { saved = await send(forHolder('/v1/holdings?kind=grant&name=' + encodeURIComponent(output.name)), bytes, { method: 'PUT', type: 'application/octet-stream' }); }
       catch { throw new Error(recovery()); }
       try { await send('/v1/relations', { relation: 'editor', object_type: 'holding', object_id: saved.holding.id }, { method: 'DELETE' }); } catch {}
       retainOutput = false;