@tomato414941/foundation 0.4.0 → 0.5.1

package/guide.mjs

@@ -19,9 +19,11 @@ 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.',
@@ -46,28 +48,34 @@ 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>    body: raw bytes, up to 1MB. A given grant: 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.',
+    '     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), status;',
+    '     for a connected one also its service, facts and the variables it yields. &method= and &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"}    a new name for the same thing.   DELETE /v1/holdings/<id>   removes it (a connected one: see below).',
     '   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}',
@@ -88,32 +96,33 @@ 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.',
+    '   To reconnect, add "connection_id":"<existing id>" inside input. This updates that connection and keeps its id.',
+    '   Without connection_id, authorization creates a separate connection, even for the same service user. List and use',
+    '   an existing connection when no new authorization is needed. Provider consent and revocation may affect several connections.',
+    '   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/holdings?kind=grant   lists connected grants with the others: for each, method (authorized / delegated),',
+    '   service details, facts and the variables it yields. To use one, deliver it (above) or bind it in http.request (below).',
+    '   DELETE /v1/holdings/<id> {"revoke": true|false}   disconnects one (the owner, in a browser); revoke also asks the',
+    '   service to withdraw what it granted. What was already handed out stays where it went.', '',
     '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).',
     '   events is the raw record, in order: page_opened / page_viewed / connect_started / connect_failed (with a code and',
-    '   Foundation\'s own message) / connected / stored / denied / cancelled. What was typed is never recorded.',
+    '   Foundation\'s own message) / connect_review (awaiting confirmation of changes) / connected / stored / denied / cancelled. What was typed is never recorded.',
     '   DELETE /v1/requests/<id>   cancels it. status is pending / done / denied / cancelled.',
     '   Completion and result are fixed until the request expires, even if the resulting resource changes or is removed.',
-    '   Current connection state is at GET /v1/connections. Revoked keys receive 401; their pending requests are cancelled.',
+    '   Current connection state is at GET /v1/holdings?kind=grant. Revoked keys receive 401; their pending requests are cancelled.',
     '   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',
+    '   reconnect_required (the service rejected it) / connection_changed (the target changed). A key approval shows its own events at',
     '   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/holdings?kind=object&name=<key>   body is the bytes; the Content-Type you send is what a reader gets back. Up to 25MB.',
@@ -126,12 +135,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.', '',
@@ -151,7 +162,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.4.0",
+  "version": "0.5.1",
   "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

@@ -107,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.
@@ -150,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}.');
@@ -264,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;
@@ -303,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(forHolder('/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;