wawesome 0.8.0 → 0.10.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
 
@@ -427,6 +501,41 @@ That is deliberate — the line that keeps a job off the internet is one line, a
 quietly honoured its deletion would put the job back on the open internet with nothing said. Every
 deploy prints the visibility it landed, beside the URL or in place of it.
 
+### A domain of your own
+
+Add `"domain"` and your App answers at a name you own, beside the address it already has:
+
+```json
+{
+  "app": "my-app",
+  "function": "api",
+  "entry": "src/index.ts",
+  "domain": "shop.client.com"
+}
+```
+
+The deploy attaches it and prints two DNS records to add at your registrar. The TXT record proves you
+own the name, which is what issues the certificate. The CNAME points traffic here, and you add that
+one once the certificate is issued, so a site that is already live never spends a minute answering on
+a certificate that is not there yet.
+
+Your deploy waits for neither. It attaches the domain, prints the records and finishes, and every
+later deploy states where the domain got to: not verified, ownership verified, certificate issued, or
+serving. A domain that is already serving is a line saying so and nothing else.
+
+A custom domain is granted from the Solo plan upwards, one per App. On a plan that grants none, the
+deploy prints the refusal and lands everything else it was doing.
+
+The address derived from your workspace slug keeps serving after you attach a domain. Both names
+answer, so webhooks and integrations already pointed at the old one keep working.
+
+An apex domain — `client.com` with no `www` — attaches like any other name. Whether a CNAME may sit at
+your zone root is your DNS provider's rule, and where it cannot, attach `www.client.com` and configure
+the redirect at the provider.
+
+Deleting the line detaches nothing. Detaching takes a live site dark, which is not something a deploy
+should infer from a deleted line.
+
 ### Reserved headers
 
 `x-wawesome-*` belongs to the platform in both directions. It is stripped off the request before your
@@ -497,6 +606,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