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

package/skills/pxbaas-cli/references/auth-and-credentials.md

@@ -1,6 +1,6 @@
 # Credentials, Environment & User Management
 
-Covers: `login` (human-only) · `logout` · `whoami` · `status` · `doctor` · `profile` · `auth users`.
+Covers: `login` (human-only) · `profile import` (agent-runnable, env-file) · `logout` · `whoami` · `status` · `doctor` · `profile` · `auth users`.
 
 ## login — agents must NEVER run this
 
@@ -11,7 +11,18 @@ pxbaas login --endpoint <url> --tenant-id <id> --anon-key-stdin --service-key-st
 - **Requires an interactive TTY** (it prompts via inquirer); agents cannot complete it. **Do not attempt.**
 - Keys are read from stdin via `--anon-key-stdin` / `--service-key-stdin` so they never land in shell history.
 - Credentials are stored in the OS keyring (keytar), falling back to a `0600` file when no keyring is available.
-- If another command reports `No active profile. Use "pxbaas login" ...` → **ask the user to log in manually**. Do not work around it and do not ask for plaintext keys.
+- If another command reports `No active profile. Use "pxbaas login" ...` → **ask the user to log in manually**, OR — if a Supabase/BaaS `.env` file for the instance is available — bind it non-interactively with `pxbaas profile import <env-file>` (see below; that one IS agent-runnable).
+
+## profile import — bind a single-tenant instance from a `.env` file (agents MAY run this)
+
+```bash
+pxbaas profile import <env-file> --name <profile> [--intranet] --json
+```
+
+- Reads `SUPABASE_URL` (fallback `SUPABASE_PUBLIC_URL` / `SUPABASE_INTRANET_URL`), `SUPABASE_ANON_KEY` (fallback `ANON_KEY` / `GLOBAL_ANON_KEY`) and `SUPABASE_SERVICE_ROLE_KEY` (fallback `SERVICE_ROLE_KEY` / `GLOBAL_SERVICE_ROLE_KEY`) from the file, validates the JWTs (rejects expired keys), then writes the profile + credentials and switches current to it.
+- **Agent-runnable**: keys come from a file, never from argv/shell history, so no TTY is needed. Prefer this over `login` when you already have the instance `.env`.
+- `--intranet` prefers `SUPABASE_INTRANET_URL` (VPC-internal entrypoint) over the public URL. `--name` sets the profile name (default: global `--profile`, else `default`); an existing profile of the same name is **overwritten**.
+- **Single-tenant only for now.** A `MULTI_TENANT_MODE=true` env file is rejected with guidance — its global keys cannot access tenant resources; use `pxbaas login` with per-tenant anon/service keys instead.
 
 ## Verify login state (run these first)
 
@@ -65,6 +76,7 @@ pxbaas logout           # clears credentials for the current profile
 pxbaas profile ls --json          # list all profiles
 pxbaas profile use <name> --json  # switch current profile
 pxbaas profile rm <name> --json   # remove a profile (destructive to local config — confirm first)
+pxbaas profile import <env-file> --name <profile> --json   # bind a single-tenant instance from a .env file (agent-runnable; see above)
 ```
 
 - You can also pass global `--profile <name>` to target one environment without changing the default.

package/skills/pxbaas-cli/references/data-postgrest.md

@@ -83,3 +83,18 @@ pxbaas rest POST "/todos" --data '{"title":"x"}' --role anon --json
 ```
 
 > REST endpoint details, embedding/RPC constraints: fetch `${endpoint}/docs` — see api-reference.md.
+
+## Schema cache after DDL
+
+The REST layer (`/rest/v1`) caches each table's column list. After a DDL change
+(`ALTER TABLE ... ADD/DROP/MODIFY COLUMN`, or `CREATE`/`DROP TABLE`) the cache
+re-introspects automatically: immediately where the platform wires DDL to a
+cache reload, otherwise within one refresh interval (~30s). Until then:
+
+- `select=*` (and `Prefer: return=representation` bodies) may still omit a
+  just-added column. This is a stale column list, not an error — the row is
+  returned, only the new field is missing.
+- Workaround: enumerate columns explicitly (`?select=id,room_id,board`) instead
+  of `*`, or retry after a few seconds.
+
+`pxbaas db add-column` / `db create-table` print a reminder about this.

