@polardbx/pxbaas 0.1.0-beta.1 → 0.1.0-beta.10

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

@@ -1,6 +1,6 @@
 # Provisioning & Managing Zero Instances (provision / instance)
 
-Covers: `provision` (alias `instance claim`) · `instance list` · `instance release` · `instance credentials` · `instance current`.
+Covers: `provision` (alias `instance claim`) · `instance list` · `instance release` · `instance credentials` · `instance current` · `instance whitelist get|add`.
 
 When a customer has no BaaS instance yet, `pxbaas provision` claims a **disposable, Supabase-compatible instance** from PolarDB-X Zero and binds it to a profile — fully automatic, no human TTY login.
 
@@ -70,6 +70,21 @@ pxbaas instance release <id> --confirm --keep-profile   # release remotely, keep
 - Without `--confirm` it only previews. Release removes the local profile/credentials too (unless `--keep-profile`).
 - If the released instance was the **current** profile, no profile is active afterwards — switch with `pxbaas profile use <name>` or `pxbaas provision`.
 
+## pxbaas instance whitelist — query / append IP allow-list (Zero instances only)
+
+```bash
+pxbaas instance whitelist get [--id <zeroId>] [--json]                 # show effective whitelist
+pxbaas instance whitelist add <ips> [--id <zeroId>] [--dry-run] [--json]  # append IPv4/CIDR
+```
+
+- **Zero instances only.** Targets the current profile when it is `source: zero`, or an explicit `--id <sbx_*>`. On a non-Zero (login) profile it refuses with a clear error — the whitelist self-service API exists only for Zero-provisioned instances.
+- **Auth**: derived locally from the stored dashboard password as `sha256hex("supabase:"+password)` and sent as `X-Studio-User` / `X-Studio-Hash`. The password and hash are never printed or persisted. Requires the instance to have been claimed on this machine (the password is stored at claim time; Zero has no credential re-read).
+- **`add` is append-only and idempotent**: existing entries are kept, duplicates are not re-added, and there is no delete/replace — by design, so you can never accidentally clear the list and lock yourself out (the API also requires the request to come from an already-allowed IP). To shrink the list, contact the platform admin. `--dry-run` previews the parsed IPs without calling Zero.
+- **`ips`** is a comma-separated IPv4/CIDR list (e.g. `9.9.9.9,10.0.0.0/24`); single request ≤ 50 entries, merged total ≤ 50. IPv6 is not supported.
+- **IP gate (`IP_MISMATCH`, 403)**: the call must originate from the claiming IP or an already-whitelisted IP. If your egress IP changed since claim, you cannot self-add the new one from it — re-provision with `--whitelist-ip`, or run from an allowed IP. Tip: claim with a CIDR (e.g. `--whitelist-ip <your-egress>/24`) if your egress rotates within a range.
+- Other codes: `ASSIGNMENT_EXPIRED` (403, past 15-day TTL → re-provision), `STUDIO_CREDENTIALS_INVALID` (403), `INSTANCE_NOT_ACCESSIBLE` (404), `INSTANCE_BUSY` / `CONCURRENT_UPDATE` (409, retry / re-`get` to reconcile), `WHITELIST_MODIFY_FAILED` (502, report the `cloudRequestId`), `RATE_LIMIT_EXCEEDED` (429).
+- `get` output: `instanceId`, `groupName`, `whitelist` (effective entries; excludes the system `127.0.0.1` baseline), `source`, `expiresAt`, `updatedAt`.
+
 ## Capacity / rate limits — stop and inform (do NOT loop)
 
 Zero is a shared pre-warmed pool with per-caller limits. On these errors, **stop, report, and let the user decide** — never retry in a loop:

package/skills/pxbaas-cli/references/safety-and-two-phase.md

@@ -2,28 +2,57 @@
 
 This is the safety baseline for using `pxbaas`. **The CLI currently has NO built-in confirmation gate**, so the responsibility to confirm falls on YOU (the agent).
 
-## Key fact: two-phase confirmation is NOT implemented
+## Which commands actually gate themselves
 
