wawesome 0.14.2 → 0.15.0

package/README.md

@@ -312,31 +312,38 @@ stderr, so a redirect catches the secret and not one character besides:
 npx wawesome credentials mint ci-pipeline > secret.txt
 ```
 
-A credential carries `deploy`, reaches every App in the workspace, and expires in ninety days unless
-you say otherwise:
+A capability is one cell of a grid: a verb, `read` or `write`, and the resource it acts on. A
+credential carries the words a deploy needs, reaches every App in the workspace, and expires in
+ninety days unless you say otherwise:
 
 ```bash
-# reads and runs what somebody else shipped, restricted to one App, never expires
-npx wawesome credentials mint agent -c read,logs:read,invoke -a prod --expires never
+# reads what ran and fires a run of what somebody else shipped, on one App, never expires
+npx wawesome credentials mint runner -c read:apps,read:functions,read:invocations,write:runs -a prod --expires never
 
-# ships code and attaches the domain the project declares
-npx wawesome credentials mint ci -c deploy,domains:attach -a prod
+# ships code into an App it may create, and attaches the domain the project declares
+npx wawesome credentials mint ci -c write:apps,write:functions,write:env,read:tenant,write:domains -a prod
 ```
 
 | Flag                 | Meaning                                                                       |
 |:---------------------|:------------------------------------------------------------------------------|
-| `-c, --capability`   | `deploy`, `read`, `logs:read`, `invoke`, `domains:attach`, or any mix. Repeatable or comma-separated. Default `deploy` |
+| `-c, --capability`   | A `{read\|write}:{resource}` word — `read:apps`, `write:functions`, `write:env`, `write:runs` and the rest. Repeatable or comma-separated. Default: `write:apps`, `write:functions`, `write:env`, `read:domains`, `read:tenant` |
+| `--preset`           | The words one job needs, by the job's name: `viewer`, `deployer`, `member`. [Which credential for which job](#which-credential-for-which-job) is what each one grants. Not with `-c` |
 | `-a, --app`          | Restrict to these Apps, by slug. Repeatable. Default: every App in the workspace |
 | `--expires`          | Days, or `never`. Default: 90                                                   |
 
-`deploy` reaches the reads of what it writes, so a credential minted with it carries `read` as well:
-it lists the workspace, the Apps in it, the Functions in an App and their versions. The command
-prints the words the credential ended up with.
+The resources are `tenant`, `apps`, `functions`, `env`, `domains`, `invocations`, `runs`,
+`schedules`, `previews` and `egress`. A write reaches the read of the same resource, so
+`write:functions` carries `read:functions` and there is no reason to name both. The command prints
+the words the credential ended up with.
+
+Some things are a person's alone, whatever a credential carries: renaming the workspace, detaching a
+domain, widening the egress allowlist, billing, and this workspace's own credentials and members.
+Those are not words to mint — a credential asking for one is told a person has to be at the keyboard.
 
 An App named in a restriction does not have to exist yet. A pipeline whose first deploy creates the
 App it was minted for is the ordinary case. A restriction bounds what a credential reads as well as
-what it disturbs, and `deploy` is the hole in it: a Function deployed into an App the credential does
-reach still reads the whole workspace's environment at runtime.
+what it disturbs, and `write:functions` is the hole in it: a Function deployed into an App the
+credential does reach still reads the whole workspace's environment at runtime.
 
 ### List them
 
@@ -470,21 +477,32 @@ concluding the platform cannot do it.
 
 | Tool                       | What it does                                                            | Needs         |
 |:---------------------------|:------------------------------------------------------------------------|:--------------|
+| `whoami`                   | The workspace, where it is administered, the words this credential carries, the Apps it reaches | nothing       |
 | `list_templates`           | The template catalogue, with what each one is for                       | nothing       |
 | `get_template`             | One template's files, environment contract and outbound providers        | nothing       |
-| `list_apps`                | The Apps the credential reaches, with the slug each is addressed by      | `read`        |
-| `list_functions`           | The Functions in one App, and what their live version carries            | `read`        |
-| `list_versions`            | A Function's Versions, and which one is live                             | `read`        |
-| `get_usage`                | The Tenant's usage and headroom                                          | `read`        |
-| `list_invocations`         | Recent Invocations of a Function, failures included                      | `logs:read`   |
-| `get_invocation`           | One Invocation by id                                                     | `logs:read`   |
-| `read_invocation_logs`     | An Invocation's log body, a page at a time                               | `logs:read`   |
-| `diagnose_latest_failure`  | The latest failure, its logs and the Version that ran it, in one call    | `logs:read`, `read` |
-| `deploy_function`          | Deploys code and the static files it carries                             | `deploy`      |
-| `deploy_status`            | How a deploy went, by the handle it answered with                        | `deploy`      |
-| `rollback_function`        | Puts a Version the Function already has back on its public address       | `deploy`      |
-| `set_env_var`              | Sets an App's environment variable, read at the next invocation          | `deploy`      |
-| `invoke_function`          | Runs a deployed Function once and answers with the Invocation id         | `invoke`      |
+| `list_apps`                | The Apps the credential reaches, each with its address and its dashboard page | `read:apps`   |
+| `list_functions`           | The Functions in one App, and what their live version carries            | `read:functions` |
+| `list_versions`            | A Function's Versions, and which one is live                             | `read:functions` |
+| `get_function_source`      | The code a Function is running, and the static files it carries          | `read:functions` |
+| `get_usage`                | The Tenant's usage and headroom                                          | `read:tenant` |
+| `list_invocations`         | Recent Invocations of a Function, failures included                      | `read:invocations` |
+| `get_invocation`           | One Invocation by id                                                     | `read:invocations` |
+| `read_invocation_logs`     | An Invocation's log body, a page at a time                               | `read:invocations` |
+| `diagnose_latest_failure`  | The latest failure, its logs and the Version that ran it, in one call    | `read:invocations`, `read:functions` |
+| `deploy_function`          | Deploys code and the static files it carries                             | `write:functions` |
+| `deploy_status`            | How a deploy went, by the handle it answered with                        | `read:functions` |
+| `rollback_function`        | Puts a Version the Function already has back on its public address       | `write:functions` |
+| `set_env_var`              | Sets an App's environment variable, read at the next invocation          | `write:env`   |
+| `invoke_function`          | Runs a deployed Function once and answers with the Invocation id         | `write:runs`  |
+| `fetch_function`           | Fetches one path from a Function's live Version and answers what it served | `write:runs`  |
+
+A word that writes reaches the read of the same thing, so `write:functions` needs no `read:functions`
+beside it, and the presets below are named in exactly these words.
+
+`whoami` is the one to call first. It answers the workspace, every word the credential carries and
+the Apps it reaches, and it asks for nothing — so your agent can say what it is able to do before it
+offers, rather than finding the edge by being refused in front of you. A member's session calling the
+endpoint gets the same answer for the role they hold.
 
 A deploy is two calls. The first says which of your files the platform does not already hold, by
 content hash; your agent uploads those bytes to `PUT /v1/assets/{content_hash}` with the same
@@ -503,32 +521,43 @@ is all the platform permits, and an agent taking it would end yours.
 ### Which credential for which job
 
 A credential carries the words its job needs and stops there. They are the same words
-[Deploy credentials](#mint-one) mints with.
+[Deploy credentials](#mint-one) mints with, and `--preset` fills them in for you: it expands into the
+words below before the request is built, and the command prints the words the credential ended up
+with. A preset and `-c` together are refused rather than merged, since both name the same thing. The
+preset is the name of the job; the words are the grant, and they are what travels.
+
+A preset is a workspace role, and the ones offered here are the roles carrying nothing only a person
+can hold. The name a job is minted under and the standing a member is given are one thing, rather
+than two lists somebody has to keep level.
 
-**Read and investigate, without the ability to ship.** The agent enumerates your Apps, reads
-Functions, Versions, Invocations and log bodies, diagnoses a failure, checks usage, and browses
-templates. Every tool that ships code or runs it refuses:
+**Read and investigate, without the ability to ship** — `viewer`, which is every `read:` word the
+platform has. The agent enumerates your Apps, reads Functions, Versions, Invocations and log bodies,
+diagnoses a failure, checks usage, and browses templates. Every tool that ships code or runs it
+refuses:
 
 ```bash