package/skills/pxbaas-cli/references/db-and-meta.md

@@ -19,6 +19,18 @@ pxbaas db query "SELECT count(*) FROM users" --role anon --json
 { "rows": [ { "count(*)": 42 } ], "rowCount": 1, "fields": [ { "name": "count(*)", "dataType": "BIGINT" } ] }
 ```
 - **Gotchas:** `db query` can also run write/DDL SQL. If the statement contains INSERT/UPDATE/DELETE/DROP/ALTER/CREATE, treat it as destructive and confirm with the user first.
+- **Multi-tenant:** with an MT profile (`--tenant-id`), `db query` routes through `/api/tenant-ddl/query` using the per-tenant service_role key and runs on the tenant's OWN database (`/pg/query` is platform-admin only and rejects per-tenant keys). `--role anon` is not applicable there — the tenant-ddl endpoint is service_role-only, so the query always runs as the tenant service_role. For batch DDL + RLS use `db push <file>` or `app db-init <name>` (see app-deploy.md); both are MT-aware.
+
+## db push — apply a SQL file (DDL + RLS + seed)
+
+```bash
+pxbaas db push ./db/schema.sql --schema public --dry-run   # preview the plan
+pxbaas db push ./db/schema.sql --yes                        # apply (stop-on-first-error, no rollback)
+```
+
+- **Flags:** `--schema <name>` (single-tenant `__SCHEMA__` target, default `public`) · `--rls <file>` (declarative `db/rls.json`) · `--role` (default service_role) · `--dry-run` · `--yes` · `--json`
+- Mode-aware: single-tenant runs through `/pg/query`; multi-tenant through `/api/tenant-ddl` (de-qualifies `__SCHEMA__`, diverts RLS to the structured endpoints). Shows the full plan and requires authorization; never rolls back.
+- `app db-init <name>` is the app-bundled convenience wrapper (reads `<appDir>/db/schema.sql` + `db/rls.json`).
 
 ## db tables — list tables
 

package/skills/pxbaas-cli/references/multi-tenant-apps.md

@@ -12,14 +12,20 @@ most common source of 401/403 confusion.
 | `/api/platform/*` (Studio: tenants CRUD) | **dashboard Basic Auth** (`DASHBOARD_USERNAME`/`DASHBOARD_PASSWORD`) | global service key → `401 Unauthorized` |
 | `/pg/query` (ad-hoc SQL) | **global service_role key**, sent as BOTH `Authorization: Bearer` and `apikey` | Basic Auth → 401 "apikey or Bearer required"; per-tenant key → `401` |
 | Data plane `/rest/v1`, `/auth/v1`; Management API `/v1/projects/default/*` (apps create/publish, functions deploy) | **per-tenant key** (Management API also needs `X-Tenant-Id`) | global key + `X-Tenant-Id` → `403 Global credentials cannot access tenant resources` |
+| `/api/tenant-ddl/*` (tenant self-service DDL + RLS) | **per-tenant service_role key** — send only `Authorization: Bearer`; Kong verifies the JWT and injects the trusted `X-Tenant-Id` (never send it yourself) | global key → `403 GLOBAL_KEY_NOT_ALLOWED`; per-tenant anon → `403 ROLE_NOT_ALLOWED`; suspended tenant → `403 TENANT_NOT_ACTIVE` |
+
+> RLS registry management is symmetric: `rls/tables` and `rls/policies` both support POST/GET/DELETE
+> (DELETE on `rls/tables` does not require the table to still exist, so it cleans up after a DROP).
 
 - A per-tenant anon/service key carries a `tenant_id` claim, so **REST and Auth route from the
   key alone** — `X-Tenant-Id` is optional there. Issued user JWTs carry `aud=<tenant_id>`.
 - Using tenant X's key with `X-Tenant-Id: Y` → `403 Token tenant mismatch` (gateway guardrail).
-- CLI: `pxbaas login --endpoint <url> --tenant-id <id>` with the tenant's keys gives a working
-  MT profile (`app capabilities`, `functions`, `rest` all fine), but **`pxbaas db query` returns
-  401 in MT** (the pg-meta path does not accept tenant keys). Run tenant SQL through
-  `/pg/query` with the global key, using fully-qualified `tenant_<id>.<table>` names.
+- CLI: `pxbaas login --endpoint <url> --tenant-id <id>` with the tenant's per-tenant keys gives a
+  working MT profile. As of the tenant self-service DDL capability, **`pxbaas db query`, `db push`,
+  and `app db-init` all work in MT** — they route through `/api/tenant-ddl` with the per-tenant
+  service_role key (DDL runs on the tenant's own db; the tenant MySQL account's `GRANT ALL ON
+  tenant_<id>.*` is the hard isolation boundary). The old "`db query` 401s in MT, use the global key
+  on `/pg/query`" guidance is obsolete; `/pg/query` remains platform-admin only.
 
 ## 2. Provisioning a tenant
 
@@ -63,6 +69,31 @@ curl -sS -o /dev/null -w '%{http_code}\n' -X POST "$ENDPOINT/rest/v1/posts" \
   -d '{"title":"x","author_id":"someone-else","status":"draft"}'   # expect 403 PGRST302
 ```
 
+## 3b. Tenant self-service DDL / db-init as a normal tenant
+
+A normal tenant (holding only its per-tenant service_role key — no platform admin credential) can
+initialize and tear down its own app database through the CLI:
+
+```bash
+pxbaas login --endpoint <url> --tenant-id <id>   # paste the tenant's per-tenant anon + service keys
+pxbaas app db-init <name> --dir ./apps --dry-run # preview the plan (DDL + seed + RLS)
+pxbaas app db-init <name> --dir ./apps --yes      # apply (stop-on-first-error, no rollback)
+pxbaas db query "SELECT count(*) FROM posts" --json
+pxbaas app destroy <name> --confirm --purge-db    # optional: also drop the app's tables + RLS rows
+```
+
+- `db-init`/`db push` read `db/schema.sql` (DDL + seed) and the declarative `db/rls.json` (RLS).
+  In MT the `__SCHEMA__` qualifier is dropped (the connection is already bound to the tenant db) and
+  cross-schema names are refused by GRANT.
+- **RLS is registered through the structured `/api/tenant-ddl/rls/*` endpoints**, not raw central
+  INSERTs (the tenant account has no GRANT on the shared `supabase` db). `table_schema` is bound
+  server-side to the verified tenant db — the CLI never sends it, so a tenant cannot touch another's
+  policies. If `db/rls.json` is absent, RLS INSERTs embedded in `schema.sql` are parsed and routed
+  the same way.
+- `--purge-db` DROPs the app's tables and DELETEs its RLS registry rows — both the policies and the
+  central `_mysqlrest_rls_tables` toggle (via `DELETE /api/tenant-ddl/rls/tables`). On instances that
+  predate that endpoint the toggle row is left (harmless; re-created on the next `db-init`).
+
 ## 4. Deploying a webapp into a tenant
 
 - Every Management API call needs `Authorization: Bearer <tenant service_role_key>` **and**

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

@@ -163,6 +163,7 @@
         "README.md",
         "backend/index.ts",
         "db/schema.sql",
+        "db/rls.json",
         "frontend/dist/index.html"
       ],
       "frontend": {
@@ -182,7 +183,7 @@
       },
       "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."
       ]
@@ -196,6 +197,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,7 +224,7 @@
         "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."
       ]
@@ -236,6 +238,7 @@
         "README.md",
         "backend/index.ts",
         "db/schema.sql",
+        "db/rls.json",
         "frontend/dist/index.html"
       ],
       "frontend": {
@@ -255,7 +258,7 @@
       },
       "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."
       ]

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 }
+  ]
+}

package/templates/webapp/ssr-blog/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_ssr` (
@@ -26,30 +28,8 @@ CREATE TABLE IF NOT EXISTS `__SCHEMA__`.`posts_ssr` (
   KEY `idx_posts_ssr_status` (`status`, `created_at`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
--- ---- RLS 注册 ----
-INSERT IGNORE INTO supabase._mysqlrest_rls_tables (table_schema, table_name, rls_enabled, rls_forced)
-VALUES ('__SCHEMA__','posts_ssr',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_ssr','posts_ssr_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_ssr','posts_ssr_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_ssr','posts_ssr_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_ssr','posts_ssr_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_ssr','posts_ssr_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_ssr` (title, content, author_id, author_name, status)

package/templates/webapp/ssr-hono/backend/index.ts

@@ -37,30 +37,45 @@ function esc(s: string): string {
     .split(String.fromCharCode(34)).join(""");
 }
 
-// L3 shape demo: server-side fetch of DB content via the derived internal base
-// (anon key from env; RLS enforced server-side). Degrades gracefully so the
-// shell still renders if the internal entry is ever unreachable.
-app.get("/ssr-data", async (c) => {
-  let rows: Array<Record<string, unknown>> = [];
-  let note = "";
-  try {
-    const r = await fetch(internalBase() + "/rest/v1/?select=1", {
-      headers: { apikey: Deno.env.get("SUPABASE_ANON_KEY") || "" },
-    });
-    note = `internal base reachable: http-${r.status}`;
-  } catch (e) {
-    note = `internal base unreachable: ${String(e).slice(0, 60)}`;
-  }
-  return c.html(`<!DOCTYPE html><html><head><meta charset="utf-8"><title>L3 demo</title></head><body>
+// Path contract (APP_WORKER_PATH_REWRITE off = current default): the proxy
+// forwards /apps/{mount}/api/<x> to the worker as /<candidateSlug>/<x> — the
+// candidate slug prefix is NOT stripped at runtime (the stripped path is only
+// delivered via X-Pxbaas-Worker-Path when the rewrite kill-switch is ON, which
+// is disabled by default due to the D18 streamRid regression). Normalize the
+// slug prefix away and match on the logical path, so handlers resolve under ANY
+// prefix shape (/{slug}/x, /api/x, or /x) and still work if the switch flips on.
+// Same convention as the ssr-shop / ssr-blog / csr-bff templates.
+function norm(path: string): string {
+  return path.replace(/^\/app_[^/]+/, "") || path;
+}
+
+app.get("*", async (c) => {
+  const p = norm(new URL(c.req.url).pathname);
+
+  // L3 shape demo: server-side fetch of DB content via the derived internal base
+  // (anon key from env; RLS enforced server-side). Degrades gracefully so the
+  // shell still renders if the internal entry is ever unreachable.
+  if (p === "/ssr-data") {
+    let rows: Array<Record<string, unknown>> = [];
+    let note = "";
+    try {
+      const r = await fetch(internalBase() + "/rest/v1/?select=1", {
+        headers: { apikey: Deno.env.get("SUPABASE_ANON_KEY") || "" },
+      });
+      note = `internal base reachable: http-${r.status}`;
+    } catch (e) {
+      note = `internal base unreachable: ${String(e).slice(0, 60)}`;
+    }
+    return c.html(`<!DOCTYPE html><html><head><meta charset="utf-8"><title>L3 demo</title></head><body>
 <div id="__ssr" data-ssr="v1"><h1>L3 full-SSR demo</h1><p>${esc(note)}</p><pre>${esc(JSON.stringify(rows))}</pre></div>
 </body></html>`);
-});
+  }
 
-app.get("/page", (c) => {
-  const theme = c.req.query("theme") === "dark" ? "dark" : "light";
-  const bg = theme === "dark" ? "#111" : "#fafafa";
-  const fg = theme === "dark" ? "#eee" : "#222";
-  const html = `<!DOCTYPE html><html><head><meta charset="utf-8">
+  if (p === "/page") {
+    const theme = c.req.query("theme") === "dark" ? "dark" : "light";
+    const bg = theme === "dark" ? "#111" : "#fafafa";
+    const fg = theme === "dark" ? "#eee" : "#222";
+    const html = `<!DOCTYPE html><html><head><meta charset="utf-8">
 <title>{{APP_NAME}} SSR</title>
 <style>body{font-family:sans-serif;max-width:720px;margin:40px auto;background:${bg};color:${fg}}</style>
 </head><body>
@@ -77,16 +92,20 @@ app.get("/page", (c) => {
 })();
 </script>
 </body></html>`;
-  return c.html(html);
-});
+    return c.html(html);
+  }
+
+  // JSON API. /apps/{m}/api/data and /api/health normalize to /data and /health
+  // after the slug strip; the /api-prefixed shapes are kept as a defensive
+  // fallback for deployments that deliver the logical path un-stripped.
+  if (p === "/data" || p === "/api/data") {
+    return c.json({ ok: true, engine: "hono", now: new Date().toISOString() });
+  }
+  if (p === "/health" || p === "/api/health") {
+    return c.json({ ok: true });
+  }
 
-// Path contract (APP_WORKER_PATH_REWRITE off, current default): the /api/* branch
-// delivers the STRIPPED logical path (/data, /health) while static-miss
-// fallthrough delivers the FULL logical path (/page). Register both shapes so
-// the worker behaves identically when the rewrite kill-switch is flipped back on.
-app.get("/data", (c) => c.json({ ok: true, engine: "hono", now: new Date().toISOString() }));
-app.get("/api/data", (c) => c.json({ ok: true, engine: "hono", now: new Date().toISOString() }));
-app.get("/health", (c) => c.json({ ok: true }));
-app.get("/api/health", (c) => c.json({ ok: true }));
+  return c.json({ ok: false, error: "not_found", path: p }, 404);
+});
 
 Deno.serve(app.fetch);

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

@@ -0,0 +1,16 @@
+{
+  "$comment": "Declarative RLS for the shop 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. using/check expressions may embed {{request.jwt.claim.*}} templates.",
+  "tables": [
+    { "table": "products", "rlsEnabled": true, "rlsForced": false },
+    { "table": "orders", "rlsEnabled": true, "rlsForced": false },
+    { "table": "order_items", "rlsEnabled": true, "rlsForced": false }
+  ],
+  "policies": [
+    { "table": "products", "name": "products_select_anon", "role": "anon", "command": "SELECT", "using": "1=1", "check": null, "permissive": true },
+    { "table": "products", "name": "products_select_auth", "role": "authenticated", "command": "SELECT", "using": "1=1", "check": null, "permissive": true },
+    { "table": "orders", "name": "orders_select_auth", "role": "authenticated", "command": "SELECT", "using": "`buyer_email` = {{request.jwt.claim.email}} OR {{request.jwt.claim.email}} = 'admin@shop.demo'", "check": null, "permissive": true },
+    { "table": "orders", "name": "orders_insert_auth", "role": "authenticated", "command": "INSERT", "using": null, "check": "`buyer_email` = {{request.jwt.claim.email}}", "permissive": true },
+    { "table": "order_items", "name": "order_items_select_auth", "role": "authenticated", "command": "SELECT", "using": "`buyer_email` = {{request.jwt.claim.email}} OR {{request.jwt.claim.email}} = 'admin@shop.demo'", "check": null, "permissive": true },
+    { "table": "order_items", "name": "order_items_insert_auth", "role": "authenticated", "command": "INSERT", "using": null, "check": "`buyer_email` = {{request.jwt.claim.email}}", "permissive": true }
+  ]
+}

package/templates/webapp/ssr-shop/db/schema.sql

@@ -6,15 +6,16 @@
 --   · 多租户实例：__SCHEMA__ = tenant_<tenant_id>（每租户一套库）
 --   sed 's/__SCHEMA__/public/g' db/schema.sql
 --
--- 执行通道：
---   · 单租户：pxbaas db query "<单条 SQL>" --role service_role --profile <p>
---   · 多租户：POST {endpoint}/pg/query（全局 service_role key 作 Authorization+apikey），
---             语句里必须写全限定名 tenant_<id>.<table>；pxbaas db query 在 MT 下会 401。
+-- 执行通道（推荐）：`pxbaas app db-init <name>` —— 单/多租户通用，自动：
+--   · 单租户：__SCHEMA__ → public，经 /pg/query（全局 admin）执行；
+--   · 多租户：__SCHEMA__ 去限定（连接已锁租户库），经 /api/tenant-ddl 用
+--             per-tenant service_role key 执行；GRANT 仅本租户库，天然隔离。
+--   本文件只含 DDL + 种子；RLS 声明在同目录 db/rls.json，由 db-init 一并应用。
 --
 -- ⚠️ RLS 元数据的落点（写错静默失效，等价于关闭 RLS）：
---   永远写中心库 supabase._mysqlrest_rls_tables / _mysqlrest_rls_policies，
---   且 table_schema 填 __SCHEMA__（单租户=public，多租户=tenant_<id>）。
---   租户库里由开通流程创建的同名 _mysqlrest_rls_* 表没有任何服务读取，勿写入。
+--   永远写中心库 supabase._mysqlrest_rls_tables / _mysqlrest_rls_policies。
+--   db-init 会自动绑定 table_schema（单租户=--schema，多租户=服务端强绑租户库），
+--   无需也不要手写库名。租户库内同名 _mysqlrest_rls_* 表没有任何服务读取，勿写入。
 -- =============================================================================
 
 -- ---- 表结构 ----
@@ -54,41 +55,10 @@ CREATE TABLE IF NOT EXISTS `__SCHEMA__`.`order_items` (
   created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
 );
 
--- ---- RLS 注册（中心库 supabase）----
-INSERT IGNORE INTO supabase._mysqlrest_rls_tables (table_schema, table_name, rls_enabled, rls_forced)
-VALUES ('__SCHEMA__','products',1,0), ('__SCHEMA__','orders',1,0), ('__SCHEMA__','order_items',1,0);
-
--- ---- RLS 策略 ----
--- products：公开目录，anon / authenticated 均可读
-INSERT IGNORE INTO supabase._mysqlrest_rls_policies
-  (table_schema, table_name, policy_name, role_name, command, using_expr, check_expr, permissive)
-VALUES ('__SCHEMA__','products','products_select_anon','anon','SELECT','1=1',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__','products','products_select_auth','authenticated','SELECT','1=1',NULL,1);
-
--- orders：仅本人（buyer_email = jwt.email）或管理员白名单可读；仅本人可写
-INSERT IGNORE INTO supabase._mysqlrest_rls_policies
-  (table_schema, table_name, policy_name, role_name, command, using_expr, check_expr, permissive)
-VALUES ('__SCHEMA__','orders','orders_select_auth','authenticated','SELECT',
-        '`buyer_email` = {{request.jwt.claim.email}} OR {{request.jwt.claim.email}} = ''admin@shop.demo''',
-        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__','orders','orders_insert_auth','authenticated','INSERT',NULL,
-        '`buyer_email` = {{request.jwt.claim.email}}', 1);
-
--- order_items：仅本人（buyer_email = jwt.email）或管理员白名单可读；仅本人可写（owner 门禁落在本表，
--- 不依赖前端按 order_id 过滤 —— 前端过滤不是安全边界，R2-05）。
-INSERT IGNORE INTO supabase._mysqlrest_rls_policies
-  (table_schema, table_name, policy_name, role_name, command, using_expr, check_expr, permissive)
-VALUES ('__SCHEMA__','order_items','order_items_select_auth','authenticated','SELECT',
-        '`buyer_email` = {{request.jwt.claim.email}} OR {{request.jwt.claim.email}} = ''admin@shop.demo''',
-        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__','order_items','order_items_insert_auth','authenticated','INSERT',NULL,
-        '`buyer_email` = {{request.jwt.claim.email}}', 1);
+-- ---- RLS 注册与策略：声明在同目录 db/rls.json，由 `pxbaas app db-init` 应用 ----
+--   · products：公开目录，anon / authenticated 均可读；
+--   · orders / order_items：仅本人（buyer_email = jwt.email）或管理员白名单可读，仅本人可写。
+--   （不再内联 INSERT，避免与 rls.json 双源；如需手动注册见 db/rls.json。）
 
 -- ---- 种子商品（10 件，幂等）----
 INSERT INTO `__SCHEMA__`.`products` (name, description, price_cents, stock, emoji, category)