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

package/dist/drivers/tenant-ddl.driver.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Tenant DDL Driver — 多租户「普通租户」自助 DDL / RLS 注册客户端。
+ *
+ * 对接 Studio BFF 的租户自助端点（Aone #87795993）：
+ *   - POST   /api/tenant-ddl/query            在租户自有库执行 DDL/DML
+ *   - POST   /api/tenant-ddl/rls/tables       开/关表级 RLS
+ *   - GET    /api/tenant-ddl/rls/tables       列出本租户已注册 RLS 的表
+ *   - DELETE /api/tenant-ddl/rls/tables       移除一张表的 RLS 注册（开关行）
+ *   - POST   /api/tenant-ddl/rls/policies     增/改一条 RLS 策略
+ *   - GET    /api/tenant-ddl/rls/policies     列出本租户策略（可按 table 过滤）
+ *   - DELETE /api/tenant-ddl/rls/policies     删除一条策略
+ *
+ * 认证模型（务必遵守，见方案文档「三、认证与信任链」）：
+ *   只发送 `Authorization: Bearer <per-tenant service_role key>`。**绝不**自行拼
+ *   `X-Tenant-Id`——Kong 入口会剥离客户端伪造的该头、验签 per-tenant JWT 后注入
+ *   可信 X-Tenant-Id，并把下游 Authorization 替换为全局 key。租户身份完全由网关推导。
+ *
+ * 成功响应统一为 `{ data: ... }`，失败为 `{ code, message }`；本 driver 解包 data、
+ * 并把失败规范化为 TenantDdlError（携带 code/message/status）。
+ */
+/** RLS 命令行枚举（与服务端 resolver 白名单一致）。 */
+export type RlsCommand = "ALL" | "SELECT" | "INSERT" | "UPDATE" | "DELETE";
+export interface TenantDdlDriverOptions {
+    endpoint: string;
+    /** per-tenant service_role key（带 tenant_id claim）。不可用全局 key。 */
+    serviceRoleKey: string;
+    timeout?: number;
+}
+export interface RlsTableInput {
+    table_name: string;
+    /** 默认 true（启用 RLS）。 */
+    rls_enabled?: boolean;
+    /** 默认 false。 */
+    rls_forced?: boolean;
+}
+export interface RlsPolicyInput {
+    table_name: string;
+    policy_name: string;
+    /** `*` 或 `[a-zA-Z0-9_]`；缺省服务端按 `*` 处理。 */
+    role_name?: string;
+    command?: RlsCommand | string;
+    using_expr?: string | null;
+    check_expr?: string | null;
+    permissive?: boolean;
+}
+/** GET /rls/tables 的一行（rls_* 以 tinyint 0/1 返回）。 */
+export interface RlsTableRow {
+    table_schema: string;
+    table_name: string;
+    rls_enabled: number | boolean;
+    rls_forced: number | boolean;
+}
+/** GET /rls/policies 的一行。 */
+export interface RlsPolicyRow {
+    table_schema: string;
+    table_name: string;
+    policy_name: string;
+    role_name: string;
+    command: string;
+    using_expr: string | null;
+    check_expr: string | null;
+    permissive: number | boolean;
+}
+/** 租户自助 DDL/RLS 调用的统一错误（携带机器码 + HTTP 状态）。 */
+export declare class TenantDdlError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    constructor(code: string, message: string, status?: number);
+}
+export declare class TenantDdlDriver {
+    private readonly client;
+    constructor(options: TenantDdlDriverOptions);
+    /**
+     * Execute a DDL/DML statement on the tenant's OWN database. The tenant MySQL
+     * account (GRANT ALL ON own_db.* only) is the hard isolation boundary; the
+     * server additionally pre-checks and rejects privilege/instance-level statements.
+     * Returns the raw pg-meta rows (`data`), or `[]` for statements with no result set.
+     */
+    query(sql: string): Promise<unknown[]>;
+    /** Enable/force RLS on one of the tenant's tables (central registry, schema server-bound). */
+    upsertRlsTable(input: RlsTableInput): Promise<void>;
+    /** List the tenant's own RLS-registered tables. */
+    listRlsTables(): Promise<RlsTableRow[]>;
+    /**
+     * Remove a table's RLS registration (the central enable/force toggle row),
+     * symmetric to {@link deleteRlsPolicy}. The server binds table_schema to the
+     * tenant db and does NOT require the table to still exist, so this is safe to
+     * call after a DROP (idempotent cleanup).
+     */
+    deleteRlsTable(tableName: string): Promise<void>;
+    /** Insert/update one RLS policy for the tenant (schema server-bound). */
+    upsertRlsPolicy(input: RlsPolicyInput): Promise<void>;
+    /** List the tenant's own policies, optionally filtered by table name. */
+    listRlsPolicies(tableName?: string): Promise<RlsPolicyRow[]>;
+    /** Delete one of the tenant's policies (scoped by table + policy name). */
+    deleteRlsPolicy(tableName: string, policyName: string): Promise<void>;
+    private request;
+}
+/**
+ * Map any failure to a TenantDdlError. Server errors carry `{ code, message }`
+ * (e.g. PERMISSION_DENIED / GLOBAL_KEY_NOT_ALLOWED / ROLE_NOT_ALLOWED /
+ * TENANT_NOT_ACTIVE / STATEMENT_NOT_ALLOWED); fall back to an HTTP-status code
+ * or a network code when the body is absent.
+ */
+export declare function normalizeTenantDdlError(error: unknown): TenantDdlError;
+//# sourceMappingURL=tenant-ddl.driver.d.ts.map