-- The README/design docs claim destructive operations support two-phase `--plan` / `--confirm <token>`.
-- **In the actual source, this is not implemented.** The descriptions of `db create-table` / `db add-column` / `data delete` say "two-phase confirmation", but there is no `--plan`/`--confirm` flag and no interactive prompt; e.g. `data delete` issues `DELETE /rest/v1/<table>?<filter>` directly.
-- **Implication:** do NOT assume the CLI will block a dangerous operation for you. **You are the confirmation gate.**
+Gating landed after this page was first written, so it is now a per-command fact rather
+than a global one. Verified against `--help` output:
 
-## Destructive / write operations (confirm with the user first)
+| Command | Gate |
+| --- | --- |
+| `db push <file>`, `app db-init <name>` | shows the full plan, then TTY confirm or `--yes`; without authorization **no statement runs** |
+| `data delete <table>` | read-only preview of affected rows + exact request URL, then TTY confirm or `--yes`; `--json` keeps a `preview` field even when refused |
+| `app remove`, `app destroy`, `app share revoke`, `instance release`, `skill remove` | require `--confirm`; without them the command returns a `dry-run` preview |
+| `tenant create` | `--dry-run` plan, then TTY confirm or `--yes`; refuses a colliding tenant id unless `--reactivate` |
+| `tenant repair-keys` | requires `--confirm` |
+
+**No gate at all** — you are the confirmation layer for these:
+
+| Command | Risk |
+| --- | --- |
+| `db create-table`, `db add-column` | DDL, executes immediately (help text says so) |
+| `db query "<write/DDL>"` | executes whatever the SQL says |
+| `data insert`, `data update` | writes; `update` requires `--filter` but may still hit many rows |
+| `rest` with POST/PATCH/PUT/DELETE | whatever the method does |
+| `functions deploy`, `functions delete` | publishes/overwrites or deletes a live function, irreversible |
+| `app deploy` | publishes live (preflight + spec lint run, but no interactive confirm) |
+| `storage rm` / `mv` / `cp` overwrite | deletes, moves, or silently overwrites objects |
+| `auth users create` / `delete` / `invite` | mutates users; `invite` sends real email |
+| `profile rm`, `logout`, `tenant logout` | removes local credentials (config, not instance data) |
+
+Read-only and always safe: `whoami` `status` `doctor` `profile ls` `tenant probe` `tenant ls`
+`tenant handoffs` `db tables` `db schema` `gen types` `data select` `functions list` `storage ls`
+`auth users list/get` `app list` `app url` `app capabilities` `app templates` `instance list/current`.
+
+## Risk classification (what impact to expect)
 
 | Command | Risk |
 |---|---|
-| `data delete <table> --filter ...` | deletes rows, irreversible |
+| `data delete <table> --filter ...` | deletes rows, irreversible (gated: preview + `--yes`) |
 | `data insert` / `data update` | writes / mutates data |
-| `db create-table` / `db add-column` | schema change (DDL) |
+| `db create-table` / `db add-column` | schema change (DDL), executes immediately |
 | `db query "<write or DDL SQL>"` | depends on the SQL |
+| `db push` / `app db-init` | DDL + RLS + seed; sequential, stops on first error, **never rolls back** |
 | `functions deploy` | publishes / overwrites a live function |
-| `functions delete <slug>` | deletes a live function, irreversible |
-| `storage rm` / `storage mv` / `storage cp` (overwrite) | deletes / moves / overwrites objects |
-| `auth users delete` / `create` / `invite` | deletes / creates users, sends invites |
+| `functions delete <slug>` | deletes a live function, irreversible; also revokes its share links |
+| `app deploy` / `publish` / `rollback` / `unpublish` | changes what is live for users |
+| `app remove` / `app destroy [--purge-db]` | deletes functions + mount; `--purge-db` also drops tables and RLS rows |
+| `storage rm` / `mv` / `cp` (overwrite) | deletes / moves / overwrites objects; remote→remote `cp` is a **move** (source is removed) |
+| `auth users delete` / `create` / `invite` | deletes / creates users; `invite` sends real email |
 | `rest` POST/PATCH/DELETE/PUT | depends on method and path |
