@polardbx/pxbaas 0.0.0-stage → 0.1.0-beta.10

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

@@ -0,0 +1,61 @@
+# Storage Management (storage)
+
+Covers: `storage ls` · `storage cp` · `storage mv` · `storage rm`.
+Backed by the Storage API (capability `storage` → `${endpoint}/storage/v1`).
+
+## Path format
+
+Always `bucket/path/to/object`: the first segment is the **bucket name**, the rest is the object key (prefix).
+
+## storage ls — list buckets or objects (read-only, safe)
+
+```bash
+pxbaas storage ls --json                    # no path: list all buckets
+pxbaas storage ls my-bucket --json          # list objects in a bucket (top level)
+pxbaas storage ls my-bucket/photos --json   # list objects under a prefix
+```
+
+- **Signature:** `storage ls [path]` · **Flags:** `--json`
+- No path → buckets (name / public / created_at). With path → objects in that bucket.
+
+## storage cp — copy/upload/download (write)
+
+```bash
+pxbaas storage cp <src> <dst> [--recursive] --json
+```
+
+- **Flags:** `--recursive` · `--json`
+- Both `src` and `dst` **must include bucket + path** (e.g. `bucket/path/to/file`), otherwise it errors.
+- Supports local↔remote and remote↔remote.
+- ⚠️ write — confirm source and destination with the user (beware silent overwrite).
+
+## storage mv — move/rename (write, remote only)
+
+```bash
+pxbaas storage mv <srcBucket/srcPath> <dstBucket/dstPath> --json
+```
+
+- Moves/renames within remote storage; both ends need bucket + path.
+- ⚠️ changes object location — confirm with the user first.
+
+## storage rm — delete objects (destructive)
+
+```bash
+pxbaas storage rm <bucket/path> [--recursive] --json
+```
+
+- **Flags:** `--recursive` (delete all objects under the prefix) · `--json`
+- ⚠️ **Irreversible, no built-in gate:** run `storage ls <path>` first to confirm the objects/count → restate to the user → get explicit consent → then delete.
+  Be especially careful with `--recursive`: a wrong prefix can delete many objects.
+
+## Workflow — safe delete/overwrite
+
+```
+1) storage ls <target prefix>            # preview
+2) restate to user: bucket + path + object count + operation (rm / mv / cp overwrite)
+3) get explicit consent
+4) execute
+5) storage ls again to verify
+```
+
+> Storage endpoints (public vs authenticated, signed URLs, multi-tenant path rewriting): fetch `${endpoint}/docs` — see api-reference.md.

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

