@polardbx/pxbaas 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/tenant/probe.js

@@ -0,0 +1,159 @@
+/**
+ * 平台管理面能力探测（tenant probe）。
+ *
+ * 为什么要它：`profile import` / `login` 撞墙时，CLI 必须先知道"这个人到底是不是
+ * 管理员"才能给出正确的下一步。判据不能用"本机有没有 DASHBOARD_* 凭据"——持有凭据
+ * 与被授予权限是两件事（运维把服务端全量 env 发给客户排查问题，客户就"被管理员"了）。
+ * 所以这里用一次**只读**调用去问平台，按回答分流。
+ *
+ * 关键陷阱（方案文档 G3）：Studio 的列表接口在「元数据查询失败」时同样返回
+ * `200 + { tenants: [], multiTenantMode: true }`（见 pages/api/platform/tenants/index.ts
+ * 的三处 200 空返回）。只看 HTTP 状态会把"平台库有问题/存量 schema 漂移"误报成
+ * "你没有权限 / 这个实例没有租户"。本模块用详情接口做二次判别：
+ *   GET /api/platform/tenants/{不存在的 id}
+ *     → 404  = 查询链路健康 ⇒ 空列表确实是"没有租户"
+ *     → 500  = 查询本身失败 ⇒ 元数据不可读（多半是 schema 漂移）
+ * 这条判据来自 [id].ts 的实现（result.error → 500，未找到 → 404），非猜测。
+ */
+import { TenantAdminDriver, TenantAdminError, } from '@polardbx/pxbaas-client';
+import { CredentialStore, ProfileManager } from '../credentials/index.js';
+/** 探测用的哨兵租户 ID：合法字符集内、且按命名规范不可能真实存在。 */
+const METADATA_PROBE_ID = '__pxbaas_probe__';
+/**
+ * 从当前（或指定）profile 的钥匙串账目里取管理凭据。
+ * 缺失时抛可直接展示的错误 —— 调用方不需要再判断"是 CLI 坏了还是没登录"。
+ */
+export async function loadAdminContext(options = {}) {
+    const profiles = new ProfileManager();
+    const profile = options.profile
+        ? await profiles.getProfile(options.profile)
+        : await profiles.getCurrentProfile();
+    if (!profile) {
+        throw new Error(options.profile
+            ? `Profile '${options.profile}' not found. Run "pxbaas profile ls" to list profiles.`
+            : 'No active profile. Run "pxbaas login" or "pxbaas tenant login --endpoint <url>" first.');
+    }
+    const store = new CredentialStore();
+    const admin = await store.getAdminCredentials(profile.name);
+    if (!admin) {
+        throw new Error(`Profile '${profile.name}' has no platform admin credentials. ` +
+            `Run "pxbaas tenant login --endpoint ${profile.endpoint}" (or add --with-admin to "pxbaas profile import") ` +
+            `with the instance dashboard credentials.`);
+    }
+    return {
+        endpoint: profile.endpoint,
+        username: admin.username,
+        password: admin.password,
+        profileName: profile.name,
+    };
+}
+/** 用给定凭据探测管理面能力。纯只读：不会发出任何写请求。 */
+export async function probeTenantAdmin(input) {
+    const driver = new TenantAdminDriver({
+        endpoint: input.endpoint,
+        username: input.username,
+        password: input.password,
+        timeout: input.timeout,
+    });
+    let tenants;
+    let multiTenantMode;
+    try {
+        const listed = await driver.list();
+        tenants = listed.tenants;
+        multiTenantMode = listed.multiTenantMode;
+    }
+    catch (error) {
+        return classifyFailure(input.endpoint, error);
+    }
+    if (!multiTenantMode) {
+        return {
+            status: 'single-tenant',
+            adminCapable: false,
+            endpoint: input.endpoint,
+            multiTenantMode: false,
+            detail: 'This instance is not in multi-tenant mode (multiTenantMode=false). Tenant administration does not apply here.',
+        };
+    }
+    if (tenants.length === 0) {
+        // 空列表有两种成因，必须用详情接口判别，否则会把平台故障报成"没有租户"。
+        const health = await probeMetadataHealth(driver);
+        if (!health.readable) {
+            return {
+                status: 'metadata-unreadable',
+                adminCapable: false,
+                endpoint: input.endpoint,
+                multiTenantMode: true,
+                tenants: [],
+                errorCode: health.errorCode,
+                detail: 'Credentials are accepted, but the tenant metadata could not be read ' +
+                    `(${health.errorCode ?? 'unknown error'}). On long-lived instances this usually means schema drift ` +
+                    '(e.g. a missing column in _platform.tenants) rather than an empty tenant list. ' +
+                    'Verify with the platform operator before retrying.',
+            };
+        }
+        return {
+            status: 'admin',
+            adminCapable: true,
+            endpoint: input.endpoint,
+            multiTenantMode: true,
+            tenants: [],
+            detail: 'Admin channel works. This instance has no tenants yet — you can create the first one with "pxbaas tenant create".',
+        };
+    }
+    return {
+        status: 'admin',
+        adminCapable: true,
+        endpoint: input.endpoint,
+        multiTenantMode: true,
+        tenants,
+        detail: `Admin channel works. ${tenants.length} tenant(s) visible on this instance.`,
+    };
+}
+async function probeMetadataHealth(driver) {
+    try {
+        await driver.get(METADATA_PROBE_ID);
+        // 哨兵 ID 竟然存在：极不可能，但存在即说明查询链路是通的。
+        return { readable: true };
+    }
+    catch (error) {
+        if (error instanceof TenantAdminError) {
+            // 404 ⇒ 查询执行成功且没找到 ⇒ 链路健康
+            if (error.code === 'TENANT_NOT_FOUND')
+                return { readable: true, errorCode: error.code };
+            return { readable: false, errorCode: error.code };
+        }
+        return { readable: false };
+    }
+}
+function classifyFailure(endpoint, error) {
+    const adminError = error instanceof TenantAdminError
+        ? error
+        : new TenantAdminError('TENANT_ADMIN_UNKNOWN_ERROR', error instanceof Error ? error.message : String(error));
+    if (adminError.code === 'TENANT_ADMIN_UNAUTHORIZED' || adminError.code === 'TENANT_ADMIN_FORBIDDEN') {
+        return {
+            status: 'not-admin',
+            adminCapable: false,
+            endpoint,
+            multiTenantMode: false,
+            errorCode: adminError.code,
+            detail: 'These credentials are not accepted by the tenant admin channel ' +
+                `(${adminError.code}, HTTP ${adminError.status ?? 'n/a'}). ` +
+                'Tenant administration needs the instance dashboard credentials, not an API key.',
+        };
+    }
+    // 注意：多租户关闭的信号是列表响应里的 `multiTenantMode: false`（GET 集合接口对
+    // 非多租户实例返回 200 + 空数组），**不是** HTTP 400 —— 400 只出现在写操作分支
+    // ("Multi-tenant mode is not enabled")。所以这里不能把 400 解读成单租户实例，
+    // 否则等于凭一个猜测替用户下结论。400 归到"端点没按预期应答"。
+    return {
+        status: 'unreachable',
+        adminCapable: false,
+        endpoint,
+        multiTenantMode: false,
+        errorCode: adminError.code,
+        detail: adminError.code === 'TENANT_ADMIN_BAD_REQUEST'
+            ? `Tenant admin channel answered 400: ${adminError.message}. This instance did not report multi-tenant mode, so no tenant operation was attempted.`
+            : `Tenant admin channel could not be reached: ${adminError.message}`,
+    };
+}
+//# sourceMappingURL=probe.js.map

