wawesome 0.7.0 → 0.9.0

package/README.md

@@ -116,6 +116,9 @@ npx wawesome deploy
 | `npx wawesome env list`                 | View environment variables for the current app                      |
 | `npx wawesome env set <key> <val>`      | Set an environment variable (add `--secret` for write-only)         |
 | `npx wawesome env rm <key>`             | Delete an environment variable                                      |
+| `npx wawesome credentials`              | List deploy credentials — name, prefix, capabilities, Apps, last use |
+| `npx wawesome credentials mint <name>`  | Mint a deploy credential and print its secret, once                 |
+| `npx wawesome credentials revoke <name>`| Revoke a deploy credential by name or prefix                        |
 
 ---
 
@@ -279,6 +282,74 @@ npx wawesome cron history my-function --state failed
 
 ---
 
+## 🔑 Deploy Credentials
+
+A deploy credential is what a CI pipeline or an agent authenticates with, where there is nobody at a
+keyboard to log in. It belongs to the workspace rather than to you: it keeps working after you leave,
+and revoking it does not end your own session. Once you have one, [Deploying from CI](#-deploying-from-ci)
+is what to do with it.
+
+Minting, listing and revoking are the workspace owner's, and are closed to deploy credentials
+themselves whatever they carry — a leaked credential cannot mint another. So these three run on your
+ordinary `npx wawesome login` session.
+
+### Mint one
+
+```bash
+npx wawesome credentials mint ci-pipeline
+```
+
+The secret is printed once and never again — the platform stores a digest of it, so no later read can
+rebuild it. It goes to stdout on a line of its own and everything else the command prints goes to
+stderr, so a redirect catches the secret and not one character besides:
+
+```bash
+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:
+
+```bash
+# reads logs and cannot deploy, restricted to one App, never expires
+npx wawesome credentials mint agent -c logs:read -a prod --expires never
+```
+
+| Flag                 | Meaning                                                                       |
+|:---------------------|:------------------------------------------------------------------------------|
+| `-c, --capability`   | `deploy`, `logs:read`, or both. Repeatable or comma-separated. Default `deploy` |
+| `-a, --app`          | Restrict to these Apps, by slug. Repeatable. Default: every App in the workspace |
+| `--expires`          | Days, or `never`. Default: 90                                                   |
+
+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 can disturb, not
+what it can read: a Function deployed into one App still reads the whole workspace's environment at
+runtime.
+
+### List them
+
+```bash
+npx wawesome credentials
+```
+
+Name, displayable prefix, capabilities, Apps, last use and expiry — never the secret, which the
+platform no longer holds. `LAST USED` lags by a few minutes and reads `never` for a credential
+nothing has ever presented, which is a better reason to revoke one than any calendar date.
+
+### Revoke one
+
+```bash
+npx wawesome credentials revoke ci-pipeline
+npx wawesome credentials revoke wawe_ab3k9x --yes
+```
+
+By name or by displayable prefix, whole or partial. It asks before it does it, `--yes` is the answer
+where nobody is at the keyboard, and a prefix naming more than one credential is refused rather than
+guessed at. A revocation lands on the very next request presenting the secret, and nothing un-revokes
+it.
+
+---
+
 ## ⚙️ Configuration & Custom Gateway
 
 ### `wawesome-function.json`
@@ -340,11 +411,14 @@ Two rules to know about:
 **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 vector a static file has.
 
-**An SVG is served with script denied.** The rule behind the refusal above is that nothing you deploy
-as a file runs script on your App's own origin, and an SVG opened directly in a browser would. It is
-served rather than refused because denying it costs the file nothing: an `<img src="logo.svg">` never
-ran that script, so your drawings render as they always did — every SVG and XML file carries
-`Content-Security-Policy: script-src 'none'`, and only navigating straight to one loses anything.
+**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 — 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.
 
 ### Schedules
 
@@ -497,6 +571,40 @@ export WAWESOME_GATEWAY_URL="http://localhost:3000"
 npx wawesome login --gateway http://localhost:3000
 ```
 
+A successful login records the gateway it used, and every later command goes there, because a token is only valid at
+the gateway that issued it. `login` itself ignores that record and reads only the three overrides above, so a bare
+`npx wawesome login` with none of them set goes to `https://api.wawesome.io`. `npx wawesome logout` clears the recorded
+gateway along with the credentials.
+
+---
+
+## 🤖 Deploying from CI
+
+A **deploy credential** is what deploys without a person at a keyboard. Your workspace mints one, and the CLI reads it
+from a single environment variable — there is no login, and no credentials file is involved at any point:
+
+```bash
+export WAWESOME_DEPLOY_CREDENTIAL="wawe_..."
+export WAWESOME_GATEWAY_URL="https://api.wawesome.io"
+
+npx wawesome deploy
+```
+
+The workspace is resolved from the credential itself, so nothing in your pipeline has to carry a workspace identifier.
+The variable name is prefixed and has no shorter alias, so it cannot collide with another tool's CI variable.
+
+While it is set:
+
+- it wins over any `~/.wawesome/credentials.json` on the machine, so a runner with a stale cached home directory still
+  deploys as the credential rather than as whoever last logged in there;
+- nothing is written to disk, and the secret stays in the environment where you put it;
+- a refusal says which of four things happened — the credential is unknown, revoked, expired, or does not carry what the
+  command needs — instead of asking you to sign in again, which a pipeline cannot do;
+- `login` and `logout` refuse, because neither would change what the next command authenticates as;
+- `credentials` is refused by the platform, because minting, listing and revoking are closed to
+  credentials whatever they carry;
+- `whoami` names the credential by its prefix, so you can match it against the one in your CI settings.
+
 ---
 
 ## 🔒 Security & Secrets