-npx wawesome credentials mint investigator -c read,logs:read -a prod
+npx wawesome credentials mint reader --preset viewer -a prod
 ```
 
-**Read, investigate and run.** The same, plus `invoke_function`, so the agent can exercise a Function
-and read what it did. It still cannot deploy, roll back, or set a variable:
+**Ship and read back** — `deployer`, which is every read plus `write:apps`, `write:functions`,
+`write:env` and `write:runs`. Deploy, run, diagnose, roll back, set a key. Every tool in the table:
 
 ```bash
-npx wawesome credentials mint runner -c read,logs:read,invoke -a prod
+npx wawesome credentials mint ci --preset deployer -a prod
 ```
 
-**The whole loop.** Deploy, run, diagnose, roll back, set a key. Every tool in the table:
+**The whole workspace** — `member`, which is the deployer's words plus `write:schedules` and
+`write:previews`, for an agent that pauses a schedule or cuts a preview as well:
 
 ```bash
-npx wawesome credentials mint agent -c deploy,read,logs:read,invoke -a prod
+npx wawesome credentials mint agent --preset member -a prod
 ```
 
-Add `domains:attach` where the project declares a custom domain the deploy should claim. Nothing
-gives an agent billing, plan changes, credential management or your workspace's slug: those are
-closed to every credential, whatever it carries.
+Add `write:domains` where the project declares a custom domain the deploy should claim. Nothing gives
+an agent billing, a plan change, credential management or the ability to rename your workspace: those
+are closed to every credential, whatever it carries. Reading the workspace's name and address is not
+among them — `whoami` answers both to any credential, which is how the agent knows where what it
+deploys will appear.
 
 Keep `-a` on all three. A credential restricted to one App is refused on every tool that names
 another, which is what stops an agent working on one client's project from touching another's.
@@ -543,10 +572,18 @@ A refusal is the tool's answer, not a protocol error, and it carries the same `r
 prints:
 
 - `credential-missing-capability`. The credential does not carry a word this tool needs. The refusal
