@polardbx/pxbaas 0.1.0-beta.3 → 0.1.0-beta.5

package/skills/pxbaas-cli/references/tenant-admin.md

@@ -0,0 +1,122 @@
+# Tenant Administration (platform-operator surface)
+
+Covers: `tenant login` · `tenant logout` · `tenant probe` · `tenant ls` · `tenant create` · `tenant keys` · `tenant repair-keys` · `tenant handoffs`, and the tenant access bundle.
+
+**Who this is for:** the operator of a **multi-tenant** PolarDB-X BaaS instance. Ordinary tenants never use this surface — they hold per-tenant API keys and use `db` / `data` / `app`. Never point a tenant at these commands.
+
+## Credential model (read this first)
+
+| | Data plane | Admin plane |
+| --- | --- | --- |
+| Secret | per-tenant `anon` + `service_role` JWT | instance dashboard HTTP Basic (`DASHBOARD_USERNAME` / `DASHBOARD_PASSWORD`) |
+| Keyring account | `credentials/<profile>` | `admin/<profile>` |
+| Used by | `db`, `data`, `storage`, `auth`, `functions`, `app` | `tenant *` |
+
+Rules that hold in code, not convention:
+
+- **The password never goes in argv.** `--dashboard-user`, `--dashboard-password`, `--admin-password` are refused by `assertNoKeyArgs`. Supply them via TTY prompt (masked) or via `--user-stdin --password-stdin` (two lines: username, then password; both flags are required together).
+- **`DASHBOARD_*` found in an env file is NOT imported by `profile import`.** It is reported as present-but-not-imported. Only `--with-admin` binds it, and then only after a successful admin-channel probe.
+- **Endpoint must be the Kong gateway.** Studio's `/api/platform/*` routes do not authenticate on their own (`apiWrapper` is called without `withAuth`); the only gate is Kong's dashboard `basic-auth`. Targeting a component port bypasses it and is refused at the prompt.
+- Plaintext is never printed. Output carries fingerprints (`sha256:<8>...<4>`); the only sinks for plaintext keys are the keyring (`--as-profile`) and a `0600` access bundle (`--bundle`).
+
+## Capability probe
+
+`pxbaas tenant probe --json` answers, in one read-only call, whether the current profile can operate the admin plane:
+
+| `status` | meaning | next move |
+| --- | --- | --- |
+| `admin` | admin channel works | `tenant ls`, then `create` / `keys` |
+| `not-admin` | 401/403 from the gateway | these are not dashboard credentials |
+| `single-tenant` | instance reports `multiTenantMode:false` | tenant administration does not apply |
+| `metadata-unreadable` | credentials accepted but tenant metadata fails to load | platform-side schema drift — do not report "no tenants" |
+| `unreachable` | network/endpoint failure | fix connectivity first |
+
+Why `metadata-unreadable` exists: the list endpoint also returns `200 + tenants: []` when its own query fails. The probe disambiguates by asking for a sentinel tenant id — `404` means the metadata path is healthy (so the empty list is real), `500` means it is not.
+
+## Command reference
+
+| Command | Options (defaults) | Notes |
+| --- | --- | --- |
+| `tenant login` | `--endpoint <url>`, `--user <name>`, `--user-stdin`, `--password-stdin` | Probes **before** storing; a refused probe stores nothing. Creates an admin-only profile when none exists (it holds no tenant keys, so data-plane commands on it still ask for `pxbaas login`) |
+| `tenant logout` | — | Removes dashboard credentials only; tenant keys untouched |
+| `tenant probe` | — | Read-only |
+| `tenant ls` | `--status <active\|suspended\|deleting\|deleted>` | Redacted rows: id, status, plan, db, plus `hasAnonKey` / `hasServiceRoleKey` booleans. A missing key shows a `repair-keys` hint |
+| `tenant create [tenant-id]` | `--generate-id`, `--plan` (`free`), `--display-name`, `--retention-days <n>`, `--reactivate`, `--dry-run`, `--yes`, `--as-profile [name]`, `--bundle <file>`, `--intranet <url>`, `--overwrite` | Id must match `^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$` |
+| `tenant keys <tenant-id>` | `--as-profile [name]`, `--bundle <file>`, `--intranet <url>`, `--overwrite` | Requires one destination; refuses to bundle when either key is NULL |
+| `tenant repair-keys` | `--confirm` | Without `--confirm` prints which tenants are missing keys and changes nothing |
+| `tenant handoffs` | — | Local ledger: tenant id, timestamps, fingerprints, bundle path + sha256. Never key material |
+
+All of them accept `--json` and `--profile <name>`.
+
+## Two-phase behaviour
+
+| Command | Preview | Authorization |
+| --- | --- | --- |
+| `tenant create` | `--dry-run` (shows plan + side effects) | TTY confirm, or `--yes`; without it **nothing is created** |
+| `tenant repair-keys` | default (no `--confirm`) | `--confirm` |
+| `tenant keys` / `ls` / `probe` / `handoffs` | n/a | read-only (writes are local: keyring / bundle file) |
+
+`tenant create` exits non-zero (`process.exitCode = 2`) when post-create verification fails — a `201` from the platform is **not** proof of a usable tenant, because CREATE DATABASE / CREATE USER / GRANT / RLS tables / Realtime registration are non-fatal server-side steps. Verification runs `SELECT DATABASE()`, an `information_schema` table count, the RLS registry read, and reports `realtime_provisioned`.
+
+## Danger: same-name create against a soft-deleted tenant
+
+The platform's create path resurrects a `status='deleted'` row and **regenerates its `jwt_secret` and both API keys**. That silently invalidates whoever held the old keys and brings any surviving data back under new credentials. The CLI therefore refuses a colliding id by default:
+
+- live tenant with the same id → refused, tells you to use `tenant keys <id>` instead
+- soft-deleted tenant → refused unless you pass `--reactivate`
+
+Never retry a failed create with a different flag combination hoping it will pass. Read the message.
+
+## Tenant access bundle (handing keys to another human)
+
+```bash
+pxbaas tenant create acme --bundle ./acme.pxbaas.env    # new tenant + bundle
+pxbaas tenant keys acme   --bundle ./acme.pxbaas.env    # existing tenant + bundle
+pxbaas tenant keys acme   --as-profile                  # bind into this machine's keyring
+```
+
+Admin credentials come from the active profile (`tenant login`), not from a per-command flag.
+
+`--bundle` writes `0600` and refuses an existing path unless `--overwrite`. The file contains exactly:
+
+```
+MULTI_TENANT_MODE=true
+SUPABASE_URL=<gateway>
+DEFAULT_TENANT_ID=<tenant>
+TENANT_ANON_KEY=<key>
+TENANT_SERVICE_ROLE_KEY=<key>
+```
+
+Built by explicit field list, so `jwt_secret`, `DASHBOARD_*` and `GLOBAL_*` cannot appear in it. It is directly consumable by the receiving user:
+
+```bash
+pxbaas profile import ./acme.pxbaas.env --name acme --json
+pxbaas whoami --json     # expect mode=multi-tenant, tenantId=acme
+pxbaas doctor --json     # Tenant Consistency must pass
+pxbaas db tables --json
+```
+
+`create`/`keys` also print a copy-paste handoff note (import steps + both fingerprints) and append a line to `~/.baas/handoffs.json`. The receiver compares those fingerprints against `whoami` to prove nothing was swapped in transit.
+
+**Treat a bundle as a long-lived plaintext credential.** Keys are signed with `exp ≈ 10 years` and the platform has **no revocation**: `PATCH /api/platform/tenants/[id]` does not accept `jwt_secret`, and HS256 tokens carry no `jti`, so re-signing keys does not invalidate old ones. Consequences for you as agent:
+
+- never cat/read a bundle file into the conversation, never echo its contents, never commit it (add `*.pxbaas.env` to ignores)
+- do not upload it to chat, ticket attachments, or shared drives; that channel choice is the operator's job
+- tell the operator that distributing a bundle = distributing an irrevocable admin-grade credential for that tenant
+
+## Gap guidance from `profile import`
+
+When a multi-tenant env file lacks tenant-level keys, `profile import` now prints a diagnosis (which variables exist, whether each JWT carries `tenant_id`, whether `DASHBOARD_*` is present), states `Nothing was created and nothing was imported`, and routes to one of:
+
+- **admin path** — when the file's dashboard credentials actually open the admin channel: `tenant login` → `tenant ls` → `tenant keys <id> --as-profile|--bundle`
+- **request path** — otherwise: a checklist to send to the operator (tenant id + both keys, plus how to prove a key is tenant-level: its JWT payload must contain `tenant_id`)
+
+The transient probe used for this routing is read-only and does **not** persist the dashboard credentials it borrowed from the file.
+
+## Agent rules for this surface
+
+1. **Never create a tenant on someone else's behalf without explicit confirmation** — it provisions a database, a MySQL account, GRANTs, a storage bucket and quota consumption.
+2. **Prefer `tenant keys <id>` over `tenant create`**: most "I have no key" cases are an existing tenant whose key was never handed over. Run `tenant ls` first.
+3. `tenant repair-keys` is the safe fix for a tenant visible with `hasAnonKey=false`; it is idempotent and re-signs from the existing `jwt_secret`. Do not present it as rotation.
+4. Do not run `tenant create` with `--reactivate` unless the user has read the resurrection warning above.
+5. There is no `suspend` / `resume` / `delete` / `quotas` in this surface yet — do not invent them; use Studio for tenant lifecycle beyond create.