package/dist/tenant/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../../src/tenant/probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,GAEjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAoB,MAAM,yBAAyB,CAAC;AAE5F,wCAAwC;AACxC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAmC7C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,UAAgC,EAAE;IACvE,MAAM,QAAQ,GAAG,IAAI,cAAc,EAAE,CAAC;IACtC,MAAM,OAAO,GAAuB,OAAO,CAAC,OAAO;QACjD,CAAC,CAAC,MAAM,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC;QAC5C,CAAC,CAAC,MAAM,QAAQ,CAAC,iBAAiB,EAAE,CAAC;IAEvC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,OAAO,CAAC,OAAO;YACb,CAAC,CAAC,YAAY,OAAO,CAAC,OAAO,wDAAwD;YACrF,CAAC,CAAC,wFAAwF,CAC7F,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;IACpC,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,YAAY,OAAO,CAAC,IAAI,uCAAuC;YAC7D,uCAAuC,OAAO,CAAC,QAAQ,qDAAqD;YAC5G,0CAA0C,CAC7C,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,WAAW,EAAE,OAAO,CAAC,IAAI;KAC1B,CAAC;AACJ,CAAC;AAUD,kCAAkC;AAClC,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAiB;IACtD,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC;QACnC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC,CAAC;IAEH,IAAI,OAAyB,CAAC;IAC9B,IAAI,eAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACnC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QACzB,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;IAC3C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,eAAe,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAChD,CAAC;IAED,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO;YACL,MAAM,EAAE,eAAe;YACvB,YAAY,EAAE,KAAK;YACnB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,eAAe,EAAE,KAAK;YACtB,MAAM,EACJ,+GAA+G;SAClH,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,uCAAuC;QACvC,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrB,OAAO;gBACL,MAAM,EAAE,qBAAqB;gBAC7B,YAAY,EAAE,KAAK;gBACnB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,eAAe,EAAE,IAAI;gBACrB,OAAO,EAAE,EAAE;gBACX,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,MAAM,EACJ,sEAAsE;oBACtE,IAAI,MAAM,CAAC,SAAS,IAAI,eAAe,6DAA6D;oBACpG,iFAAiF;oBACjF,oDAAoD;aACvD,CAAC;QACJ,CAAC;QACD,OAAO;YACL,MAAM,EAAE,OAAO;YACf,YAAY,EAAE,IAAI;YAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,eAAe,EAAE,IAAI;YACrB,OAAO,EAAE,EAAE;YACX,MAAM,EACJ,mHAAmH;SACtH,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM,EAAE,OAAO;QACf,YAAY,EAAE,IAAI;QAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,eAAe,EAAE,IAAI;QACrB,OAAO;QACP,MAAM,EAAE,wBAAwB,OAAO,CAAC,MAAM,sCAAsC;KACrF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,mBAAmB,CAChC,MAAyB;IAEzB,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;QACpC,iCAAiC;QACjC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;YACtC,0BAA0B;YAC1B,IAAI,KAAK,CAAC,IAAI,KAAK,kBAAkB;gBAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;YACxF,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QACpD,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,QAAgB,EAAE,KAAc;IACvD,MAAM,UAAU,GACd,KAAK,YAAY,gBAAgB;QAC/B,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,IAAI,gBAAgB,CAClB,4BAA4B,EAC5B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC;IAER,IAAI,UAAU,CAAC,IAAI,KAAK,2BAA2B,IAAI,UAAU,CAAC,IAAI,KAAK,wBAAwB,EAAE,CAAC;QACpG,OAAO;YACL,MAAM,EAAE,WAAW;YACnB,YAAY,EAAE,KAAK;YACnB,QAAQ;YACR,eAAe,EAAE,KAAK;YACtB,SAAS,EAAE,UAAU,CAAC,IAAI;YAC1B,MAAM,EACJ,iEAAiE;gBACjE,IAAI,UAAU,CAAC,IAAI,UAAU,UAAU,CAAC,MAAM,IAAI,KAAK,KAAK;gBAC5D,iFAAiF;SACpF,CAAC;IACJ,CAAC;IAED,wDAAwD;IACxD,uDAAuD;IACvD,6DAA6D;IAC7D,oCAAoC;IACpC,OAAO;QACL,MAAM,EAAE,aAAa;QACrB,YAAY,EAAE,KAAK;QACnB,QAAQ;QACR,eAAe,EAAE,KAAK;QACtB,SAAS,EAAE,UAAU,CAAC,IAAI;QAC1B,MAAM,EACJ,UAAU,CAAC,IAAI,KAAK,0BAA0B;YAC5C,CAAC,CAAC,sCAAsC,UAAU,CAAC,OAAO,yFAAyF;YACnJ,CAAC,CAAC,8CAA8C,UAAU,CAAC,OAAO,EAAE;KACzE,CAAC;AACJ,CAAC"}