-| `profile rm` / `logout` | removes local credential config |
-
-**Read-only safe commands** (no confirmation needed): `whoami` `status` `doctor` `profile ls/use` `db tables/schema` `db query "<SELECT>"` `gen types` `data select` `functions list` `functions new` (local only) `storage ls` `auth users list/get` `completion`.
+| `profile rm` / `logout` / `tenant logout` | removes local credentials (also the stored keys, so re-login is required) |
+| `tenant create` | provisions a database, a MySQL account + GRANTs, a storage bucket, RLS tables, Realtime registration; consumes quota |
+| `tenant repair-keys` | re-signs NULL-keyed tenants from the existing `jwt_secret`; idempotent, **not** a rotation |
+| `instance release` | destroys cloud resources and the local profile |
 
 ## Agent confirmation protocol (for destructive ops)
 

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× |

package/templates/webapp/csr-bff/db/rls.json

@@ -0,0 +1,13 @@
+{
+  "$comment": "Declarative RLS for the CSR/BFF blog webapp. Applied by `pxbaas app db-init` (single-tenant AND multi-tenant). table_schema is NEVER declared here: single-tenant binds it to --schema (default public); multi-tenant binds it server-side to the tenant db.",
+  "tables": [
+    { "table": "posts", "rlsEnabled": true, "rlsForced": false }
+  ],
+  "policies": [
+    { "table": "posts", "name": "posts_select_anon", "role": "anon", "command": "SELECT", "using": "`status` = 'published'", "check": null, "permissive": true },
+    { "table": "posts", "name": "posts_select_auth", "role": "authenticated", "command": "SELECT", "using": "`status` = 'published' OR author_id = {{request.jwt.claim.sub}}", "check": null, "permissive": true },
+    { "table": "posts", "name": "posts_insert_auth", "role": "authenticated", "command": "INSERT", "using": null, "check": "author_id = {{request.jwt.claim.sub}}", "permissive": true },
+    { "table": "posts", "name": "posts_update_auth", "role": "authenticated", "command": "UPDATE", "using": "author_id = {{request.jwt.claim.sub}}", "check": "author_id = {{request.jwt.claim.sub}}", "permissive": true },
+    { "table": "posts", "name": "posts_delete_auth", "role": "authenticated", "command": "DELETE", "using": "author_id = {{request.jwt.claim.sub}}", "check": null, "permissive": true }
+  ]
+}

package/templates/webapp/csr-bff/db/schema.sql

@@ -6,11 +6,13 @@
 --   · 多租户实例：__SCHEMA__ = tenant_<tenant_id>
 --   sed 's/__SCHEMA__/public/g' db/schema.sql
 --
--- 执行通道：单租户可 pxbaas db query；多租户走 POST {endpoint}/pg/query
---           （全局 service_role key 作 Authorization+apikey），语句写全限定名。
+-- 执行通道（推荐）：`pxbaas app db-init <name>` —— 单/多租户通用：
+--   单租户 __SCHEMA__→public 经 /pg/query；多租户 __SCHEMA__ 去限定经 /api/tenant-ddl
+--   用 per-tenant service_role key 执行（GRANT 仅本租户库）。本文件只含 DDL + 种子；
+--   RLS 声明在同目录 db/rls.json，由 db-init 一并应用。
 --
