@supacloud/cli 0.28.1 → 0.30.0

package/README.md

@@ -108,10 +108,12 @@ loopback development origins, with the default `:80` likewise omitted. Use
 
 ### Verified release controls
 
-`release` is an official CLI entry point for the existing Management API
-logical-backup and PostgREST lifecycle capabilities. It requires the Management
-API context above; it does not promote an application `service_role` key to
-Management authority.
+`release` is an official CLI entry point for verified Management API controls
+and the release-canary fixture receipt replay. Management actions require the
+Management API context above. `release_canary_fixture_stage_replay` additionally
+requires the same project's `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY`; the
+key is sent only to that application origin and is never promoted to Management
+authority.
 
 Project pause and restore are explicit lifecycle commands. A logical backup
 restore requires an operator to pause the selected project first and then use
@@ -138,6 +140,11 @@ supacloud-cli release logical_backup_restore --ref abc123 \
   --restore_confirmation RESTORE_PROJECT:abc123:logical-full_abc123_<backup-id-suffix>:<64-lowercase-hex>
 supacloud-cli release postgrest_status --ref abc123
 supacloud-cli release postgrest_restart --ref abc123
+supacloud-cli release release_canary_fixture_stage_replay --ref abc123 \
+  --subject <central-subject-uuid> --request_id <stage-request-uuid>
+supacloud-cli release release_canary_fixture_disable_replay --ref abc123 \
+  --fixture_id <fixture-uuid> --disable_request_id <disable-request-uuid> \
+  --issuer <issuer-url> --subject <central-subject-uuid>
 ```
 
 Backup creation reports success only after the CLI verifies exactly one new
@@ -158,6 +165,26 @@ receipt and reads back `desired=running`, `actual=running`, and
 `health=healthy`. Both mutating controls follow the normal production
 confirmation and read-only protections.
 
+`release_canary_fixture_stage_replay` performs one non-retried, response-bounded
+call to the fixed `fa_release_canary_fixture_stage` PostgREST RPC with both
+bearer and `apikey` service-role headers. It accepts only canonical subject and
+request UUIDs, requires a strict `staged` and `idempotent=true` four-field
+receipt, and emits only that safe projection. Before and after the call, the CLI
+reads the selected project's authoritative endpoint projection and requires the
+configured application origin to match its API origin or alias. Production
+confirmation is mandatory.
+
+`release_canary_fixture_disable_replay` performs one non-retried call to the
+fixed `fa_release_canary_fixture_disable` PostgREST RPC using the selected
+project's application service-role origin. Its receipt must contain exactly
+`fixtureId`, `state="disabled"`, and a boolean `idempotent`; both the first
+disable (`idempotent=false`) and same-request replay (`idempotent=true`) are
+valid. The CLI then calls the existing fixed
+`fa_release_canary_fixture_pending` RPC with only the exact issuer and subject
+query parameters and accepts only its authoritative JSON boolean `false`
+read-back. The fixture binding comes from the validated disable receipt before
+reporting success. Management endpoint projection is checked before and after.
+
 The legacy `.env` fallback is unclassified and therefore does not enable the
 production confirmation gate. Production automation must select a `prod` or
 `production` profile, or set `SUPACLOUD_ENV=production` together with a complete

package/dist/index.js

@@ -6491,7 +6491,7 @@ var ACTION_POLICY = {
   mutations: { read: ["status"] },
   release: {
     read: ["logical_backup_list", "postgrest_status"],
-    write: ["logical_backup_create", "logical_backup_restore", "postgrest_restart"]
+    write: ["logical_backup_create", "logical_backup_restore", "postgrest_restart", "release_canary_fixture_stage_replay", "release_canary_fixture_disable_replay"]
   },
   secrets: { read: ["list"], write: ["upsert", "delete"] },
   frontend: {
@@ -6805,14 +6805,17 @@ async function responseJsonOrNull(response) {
 class HttpTransport {
   baseUrl;
   token;
+  apiKey;
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
     this.token = config.token;
+    this.apiKey = config.apiKey ?? "";
   }
   headers() {
     return {
       Authorization: `Bearer ${this.token}`,
-      "Content-Type": "application/json"
+      "Content-Type": "application/json",
+      ...this.apiKey ? { apikey: this.apiKey } : {}
     };
   }
   async mutationWithResponseReader(method, path, serializedBody, responseReader, timeoutMs = DEFAULT_TIMEOUT) {
@@ -10562,6 +10565,15 @@ function projectEndpointRead(response, expectedRef) {
   const projection = projectEndpointProjection(response.data);
   return projection && projection.project_ref === expectedRef ? successfulResult2(projection) : failedResult2("Invalid project endpoint response");
 }
+function projectApiOrigins(response, expectedRef) {
+  if (!successfulResponse2(response))
+    return null;
+  const projection = projectEndpointProjection(response.data);
+  if (!projection || projection.project_ref !== expectedRef)
+    return null;
+  const api = projection.endpoints.api;
+  return [api.origin, ...api.aliases.map((alias) => `${api.scheme}://${alias}`)];
+}
 
 // src/shared/tools/project-cli-tools.ts
 function projectReadResponse(readResult) {
@@ -12829,6 +12841,13 @@ var INVENTORY_MAX_BYTES = 1024 * 1024;
 var MUTATION_MAX_BYTES = 64 * 1024;
 var BACKUP_TIMEOUT_MS = 36 * 60000;
 var RELEASE_READ_RESPONSE_TIMEOUT_MS = 5000;
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var RELEASE_CANARY_TENANT_KEY = /^release-canary-[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var RELEASE_CANARY_STAGE_RECEIPT_KEYS = new Set(["fixtureId", "tenantKey", "state", "idempotent"]);
+var RELEASE_CANARY_DISABLE_RECEIPT_KEYS = new Set(["fixtureId", "state", "idempotent"]);
+var RELEASE_CANARY_DISABLE_RPC_PATH = "/rest/v1/rpc/fa_release_canary_fixture_disable";
+var RELEASE_CANARY_PENDING_RPC_PATH = "/rest/v1/rpc/fa_release_canary_fixture_pending";
+var RELEASE_CANARY_CLAIM_MAX_LENGTH = 2048;
 function isRecord3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -12961,20 +12980,96 @@ function readPostgrestFailure(operation, read) {
 function isRestartReceipt(value) {
   return isRecord3(value) && value.service === "postgrest" && value.action === "restart" && value.success === true;
 }
+function releaseCanaryStageInput(subject, requestId) {
+  if (typeof subject !== "string" || !UUID.test(subject))
+    throw new Error("'subject' must be a canonical UUID");
+  if (typeof requestId !== "string" || !UUID.test(requestId))
+    throw new Error("'request_id' must be a canonical UUID");
+  return { p_subject: subject, p_request_id: requestId };
+}
+function releaseCanaryStageReceipt(value) {
+  if (!isRecord3(value) || Object.keys(value).some((key) => !RELEASE_CANARY_STAGE_RECEIPT_KEYS.has(key)) || Object.keys(value).length !== RELEASE_CANARY_STAGE_RECEIPT_KEYS.size || typeof value.fixtureId !== "string" || !UUID.test(value.fixtureId) || typeof value.tenantKey !== "string" || !RELEASE_CANARY_TENANT_KEY.test(value.tenantKey) || value.state !== "staged" || value.idempotent !== true)
+    return null;
+  return {
+    fixtureId: value.fixtureId,
+    tenantKey: value.tenantKey,
+    state: "staged",
+    idempotent: true
+  };
+}
+function releaseCanaryIssuer(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > RELEASE_CANARY_CLAIM_MAX_LENGTH || value !== value.trim() || /[\u0000-\u001f\u007f]/u.test(value)) {
+    throw new Error("'issuer' must be a bounded absolute HTTP(S) issuer");
+  }
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error("'issuer' must be a bounded absolute HTTP(S) issuer");
+  }
+  const loopbackHttp = parsed.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname) && parsed.port.length > 0;
+  if (parsed.protocol !== "https:" && !loopbackHttp || parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new Error("'issuer' must be a bounded absolute HTTP(S) issuer");
+  }
+  return value;
+}
+function releaseCanaryDisableInput(fixtureId, disableRequestId, issuer, subject) {
+  if (typeof fixtureId !== "string" || !UUID.test(fixtureId)) {
+    throw new Error("'fixture_id' must be a canonical UUID");
+  }
+  if (typeof disableRequestId !== "string" || !UUID.test(disableRequestId)) {
+    throw new Error("'disable_request_id' must be a canonical UUID");
+  }
+  if (typeof subject !== "string" || !UUID.test(subject)) {
+    throw new Error("'subject' must be a canonical UUID");
+  }
+  return {
+    p_fixture_id: fixtureId,
+    p_disable_request_id: disableRequestId,
+    p_issuer: releaseCanaryIssuer(issuer),
+    p_subject: subject
+  };
+}
+function releaseCanaryDisableReceipt(receiptCandidate, fixtureId) {
+  if (!isRecord3(receiptCandidate) || Object.keys(receiptCandidate).some((key) => !RELEASE_CANARY_DISABLE_RECEIPT_KEYS.has(key)) || Object.keys(receiptCandidate).length !== RELEASE_CANARY_DISABLE_RECEIPT_KEYS.size || receiptCandidate.fixtureId !== fixtureId || receiptCandidate.state !== "disabled" || typeof receiptCandidate.idempotent !== "boolean")
+    return null;
+  return { fixtureId, state: "disabled", idempotent: receiptCandidate.idempotent };
+}
+function releaseCanaryPendingPath(request) {
+  const params = new URLSearchParams({
+    p_issuer: request.p_issuer,
+    p_subject: request.p_subject
+  });
+  return `${RELEASE_CANARY_PENDING_RPC_PATH}?${params.toString()}`;
+}
+function releaseCanaryPendingReadback(readbackCandidate) {
+  return readbackCandidate === false;
+}
+async function applicationOriginMatches(http, projectRef2, applicationOrigin) {
+  const endpointRead = await http.get(`${endpoint(projectRef2)}/endpoint/projection`, { maxJsonBytes: PROJECT_ENDPOINT_RESPONSE_MAX_BYTES, responseTimeoutMs: RELEASE_READ_RESPONSE_TIMEOUT_MS });
+  return projectApiOrigins(endpointRead, projectRef2)?.includes(applicationOrigin) === true;
+}
 function registerReleaseTools(server, http, options = {}) {
-  server.tool("release", "Verified release controls using a Management API credential. Actions: logical_backup_list, logical_backup_create, logical_backup_restore, postgrest_status, postgrest_restart", {
+  server.tool("release", "Verified release controls. Management actions use the Management API; release canary stage/disable replay additionally require the selected project's SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.", {
     action: withDescription(stringEnum([
       "logical_backup_list",
       "logical_backup_create",
       "logical_backup_restore",
       "postgrest_status",
-      "postgrest_restart"
+      "postgrest_restart",
+      "release_canary_fixture_stage_replay",
+      "release_canary_fixture_disable_replay"
     ]), "Release control action"),
     ref: optional(Type.String(), options.projectRef ? "Optional override when not auto-linked" : "Project ref"),
     backup_id: optional(Type.String(), "[logical_backup_restore] Exact verified logical-full backup ID from the selected project inventory"),
     expected_sha256: optional(Type.String(), "[logical_backup_restore] Exact lowercase SHA-256 from the selected project inventory"),
-    restore_confirmation: optional(Type.String(), "[logical_backup_restore] Exact RESTORE_PROJECT:<ref>:<backup_id>:<sha256> confirmation")
-  }, async ({ action, ref, backup_id, expected_sha256, restore_confirmation }) => {
+    restore_confirmation: optional(Type.String(), "[logical_backup_restore] Exact RESTORE_PROJECT:<ref>:<backup_id>:<sha256> confirmation"),
+    subject: optional(Type.String(), "[release_canary_fixture_stage_replay/disable_replay] Exact central subject UUID"),
+    request_id: optional(Type.String(), "[release_canary_fixture_stage_replay] Exact idempotent stage request UUID"),
+    fixture_id: optional(Type.String(), "[release_canary_fixture_disable_replay] Exact staged fixture UUID"),
+    disable_request_id: optional(Type.String(), "[release_canary_fixture_disable_replay] Exact idempotent disable request UUID"),
+    issuer: optional(Type.String(), "[release_canary_fixture_disable_replay] Exact HTTP(S) issuer")
+  }, async ({ action, ref, backup_id, expected_sha256, restore_confirmation, subject, request_id, fixture_id, disable_request_id, issuer }) => {
     const projectRef2 = typeof ref === "string" && ref || options.projectRef;
     if (!projectRef2)
       throw new Error("'ref' is required for release controls");
@@ -13045,6 +13140,57 @@ function registerReleaseTools(server, http, options = {}) {
         postgrest: read2.status
       });
     }
+    if (action === "release_canary_fixture_stage_replay") {
+      if (!options.applicationHttp || !options.applicationOrigin) {
+        throw new Error("release_canary_fixture_stage_replay requires SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY");
+      }
+      const request = releaseCanaryStageInput(subject, request_id);
+      if (!await applicationOriginMatches(http, projectRef2, options.applicationOrigin)) {
+        return releaseControlFailure("release.release_canary.fixture_stage_replay", "INVALID_RESPONSE", null);
+      }
+      const response = await options.applicationHttp.postReleaseMutation("/rest/v1/rpc/fa_release_canary_fixture_stage", request);
+      if (!response.ok || response.status !== 200) {
+        return mutationFailure("release.release_canary.fixture_stage_replay", response);
+      }
+      const receipt = releaseCanaryStageReceipt(response.data);
+      if (!receipt || !await applicationOriginMatches(http, projectRef2, options.applicationOrigin)) {
+        return releaseControlFailure("release.release_canary.fixture_stage_replay", "OUTCOME_UNKNOWN", response.status);
+      }
+      return releaseControlSuccess("release.release_canary.fixture_stage_replay", {
+        project_ref: projectRef2,
+        receipt
+      });
+    }
+    if (action === "release_canary_fixture_disable_replay") {
+      if (!options.applicationHttp || !options.applicationOrigin) {
+        throw new Error("release_canary_fixture_disable_replay requires SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY");
+      }
+      const request = releaseCanaryDisableInput(fixture_id, disable_request_id, issuer, subject);
+      if (!await applicationOriginMatches(http, projectRef2, options.applicationOrigin)) {
+        return releaseControlFailure("release.release_canary.fixture_disable_replay", "INVALID_RESPONSE", null);
+      }
+      const response = await options.applicationHttp.postReleaseMutation(RELEASE_CANARY_DISABLE_RPC_PATH, request);
+      if (!response.ok || response.status !== 200) {
+        return mutationFailure("release.release_canary.fixture_disable_replay", response);
+      }
+      const receipt = releaseCanaryDisableReceipt(response.data, request.p_fixture_id);
+      if (!receipt) {
+        return releaseControlFailure("release.release_canary.fixture_disable_replay", "OUTCOME_UNKNOWN", response.status);
+      }
+      const pendingRequest = {
+        p_issuer: request.p_issuer,
+        p_subject: request.p_subject
+      };
+      const pendingResponse = await options.applicationHttp.get(releaseCanaryPendingPath(pendingRequest), { maxJsonBytes: MUTATION_MAX_BYTES, responseTimeoutMs: RELEASE_READ_RESPONSE_TIMEOUT_MS });
+      if (!pendingResponse.ok || pendingResponse.status !== 200 || !releaseCanaryPendingReadback(pendingResponse.data) || !await applicationOriginMatches(http, projectRef2, options.applicationOrigin)) {
+        return releaseControlFailure("release.release_canary.fixture_disable_replay", "OUTCOME_UNKNOWN", pendingResponse.transportError ? null : pendingResponse.status);
+      }
+      return releaseControlSuccess("release.release_canary.fixture_disable_replay", {
+        project_ref: projectRef2,
+        receipt,
+        pending: false
+      });
+    }
     if (action !== "postgrest_restart")
       throw new Error("Unknown release control action");
     const mutation = await http.postReleaseMutation(`${endpoint(projectRef2)}/services/postgrest/restart`);
@@ -13065,7 +13211,7 @@ function registerReleaseTools(server, http, options = {}) {
 // package.json
 var package_default = {
   name: "@supacloud/cli",
-  version: "0.28.1",
+  version: "0.30.0",
   description: "Project-scoped CLI for SupaCloud users",
   type: "module",
   main: "./dist/index.js",
@@ -13294,7 +13440,8 @@ DEFAULT CONTEXT
   Without a selector or project variables, runs use the current project's legacy .env.
   Application status accepts SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY.
   Management-backed project commands require SUPACLOUD_API_URL +
-  SUPACLOUD_API_TOKEN. These credential scopes are never mixed.
+  SUPACLOUD_API_TOKEN. Only release canary stage/disable replay actions may additionally use
+  the selected project's SUPABASE_* pair for fixed application-origin RPCs.
   SUPACLOUD_PROJECT_REF is required when it cannot be inferred from <ref>.api.*.
 
   SUPACLOUD_READ_ONLY=true blocks remote writes. Production writes require an
@@ -13315,6 +13462,8 @@ EXAMPLES
   ${preferredCommand} release logical_backup_restore --ref abc123 --backup_id <backup_id> --expected_sha256 <sha256> --restore_confirmation RESTORE_PROJECT:abc123:<backup_id>:<sha256>
   ${preferredCommand} release postgrest_status --ref abc123
   ${preferredCommand} release postgrest_restart --ref abc123
+  ${preferredCommand} release release_canary_fixture_stage_replay --ref abc123 --subject <uuid> --request_id <uuid>
+  ${preferredCommand} release release_canary_fixture_disable_replay --ref abc123 --fixture_id <uuid> --disable_request_id <uuid> --issuer <issuer-url> --subject <uuid>
   ${preferredCommand} queue stats --queue emails
   ${preferredCommand} queue dlq --queue emails --limit 20
   ${preferredCommand} frontend list --ref abc123
@@ -13473,6 +13622,11 @@ function createCliTools(context, confirmProduction) {
     baseUrl: context.apiUrl,
     token: context.apiToken
   });
+  const applicationHttp = context.inferredSupabaseUrl && context.inferredServiceRoleKey ? new HttpTransport({
+    baseUrl: context.inferredSupabaseUrl,
+    token: context.inferredServiceRoleKey,
+    apiKey: context.inferredServiceRoleKey
+  }) : undefined;
   const assign = (extra) => Object.assign(tools, extra);
   assign(captureTools((server) => registerUserProjectCliTools(server, http, {
     projectRef: context.projectRef || undefined
@@ -13494,7 +13648,9 @@ function createCliTools(context, confirmProduction) {
   })));
   assign(captureTools((server) => registerMutationTools(server, http)));
   assign(captureTools((server) => registerReleaseTools(server, http, {
-    projectRef: context.projectRef || undefined
+    projectRef: context.projectRef || undefined,
+    applicationHttp,
+    applicationOrigin: context.inferredSupabaseUrl || undefined
   })));
   assign(captureTools((server) => registerFrontendTools(server, http)));
   assign(captureTools((server) => registerGatewayTools(server, http, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/cli",
-  "version": "0.28.1",
+  "version": "0.30.0",
   "description": "Project-scoped CLI for SupaCloud users",
   "type": "module",
   "main": "./dist/index.js",

package/skills/supacloud-cli/references/command-map.md

@@ -15,6 +15,8 @@ Load this reference when selecting a command surface or when a user asks an AI t
 | Generate migration from local schema changes | `supabase db_diff` | Review generated SQL before use |
 | Rebuild local database | `supabase db_reset` | Local only; preserve required seed behavior |
 | Inspect or back up a remote database | `supabase db_pull`, `migration_list`, `db_dump`, `gen_types` | Requires explicit PostgreSQL DSN; redact it |
+| Replay the release-canary fixture stage receipt | `release release_canary_fixture_stage_replay` | Dual-bind Management project context and that project's service-role application origin; accepts only the exact subject/request UUID pair and a strict idempotent receipt |
+| Disable a staged release-canary fixture | `release release_canary_fixture_disable_replay` | Uses the fixed disable RPC once, accepts idempotent false/true receipts, then queries the existing pending RPC with issuer/subject and requires authoritative JSON `false`; fixture binding comes from the strict disable receipt |
 | Preview/apply migrations remotely | `supabase push` | Always dry-run first; production needs explicit approval |
 | Mark proven-equivalent historical migrations as applied | `database baseline_migrations` | Dry-run, schema-equivalence proof, backup, explicit approval |
 | Inspect auth users or generate a controlled login link | `auth list_users`, `auth get_user`, `auth generate_link` | User reads are bounded; generation supports only `magiclink`, `recovery`, and `invite`, requires production confirmation, and returns only a validated action URL |
@@ -39,6 +41,7 @@ until a project-scoped context is resolved.
 - `secrets`: project secret management; never print values after write.
 - `queue`, `task_events`, `diagnostics`: asynchronous workload operations and bounded diagnostics.
 - `gateway`: project route/config/rebuild operations.
+- `release`: verified backup/PostgREST lifecycle controls plus production-confirmed, non-retried, strict release-canary fixture stage and disable replay actions. These actions require both the selected Management project binding and that project's `SUPABASE_URL`/`SUPABASE_SERVICE_ROLE_KEY`.
 - `ai`: inspect or install this packaged Skill.
 
 ## Safe inspection pattern