package/dist/tenant/verify.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 建租户后的验证闭环（方案文档 G4）。
+ *
+ * 平台侧的建租户接口会把「建库 / 建账号 / GRANT / 租户库内 RLS 表 / Realtime 注册」
+ * 全部当作**非致命**步骤：任何一步失败只 console.error，HTTP 仍然返回 201
+ * （pages/api/platform/tenants/index.ts:265 起）。也就是说"创建成功"并不等于
+ * "这个租户可用"。CLI 若在 create 之后直接报成功，管理员就会把平台缺陷当成 CLI 的 bug。
+ *
+ * 这里用新签发的**租户自己的** service_role key 走一遍租户自助 DDL 通道，逐项确认：
+ *   1. SELECT DATABASE()      ⇒ 密钥有效、租户处于 active、自助 DDL 通道可用，并拿到真实库名
+ *   2. information_schema 计数 ⇒ 租户库确实存在且可内省（0 张表对新租户是正常的）
+ *   3. RLS 注册表可读          ⇒ 中心 RLS 元数据对该租户可达（RLS 落库的前置条件）
+ * 三条都是只读语句，不改变任何状态。
+ */
+export type VerifyStatus = 'pass' | 'fail' | 'skip';
+export interface VerifyStep {
+    name: string;
+    status: VerifyStatus;
+    detail: string;
+    /** 失败时给管理员的可执行补救建议。 */
+    remediation?: string;
+}
+export interface VerifyTenantResult {
+    ok: boolean;
+    /** 租户实际生效的库名（来自 SELECT DATABASE()，非拼接推断）。 */
+    dbName?: string;
+    steps: VerifyStep[];
+}
+export interface VerifyTenantInput {
+    endpoint: string;
+    serviceRoleKey: string;
+    /** create 响应里的 realtime_provisioned；为 false 时记为 warn 级步骤（平台侧非致命）。 */
+    realtimeProvisioned?: boolean;
+    timeout?: number;
+}
+export declare function verifyTenantUsable(input: VerifyTenantInput): Promise<VerifyTenantResult>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/tenant/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/tenant/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAkH9F"}

package/dist/tenant/verify.js