-  names it in `missing_capability`, which is the word to mint a credential with.
+  names the first in `missing_capability` and every one of them in `missing_capabilities`, which are
+  the words to mint a credential with. This one answers `403` rather than `200`, with a
+  `WWW-Authenticate: Bearer error="insufficient_scope"` challenge naming the same words and where
+  this endpoint's OAuth metadata is — a connector installed through consent reads it and asks its
+  human to widen the grant rather than to install again.
 - `app-outside-credential-scope`. The credential is restricted to named Apps and this is not one of
   them. A wider capability changes nothing here.
 
+A `401` is the credential itself: revoked, expired, or one this platform never issued. Nothing else
+answers one — a workspace that cannot deploy for a lapsed plan or a restriction is refused under its
+own reason, and re-installing the connector would not fix either.
+
 A quota refusal carries its numbers under `allowance` beside the prose, so your agent reports
 "3 of 3 App slots" rather than handing you a sentence to read.
 
@@ -575,6 +612,33 @@ URL, serving the code its callers already hold. The CLI remembers where this dir
 deployed and asks before that happens, naming both URLs. If you meant it, delete the old Function
 from the dashboard once nothing calls it.
 
+### A site with no handler
+
+Leave `entry` out, write no `src/index.ts`, and point `"assets"` at the directory your build wrote
+its pages into:
+
+```json
+{
+  "app": "my-app",
+  "function": "root",
+  "assets": "dist"
+}
+```
+
+That deploys the pages and no code at all, and the site is live at your App's address. Nothing in the
+file declares a kind: a project with a handler is one that has an entry point, and a project with
+both deploys them together and rolls them back together.
+
+An `entry` you did name and that is not there is a hard error, so a typo never quietly becomes a site
+with nothing running behind it. Every deploy says which of the two it landed.
+
+One thing the deploy will warn you about: everything beneath a Function's address reaches that
+Function, so a page your root Function carries at `about/index.html` is shadowed by a sibling Function
+named `about`. The deploy says so and names both addresses. It refuses nothing — the two Functions are
+versioned independently, and either one may deploy first.
+
+### Static files
+
 Add `"assets"` to deploy static files beside your code:
 
 ```json
@@ -596,28 +660,32 @@ Files are served straight from object storage; your Function is never invoked fo
 invocation is recorded. They answer on your App's own hostname and nowhere else. On the
 development path form (`/x/<tenant>/<app>/<function>/...`) the same address reaches your handler
 as it always has, because a file on an origin every workspace shares would be same-origin with
-all of them. Each carries `Cache-Control: public, max-age=31536000, immutable` and an
-`ETag`, so name your build output by content hash. A file's bytes must never change under a name a
-browser has already cached for a year. The content type comes from the extension against a fixed
-allowlist and is never sniffed; anything off it is served as a download.
+all of them. A file beneath `assets/` carries `Cache-Control: public, max-age=31536000, immutable`,
+so name your build output by content hash: its bytes must never change under a name a browser has
+already cached for a year. A file outside `assets/` keeps one name across every deploy, so it carries
+`max-age=300` instead — five minutes is inside the reach of a deploy and of a rollback, which a year
+is not. The content type comes from the extension against a fixed allowlist and is never sniffed;
+anything off it is served as a download.
 
 Two rules to know about:
 
 - **Everything beneath `assets/` is static**, whatever the deploy carries. A request there never
   reaches your handler, and an unknown path under it is a 404 rather than a route for you to answer.
-- **At most 100 files may sit outside `assets/`.** Those paths travel on the version record so a
-  request can be routed without a lookup per file. Put bulk output under `assets/`, where a file
-  costs nothing; `favicon.ico`, `robots.txt` and a `.well-known/` directory are what the rest is
-  for.
-
-**HTML is refused at deploy time.** Your Function renders its own markup, and a document served from
-your App's own origin is the sharpest same-origin risk a static file carries.
-
-**An SVG is served inert.** The rule behind the refusal above is that nothing you deploy as a file
-becomes a page on your App's own origin, and an SVG opened directly in a browser would become one.
-It runs script, and it renders whatever HTML a `<foreignObject>` holds. It is served rather than
-refused because making it inert costs the file nothing. An `<img src="logo.svg">` never ran that
-script and is never checked against the policy, so your drawings render as they always did. Every
+- **A file outside `assets/` answers at its own name**, however many of them a deploy carries.
+  `favicon.ico`, `robots.txt` and a `.well-known/` directory are what that is for; hashed build
+  output belongs under `assets/`.
+
+**A page is a file like any other.** An `index.html` your build wrote is deployed, hashed, retained
+and billed exactly as your other files are, and it is what a directory-style address resolves to: a
+path whose last segment carries no extension is served the `index.html` beneath it, so `/`, `/about`,
+`/about/` and `/blog/hello` each answer with a page. A page revalidates rather than being pinned for a
+year, wherever it sits, so deploying and refreshing is a loop that works.
+
+**An SVG is served inert.** Nothing you deploy as a resource should be able to run script on your
+App's own origin, and an SVG opened directly in a browser can: it runs script, and it renders whatever
+HTML a `<foreignObject>` holds. It is served rather than refused because making it inert costs the
+file nothing. An `<img src="logo.svg">` never ran that script and is never checked against the
+policy, so your drawings render as they always did. Every
 SVG and XML file carries `Content-Security-Policy: script-src 'none'; sandbox`, and only navigating
 straight to one loses anything. Such a file is sandboxed onto an origin of its own, so its links no
 longer navigate and a page embedding it through `<object>` or `<iframe>` cannot reach into its DOM.
@@ -732,9 +800,9 @@ npx wawesome domains
 ```
 
 It prints the domain, where it got to, when the platform last checked, and the records to add. It
-changes nothing, and a deploy credential carrying `deploy` can run it, so a pipeline reads the same
-thing you do. The TXT record is minted a moment after the name is claimed, and an attach that outran
-it prints a row saying so rather than dropping the record from the list. That row is what this
+changes nothing, and a deploy credential carrying `read:domains` can run it, so a pipeline reads the
+same thing you do. The TXT record is minted a moment after the name is claimed, and an attach that
+outran it prints a row saying so rather than dropping the record from the list. That row is what this
 command fills in, and it is where the deploy sends you: deploying again would change nothing, and a
 deploy that changes nothing is refused.