package/skills/pxbaas-cli/references/troubleshooting.md

@@ -57,7 +57,10 @@ pxbaas whoami --json    # verify profile / tenant / role / key fingerprints
 | MT: `/pg/query` 401 | it takes the **global** service key as both `Authorization` and `apikey`; Basic Auth and tenant keys are rejected | switch credential tier |
 | MT: `403 Global credentials cannot access tenant resources` | global key used on a tenant-scoped endpoint | use that tenant's own anon/service key |
 | MT: `403 Token tenant mismatch` | the key's `tenant_id` claim ≠ `X-Tenant-Id` | align them; never cross tenants |
-| MT: `db query` 401 on a tenant profile | the pg-meta path rejects tenant keys | run SQL via `/pg/query` + global key with `tenant_<id>.<table>` names |
+| MT: `db query` 401 on a tenant profile | obsolete workaround — MT SQL no longer goes through `/pg/query`; something is wrong with the profile or the key | check `pxbaas doctor --json` (Tenant Consistency, JWT Expiry) and re-login with that tenant's per-tenant keys; `/pg/query` stays platform-admin only |
+| `profile import` refuses a MT env file ("lacks tenant-level credentials") | the file only carries platform-global keys (JWT has no `tenant_id`) | follow the printed route: operator → `tenant login` then `tenant keys <id> --as-profile`; non-operator → send the printed checklist to the operator. Never create a tenant to work around a missing key |
+| `tenant login` says "Not saved. ... could not open the tenant admin channel" | wrong credentials for the admin plane, or endpoint is not the Kong gateway | use the gateway URL (typically :8000); dashboard Basic creds are required — an API key never works here |
+| `tenant probe` → `metadata-unreadable` | the credentials are fine but tenant metadata fails to load (schema drift on long-lived instances) | do not report "no tenants"; escalate to the platform operator |
 | MT: RLS policies registered but have **no effect** | wrong `table_schema` (must be the tenant DB name, not `public`), or written into the tenant DB's unread `_mysqlrest_rls_*` copies | rewrite into the central `supabase._mysqlrest_rls_*`, then verify behaviourally (anon read / forged-owner write → 403) |
 | `app publish` → `APP_MANIFEST_INVALID` | manifest `name` ≠ mount `appName`, or a v1 `mpa` manifest on a schemaVersion-2-only instance | align `name`; migrate the manifest (pxbaas-app-spec `deploy-options.md`) |
 | `app publish` → `APP_SSR_PROBE_FAILED` | **platform-side**: cold tenant sandbox vs the probe budget (heavy `npm:` graph, ≈60 s) | warm the sandbox with a legacy function, then retry publish 3–5× |