@@ -0,0 +1,76 @@
+# Troubleshooting (doctor / status + error triage)
+
+When the agent hits connection, auth, or permission problems, triage in this order — do not blindly retry or work around.
+
+## Step 1: doctor self-check
+
+```bash
+pxbaas doctor --json
+```
+
+`doctor` runs 5 checks; each returns `status` (pass/warn/fail/skip), `detail`, `duration`, and `remediation` (a fix hint):
+
+| Check | Meaning |
+|---|---|
+| **Endpoint Connectivity** | is the endpoint reachable (HTTP) |
+| **JWT Signature** | are the anon/service key JWTs well-formed and valid |
+| **JWT Expiry** | are the JWTs expired |
+| **Tenant Consistency** | in multi-tenant mode, does the key `tenant_id` match the profile (skip in single-tenant) |
+| **Permissions** | are anon / service_role usable |
+
+**Output (`--json`):**
+```json
+{
+  "profile": "local",
+  "checks": [
+    { "name": "Endpoint Connectivity", "status": "pass", "detail": "HTTP 200", "duration": 42 },
+    { "name": "JWT Expiry", "status": "warn", "detail": "anon key expires in 3 days", "duration": 1, "remediation": "Re-login before expiry" }
+  ],
+  "summary": { "pass": 4, "warn": 1, "fail": 0, "skip": 0 }
+}
+```
+
+- Any `fail` → the process exits non-zero. **Read each `remediation` first** and follow it.
+- Do not continue with data-plane commands while a check is failing — fix the root cause first.
+
+## Step 2: confirm capability URLs and identity
+
+```bash
+pxbaas status --json    # capability URLs: verify rest/auth/storage/functions/meta addresses
+pxbaas whoami --json    # verify profile / tenant / role / key fingerprints
+```
+
+## Common error triage
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| `No active profile. Use "pxbaas login"` | not logged in / no profile set | **ask the user to run `pxbaas login`** (agents cannot) |
+| `No credentials found for profile: <name>` | no credentials in keyring for that profile | same — ask the user to re-login that profile |
+| **401 Unauthorized** | invalid/expired JWT, missing apikey | check doctor's JWT Signature / Expiry / Permissions; if expired, ask the user to re-login |
+| **403 Forbidden** | insufficient role or RLS denial | confirm whether `service_role` is needed; `data`/`rest` default to anon and are RLS-constrained; do not escalate blindly — explain to the user |
+| **404 Not Found** | table/function/object/bucket does not exist, or wrong capability URL | verify with `db tables` / `functions list` / `storage ls` / `status` |
+| **429 Too Many Requests** | rate limit (esp. Edge Function quotas) | back off and retry slowly; explain the quota to the user; do not hammer |
+| tenant-related failure | key `tenant_id` ≠ profile | check doctor's Tenant Consistency; never mix credentials across profiles |
+| `tenant_suspended` (403) / `tenant_deleted` (410) | tenant not active | report to the user; this is a platform-side state, not fixable via the CLI |
+| `functions deploy` 400 / parse error | multipart `metadata` field format (see edge-functions.md known pitfall) | check whether it is a driver-layer issue; consult the platform Management API |
+| MT: `/api/platform/*` 401 | that Studio surface takes **dashboard Basic Auth**, not the global service key | `-u $DASHBOARD_USERNAME:$DASHBOARD_PASSWORD` (multi-tenant-apps.md §1) |
+| 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 | 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× |
+| `app publish` → `APP_ARTIFACT_INVALID: Candidate is already active` | idempotent re-run of the same candidate | treat as success |
+
+## Principles
+
+- **Diagnose before acting:** on any failure run `doctor --json` first and read `remediation`.
+- **Never self-rescue auth issues:** for login/credential failures, always ask the user to handle it — do not attempt `login`, do not request plaintext keys.
+- **Report faithfully:** distinguish permission / network / rate-limit / server errors; do not lump 404 as "resource missing" or treat 403 as 401.
+- **Use `--debug`:** reproduce with the global `--debug` flag for more context and share the key output with the user.
+
+> Full error-code table and multi-tenant status codes: fetch `${endpoint}/docs` — see api-reference.md.

package/templates/webapp/api/index.ts

@@ -0,0 +1,55 @@
+// {{APP_NAME}} — headless JSON backend Edge Function (Deno.serve) with ?action= routing.
+//
+// Spec: follow the `pxbaas-app-spec` skill — `pxbaas app deploy` lints this file against it.
+//
+// Deploy with:  pxbaas app deploy {{SLUG}}
+// Base URL:     {endpoint}/functions/v1/{{SLUG}}
+// Examples:     GET  ?action=health   -> { ok, now }
+//               POST ?action=echo      -> echoes the JSON body
+//
+// Guardrails: CORS enabled; JSON-only; no root-absolute asset refs (none here).
+// Extend the switch below with your own actions. Keep secrets out of a
+// verify_jwt=false function (it is publicly reachable).
+
+function corsHeaders(): Record<string, string> {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization, apikey, X-Tenant-Id",
+  };
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json", ...corsHeaders() },
+  });
+}
+
+Deno.serve(async (req: Request) => {
+  const url = new URL(req.url);
+
+  if (req.method === "OPTIONS") {
+    return new Response(null, { status: 204, headers: corsHeaders() });
+  }
+
+  const action = url.searchParams.get("action") ?? "health";
+
+  switch (action) {
+    case "health":
+      return json({ ok: true, app: "{{APP_NAME}}", now: new Date().toISOString() });
+
+    case "echo": {
+      let body: unknown = null;
+      try {
+        body = await req.json();
+      } catch {
+        return json({ ok: false, error: "invalid JSON body" }, 400);
+      }
+      return json({ ok: true, echo: body });
+    }
+
+    default:
+      return json({ ok: false, error: `unknown action: ${action}` }, 400);
+  }
+});

