@tomato414941/foundation 0.9.0 → 0.10.0

package/guide.mjs

@@ -134,8 +134,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.10.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

@@ -233,11 +233,15 @@ 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].id : 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;
   let injection;
   if (names.length) ({ injection } = await send(forHolder('/v1/injections'), { names }));
   else injection = { environment: {}, files: [] };