package/dist/drivers/tenant-ddl.driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-ddl.driver.d.ts","sourceRoot":"","sources":["../../src/drivers/tenant-ddl.driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,sCAAsC;AACtC,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gBAAgB;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AAED,6BAA6B;AAC7B,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B;AAED,6CAA6C;AAC7C,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAM3D;AAQD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAE3B,OAAO,EAAE,sBAAsB;IAW3C;;;;;OAKG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAO5C,8FAA8F;IACxF,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzD,mDAAmD;IAC7C,aAAa,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAO7C;;;;;OAKG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtD,yEAAyE;IACnE,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3D,yEAAyE;IACnE,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IASlE,2EAA2E;IACrE,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAQ7D,OAAO;CAUtB;AAQD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAwBtE"}

package/dist/drivers/tenant-ddl.driver.js

@@ -0,0 +1,131 @@
+/**
+ * Tenant DDL Driver — 多租户「普通租户」自助 DDL / RLS 注册客户端。
+ *
+ * 对接 Studio BFF 的租户自助端点（Aone #87795993）：
+ *   - POST   /api/tenant-ddl/query            在租户自有库执行 DDL/DML
+ *   - POST   /api/tenant-ddl/rls/tables       开/关表级 RLS
+ *   - GET    /api/tenant-ddl/rls/tables       列出本租户已注册 RLS 的表
+ *   - DELETE /api/tenant-ddl/rls/tables       移除一张表的 RLS 注册（开关行）
+ *   - POST   /api/tenant-ddl/rls/policies     增/改一条 RLS 策略
+ *   - GET    /api/tenant-ddl/rls/policies     列出本租户策略（可按 table 过滤）
+ *   - DELETE /api/tenant-ddl/rls/policies     删除一条策略
+ *
+ * 认证模型（务必遵守，见方案文档「三、认证与信任链」）：
+ *   只发送 `Authorization: Bearer <per-tenant service_role key>`。**绝不**自行拼
+ *   `X-Tenant-Id`——Kong 入口会剥离客户端伪造的该头、验签 per-tenant JWT 后注入
+ *   可信 X-Tenant-Id，并把下游 Authorization 替换为全局 key。租户身份完全由网关推导。
+ *
+ * 成功响应统一为 `{ data: ... }`，失败为 `{ code, message }`；本 driver 解包 data、
+ * 并把失败规范化为 TenantDdlError（携带 code/message/status）。
+ */
+import axios from "axios";
+/** 租户自助 DDL/RLS 调用的统一错误（携带机器码 + HTTP 状态）。 */
+export class TenantDdlError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.name = "TenantDdlError";
+        this.code = code;
+        this.status = status;
+    }
+}
+export class TenantDdlDriver {
+    client;
+    constructor(options) {
+        const endpoint = options.endpoint.replace(/\/$/, "");
+        this.client = axios.create({
+            baseURL: `${endpoint}/api/tenant-ddl`,
+            timeout: options.timeout ?? 60_000,
+            // Only the per-tenant service_role bearer. Never send X-Tenant-Id here —
+            // Kong strips any client-supplied value and injects the trusted one.
+            headers: { Authorization: `Bearer ${options.serviceRoleKey}` },
+        });
+    }
+    /**
+     * Execute a DDL/DML statement on the tenant's OWN database. The tenant MySQL
+     * account (GRANT ALL ON own_db.* only) is the hard isolation boundary; the
+     * server additionally pre-checks and rejects privilege/instance-level statements.
+     * Returns the raw pg-meta rows (`data`), or `[]` for statements with no result set.
+     */
+    async query(sql) {
+        const data = await this.request(() => this.client.post("/query", { sql }));
+        return data ?? [];
+    }
+    /** Enable/force RLS on one of the tenant's tables (central registry, schema server-bound). */
+    async upsertRlsTable(input) {
+        await this.request(() => this.client.post("/rls/tables", compact(input)));
+    }
+    /** List the tenant's own RLS-registered tables. */
+    async listRlsTables() {
+        const data = await this.request(() => this.client.get("/rls/tables"));
+        return data ?? [];
+    }
+    /**
+     * Remove a table's RLS registration (the central enable/force toggle row),
+     * symmetric to {@link deleteRlsPolicy}. The server binds table_schema to the
+     * tenant db and does NOT require the table to still exist, so this is safe to
+     * call after a DROP (idempotent cleanup).
+     */
+    async deleteRlsTable(tableName) {
+        await this.request(() => this.client.delete("/rls/tables", {
+            params: { table_name: tableName },
+        }));
+    }
+    /** Insert/update one RLS policy for the tenant (schema server-bound). */
+    async upsertRlsPolicy(input) {
+        await this.request(() => this.client.post("/rls/policies", compact(input)));
+    }
+    /** List the tenant's own policies, optionally filtered by table name. */
+    async listRlsPolicies(tableName) {
+        const data = await this.request(() => this.client.get("/rls/policies", {
+            params: tableName ? { table_name: tableName } : undefined,
+        }));
+        return data ?? [];
+    }
+    /** Delete one of the tenant's policies (scoped by table + policy name). */
+    async deleteRlsPolicy(tableName, policyName) {
+        await this.request(() => this.client.delete("/rls/policies", {
+            params: { table_name: tableName, policy_name: policyName },
+        }));
+    }
+    async request(operation) {
+        try {
+            const response = await operation();
+            return response.data?.data;
+        }
+        catch (error) {
+            throw normalizeTenantDdlError(error);
+        }
+    }
+}
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+/**
+ * Map any failure to a TenantDdlError. Server errors carry `{ code, message }`
+ * (e.g. PERMISSION_DENIED / GLOBAL_KEY_NOT_ALLOWED / ROLE_NOT_ALLOWED /
+ * TENANT_NOT_ACTIVE / STATEMENT_NOT_ALLOWED); fall back to an HTTP-status code
+ * or a network code when the body is absent.
+ */
+export function normalizeTenantDdlError(error) {
+    if (!axios.isAxiosError(error)) {
+        const message = error instanceof Error ? error.message : String(error);
+        return new TenantDdlError("TENANT_DDL_UNKNOWN_ERROR", message);
+    }
+    const axiosError = error;
+    const status = axiosError.response?.status;
+    const body = axiosError.response?.data;
+    const code = typeof body?.code === "string"
+        ? body.code
+        : status
+            ? `TENANT_DDL_HTTP_${status}`
+            : "TENANT_DDL_NETWORK_ERROR";
+    const message = typeof body?.message === "string"
+        ? body.message
+        : status
+            ? `Tenant DDL request failed (HTTP ${status})`
+            : axiosError.message || "Tenant DDL network request failed";
+    return new TenantDdlError(code, message, status);
+}
+//# sourceMappingURL=tenant-ddl.driver.js.map