package/templates/webapp/csr-bff/README.md

@@ -0,0 +1,81 @@
+# {{APP_NAME}} — 前后端分离（CSR + BFF）参考模板
+
+**形态**：7 个真实静态页（`index/article/blogger/login/signup/admin/profile`）+ `style.css` + `blog.js`，由 proxy 静态分支直发（**不启 worker**）；所有数据/认证走同源 `./api/*` 打到 Deno BFF worker，worker 再转发到实例**内网**的 `/rest/v1`、`/auth/v1`。
+**会话模型**：`proxy-injected` —— 浏览器不直连 Supabase；登录经平台 `./_session/login` 建立 per-mount HttpOnly cookie，proxy 校验后向 worker 注入 `X-App-User-*`，worker 用 `X-App-User-Token` 作为下游 `Authorization`，由 GoTrue/MysqlREST 的 RLS 做最终裁决。
+
+## 为什么 BFF 不能靠"透传浏览器 Authorization"
+
+`/apps/{mount}/api/*` 走 `TRUSTED_INTERNAL` 凭据策略，proxy 会剥掉客户端的
+`authorization / cookie / apikey / x-api-key`。实测判据：同一 token 直连公网 `/auth/v1/user` 得 200，
+经 BFF 透传却得 `403 bad_jwt: invalid claim: missing sub claim` —— 说明中间层剥了头，worker 恒回落 anon。
+因此本模板的身份来源**只有**注入头：
+
+```ts
+const injected = req.headers.get("x-app-user-token") || "";   // 方案 C
+const userAuth = injected || incomingAuth;                     // 兼容 /functions 入口的透传
+```
+
+前端侧对应：登录/注册成功后追加 `fetch("./_session/login")` 建立 cookie，`clearToken()` 时
+`fetch("./_session/logout", { keepalive: true })`（`keepalive` 保证跳转后请求仍能完成）；
+端点不存在时静默忽略，以兼容旧实例与 `/functions` 入口。
+
+## 目录
+
+```
+{{APP_NAME}}/
+├── app.json                  # schemaVersion 2；fallback=null（页面都是真实静态文件）
+├── backend/index.ts          # BFF worker：/api/health /api/config /api/me /api/rest/* /api/auth/*
+├── frontend/dist/            # 7 个页面 + style.css + blog.js（相对路径引用）
+├── db/schema.sql             # 幂等数据层：posts + 5 条 RLS + 3 篇种子
+└── README.md
+```
+
+`fallback: null` 意味着静态未命中即 404（不落到 worker）；BFF 只经 `/api/*` 访问，因此不需要 SSR 探针。
+
+## 部署前必须做的一件事：填 DEPLOY CONFIG
+
+`backend/index.ts` 顶部两个常量默认为空；留空时除 `/api/health` 外一律返回
+`503 {"error":"deploy config missing"}`（刻意设计：绝不回落到任何真实实例）。
+
+```ts
+const INTERNAL_BASE = "";   // 目标实例内网基址（公网 host 去掉 http./https. 中缀）
+const ANON_KEY = "";        // 单租户=实例 anon；多租户=该租户 anon
+```
+
+worker 只用 anon 作 Kong 的 `apikey`，并把用户 JWT 原样带给下游；**从不使用 service_role**，
+因此它拿到的权限不会超过调用者本人。
+
+## 数据层
+
+```bash
+sed 's/__SCHEMA__/public/g' db/schema.sql          # 单租户
+sed 's/__SCHEMA__/tenant_acme/g' db/schema.sql     # 多租户
+```
+
+RLS 元数据写**中心库** `supabase._mysqlrest_rls_*`，`table_schema` = 上面的 `__SCHEMA__`；写错静默失效。
+
+## 部署
+
+```bash
+pxbaas app deploy {{APP_NAME}} --dir .     # appName 必须与 app.json 的 name 一致
+```
+
+走 curl Management API 时：静态文件必须用显式嵌套 `filename=frontend/dist/<name>`，否则路径被压平导致 publish 报缺文件。
+
+## 验收清单
+
+| # | 检查 | 期望 |
+|---|---|---|
+| 1 | 7 个页面 + `style.css` + `blog.js` | 全 200，content-type 正确（`text/css` / `text/javascript`） |
+| 2 | `GET /apps/{m}/api/health` | `{"ok":true,"via":"bff"}`（未配置 DEPLOY CONFIG 时也应可用） |
+| 3 | `GET /apps/{m}/api/config` | 返回的 `anon` **等于目标实例/租户的 anon**（证明参数化生效，没串到别的实例） |
+| 4 | `GET /apps/{m}/api/rest/posts` 匿名 | 只见 published |
+| 5 | `POST /apps/{m}/_session/login` | 200 + `Set-Cookie: pxbaas-app-session; Path=/apps/{m}/; HttpOnly` |
+| 6 | **只带 cookie**（不带 Authorization）`GET /api/me` | 返回完整用户对象 |
+| 7 | 带 cookie 发文（`author_id`=自己 / 他人） | 201 / **403 PGRST302** |
+| 8 | 带 cookie 读 posts | published + 自己的 draft |
+| 9 | `POST /api/../_session/logout` 后 `GET /api/me` | `{"user":null}` |
+| 10 | 双用户交替请求 | 各自只见自己（无共享 jar 串味） |
+
+> 注意：`logout` 页靠内联 JS 调 `./_session/logout`，**curl 不执行 JS**，用 curl 复验时要直接打 proxy 的退出端点。
+> 另：在容器内以 `Host: 127.0.0.1:8000` 打 `/apps/*` 会得到 `APP_HOST_REJECTED`，属预期；验证请从公网侧发起。

