@tomato414941/foundation 0.1.0 → 0.3.0

package/guide.mjs

@@ -26,24 +26,33 @@ export function guide(connectors) {
     '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.', '',
-    'YOUR KEY',
-    '   Your key is a secret of your own making: 43 URL-safe base64 characters after `fdn_`. Generate one, keep it private,',
+    '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.',
-    '   POST /v1/keys  {"name": "<what to call you>"}   with your key as the bearer.',
-    '     Returns verification_uri and confirmation_code. Give the owner both; they open the URL and type the code.',
-    '     Until they do, every other call answers 401 not_approved. Retry GET /v1/keys/current every few seconds. Do not hammer it.',
-    '   GET /v1/keys/current    your request and what happened at its page; once approved, also who you are (key).',
-    '     Approval also has kind=approve, status=done and result.key_id. A current key, not request completion, authorizes use.',
-    '     Revoking a key stops Foundation access; credentials already obtained must be revoked at their provider.',
-    '   PATCH /v1/keys/current {"name"}    DELETE /v1/keys/current    cancels the request, or revokes your approved key.', '',
+    '   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.',
+    '   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>.',
+    '   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.',
+    '   Everything kept has an id, shown in every listing. The holder shows one thing to another principal with',
+    '   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/secrets?name=<name>&secret=true    body: raw bytes, up to 1MB. The same exact name replaces that value.',
-    '     secret=true blocks direct GET by an access key. The owner can read it; authorized delivery can still return it.',
-    '     This is not a boundary against an agent with the approved key. Do not print delivered values into its context.',
-    '   GET /v1/secrets    names, sizes, read permissions and timestamps, not contents.',
-    '   GET /v1/secrets?prefix=<literal prefix>   optional case-sensitive text filtering, not a directory.',
-    '   GET /v1/secrets?name=<name>               bytes, as written; 403 write_only for a secret.',
-    '   DELETE /v1/secrets?name=<name>',
+    '   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.',
+    '     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.',
+    '     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.',
     '   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.', '',
@@ -56,7 +65,7 @@ export function guide(connectors) {
     '     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/secrets?name=<name>, above.',
+    '1. Put it there yourself. Anything you obtained or wrote: PUT /v1/holdings?kind=secret&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}',
@@ -64,7 +73,7 @@ export function guide(connectors) {
     '     fields[].label     what they are being asked for, in their language. It titles the screen and names the field.',
 
     '     fields[].site      the page where they make it, offered as a link',
-    '     fields[].secret    false lets you read it back afterwards; the default is that you cannot',
+    '     fields[].readable  true asks to read it back afterwards (a viewer line); the default is that you cannot',
     '     fields[].multiline true for something like a PEM',
     '     fields[].replace   true to put the value in place of the one already kept under that exact name (rotation).',
     '                     Refused at creation: name_taken when the name exists and replace is not declared, name_missing',
@@ -103,11 +112,12 @@ export function guide(connectors) {
     '   Request feedback expires with the request. A done result is a connection_id or the names saved at completion.',
     '   Why a registration failed: invalid_values (wrong shape) / invalid_credential (the connector would not take it) /',
     '   reconnect_required (the service rejected it) / already_connected. A key approval shows its own events at',
-    '   GET /v1/keys/current: confirmation_required (a wrong code) / confirmation_locked (5 tries).', '',
+    '   GET /v1/requests/<id>: confirmation_required (a wrong code) / confirmation_locked (5 tries).', '',
     'A PLACE FOR FILES (object storage the owner did not have to sign up for)',
-    '   PUT /v1/objects/<key>      body is the bytes; the Content-Type you send is what a reader gets back. Up to 25MB.',
-    '   GET /v1/objects/<key>      the bytes. DELETE removes it. GET /v1/objects?prefix=<p>&cursor=<c> lists what is there.',
-    '   POST /v1/objects/<key>/link {"minutes":n}   a time-limited URL anyone can read, for a thing that only takes a URL.',
+    '   PUT /v1/holdings?kind=object&name=<key>   body is the bytes; the Content-Type you send is what a reader gets back. Up to 25MB.',
+    '   GET /v1/holdings?kind=object&prefix=<p>   lists what is there, with ids. &name=<key> finds one.',
+    '   GET /v1/holdings/<id>/content   the bytes. PUT writes them. DELETE /v1/holdings/<id> removes it. PATCH renames it.',
+    '   POST /v1/holdings/<id>/link {"minutes":n}   a time-limited URL anyone can read, for a thing that only takes a URL.',
     '   Keys look like a path (a/b/c.txt) but name one whole object: no renaming, no directories, no partial reads or writes.',
     '   This is not a filesystem. If the owner needs one, they need a machine to mount it on.',
     '   Where the bytes live is the owner\'s business: a space lent to them now, a bucket of their own later. Nothing you call changes.', '',
@@ -139,7 +149,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 with secret=true, then removes the temporary file.',
+    '     After exit 0, saves the file bytes 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.1.0",
+  "version": "0.3.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

@@ -206,20 +206,22 @@ async function main() {
   // 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') {
-    const answer = await send('/v1/keys', { name: name ?? hostname() + ' の ' + (agentName || 'AI') }, { accept: data => data.error?.code === 'already_approved' });
+    // A key someone already accepted has nothing to ask; connecting again only changes which server is remembered.
+    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 (connectTo !== undefined) await saveUrl(url.origin);
-    console.log(answer.error ? 'Already approved on ' + url.origin + '.' : JSON.stringify(answer, null, 2));
+    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>');
     return;
   }
-  // Even output-only commands need an approved key before they start an external login.
+  // Nothing runs before someone has accepted this key: a key that acts for nobody reaches only its own empty holdings,
+  // 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 : '') + '.');
   let delivery;
   if (names.length) ({ delivery } = await send('/v1/deliveries', { names }));
-  else {
-    const current = await send('/v1/keys/current', undefined, { method: 'GET' });
-    if (!current.key) throw new Error('Foundation request failed (401, not_approved). This key is waiting for approval at ' + current.request?.verification_uri + '.');
-    delivery = { environment: {}, files: [] };
-  }
+  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.
   const environment = { ...process.env };
@@ -248,7 +250,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/secrets?name=<URL-encoded-name>&secret=true" --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=secret&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;
@@ -285,8 +287,11 @@ async function main() {
     if (output && process.exitCode === 0) {
       const bytes = await outputBytes(outputPath);
       retainOutput = true;
-      try { await send('/v1/secrets?name=' + encodeURIComponent(output.name) + '&secret=true', bytes, { method: 'PUT', type: 'application/octet-stream' }); }
+      // 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' }); }
       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;
       console.error('Saved output as ' + JSON.stringify(output.name) + '.');
     }