package/dist/drivers/tenant-ddl.driver.js.map

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

package/dist/drivers/zero.driver.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Zero Driver — PolarDB-X Zero PXBaas provisioning client.
+ *
+ * Wraps the unauthenticated Zero API that claims a disposable, Supabase-compatible
+ * BaaS instance from a pre-warmed pool (15-day TTL, no renewal).
+ *
+ * Contract source: https://zero.polardbx.com/BAAS-SKILL.md (polardbx-zero-pxbaas v0.1.0)
+ *
+ * Endpoints:
+ * - POST   /api/v1/supabase/instances                  claim (body: { whitelistIp? })
+ * - GET    /api/v1/supabase/instances                  list  (needs pxz_token cookie)
+ * - DELETE /api/v1/supabase/instances/{id}             release (needs pxz_token cookie; id = sbx_*)
+ * - GET    /api/v1/supabase/instances/{cloudId}/whitelist   query whitelist (Studio-credential hash; cloudId = pxsp-*)
+ * - PUT    /api/v1/supabase/instances/{cloudId}/whitelist   append whitelist (Studio-credential hash; append-only)
+ *
+ * Ownership: the claim response returns a `token` (also set as the `pxz_token`
+ * cookie). list/release must send it back via `Cookie: pxz_token=<token>`.
+ *
+ * The whitelist self-service API uses a DIFFERENT auth + id space: an
+ * `X-Studio-User: supabase` / `X-Studio-Hash: sha256hex("supabase:"+dashboardPassword)`
+ * pair, and the cloud instance id (`pxsp-*`, derived from the public endpoint host),
+ * not the `sbx_*` ownership id. Callers compute the hash (see apps/baas
+ * instance/zero-whitelist.ts) and pass it in; the password/hash is never logged.
+ */
+import { AxiosError } from 'axios';
+export interface ZeroInstance {
+    id: string;
+    status: string;
+    region?: string;
+    zoneId?: string;
+    aliyunInstanceId?: string;
+    /** host:8000 WITHOUT scheme, e.g. "pxsp-xxxhttp.polardbxaisupabase.rds.aliyuncs.com:8000" */
+    publicEndpoint: string;
+    dashboardUrl?: string;
+    /** Canonical App origin returned by the platform; clients must not derive it. */
+    appEndpoint?: string;
+    appDomain?: {
+        hostname: string;
+        status: string;
+        tlsStatus: string;
+    };
+    apiKey: string;
+    serviceRoleKey: string;
+    dbPassword?: string;
+    dashboardPassword?: string;
+    whitelistIp?: string;
+    assignedAt?: string;
+    expiresAt?: string;
+    createdAt?: string;
+}
+export interface ZeroClaimResponse {
+    instance: ZeroInstance;
+    token: string;
+}
+/** Result of `GET .../{cloudId}/whitelist` (flat success body). */
+export interface ZeroWhitelist {
+    instanceId: string;
+    groupName: string;
+    /** Comma-separated effective entries (excludes the system 127.0.0.1 baseline). */
+    whitelist: string;
+    /** Where the value came from, e.g. "zero-record". */
+    source: string;
+    expiresAt?: string;
+    updatedAt?: string;
+}
+/** Result of `PUT .../{cloudId}/whitelist` (append-only; flat success body). */
+export interface ZeroWhitelistAppendResult {
+    instanceId: string;
+    groupName: string;
+    appliedIps: string;
+    effectiveWhitelist: string;
+    cloudRequestId?: string;
+}
+export interface ZeroDriverOptions {
+    /** Zero API base URL. Defaults to https://zero.polardbx.com (override via BAAS_ZERO_ENDPOINT). */
+    baseUrl?: string;
+    timeout?: number;
+}
+/** Error codes returned by Zero (`{ error: { code, message } }`). */
+export type ZeroErrorCode = 'INVALID_WHITELIST_IP' | 'INSTANCE_NOT_FOUND' | 'RATE_LIMIT_EXCEEDED' | 'SUPABASE_LIMIT_REACHED' | 'SUPABASE_POOL_EXHAUSTED' | 'SUPABASE_DISABLED' | 'INTERNAL_ERROR' | 'NETWORK_ERROR' | 'UNKNOWN' | 'INVALID_PARAMETER' | 'IP_MISMATCH' | 'ASSIGNMENT_EXPIRED' | 'STUDIO_CREDENTIALS_INVALID' | 'INSTANCE_NOT_ACCESSIBLE' | 'INSTANCE_BUSY' | 'CONCURRENT_UPDATE' | 'CREDENTIALS_UNAVAILABLE' | 'WHITELIST_MODIFY_FAILED';
+export declare class ZeroError extends Error {
+    code: ZeroErrorCode;
+    status?: number;
+    constructor(code: ZeroErrorCode, message: string, status?: number);
+}
+export declare class ZeroDriver {
+    private client;
+    /** The whitelist API fixes the Studio user to `supabase` (see spec). */
+    private static readonly STUDIO_USER;
+    constructor(options?: ZeroDriverOptions);
+    /** Claim a new instance. Unauthenticated. Optionally whitelist extra IPs. */
+    claim(whitelistIp?: string): Promise<ZeroClaimResponse>;
+    /** List the caller's non-released instances. Requires the ownership token. */
+    list(token: string): Promise<ZeroInstance[]>;
+    /** Release (destroy) an instance. Requires the ownership token. */
+    release(id: string, token: string): Promise<void>;
+    /**
+     * Query the effective IP whitelist of a Zero instance.
+     * Auth: Studio-credential hash (NOT the pxz_token). `cloudInstanceId` is the
+     * `pxsp-*` id (see ZeroDriver.cloudInstanceId), not the `sbx_*` ownership id.
+     */
+    getWhitelist(cloudInstanceId: string, studioHash: string): Promise<ZeroWhitelist>;
+    /**
+     * Append IPs/CIDRs to the whitelist (append-only and idempotent: existing
+     * entries are kept, duplicates are not added). Same auth/id space as getWhitelist.
+     */
+    appendWhitelist(cloudInstanceId: string, ips: string, studioHash: string): Promise<ZeroWhitelistAppendResult>;
+    /**
+     * Derive the cloud instance id (`pxsp-*`) from a public/intranet endpoint or
+     * bare host. The platform inserts an `http`/`https` infix before the registrable
+     * domain on the public host (e.g. `pxsp-abc123http.pxbaas...`); strip scheme,
+     * path, port, then the trailing infix from the first label.
+     */
+    static cloudInstanceId(endpointOrHost: string): string;
+    /**
+     * Normalize the publicEndpoint (host:8000, no scheme) into a base URL.
+     * Prefers dashboardUrl when it already carries a scheme.
+     */
+    static toEndpoint(instance: ZeroInstance, scheme?: string): string;
+    private toError;
+    private codeFromStatus;
+}
+/** Wrap a network-level axios failure into a ZeroError. */
+export declare function isZeroNetworkError(e: unknown): e is AxiosError;
+//# sourceMappingURL=zero.driver.d.ts.map