package/templates/webapp/csr-bff/backend/index.ts

@@ -0,0 +1,168 @@
+// mpa-blog BFF worker (front/back separated).
+//
+//   browser ──./api/*──> THIS worker ──internal DNS──> /rest/v1 + /auth/v1 ──> db / GoTrue
+//
+// The sandbox CANNOT reach the instance's public SUPABASE_URL (egress-filtered), but CAN reach
+// the internal/private DNS entry (pxsp-<id>.pxbaas...:8000 -> 10.x VPC VIP). So the worker proxies
+// browser calls to the internal Kong base. Credential model = JWT PASSTHROUGH: the browser's
+// Authorization header (GoTrue user JWT) is forwarded verbatim so MysqlREST RLS and GoTrue enforce
+// per-user rules server-side. The worker injects only the global `apikey` (anon) for Kong key-auth
+// and NEVER uses service_role, so it gains no privilege beyond the calling user.
+//
+// Static pages/assets are served by the edge-function-proxy static branch (app.json mode=mpa);
+// this worker only handles /api/*.
+
+const CORS: Record<string, string> = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, PATCH, PUT, DELETE, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization, apikey, Prefer, Range, X-Tenant-Id",
+  "Access-Control-Expose-Headers": "Content-Range, Prefer, Location",
+};
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json; charset=utf-8", ...CORS },
+  });
+}
+
+// ─── DEPLOY CONFIG（平台注入优先；缺失则除 /api/health 外一律 503，绝不回落到任何真实实例）───
+// env 契约（MR #30497903 起）：平台按三键白名单向 App candidate 注入 SUPABASE_INTERNAL_URL /
+//   SUPABASE_ANON_KEY / SUPABASE_URL，spec-lint 的 deno-env-not-allowed 放行这三键。本模板直读
+//   SUPABASE_INTERNAL_URL（数据面唯一可达基址）与 SUPABASE_ANON_KEY（数据面凭据），无需手填明文 key。
+//   若目标实例 sandbox 镜像尚未含该 MR，两值为空 → configError 明确 503，绝不静默连到别的实例/租户。
+//   INTERNAL_BASE —— 平台注入的内网基址（公网 host 去掉 http./https. 中缀）；公网 VIP 在沙箱内因
+//                    egress 过滤不可达（非 hairpin），切勿改填公网地址。
+//   ANON_KEY      —— 单租户=实例 anon key；多租户=**该租户** anon key（自带 tenant_id claim，
+//                    REST/Auth 据此路由，无需 X-Tenant-Id）。anon 是公开值；service_role 严禁入 worker。
+const INTERNAL_BASE = Deno.env.get("SUPABASE_INTERNAL_URL") ?? "";
+const ANON_KEY = Deno.env.get("SUPABASE_ANON_KEY") ?? "";
+
+function configError(): string | null {
+  if (!INTERNAL_BASE) return "SUPABASE_INTERNAL_URL not injected: the sandbox image predates MR #30497903; the platform must inject the internal base before this BFF can reach the data plane";
+  if (!ANON_KEY) return "SUPABASE_ANON_KEY not injected: the sandbox image predates MR #30497903; the platform must inject the anon key";
+  return null;
+}
+
+function anonKey(): string {
+  return ANON_KEY;
+}
+
+/** 服务端转发唯一合法通道：内网基址（见上方 DEPLOY CONFIG）。 */
+function internalBase(): string {
+  return INTERNAL_BASE.replace(/\/+$/, "");
+}
+
+/** Extract the segments after the "api" marker, robust to mount/dispatch prefix differences. */
+function apiTail(pathname: string): string[] {
+  // Mount/webapp dispatch hands the worker the candidate-slug-prefixed logical path
+  // (/{app_<uuid>_r_<rev>}/...); strip that first, then locate the "api" marker.
+  const norm = pathname.replace(/^\/app_[^/]+/, "") || pathname;
+  const segs = norm.split("/").filter(Boolean);
+  const i = segs.lastIndexOf("api");
+  if (i >= 0) return segs.slice(i + 1);
+  return segs; // fallback: whole path
+}
+
+async function readBody(req: Request): Promise<BodyInit | null> {
+  if (req.method === "GET" || req.method === "HEAD" || req.method === "OPTIONS") return null;
+  try {
+    return await req.arrayBuffer();
+  } catch {
+    return null;
+  }
+}
+
+/** Forward a request to the internal Kong base, injecting apikey and passing through the user's JWT. */
+async function proxy(req: Request, internalPath: string, search: string): Promise<Response> {
+  const base = internalBase();
+  const url = base + internalPath + (search || "");
+  const anon = anonKey();
+  // /apps/{mount}/api/* runs under TRUSTED_INTERNAL, which strips the browser's
+  // Authorization/Cookie before the worker ever sees them, so plain JWT passthrough
+  // cannot work on that entry. There the proxy validates the per-mount session
+  // cookie and injects the trusted X-App-User-Token instead. Prefer the injected
+  // token, fall back to a passed-through Authorization (/functions entry), then to
+  // anon for public reads.
+  const injected = req.headers.get("x-app-user-token") || "";
+  const incomingAuth = req.headers.get("Authorization") || "";
+  const userAuth = injected || incomingAuth;
+  const authValue = userAuth
+    ? (/^Bearer\s+/i.test(userAuth) ? userAuth : `Bearer ${userAuth}`)
+    : (anon ? `Bearer ${anon}` : "");
+
+  const headers: Record<string, string> = {
+    "apikey": anon,
+    // Forward the caller's JWT (RLS/GoTrue act on it); fall back to anon for public reads.
+    "Authorization": authValue,
+    "Accept": req.headers.get("Accept") || "application/json",
+  };
+  const ct = req.headers.get("Content-Type");
+  if (ct) headers["Content-Type"] = ct;
+  const prefer = req.headers.get("Prefer");
+  if (prefer) headers["Prefer"] = prefer;
+
+  const body = await readBody(req);
+  let upstream: Response;
+  try {
+    upstream = await fetch(url, { method: req.method, headers, body });
+  } catch (e) {
+    const msg = String((e as any)?.message ?? e);
+    return json({ error: "upstream_unreachable", detail: msg, internalBase: base, internalPath }, 502);
+  }
+
+  const respHeaders: Record<string, string> = { ...CORS };
+  const rct = upstream.headers.get("Content-Type");
+  if (rct) respHeaders["Content-Type"] = rct;
+  for (const h of ["Content-Range", "Prefer", "Location"]) {
+    const v = upstream.headers.get(h);
+    if (v) respHeaders[h] = v;
+  }
+  // 204/205/304 are "null body" statuses: constructing a Response with a body throws.
+  // PostgREST returns 204 for DELETE/PATCH without Prefer: return=representation.
+  if (upstream.status === 204 || upstream.status === 205 || upstream.status === 304) {
+    return new Response(null, { status: upstream.status, headers: respHeaders });
+  }
+  const payload = await upstream.arrayBuffer().catch(() => new ArrayBuffer(0));
+  return new Response(payload, { status: upstream.status, headers: respHeaders });
+}
+
+Deno.serve(async (req: Request): Promise<Response> => {
+  if (req.method === "OPTIONS") return new Response(null, { status: 204, headers: CORS });
+
+  const url = new URL(req.url);
+  const tail = apiTail(url.pathname);
+  const head = (tail[0] || "").toLowerCase();
+  const search = url.search || "";
+
+  // ---- worker-local endpoints ----
+  if (head === "health") return json({ ok: true, now: new Date().toISOString(), via: "bff" });
+  const cfgErr = configError();
+  if (cfgErr) return json({ error: "deploy config missing", detail: cfgErr }, 503);
+  if (head === "config") return json({ anon: anonKey(), mode: "bff" });
+  if (head === "me") {
+    // Server-side session check via internal GoTrue, using the caller's JWT.
+    const r = await proxy(req, "/auth/v1/user", "");
+    if (r.status !== 200) return json({ user: null });
+    try {
+      const u = await r.clone().json();
+      return json({ user: u && u.id ? u : null });
+    } catch {
+      return json({ user: null });
+    }
+  }
+
+  // ---- generic authenticated proxies ----
+  // /api/rest/<rest...>  -> internal /rest/v1/<rest...>
+  if (head === "rest") {
+    const sub = tail.slice(1).join("/");
+    return proxy(req, "/rest/v1/" + sub, search);
+  }
+  // /api/auth/<auth...>  -> internal /auth/v1/<auth...>
+  if (head === "auth") {
+    const sub = tail.slice(1).join("/");
+    return proxy(req, "/auth/v1/" + sub, search);
+  }
+
+  return json({ error: "not found", path: url.pathname, tail }, 404);
+});

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