--- ⚠️ RLS 元数据落点（写错静默失效＝RLS 关闭）：永远写中心库 supabase._mysqlrest_rls_*，
---    且 table_schema 填 __SCHEMA__；租户库内同名表无人读取，勿写入。
+-- ⚠️ RLS 元数据落点（写错静默失效＝RLS 关闭）：永远写中心库 supabase._mysqlrest_rls_*；
+--    db-init 自动绑定 table_schema（单租户=--schema，多租户=服务端强绑），勿手写库名。
 -- =============================================================================
 
 CREATE TABLE IF NOT EXISTS `__SCHEMA__`.`posts` (
@@ -24,30 +26,8 @@ CREATE TABLE IF NOT EXISTS `__SCHEMA__`.`posts` (
   updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
 );
 
--- ---- RLS 注册 ----
-INSERT IGNORE INTO supabase._mysqlrest_rls_tables (table_schema, table_name, rls_enabled, rls_forced)
-VALUES ('__SCHEMA__','posts',1,0);
-
--- ---- RLS 策略：anon 只读 published；authenticated 读 published 或本人；写改删限本人 ----
-INSERT IGNORE INTO supabase._mysqlrest_rls_policies
-  (table_schema, table_name, policy_name, role_name, command, using_expr, check_expr, permissive)
-VALUES ('__SCHEMA__','posts','posts_select_anon','anon','SELECT','`status` = ''published''',NULL,1);
-INSERT IGNORE INTO supabase._mysqlrest_rls_policies
-  (table_schema, table_name, policy_name, role_name, command, using_expr, check_expr, permissive)
-VALUES ('__SCHEMA__','posts','posts_select_auth','authenticated','SELECT',
-        '`status` = ''published'' OR author_id = {{request.jwt.claim.sub}}',NULL,1);
-INSERT IGNORE INTO supabase._mysqlrest_rls_policies
-  (table_schema, table_name, policy_name, role_name, command, using_expr, check_expr, permissive)
-VALUES ('__SCHEMA__','posts','posts_insert_auth','authenticated','INSERT',NULL,
-        'author_id = {{request.jwt.claim.sub}}',1);
-INSERT IGNORE INTO supabase._mysqlrest_rls_policies
-  (table_schema, table_name, policy_name, role_name, command, using_expr, check_expr, permissive)
-VALUES ('__SCHEMA__','posts','posts_update_auth','authenticated','UPDATE',
-        'author_id = {{request.jwt.claim.sub}}','author_id = {{request.jwt.claim.sub}}',1);
-INSERT IGNORE INTO supabase._mysqlrest_rls_policies
-  (table_schema, table_name, policy_name, role_name, command, using_expr, check_expr, permissive)
-VALUES ('__SCHEMA__','posts','posts_delete_auth','authenticated','DELETE',
-        'author_id = {{request.jwt.claim.sub}}',NULL,1);
+-- ---- RLS 注册与策略：声明在同目录 db/rls.json，由 `pxbaas app db-init` 应用 ----
+--   anon 只读 published；authenticated 读 published 或本人；写/改/删限本人（author_id = jwt.sub）。
 
 -- ---- 种子文章（3 篇 published，幂等）----
 INSERT INTO `__SCHEMA__`.`posts` (title, content, author_id, author_name, status)

package/templates/webapp/manifest.json

@@ -3,16 +3,46 @@
   "templates": [
     {
       "id": "spa",
+      "meta": {
+        "delivery": "legacy",
+        "render": "csr",
+        "frontend": "inline",
+        "backend": "none",
+        "session": "none",
+        "hasDb": false,
+        "coldStart": "light",
+        "purpose": "legacy-demo"
+      },
       "description": "Self-contained single-page webapp: inline HTML/CSS/JS + a built-in JSON API via ?action=. Best for shareable demos.",
       "entrypoint": "index.ts"
     },
     {
       "id": "api",
+      "meta": {
+        "delivery": "legacy",
+        "render": "headless",
+        "frontend": "none",
+        "backend": "none",
+        "session": "none",
+        "hasDb": false,
+        "coldStart": "light",
+        "purpose": "legacy-demo"
+      },
       "description": "Headless JSON backend (Deno.serve) with ?action= routing and CORS. Best for webhooks / API-only demos.",
       "entrypoint": "index.ts"
     },
     {
       "id": "mpa",
+      "meta": {
+        "delivery": "legacy",
+        "render": "static",
+        "frontend": "html",
+        "backend": "none",
+        "session": "none",
+        "hasDb": false,
+        "coldStart": "light",
+        "purpose": "legacy-demo"
+      },
       "description": "Multi-page static webapp: real index.html/about.html/style.css/app.js served by path via the proxy static branch, plus a worker JSON API via ?action=. Best for traditional multi-page sites.",
       "entrypoint": "index.ts",
       "mode": "mpa",
@@ -34,13 +64,23 @@
     },
     {
       "id": "vanilla-static",
-      "description": "Minimal text-only static app for validating the /apps mount and release lifecycle.",
-      "entrypoint": "frontend/index.html",
+      "meta": {
+        "delivery": "webapp",
+        "render": "static",
+        "frontend": "vanilla",
+        "backend": "none",
+        "session": "none",
+        "hasDb": false,
+        "coldStart": "light",
+        "purpose": "validation"
+      },
+      "description": "Minimal text-only static app for validating the /apps mount and release lifecycle. Editable files live in frontend/dist, which is also the artifact directory deploy uploads.",
+      "entrypoint": "frontend/dist/index.html",
       "mode": "webapp",
       "files": [
-        "frontend/index.html",
-        "frontend/style.css",
-        "frontend/app.js"
+        "frontend/dist/index.html",
+        "frontend/dist/style.css",
+        "frontend/dist/app.js"
       ],
       "frontend": {
         "root": "frontend/dist",
@@ -52,6 +92,16 @@
     },
     {
       "id": "react-vite",
+      "meta": {
+        "delivery": "webapp",
+        "render": "csr",
+        "frontend": "react",
+        "backend": "none",
+        "session": "none",
+        "hasDb": false,
+        "coldStart": "light",
+        "purpose": "starter"
+      },
       "description": "React + Vite static app with HashRouter, relative base, plain CSS, and exact dependency versions.",
       "entrypoint": "frontend/src/App.tsx",
       "mode": "webapp",
@@ -75,6 +125,16 @@
     },
     {
       "id": "react-vite-hono",
+      "meta": {
+        "delivery": "webapp",
+        "render": "csr",
+        "frontend": "react",
+        "backend": "hono",
+        "session": "none",
+        "hasDb": false,
+        "coldStart": "light",
+        "purpose": "starter"
+      },
       "description": "React + Vite + HashRouter frontend with a Deno-served, platform-versioned Hono backend.",
       "entrypoint": "backend/index.ts",
       "mode": "webapp",
@@ -106,6 +166,16 @@
     },
     {
       "id": "ssr-hono",
+      "meta": {
+        "delivery": "webapp",
+        "render": "ssr",
+        "frontend": "static-shell",
+        "backend": "hono",
+        "session": "none",
+        "hasDb": false,
+        "coldStart": "moderate",
+        "purpose": "starter"
+      },
       "description": "SSR-shell webapp: Hono worker server-renders the page shell at /page (static-miss fallthrough, fallback=worker); browser hydrates and fetches data client-side. Single-file self-contained worker per D16.",
       "entrypoint": "backend/index.ts",
       "mode": "webapp",
@@ -131,6 +201,16 @@
     },
     {
       "id": "ssr-auth",
+      "meta": {
+        "delivery": "webapp",
+        "render": "ssr",
+        "frontend": "static-shell",
+        "backend": "deno",
+        "session": "proxy-injected",
+        "hasDb": false,
+        "coldStart": "light",
+        "purpose": "reference"
+      },
       "description": "SSR webapp with proxy-injected session (方案 C): the worker server-renders authenticated pages from trusted X-App-User-* headers; it never reads cookies, never sets Set-Cookie, and never puts tokens in URLs. Requires capabilities.sessionMode=proxy-injected-header.",
       "entrypoint": "backend/index.ts",
       "mode": "webapp",
@@ -156,6 +236,16 @@
     },
     {
       "id": "ssr-blog",
+      "meta": {
+        "delivery": "webapp",
+        "render": "ssr",
+        "frontend": "static-shell",
+        "backend": "deno",
+        "session": "proxy-injected",
+        "hasDb": true,
+        "coldStart": "light",
+        "purpose": "reference"
+      },
       "description": "Full-site SSR blog (zero npm deps) with proxy-injected session: the worker renders every page server-side from the instance internal base and reads identity ONLY from X-App-User-* headers. Requires capabilities.sessionMode=proxy-injected-header.",
       "entrypoint": "backend/index.ts",
       "mode": "webapp",
@@ -163,6 +253,7 @@
         "README.md",
         "backend/index.ts",
         "db/schema.sql",
+        "db/rls.json",
         "frontend/dist/index.html"
       ],
       "frontend": {
@@ -182,13 +273,23 @@
       },
       "ssrProbePath": "/posts",
       "nextSteps": [
-        "Initialize the database BEFORE deploy: run `pxbaas app db-init <name> --dir <appsDir>` (single-tenant). It reads db/schema.sql, substitutes __SCHEMA__=public, shows the full DDL + RLS + seed plan, and applies it only after you authorize (--dry-run to preview, --yes for non-interactive). The CLI never auto-runs DDL. Multi-tenant: use POST /pg/query with the global service_role key and tenant_<id>.<table> names.",
+        "Initialize the database BEFORE deploy: run `pxbaas app db-init <name> --dir <appsDir>`. It reads db/schema.sql (DDL + seed) and db/rls.json (RLS registry), shows the full plan, and applies it only after you authorize (--dry-run to preview, --yes for non-interactive). Works in single-tenant (/pg/query) AND multi-tenant (/api/tenant-ddl with your per-tenant service_role key); the CLI never auto-runs DDL.",
         "Requires capabilities.sessionMode=proxy-injected-header.",
         "Data-plane base and anon key come from the platform-in SUPABASE_INTERNAL_URL / SUPABASE_ANON_KEY (edge-runtime MR #30497903); no plaintext key editing is needed."
       ]
     },
     {
       "id": "csr-bff",
+      "meta": {
+        "delivery": "webapp",
+        "render": "csr",
+        "frontend": "html",
+        "backend": "deno",
+        "session": "proxy-injected",
+        "hasDb": true,
+        "coldStart": "light",
+        "purpose": "reference"
+      },
       "description": "Front/back separated CSR blog: real static pages served by path plus a same-origin Deno BFF worker that proxies /api/* to the instance internal REST/Auth. Identity comes from proxy-injected X-App-User-Token (client Authorization is stripped on /apps).",
       "entrypoint": "backend/index.ts",
       "mode": "webapp",
@@ -196,6 +297,7 @@
         "README.md",
         "backend/index.ts",
         "db/schema.sql",
+        "db/rls.json",
         "frontend/dist/admin.html",
         "frontend/dist/article.html",
         "frontend/dist/blog.js",
@@ -222,13 +324,23 @@
         "session": "proxy-injected"
       },
       "nextSteps": [
-        "Initialize the database BEFORE deploy: run `pxbaas app db-init <name> --dir <appsDir>` (single-tenant). It reads db/schema.sql, substitutes __SCHEMA__=public, shows the full DDL + RLS + seed plan, and applies it only after you authorize (--dry-run to preview, --yes for non-interactive). The CLI never auto-runs DDL. Multi-tenant: use POST /pg/query with the global service_role key and tenant_<id>.<table> names.",
+        "Initialize the database BEFORE deploy: run `pxbaas app db-init <name> --dir <appsDir>`. It reads db/schema.sql (DDL + seed) and db/rls.json (RLS registry), shows the full plan, and applies it only after you authorize (--dry-run to preview, --yes for non-interactive). Works in single-tenant (/pg/query) AND multi-tenant (/api/tenant-ddl with your per-tenant service_role key); the CLI never auto-runs DDL.",
         "Requires capabilities.sessionMode=proxy-injected-header.",
         "The BFF forwards to the platform-injected SUPABASE_INTERNAL_URL with SUPABASE_ANON_KEY (edge-runtime MR #30497903); no plaintext key editing is needed."
       ]
     },
     {
       "id": "ssr-shop",
+      "meta": {
+        "delivery": "webapp",
+        "render": "ssr",
+        "frontend": "react",
+        "backend": "hono",
+        "session": "browser-side",
+        "hasDb": true,
+        "coldStart": "moderate",
+        "purpose": "reference"
+      },
       "description": "React 18 + Hono SSR shop: catalog/detail/search are fully server-rendered from MySQL; cart/checkout/orders hydrate in the browser. Browser-side session (localStorage + Authorization direct to /rest,/auth); order gating enforced by RLS.",
       "entrypoint": "backend/index.ts",
       "mode": "webapp",
@@ -236,6 +348,7 @@
         "README.md",
         "backend/index.ts",
         "db/schema.sql",
+        "db/rls.json",
         "frontend/dist/index.html"
       ],
       "frontend": {
@@ -255,13 +368,23 @@
       },
       "ssrProbePath": "/shop",
       "nextSteps": [
-        "Initialize the database BEFORE deploy: run `pxbaas app db-init <name> --dir <appsDir>` (single-tenant). It reads db/schema.sql, substitutes __SCHEMA__=public, shows the full DDL + RLS (products public-read; orders and order_items are owner-gated by buyer_email = jwt.email) + seed plan, and applies it only after you authorize (--dry-run to preview, --yes for non-interactive). The CLI never auto-runs DDL. Multi-tenant: use POST /pg/query with the global service_role key and tenant_<id>.<table> names.",
+        "Initialize the database BEFORE deploy: run `pxbaas app db-init <name> --dir <appsDir>`. It reads db/schema.sql (DDL + seed) and db/rls.json (RLS: products public-read; orders and order_items owner-gated by buyer_email = jwt.email), shows the full plan, and applies it only after you authorize (--dry-run to preview, --yes for non-interactive). Works in single-tenant (/pg/query) AND multi-tenant (/api/tenant-ddl with your per-tenant service_role key); the CLI never auto-runs DDL.",
         "Create the admin account (admin@shop.demo) via GoTrue signup if the admin whitelist is needed.",
         "Data-plane base and anon key come from the platform-injected SUPABASE_INTERNAL_URL / SUPABASE_ANON_KEY (edge-runtime MR #30497903); no plaintext key editing is needed. Requires the instance to report react/react-dom in capabilities.ssrLibs."
       ]
     },
     {
       "id": "ssr-frameworks",
+      "meta": {
+        "delivery": "webapp",
+        "render": "ssr",
+        "frontend": "static-shell",
+        "backend": "hono",
+        "session": "none",
+        "hasDb": false,
+        "coldStart": "heavy",
+        "purpose": "showcase"
+      },
       "description": "Four-framework SSR showcase (React / Vue / Preact / Solid on Hono) rendering the same UI spec server-side, plus /compare. No data plane and no credentials; heaviest cold start of the set (~60s), so warm the tenant sandbox before publish.",
       "entrypoint": "backend/index.ts",
       "mode": "webapp",

package/templates/webapp/react-vite-hono/backend/index.ts

@@ -10,10 +10,27 @@ app.use("*", async (context, next) => {
 });
 
 app.options("*", (context) => context.body(null, 204));
-app.get("/health", (context) => context.json({ ok: true, app: "{{SLUG}}" }));
-app.get("/hello", (context) =>
-  context.json({ message: "Hello from {{APP_NAME}}" }),
-);
+
+// Path contract (APP_WORKER_PATH_REWRITE off = current default): the proxy
+// forwards /apps/{mount}/api/<x> to the worker as /<candidateSlug>/<x>, so a
+// literal app.get("/health") never matches at runtime. Normalize the candidate
+// slug prefix away and dispatch on the logical path (same convention as the
+// ssr-shop / ssr-blog / csr-bff templates).
+function norm(path: string): string {
+  return path.replace(/^\/app_[^/]+/, "") || path;
+}
+
+app.get("*", (context) => {
+  const p = norm(new URL(context.req.url).pathname);
+  if (p === "/health" || p === "/api/health") {
+    return context.json({ ok: true, app: "{{SLUG}}" });
+  }
+  if (p === "/hello" || p === "/api/hello") {
+    return context.json({ message: "Hello from {{APP_NAME}}" });
+  }
+  return context.json({ code: "NOT_FOUND", message: "Route not found", path: p }, 404);
+});
+
 app.notFound((context) =>
   context.json({ code: "NOT_FOUND", message: "Route not found" }, 404),
 );

package/templates/webapp/ssr-blog/db/rls.json

@@ -0,0 +1,13 @@
+{
+  "$comment": "Declarative RLS for the SSR blog webapp. Applied by `pxbaas app db-init` (single-tenant AND multi-tenant). table_schema is NEVER declared here: single-tenant binds it to --schema (default public); multi-tenant binds it server-side to the tenant db.",
+  "tables": [
+    { "table": "posts_ssr", "rlsEnabled": true, "rlsForced": false }
+  ],
+  "policies": [
+    { "table": "posts_ssr", "name": "posts_ssr_select_anon", "role": "anon", "command": "SELECT", "using": "`status` = 'published'", "check": null, "permissive": true },
+    { "table": "posts_ssr", "name": "posts_ssr_select_auth", "role": "authenticated", "command": "SELECT", "using": "`status` = 'published' OR author_id = {{request.jwt.claim.sub}}", "check": null, "permissive": true },
+    { "table": "posts_ssr", "name": "posts_ssr_insert_auth", "role": "authenticated", "command": "INSERT", "using": null, "check": "author_id = {{request.jwt.claim.sub}}", "permissive": true },
+    { "table": "posts_ssr", "name": "posts_ssr_update_auth", "role": "authenticated", "command": "UPDATE", "using": "author_id = {{request.jwt.claim.sub}}", "check": "author_id = {{request.jwt.claim.sub}}", "permissive": true },
+    { "table": "posts_ssr", "name": "posts_ssr_delete_auth", "role": "authenticated", "command": "DELETE", "using": "author_id = {{request.jwt.claim.sub}}", "check": null, "permissive": true }
+  ]
+}