@@ -0,0 +1,132 @@
+/**
+ * 建租户后的验证闭环（方案文档 G4）。
+ *
+ * 平台侧的建租户接口会把「建库 / 建账号 / GRANT / 租户库内 RLS 表 / Realtime 注册」
+ * 全部当作**非致命**步骤：任何一步失败只 console.error，HTTP 仍然返回 201
+ * （pages/api/platform/tenants/index.ts:265 起）。也就是说"创建成功"并不等于
+ * "这个租户可用"。CLI 若在 create 之后直接报成功，管理员就会把平台缺陷当成 CLI 的 bug。
+ *
+ * 这里用新签发的**租户自己的** service_role key 走一遍租户自助 DDL 通道，逐项确认：
+ *   1. SELECT DATABASE()      ⇒ 密钥有效、租户处于 active、自助 DDL 通道可用，并拿到真实库名
+ *   2. information_schema 计数 ⇒ 租户库确实存在且可内省（0 张表对新租户是正常的）
+ *   3. RLS 注册表可读          ⇒ 中心 RLS 元数据对该租户可达（RLS 落库的前置条件）
+ * 三条都是只读语句，不改变任何状态。
+ */
+import { TenantDdlDriver, TenantDdlError } from '@polardbx/pxbaas-client';
+export async function verifyTenantUsable(input) {
+    const driver = new TenantDdlDriver({
+        endpoint: input.endpoint,
+        serviceRoleKey: input.serviceRoleKey,
+        timeout: input.timeout ?? 30_000,
+    });
+    const steps = [];
+    let dbName;
+    // 1) 租户自助 DDL 通道 + 密钥有效性
+    let channelOk = false;
+    try {
+        const rows = (await driver.query('SELECT DATABASE() AS db'));
+        const value = rows?.[0]?.db;
+        dbName = typeof value === 'string' && value ? value : undefined;
+        channelOk = Boolean(dbName);
+        steps.push({
+            name: 'Tenant DDL channel',
+            status: channelOk ? 'pass' : 'fail',
+            detail: channelOk
+                ? `Connected as tenant database "${dbName}"`
+                : 'SELECT DATABASE() returned no database name',
+            remediation: channelOk
+                ? undefined
+                : 'Verify the tenant is active and that the key belongs to this tenant (pxbaas doctor --json).',
+        });
+    }
+    catch (error) {
+        steps.push({
+            name: 'Tenant DDL channel',
+            status: 'fail',
+            detail: describe(error),
+            remediation: 'The tenant database or its account may not have been provisioned. Platform-side tenant creation treats those steps as non-fatal, so a 201 response does not guarantee a usable tenant — ask the operator to check the tenant db, user and GRANT.',
+        });
+    }
+    // 2) 库可内省（存在性代理判据：能查 information_schema 即库已在）
+    if (channelOk) {
+        try {
+            const rows = (await driver.query('SELECT COUNT(*) AS t FROM information_schema.tables WHERE table_schema = DATABASE()'));
+            const count = Number(rows?.[0]?.t ?? NaN);
+            steps.push({
+                name: 'Tenant database introspectable',
+                status: Number.isFinite(count) ? 'pass' : 'fail',
+                detail: Number.isFinite(count)
+                    ? `${count} table(s) currently in "${dbName}"`
+                    : 'Count query returned an unexpected shape',
+            });
+        }
+        catch (error) {
+            steps.push({
+                name: 'Tenant database introspectable',
+                status: 'fail',
+                detail: describe(error),
+                remediation: 'Create tables with "pxbaas db push <file>" or "pxbaas app db-init <name>".',
+            });
+        }
+    }
+    else {
+        steps.push({
+            name: 'Tenant database introspectable',
+            status: 'skip',
+            detail: 'Skipped because the DDL channel is not usable.',
+        });
+    }
+    // 3) 中心 RLS 注册表对该租户可达
+    if (channelOk) {
+        try {
+            const tables = await driver.listRlsTables();
+            steps.push({
+                name: 'RLS registry reachable',
+                status: 'pass',
+                detail: `${tables.length} RLS-registered table(s) for this tenant`,
+            });
+        }
+        catch (error) {
+            steps.push({
+                name: 'RLS registry reachable',
+                status: 'fail',
+                detail: describe(error),
+                remediation: 'RLS metadata may not be initialized for this tenant. Register policies through "pxbaas db push --rls db/rls.json" (multi-tenant binds table_schema server-side).',
+            });
+        }
+    }
+    else {
+        steps.push({ name: 'RLS registry reachable', status: 'skip', detail: 'Skipped (channel unavailable).' });
+    }
+    // 4) Realtime 注册（平台侧非致命；false 时该租户 WS 握手会 403）
+    if (input.realtimeProvisioned === undefined) {
+        steps.push({
+            name: 'Realtime registration',
+            status: 'skip',
+            detail: 'Not reported by this endpoint (only the create response carries it).',
+        });
+    }
+    else {
+        steps.push({
+            name: 'Realtime registration',
+            status: input.realtimeProvisioned ? 'pass' : 'fail',
+            detail: input.realtimeProvisioned
+                ? 'Tenant registered for Realtime'
+                : 'Realtime registration failed (platform-side, non-fatal for REST/Auth)',
+            remediation: input.realtimeProvisioned
+                ? undefined
+                : 'WebSocket subscriptions for this tenant will be rejected until it is registered in Realtime; ask the operator to re-run registration.',
+        });
+    }
+    return {
+        ok: steps.every((step) => step.status !== 'fail'),
+        dbName,
+        steps,
+    };
+}
+function describe(error) {
+    if (error instanceof TenantDdlError)
+        return `${error.code}: ${error.message}`;
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=verify.js.map

package/dist/tenant/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/tenant/verify.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Runtime CLI version resolution.
+ *
+ * `npm run build` is a plain `tsc --build`, so there is no bundler step that
+ * could inline `package.json#version` into the emitted JS — and adding one is
+ * out of the question for a build pipeline this simple. Read the manifest from
+ * disk instead, walking up from this module so every supported layout works:
+ *
+ *   - source tree : <pkg>/dist/version.js  -> <pkg>/package.json
+ *   - npm install : node_modules/@polardbx/pxbaas/dist/version.js -> .../package.json
+ *
+ * The walk-up must not stop at the first manifest it finds: in a monorepo the
+ * workspace root (`cli/package.json`, version `0.0.0-dev`) is also an ancestor,
+ * which is exactly how `--version` used to report a version nobody published.
+ * Only the manifest that owns this package (matching `name`, or declaring the
+ * `pxbaas` bin) counts.
+ *
+ * Never throws: an unreadable manifest must not stop `pxbaas --help`.
+ */
+export declare const PACKAGE_NAME = "@polardbx/pxbaas";
+/** Reported when no owning manifest can be found (e.g. a single-file bundle). */
+export declare const UNKNOWN_VERSION = "0.0.0-unknown";
+/**
+ * The published version of this CLI, or {@link UNKNOWN_VERSION} when it cannot be
+ * determined. Synchronous on purpose: commander's `.version()` is wired up at
+ * module scope, before any await could run.
+ */
+export declare function resolvePackageVersion(startDir?: string): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,eAAO,MAAM,YAAY,qBAAqB,CAAC;AAE/C,iFAAiF;AACjF,eAAO,MAAM,eAAe,kBAAkB,CAAC;AA8B/C;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,GAAE,MAAoB,GAAG,MAAM,CAY5E"}

package/dist/version.js

@@ -0,0 +1,65 @@
+/**
+ * Runtime CLI version resolution.
+ *
+ * `npm run build` is a plain `tsc --build`, so there is no bundler step that
+ * could inline `package.json#version` into the emitted JS — and adding one is
+ * out of the question for a build pipeline this simple. Read the manifest from
+ * disk instead, walking up from this module so every supported layout works:
+ *
+ *   - source tree : <pkg>/dist/version.js  -> <pkg>/package.json
+ *   - npm install : node_modules/@polardbx/pxbaas/dist/version.js -> .../package.json
+ *
+ * The walk-up must not stop at the first manifest it finds: in a monorepo the
+ * workspace root (`cli/package.json`, version `0.0.0-dev`) is also an ancestor,
+ * which is exactly how `--version` used to report a version nobody published.
+ * Only the manifest that owns this package (matching `name`, or declaring the
+ * `pxbaas` bin) counts.
+ *
+ * Never throws: an unreadable manifest must not stop `pxbaas --help`.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const PACKAGE_NAME = '@polardbx/pxbaas';
+/** Reported when no owning manifest can be found (e.g. a single-file bundle). */
+export const UNKNOWN_VERSION = '0.0.0-unknown';
+/** How many parent directories to probe before giving up. */
+const MAX_WALK_DEPTH = 8;
+function moduleDir() {
+    return dirname(fileURLToPath(import.meta.url));
+}
+function readManifest(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** True when the manifest belongs to this CLI package rather than an ancestor workspace. */
+function ownsThisPackage(manifest) {
+    if (manifest.name === PACKAGE_NAME)
+        return true;
+    const bin = manifest.bin;
+    return typeof bin === 'object' && bin !== null && 'pxbaas' in bin;
+}
+/**
+ * The published version of this CLI, or {@link UNKNOWN_VERSION} when it cannot be
+ * determined. Synchronous on purpose: commander's `.version()` is wired up at
+ * module scope, before any await could run.
+ */
+export function resolvePackageVersion(startDir = moduleDir()) {
+    let dir = startDir;
+    for (let i = 0; i < MAX_WALK_DEPTH; i += 1) {
+        const manifest = readManifest(dir);
+        if (manifest && ownsThisPackage(manifest)) {
+            return manifest.version ?? UNKNOWN_VERSION;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return UNKNOWN_VERSION;
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,CAAC,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAE/C,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;AAE/C,6DAA6D;AAC7D,MAAM,cAAc,GAAG,CAAC,CAAC;AAQzB,SAAS,SAAS;IAChB,OAAO,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,YAAY,CAAC,GAAW;IAC/B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAoB,CAAC;IACxF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,4FAA4F;AAC5F,SAAS,eAAe,CAAC,QAAyB;IAChD,IAAI,QAAQ,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IAChD,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC;IACzB,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,QAAQ,IAAI,GAAG,CAAC;AACpE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB,SAAS,EAAE;IAClE,IAAI,GAAG,GAAG,QAAQ,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,cAAc,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,QAAQ,IAAI,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1C,OAAO,QAAQ,CAAC,OAAO,IAAI,eAAe,CAAC;QAC7C,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polardbx/pxbaas",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "description": "PolarDB-X BaaS CLI application",
   "keywords": [
     "polardbx",
@@ -35,7 +35,7 @@
     "inquirer": "^9.2.0",
     "jsonwebtoken": "^9.0.0",
     "keytar": "^7.9.0",
-    "@polardbx/pxbaas-client": "0.1.0-beta.2"
+    "@polardbx/pxbaas-client": "0.1.0-beta.4"
   },
   "devDependencies": {
     "@types/inquirer": "^9.0.0",

package/skills/pxbaas-app-spec/references/runtime-contract.md

@@ -98,7 +98,7 @@ Apps may declare `frontend.fallback: "worker"` in app.json: static-miss non-`/ap
 - **React SSR emits no event handlers**: `renderToString` drops every `on*` prop (lowercase `onclick` included). Wire interactivity with `data-*` attributes (passed through verbatim) plus one client-side delegated listener; verify by grepping the served HTML for the attribute, not by reading component code.
 - **MUST** fetch data client-side after hydration (relative `./api/*` or the instance REST/Auth URLs with the user's JWT) for the default SSR-shell shape. For server-side data fetching (L3 full SSR / SEO first paint), **MUST** use the platform-injected `SUPABASE_INTERNAL_URL` as the base — it is the ONLY origin reachable from inside the sandbox (the public `SUPABASE_URL` is egress-filtered and cluster service names do not resolve). The platform derives `SUPABASE_INTERNAL_URL` from the public host via DX-12 (edge-runtime `app-env.ts`, MR #30497903); the worker just reads it and **MUST NOT** re-derive from `SUPABASE_URL` or fetch `SUPABASE_URL` directly. Use `SUPABASE_ANON_KEY` (or the forwarded user JWT) as the credential; server-side RLS still applies on the internal base. These three public keys reach App candidate workers only on sandbox images carrying MR #30497903 — degrade gracefully (render the shell without server data) when `SUPABASE_INTERNAL_URL` is empty.
 - SSR responses are `private, no-cache` with the platform CSP (inline hydrate scripts allowed); do not rely on shared caching of rendered pages.
-- **Path shapes (interim contract while `APP_WORKER_PATH_REWRITE` is off)**: the `/api/*` branch delivers the STRIPPED logical path to the worker (`/apps/{m}/api/data` → worker sees `/data`), while static-miss fallthrough delivers the FULL logical path (`/apps/{m}/page` → worker sees `/page`). Workers MUST register both the stripped and `/api`-prefixed shapes for every JSON endpoint (the `ssr-hono` template does); hydrate scripts calling `./api/*` from an SSR page rely on the stripped shape being routed.
+- **Path shapes (current default, `APP_WORKER_PATH_REWRITE` OFF)**: the proxy forwards EVERY worker request as `/<candidateSlug>/<logicalPath>` — the candidate slug prefix is **not** stripped at runtime. So `/apps/{m}/api/data` reaches the worker as `/<candidateSlug>/data`, and a static-miss fallthrough `/apps/{m}/page` reaches it as `/<candidateSlug>/page` (the `/api` segment is consumed by the proxy; the slug is prepended for edge-runtime function routing). The stripped logical path is delivered ONLY via the `X-Pxbaas-Worker-Path` header when `APP_WORKER_PATH_REWRITE` is ON, which is **disabled by default** (the runtime `new Request(url, req)` rewrite crashes with a streamRid TypeError on current sandbox binaries — D18). Workers MUST therefore normalize the leading `/<candidateSlug>` prefix and match on the logical path, e.g. `const p = new URL(req.url).pathname.replace(/^\/app_[^/]+/, "")` then dispatch on `p` (the `ssr-hono`, `ssr-shop`, `ssr-blog`, `csr-bff` templates all do this). A literal `app.get("/data")` will NOT match; do not rely on the declared `pathMode: "strip-app-api-prefix"` being honored at runtime yet. Hydrate scripts calling `./api/*` from an SSR page are routed the same way (browser `/apps/{m}/api/data` → worker `/<candidateSlug>/data`).
 - Start from the `ssr-hono` template (`pxbaas app new --template ssr-hono`); spec-lint enforces the rules above (`ssr-probe-declared`, `ssr-self-contained`, `ssr-marker-present`, `ssr-no-browser-globals`, `ssr-lib-not-allowed`).
 
 ## Lifecycle & cold start
@@ -139,7 +139,7 @@ For large frontends regardless of mode, host heavy static assets on Storage/CDN
 
 - The backend entrypoint must call `Deno.serve`; do not bind a port.
 - Node APIs (`node:*`, `require`, `process`, and Node server APIs) are forbidden.
-- Runtime `Deno.env` access is limited to the platform public three-key whitelist `SUPABASE_URL` / `SUPABASE_ANON_KEY` / `SUPABASE_INTERNAL_URL` (injected into App candidate workers per edge-runtime `app-env.ts`, MR #30497903). Reading any other variable or `Deno.env.toObject()`, non-empty Secrets, and any egress policy other than `deny` are unsupported in the first release (`deno-env-not-allowed`, `custom-secrets-not-supported`). `SUPABASE_URL` is render-only — never fetch through it; use `SUPABASE_INTERNAL_URL` as the data-plane base.
+- Runtime `Deno.env` access is limited to the platform public three-key whitelist `SUPABASE_URL` / `SUPABASE_ANON_KEY` / `SUPABASE_INTERNAL_URL` (injected into App candidate workers per edge-runtime `app-env.ts`, MR #30497903). Reading any other variable or `Deno.env.toObject()`, non-empty Secrets, and any egress policy other than `deny` are unsupported in the first release (`deno-env-not-allowed`, `custom-secrets-not-supported`). `SUPABASE_URL` is render-only — never fetch through it; use `SUPABASE_INTERNAL_URL` as the data-plane base. These three names are platform-reserved: the platform value always wins over a user Secret of the same name, so never declare them in `backend.secrets`.
 - `egressPolicy: "deny"` means **no public egress**, not "no network": the sandbox egress filter blocks public origins and arbitrary outbound, but the platform-internal base (`SUPABASE_INTERNAL_URL`) stays reachable, so the worker MAY fetch the instance's own REST/Auth/Storage through it. Only `deny` is accepted in the first release (any other value is a blocker).
 - Arbitrary `http:`, `https:`, and `jsr:` imports are blocked. The only approved `npm:` packages are Hono (exact capability version) plus the curated SSR renderers reported by capability `ssrLibs` (exact `npm:<name>@<version>`, optional `/subpath`); anything else fails spec-lint (`ssr-lib-not-allowed`, or `no-remote-import` when the instance reports no `ssrLibs`).
 - Scaffolded Hono source uses `npm:hono@{{HONO_VERSION}}`; candidate staging substitutes the exact version without modifying local source.

package/skills/pxbaas-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pxbaas-cli
-description: Use the PolarDB-X BaaS CLI (command `pxbaas`) to consume the data plane from the command line — run SQL, inspect tables/schema, query and edit table data (PostgREST), deploy/list/delete Edge Functions, manage storage objects and auth users, generate types, claim a free disposable instance (`pxbaas provision`), and scaffold/deploy/publish/rollback Webapps (`pxbaas app`). Use when the user works with a PolarDB-X BaaS / MySQL-Supabase instance through `pxbaas`, has no instance yet and wants to provision one, wants to deploy a demo webapp, or mentions the pxbaas CLI, querying BaaS tables/data, running SQL, edge function deploy, storage objects, auth users, gen types, or pxbaas login/doctor/401/403 errors. Data-plane consumption + self-service provisioning (not platform deployment or tenant lifecycle). Agent rules — never run `pxbaas login` (human-only TTY), but `pxbaas provision` and `pxbaas profile import <env-file>` (bind a single-tenant instance from a `.env` file) ARE agent-runnable; always pass `--json`; confirm destructive operations with the user before executing.
+description: Use the PolarDB-X BaaS CLI (`pxbaas`) to work with a PolarDB-X BaaS / MySQL-Supabase instance: run SQL and inspect tables/schema (`db`), read/write rows PostgREST-style (`data`, `rest`), deploy/list/delete Edge Functions (`functions`), scaffold-deploy-publish Webapps and share links (`app`), storage objects, auth users, type generation, claim a free disposable instance (`provision`), and - for instance operators - administer tenants and hand out per-tenant keys (`tenant probe/ls/create/keys/repair-keys`, access bundles). Trigger on pxbaas commands, BaaS SQL or table questions, function/webapp deploy, storage or users, gen types, provisioning, multi-tenant login, and 401/403 errors. Agent rules: never run `pxbaas login` (TTY-only); `provision` and `profile import <env-file>` are agent-runnable; always pass `--json`; never print or request plaintext keys; never create a tenant without explicit user confirmation.
 ---
 
 # pxbaas-cli
@@ -54,7 +54,7 @@ All requests go through a single Kong gateway (port **8000**). Key path prefixes
 | **1** | **NEVER run `pxbaas login`** | It requires an interactive TTY; agents cannot complete it. Credentials are provisioned by a human. If not logged in, **ask the user to run `pxbaas login`** — do not attempt it and do not ask for plaintext keys. **Exception:** `pxbaas provision` IS agent-runnable (keys come from Zero over TLS and are stored without being shown) — see `references/provision.md`. |
 | **2** | **Pass `--json` for anything you parse** | Status queries, remote operations, and any command whose result you read MUST use `--json` (parse JSON, never human-readable text). Pure local scaffolding, shell completion, and file-output commands (e.g. `gen types --output <file>`) are human-facing — `--json` is optional there. |
 | **3** | **You cannot see plaintext keys** | Output shows only fingerprints (sha256 first 8 + last 4). Never expect, echo, or reconstruct a plaintext anon/service key. |
-| **4** | **Confirm destructive ops first** | ⚠️ The CLI currently has **no built-in confirmation gate**. Before any write/delete/DDL, YOU must restate the target and impact and get the user's explicit consent. See `references/safety-and-two-phase.md`. |
+| **4** | **Confirm destructive ops first** | Some commands gate themselves (`--dry-run`/`--yes` on `db push`, `app db-init`, `data delete`; `--confirm` on `app remove`, `app destroy`, `instance release`, `app share revoke`, `skill remove`, `tenant create`, `tenant repair-keys`). **Many do not** — `db create-table` / `db add-column`, `functions deploy` / `delete`, `storage rm` / `mv` / `cp` overwrite, `auth users delete`, `rest` writes execute immediately. For those, YOU are the gate: restate target, impact and reversibility, then get explicit consent. See `references/safety-and-two-phase.md`. |
 | **5** | **Respect role & tenant isolation** | Prefer `anon` for reads; explain when `service_role` is needed (it bypasses RLS). Never mix credentials across profiles. |
 
 ## First-run discovery
@@ -76,7 +76,7 @@ Legend — **R** = read/safe · **W** = write · **D** = destructive (consent re
 | Command | Default role | R/W/D | Details |
 |---|---|---|---|
 | `login` (human TTY only) | — | special | auth-and-credentials.md |
-| `profile import <env-file>` (agent-runnable, single-tenant) | — | W (local) | auth-and-credentials.md |
+| `profile import <env-file>` (agent-runnable; single-tenant, or multi-tenant when the file carries `TENANT_*` keys) | — | W (local) | auth-and-credentials.md |
 | `logout` | — | W (local) | auth-and-credentials.md |
 | `whoami` | — | R | auth-and-credentials.md |
 | `status` | — | R | auth-and-credentials.md |
@@ -109,6 +109,11 @@ Legend — **R** = read/safe · **W** = write · **D** = destructive (consent re
 | `auth users delete <userId>` | service_role | **D** | auth-and-credentials.md |
 | `auth users invite <email>` | service_role | W | auth-and-credentials.md |
 | `completion <shell>` | — | R (local) | (this file) |
+| `tenant login` / `tenant logout` | dashboard Basic | W (local) | tenant-admin.md |
+| `tenant probe` / `tenant ls` / `tenant handoffs` | dashboard Basic | R | tenant-admin.md |
+| `tenant create [id]` | dashboard Basic | **D/W** (provisions db, account, GRANT, bucket, quota) | tenant-admin.md |
+| `tenant keys <id>` | dashboard Basic | W (local; writes keyring or 0600 bundle) | tenant-admin.md |
+| `tenant repair-keys` | dashboard Basic | W (`--confirm`) | tenant-admin.md |
 | `provision` (agent-runnable) | — | W (local+remote) | provision.md |
 | `instance list` / `instance current` | — | R | provision.md |
 | `instance credentials <id>` | — | R (`--reveal` for dashboard pw) | provision.md |
@@ -122,7 +127,7 @@ Legend — **R** = read/safe · **W** = write · **D** = destructive (consent re
 | `app remove <name>` | service_role | **D** (`--confirm`; legacy `spa/api/mpa` only) | app-deploy.md |
 | `app destroy <name>` | service_role | **D** (two-phase `--confirm`; webapp only; deletes edge funcs + mount, **keeps DB tables**) | app-deploy.md |
 
-For provisioning / multi-instance selection see **provision.md**; for the `pxbaas app` commands see **app-deploy.md**. For how to **write** edge-function webapp code (Deno runtime contract, guardrails, templates, raw deploy paths), use the companion **`pxbaas-app-spec` skill**. For the live platform API beyond the CLI (all endpoints, multi-tenant rules, error codes, limitations), see **api-reference.md** (`GET ${endpoint}/docs`).
+For provisioning / multi-instance selection see **provision.md**; for the `pxbaas app` commands see **app-deploy.md**; for tenant provisioning and handing per-tenant keys to end users see **tenant-admin.md** (operator-only surface). For how to **write** edge-function webapp code (Deno runtime contract, guardrails, templates, raw deploy paths), use the companion **`pxbaas-app-spec` skill**. For the live platform API beyond the CLI (all endpoints, multi-tenant rules, error codes, limitations), see **api-reference.md** (`GET ${endpoint}/docs`).
 
 ## Natural language → command
 
@@ -142,13 +147,15 @@ For provisioning / multi-instance selection see **provision.md**; for the `pxbaa
 "give me a shareable demo URL"  → pxbaas app url <name> --json
 "destroy/delete this webapp"    → confirm first → pxbaas app destroy <name> --confirm --json  (removes edge funcs + mount; DB tables kept)
 "can't connect / error"         → pxbaas doctor --json; if credentials missing, ask user to run pxbaas login
+"env says no tenant-level keys"  → read the guidance it prints; if the user operates the instance: pxbaas tenant login → tenant ls → tenant keys <id> --as-profile (never create a tenant without asking)
+"give this tenant to a new user" → pxbaas tenant keys <id> --bundle ./<id>.pxbaas.env, then send the printed handoff note (contains fingerprints, not keys)
 ```
 
 ## What NOT to do
 
 - **NEVER run `pxbaas login`** — it needs an interactive TTY. Ask the user to log in instead.
 - **NEVER expect or echo plaintext keys** — output is fingerprint-only; never ask the user for a raw key to build a command.
-- **NEVER run `data delete` / `storage rm` / `functions delete` / DDL without previewing first** and getting explicit user consent (no built-in gate exists).
+- **NEVER run `storage rm` / `functions delete` / `db create-table` / `db add-column` / `rest` writes / `auth users delete` without previewing first** and getting explicit user consent — those have **no** gate. `data delete`, `db push`, `app db-init`, `app destroy`, `instance release`, `tenant create` and `tenant repair-keys` do gate themselves; satisfy their `--yes`/`--confirm` only **after** the user agreed.
 - **NEVER write PostgreSQL SQL in `db query`** — the backend is MySQL/PolarDB-X (use `CAST(x AS t)`, backticks, `JSON_EXTRACT`, `UUID()`, not `::`, `"col"`, `->>`, `gen_random_uuid()`).
 - **NEVER assume an API listed in `/docs` is available via the CLI** — `/docs` covers the whole platform including admin APIs (PG-Meta, Management API) and tenant lifecycle; the CLI wraps only the customer data-plane subset in the command map above.
 - **NEVER mix credentials across profiles** or target another tenant; the CLI enforces tenant isolation.
@@ -157,6 +164,8 @@ For provisioning / multi-instance selection see **provision.md**; for the `pxbaa
 - **NEVER parse human-readable output** — always use `--json`.
 - **NEVER loop-retry Zero capacity/rate errors** (`429 SUPABASE_LIMIT_REACHED` / `503 SUPABASE_POOL_EXHAUSTED`) — stop, inform the user, offer `pxbaas instance release`; retry at most once for pool exhaustion.
 - **NEVER expect plaintext keys from `pxbaas provision`** — it stores them in the keyring and shows only fingerprints (this is why it is agent-runnable, unlike `pxbaas login`).
+- **NEVER cat, echo, commit or transmit a tenant access bundle** (`*.pxbaas.env`) — it holds plaintext, ~10-year, non-revocable keys. The CLI only writes them to a `0600` file or the keyring; distributing the file is the operator's decision, made over a secure channel.
+- **NEVER create a tenant as a workaround for a missing key.** Run `tenant ls` first: most "no key" cases are an existing tenant whose key was never handed over. A create that collides with a soft-deleted id resurrects it and regenerates that tenant's keys — the CLI refuses this without `--reactivate`.
 - **NEVER upload frontend source, `.env` files, source maps, `node_modules`, Service Workers, or binary assets as a Webapp artifact.** Build first; upload only the bounded static output. Put large/binary assets on Storage/CDN (see app-deploy.md).
 
 ## Global flags

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

@@ -1,6 +1,6 @@
 # Credentials, Environment & User Management
 
-Covers: `login` (human-only) · `profile import` (agent-runnable, env-file) · `logout` · `whoami` · `status` · `doctor` · `profile` · `auth users`.
+Covers: `login` (human-only) · `profile import` (agent-runnable, env-file) · `logout` · `whoami` · `status` · `doctor` · `profile` · `auth users` · `tenant login` / `tenant logout` (operator credentials; see tenant-admin.md).
 
 ## login — agents must NEVER run this
 
@@ -13,7 +13,7 @@ pxbaas login --endpoint <url> --tenant-id <id> --anon-key-stdin --service-key-st
 - 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**, 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)
+## profile import — bind an instance from a `.env` file (agents MAY run this)
 
 ```bash
 pxbaas profile import <env-file> --name <profile> [--intranet] --json
@@ -22,7 +22,23 @@ 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.
+- **Multi-tenant env files are supported** when they carry tenant-level credentials: `MULTI_TENANT_MODE=true` + `DEFAULT_TENANT_ID` + `TENANT_ANON_KEY` + `TENANT_SERVICE_ROLE_KEY`. Global keys (`GLOBAL_ANON_KEY` / `GLOBAL_SERVICE_ROLE_KEY`) are reported as present-but-not-imported — they cannot reach tenant resources, so the profile never absorbs them.
+- If a `MULTI_TENANT_MODE=true` file lacks the tenant keys, the command refuses and prints a diagnosis (which variables exist, whether each JWT carries a `tenant_id` claim) plus one of two routes: the operator path (`pxbaas tenant login` → `tenant ls` → `tenant keys <id> --as-profile`) or a checklist to send to the operator. Nothing is created and nothing is imported either way; the temporary admin probe it runs to pick the route does not persist the credentials it borrowed.
+- **`DASHBOARD_USERNAME` / `DASHBOARD_PASSWORD` in an env file are NOT imported by default.** Only `--with-admin` binds them, and then only after the credentials actually open the tenant admin channel. Pass `--with-admin` only when the user is the instance operator.
+
+## Operator credentials (`tenant login`)
+
+```bash
+pxbaas tenant login --endpoint https://<gateway>          # TTY: masked password prompt
+printf '%s\n%s\n' "$USER" "$PASS" | \
+  pxbaas tenant login --endpoint https://<gateway> --user-stdin --password-stdin
+pxbaas tenant logout                                      # drops dashboard creds only, keeps tenant keys
+```
+
+- Stored under a separate keyring account (`admin/<profile>`); data-plane commands cannot read it.
+- The password is refused in argv (`--dashboard-password` / `--admin-password` are blocked by the same guard as API keys).
+- `tenant login` probes the admin channel **before** storing; a refused probe stores nothing.
+- `pxbaas whoami --json` reports `platformAdmin: {available, userMasked, passwordFingerprint}` — never the secret.
 
 ## Verify login state (run these first)