@@ -0,0 +1,49 @@
+-- =============================================================================
+-- multi-page-blog-csr — 数据层（幂等，可重复执行）
+--
+-- 用法：把 __SCHEMA__ 替换为目标库名后逐条执行
+--   · 单租户实例：__SCHEMA__ = public
+--   · 多租户实例：__SCHEMA__ = tenant_<tenant_id>
+--   sed 's/__SCHEMA__/public/g' db/schema.sql
+--
+-- 执行通道（推荐）：`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_*；
+--    db-init 自动绑定 table_schema（单租户=--schema，多租户=服务端强绑），勿手写库名。
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS `__SCHEMA__`.`posts` (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  title VARCHAR(200) NOT NULL,
+  content MEDIUMTEXT,
+  author_id VARCHAR(64) NOT NULL,
+  author_name VARCHAR(100) DEFAULT '',
+  status VARCHAR(16) DEFAULT 'draft',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+-- ---- 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)
+SELECT * FROM (
+  SELECT '前后端分离的博客长什么样' a,
+         '静态多页 + BFF worker：浏览器只跟自己同源的 ./api/* 说话，worker 再转发到内网 REST/Auth，凭据由平台注入的身份头承载，RLS 在服务端兜底。' b,
+         'demo-author' c, '架构笔记' d, 'published' e
+  UNION ALL SELECT '为什么浏览器不该直连数据库网关',
+         '直连意味着 anon key 与用户 JWT 都暴露在页面里，跨域与凭据边界都变复杂；走同源 BFF 后前端只需相对路径，权限判定全部落在服务端。',
+         'demo-author', '安全', 'published'
+  UNION ALL SELECT 'CSR 与 SSR 的取舍',
+         'CSR 首屏靠 JS 拉数据，利于交互复杂、SEO 要求不高的页面；SSR 首屏即内容，利于分享与收录。两者可共存于同一套数据层与 RLS 策略之上。',
+         'demo-author', '随笔', 'published'
+) t WHERE NOT EXISTS (SELECT 1 FROM `__SCHEMA__`.`posts` WHERE title='前后端分离的博客长什么样');
+
+-- ---- 验收 ----
+-- 1) anon 读 posts → 只见 3 篇 published；
+-- 2) 用户 token 写 posts（author_id=自己）→ 201；伪造他人 author_id → 403 PGRST302；
+-- 3) 用户读 posts → 3 篇 published + 自己的 draft。