package/dist/drivers/zero.driver.d.ts.map

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

package/dist/drivers/zero.driver.js

@@ -0,0 +1,165 @@
+/**
+ * Zero Driver — PolarDB-X Zero PXBaas provisioning client.
+ *
+ * Wraps the unauthenticated Zero API that claims a disposable, Supabase-compatible
+ * BaaS instance from a pre-warmed pool (15-day TTL, no renewal).
+ *
+ * Contract source: https://zero.polardbx.com/BAAS-SKILL.md (polardbx-zero-pxbaas v0.1.0)
+ *
+ * Endpoints:
+ * - POST   /api/v1/supabase/instances                  claim (body: { whitelistIp? })
+ * - GET    /api/v1/supabase/instances                  list  (needs pxz_token cookie)
+ * - DELETE /api/v1/supabase/instances/{id}             release (needs pxz_token cookie; id = sbx_*)
+ * - GET    /api/v1/supabase/instances/{cloudId}/whitelist   query whitelist (Studio-credential hash; cloudId = pxsp-*)
+ * - PUT    /api/v1/supabase/instances/{cloudId}/whitelist   append whitelist (Studio-credential hash; append-only)
+ *
+ * Ownership: the claim response returns a `token` (also set as the `pxz_token`
+ * cookie). list/release must send it back via `Cookie: pxz_token=<token>`.
+ *
+ * The whitelist self-service API uses a DIFFERENT auth + id space: an
+ * `X-Studio-User: supabase` / `X-Studio-Hash: sha256hex("supabase:"+dashboardPassword)`
+ * pair, and the cloud instance id (`pxsp-*`, derived from the public endpoint host),
+ * not the `sbx_*` ownership id. Callers compute the hash (see apps/baas
+ * instance/zero-whitelist.ts) and pass it in; the password/hash is never logged.
+ */
+import axios from 'axios';
+export class ZeroError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.name = 'ZeroError';
+        this.code = code;
+        this.status = status;
+    }
+}
+const DEFAULT_BASE_URL = 'https://zero.polardbx.com';
+export class ZeroDriver {
+    client;
+    /** The whitelist API fixes the Studio user to `supabase` (see spec). */
+    static STUDIO_USER = 'supabase';
+    constructor(options = {}) {
+        const baseUrl = options.baseUrl ?? process.env.BAAS_ZERO_ENDPOINT ?? DEFAULT_BASE_URL;
+        this.client = axios.create({
+            baseURL: baseUrl.replace(/\/$/, ''),
+            timeout: options.timeout ?? 30000,
+            // NOTE: do NOT set a default Content-Type. axios adds application/json
+            // automatically for the claim() POST object body, but a DELETE/GET carrying
+            // Content-Type: application/json with no body makes Zero return HTTP 400.
+            // Do not throw on non-2xx; we map errors ourselves.
+            validateStatus: () => true,
+        });
+    }
+    /** Claim a new instance. Unauthenticated. Optionally whitelist extra IPs. */
+    async claim(whitelistIp) {
+        const body = {};
+        if (whitelistIp)
+            body.whitelistIp = whitelistIp;
+        const res = await this.client.post('/api/v1/supabase/instances', body);
+        if (res.status !== 200 && res.status !== 201) {
+            throw this.toError(res.status, res.data);
+        }
+        const data = res.data;
+        if (!data?.instance?.id || !data?.token) {
+            throw new ZeroError('UNKNOWN', 'Malformed claim response: missing instance.id or token', res.status);
+        }
+        return data;
+    }
+    /** List the caller's non-released instances. Requires the ownership token. */
+    async list(token) {
+        const res = await this.client.get('/api/v1/supabase/instances', {
+            headers: { Cookie: `pxz_token=${token}` },
+        });
+        if (res.status !== 200) {
+            throw this.toError(res.status, res.data);
+        }
+        const data = res.data;
+        if (Array.isArray(data))
+            return data;
+        const obj = data;
+        return obj?.instances ?? [];
+    }
+    /** Release (destroy) an instance. Requires the ownership token. */
+    async release(id, token) {
+        const res = await this.client.delete(`/api/v1/supabase/instances/${encodeURIComponent(id)}`, {
+            headers: { Cookie: `pxz_token=${token}` },
+        });
+        if (res.status !== 200 && res.status !== 204) {
+            throw this.toError(res.status, res.data);
+        }
+    }
+    /**
+     * Query the effective IP whitelist of a Zero instance.
+     * Auth: Studio-credential hash (NOT the pxz_token). `cloudInstanceId` is the
+     * `pxsp-*` id (see ZeroDriver.cloudInstanceId), not the `sbx_*` ownership id.
+     */
+    async getWhitelist(cloudInstanceId, studioHash) {
+        const res = await this.client.get(`/api/v1/supabase/instances/${encodeURIComponent(cloudInstanceId)}/whitelist`, { headers: { 'X-Studio-User': ZeroDriver.STUDIO_USER, 'X-Studio-Hash': studioHash } });
+        if (res.status !== 200) {
+            throw this.toError(res.status, res.data);
+        }
+        return res.data;
+    }
+    /**
+     * Append IPs/CIDRs to the whitelist (append-only and idempotent: existing
+     * entries are kept, duplicates are not added). Same auth/id space as getWhitelist.
+     */
+    async appendWhitelist(cloudInstanceId, ips, studioHash) {
+        const res = await this.client.put(`/api/v1/supabase/instances/${encodeURIComponent(cloudInstanceId)}/whitelist`, { ips }, { headers: { 'X-Studio-User': ZeroDriver.STUDIO_USER, 'X-Studio-Hash': studioHash } });
+        if (res.status !== 200) {
+            throw this.toError(res.status, res.data);
+        }
+        return res.data;
+    }
+    /**
+     * Derive the cloud instance id (`pxsp-*`) from a public/intranet endpoint or
+     * bare host. The platform inserts an `http`/`https` infix before the registrable
+     * domain on the public host (e.g. `pxsp-abc123http.pxbaas...`); strip scheme,
+     * path, port, then the trailing infix from the first label.
+     */
+    static cloudInstanceId(endpointOrHost) {
+        const host = endpointOrHost.replace(/^https?:\/\//, '').split('/')[0].split(':')[0];
+        const firstLabel = host.split('.')[0] ?? '';
+        const id = firstLabel.replace(/https?$/, '');
+        if (!/^pxsp-/.test(id)) {
+            throw new ZeroError('INVALID_PARAMETER', `Cannot derive a pxsp- cloud instance id from '${endpointOrHost}'`);
+        }
+        return id;
+    }
+    /**
+     * Normalize the publicEndpoint (host:8000, no scheme) into a base URL.
+     * Prefers dashboardUrl when it already carries a scheme.
+     */
+    static toEndpoint(instance, scheme = 'http') {
+        if (instance.dashboardUrl && /^https?:\/\//.test(instance.dashboardUrl)) {
+            return instance.dashboardUrl.replace(/\/$/, '');
+        }
+        const host = instance.publicEndpoint.replace(/^https?:\/\//, '').replace(/\/$/, '');
+        return `${scheme}://${host}`;
+    }
+    toError(status, data) {
+        const err = data?.error;
+        const code = err?.code ?? this.codeFromStatus(status);
+        const message = err?.message ?? `Zero API error (HTTP ${status})`;
+        return new ZeroError(code, message, status);
+    }
+    codeFromStatus(status) {
+        if (status === 429)
+            return 'RATE_LIMIT_EXCEEDED';
+        if (status === 503)
+            return 'SUPABASE_POOL_EXHAUSTED';
+        if (status === 404)
+            return 'INSTANCE_NOT_FOUND';
+        if (status >= 500)
+            return 'INTERNAL_ERROR';
+        // 400 is not mapped to a specific code: INVALID_WHITELIST_IP is claim-only and
+        // comes from the response body's error.code (preferred in toError). A bare 400
+        // on other calls (e.g. release) must not be mislabeled as a whitelist error.
+        return 'UNKNOWN';
+    }
+}
+/** Wrap a network-level axios failure into a ZeroError. */
+export function isZeroNetworkError(e) {
+    return axios.isAxiosError(e);
+}
+//# sourceMappingURL=zero.driver.js.map

package/dist/drivers/zero.driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zero.driver.js","sourceRoot":"","sources":["../../src/drivers/zero.driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAoC,MAAM,OAAO,CAAC;AAkFzD,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,IAAI,CAAgB;IACpB,MAAM,CAAU;IAChB,YAAY,IAAmB,EAAE,OAAe,EAAE,MAAe;QAC/D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED,MAAM,gBAAgB,GAAG,2BAA2B,CAAC;AAErD,MAAM,OAAO,UAAU;IACb,MAAM,CAAgB;IAE9B,wEAAwE;IAChE,MAAM,CAAU,WAAW,GAAG,UAAU,CAAC;IAEjD,YAAY,UAA6B,EAAE;QACzC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,gBAAgB,CAAC;QACtF,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YACzB,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;YACnC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK;YACjC,uEAAuE;YACvE,4EAA4E;YAC5E,0EAA0E;YAC1E,oDAAoD;YACpD,cAAc,EAAE,GAAG,EAAE,CAAC,IAAI;SAC3B,CAAC,CAAC;IACL,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,KAAK,CAAC,WAAoB;QAC9B,MAAM,IAAI,GAA4B,EAAE,CAAC;QACzC,IAAI,WAAW;YAAE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAEhD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,4BAA4B,EAAE,IAAI,CAAC,CAAC;QACvE,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC7C,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAyB,CAAC;QAC3C,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;YACxC,MAAM,IAAI,SAAS,CAAC,SAAS,EAAE,wDAAwD,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACvG,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,IAAI,CAAC,KAAa;QACtB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,4BAA4B,EAAE;YAC9D,OAAO,EAAE,EAAE,MAAM,EAAE,aAAa,KAAK,EAAE,EAAE;SAC1C,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAe,CAAC;QACjC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,OAAO,IAAsB,CAAC;QACvD,MAAM,GAAG,GAAG,IAAsC,CAAC;QACnD,OAAO,GAAG,EAAE,SAAS,IAAI,EAAE,CAAC;IAC9B,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,OAAO,CAAC,EAAU,EAAE,KAAa;QACrC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,8BAA8B,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE;YAC3F,OAAO,EAAE,EAAE,MAAM,EAAE,aAAa,KAAK,EAAE,EAAE;SAC1C,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC7C,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,eAAuB,EAAE,UAAkB;QAC5D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAC/B,8BAA8B,kBAAkB,CAAC,eAAe,CAAC,YAAY,EAC7E,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,UAAU,CAAC,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,EAAE,CACtF,CAAC;QACF,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,GAAG,CAAC,IAAqB,CAAC;IACnC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe,CACnB,eAAuB,EACvB,GAAW,EACX,UAAkB;QAElB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAC/B,8BAA8B,kBAAkB,CAAC,eAAe,CAAC,YAAY,EAC7E,EAAE,GAAG,EAAE,EACP,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,UAAU,CAAC,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,EAAE,CACtF,CAAC;QACF,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,GAAG,CAAC,IAAiC,CAAC;IAC/C,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,cAAsB;QAC3C,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACpF,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5C,MAAM,EAAE,GAAG,UAAU,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAC7C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,SAAS,CACjB,mBAAmB,EACnB,iDAAiD,cAAc,GAAG,CACnE,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,QAAsB,EAAE,MAAM,GAAG,MAAM;QACvD,IAAI,QAAQ,CAAC,YAAY,IAAI,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YACxE,OAAO,QAAQ,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,MAAM,IAAI,GAAG,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACpF,OAAO,GAAG,MAAM,MAAM,IAAI,EAAE,CAAC;IAC/B,CAAC;IAEO,OAAO,CAAC,MAAc,EAAE,IAAa;QAC3C,MAAM,GAAG,GAAI,IAAwD,EAAE,KAAK,CAAC;QAC7E,MAAM,IAAI,GAAI,GAAG,EAAE,IAAsB,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACzE,MAAM,OAAO,GAAG,GAAG,EAAE,OAAO,IAAI,wBAAwB,MAAM,GAAG,CAAC;QAClE,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9C,CAAC;IAEO,cAAc,CAAC,MAAc;QACnC,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,qBAAqB,CAAC;QACjD,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,yBAAyB,CAAC;QACrD,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,oBAAoB,CAAC;QAChD,IAAI,MAAM,IAAI,GAAG;YAAE,OAAO,gBAAgB,CAAC;QAC3C,+EAA+E;QAC/E,+EAA+E;QAC/E,6EAA6E;QAC7E,OAAO,SAAS,CAAC;IACnB,CAAC;;AAGH,2DAA2D;AAC3D,MAAM,UAAU,kBAAkB,CAAC,CAAU;IAC3C,OAAO,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AAC/B,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared API error formatting for all drivers.
+ *
+ * WHY: Storage/Meta error bodies are `{ statusCode, error, message }` where
+ * `error` is a coarse category (literally "Error" for Storage 400s) and
+ * `message` carries the actionable detail. Each driver used to prefer `error`
+ * and hard-coded 401/403/404 texts that swallowed the server `message`
+ * entirely, so users saw e.g. `Storage API error (400): Error` instead of
+ * `body must have required property 'prefix'`.
+ *
+ * Contract: always throws a plain `Error` whose message starts with
+ * `<source> API error (<status>): ` — upper layers match on that text, so do
+ * not introduce custom error classes or codes here.
+ */
+/** Minimal view of an AxiosResponse so drivers can pass plain object literals. */
+export interface ApiErrorInfo {
+    status?: number;
+    data?: unknown;
+    /** Transport-level message (axiosError.message); used when there is no response body. */
+    fallbackMessage?: string;
+    /** Debug context appended verbatim under `--debug`. */
+    debug?: {
+        method?: string;
+        url?: string;
+        /** Response body serialized by the caller. */
+        responseBody?: string;
+    };
+}
+export interface FormatApiErrorOptions {
+    /** Friendly texts per HTTP status; the server message (if any) is appended after them. */
+    statusTexts?: Partial<Record<401 | 403 | 404, string>>;
+}
+/**
+ * Build the error for a failed API call and throw it as a plain `Error`.
+ */
+export declare function formatApiError(source: string, info: ApiErrorInfo, options?: FormatApiErrorOptions): never;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,yFAAyF;IACzF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,KAAK,CAAC,EAAE;QACN,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,8CAA8C;QAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;CACxD;AAaD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,YAAY,EAClB,OAAO,GAAE,qBAA0B,GAClC,KAAK,CAoCP"}