@tomato414941/foundation 0.9.0 → 0.11.0

package/guide.mjs

@@ -41,10 +41,15 @@ export function guide(services) {
     '   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/audit-log   what was done in your name or to you.',
-    '   Every resource has an id, shown in every listing. The holder shows one to another principal with',
-    '   POST /v1/relations {"subject":"<principal id>","relation":"viewer"|"editor","object_type":"resource","object_id":"<id>"}   DELETE takes it back.',
+    '   Every resource has an id, shown in every listing. What a principal may do comes from lines drawn to it:',
+    '   POST /v1/relations {"subject":"<principal id>","relation":"<role or action>","object_type":"resource"|"principal","object_id":"<id>"}',
+    '     A role is viewer or editor onto a resource, or actor onto a principal (acting for it). An action is one the rules',
+    '     name, such as credential.disconnect, onto one resource or onto a principal (all it holds). One draws a line where',
+    '     one may give lines (share on a resource, relate on a principal) and may do all the line reaches. DELETE takes it',
+    '     back; anyone may step off a line drawn to them. Owning a principal is never drawn: it comes from making or approving.',
     '   GET /v1/resources?shown=me   what others have shown you.   GET /v1/resources/<id>   one resource, whoever holds it.',
-    '   GET /v1/resources/<id>/content   reads it; PUT writes it, as editor. Lines point at the id, so renaming changes nothing.', '',
+    '   GET /v1/resources/<id>/content   reads it; PUT writes it, as editor. Lines point at the id, so renaming changes nothing.',
+    '',
     'CREDENTIALS',
     '   GET /v1/resources?kind=credential    every credential: id, name, status, and for one made for a service, its',
     '     service, auth_scheme, facts and the variables it yields. &service=<id> narrows to one service; &secret=true to',
@@ -134,8 +139,22 @@ export function guide(services) {
     '   Poll GET /v1/requests/<id> every few seconds until done; result.credential_id identifies the credential.',
     '   DELETE /v1/resources/<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.', '',
+    'ENVIRONMENTS (a machine with a shell, for when you have none)',
+    '   A lent machine: a shell, files and the network, thrown away when done. By itself it reaches nothing of Foundation.',
+    '   Give it an identity - a principal you may act as (yourself, one you own, or one you act for) - and it holds that',
+    '   principal\'s key for its life: inside, the foundation CLI works as that principal (foundation exec, foundation api).',
+    '   POST /v1/environments {"identity":"<principal id>"|null, "size":"small|medium|large",',
+    '     "lifetime":{"end":"idle|exit","idle_seconds":600,"max_seconds":3600}}   opens one; it is a resource (kind environment).',
+    '   POST /v1/environments/<id>/commands {"command":["npm","test"],"stdin":null,"timeout_seconds":300}',
+    '     runs one command: exit_code, stdout, stderr. 202 with status running if it takes longer; then',
+    '   GET /v1/environments/<id>/commands/<command id>.   One command at a time; files persist between commands.',
+    '   PATCH /v1/environments/<id> {"identity":… or null}   gives or takes away its identity.   DELETE closes it.',
+    '   POST /v1/runs {…as opening, plus "command"}   opens, runs one command, stops: the answer carries the result.',
+    '   What a command prints is cleaned of values handed in with injections. Keep what matters as an object.',
+    '   Computing is spent: GET /v1/principals/<id>/compute shows this month\'s use and limit; its owner may lower the',
+    '   limit with PUT {"monthly_seconds": n}. A medium machine spends twice its time, a large one four times.', '',
     'FUNCTIONS',
-    '   GET /v1/functions   catalog of built-in operations and their invocation endpoints; no arbitrary-code runtime.', '',
+    '   GET /v1/functions   catalog of built-in operations and their invocation endpoints.', '',
     '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).',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomato414941/foundation",
-  "version": "0.9.0",
+  "version": "0.11.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

@@ -199,7 +199,7 @@ async function main() {
   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);
+      if (me.acts_for?.length === 1) call.target += (call.target.includes('?') ? '&' : '?') + 'as=' + encodeURIComponent(me.acts_for[0]);
     }
     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) });
@@ -233,11 +233,22 @@ async function main() {
   // Nothing runs before someone has accepted this key: a key that acts for nobody reaches only its own empty resources,
   // 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 resources 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);
+  // A key given to a lent machine acts as its principal's own self. Any other key acts for someone once approved;
+  // until then, whether waiting or refused, it has nothing to run with.
+  const own = Boolean(current.key?.environment);
+  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;
+  // A client can be updated before its server. Discover the storage kind before the command creates an output.
+  let outputKind = 'secret';
+  if (output) {
+    const probe = await send(forHolder('/v1/resources?kind=secret&prefix=' + encodeURIComponent(output.name)), undefined,
+      { method: 'GET', accept: data => data.error?.code === 'invalid_kind' });
+    if (probe.error?.code === 'invalid_kind') outputKind = 'credential';
+  }
   let injection;
   if (names.length) ({ injection } = await send(forHolder('/v1/injections'), { names }));
   else injection = { environment: {}, files: [] };
@@ -269,7 +280,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=credential&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/resources?kind=' + outputKind + '&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;
@@ -308,7 +319,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/resources?kind=credential&name=' + encodeURIComponent(output.name)), bytes, { method: 'PUT', type: 'application/octet-stream' }); }
+      try { saved = await send(forHolder('/v1/resources?kind=' + outputKind + '&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: 'resource', object_id: saved.resource.id }, { method: 'DELETE' }); } catch {}
       retainOutput = false;