@integrity-labs/cloud-broker 0.7.3 → 0.7.4

package/README.md

@@ -37,6 +37,23 @@ See the PRDs ([AWS](../../docs/prds/aws-ephemeral-access.md), [GCP](../../docs/p
 | `gcp_check_approval_channel` | Pre-flight Slack channel reachability for the project's approval channel. |
 | `gcp_list_accounts` | Live inventory of enrolled GCP projects. |
 
+### Supabase
+
+Credentials returned are a short-lived **Supabase JWT** (+ `supabase_url`, `db_host`, `project_ref`), not a cloud IAM token. The agent uses it for PostgREST (`Authorization: Bearer …`) or `psql` via the session pooler.
+
+| Tool | Purpose |
+|---|---|
+| `supabase_describe_scope` | Resolved policy ceiling for a Supabase project (auto-approvable roles, schema ceiling, write gating). Free, idempotent. |
+| `supabase_preview_request` | Dry-run a candidate request. Writes nothing. |
+| `supabase_request_access` | Mint or queue a grant. `service_role` always routes to a human approver; privileged internal roles (`postgres`, `supabase_admin`, …) are hard-denied. |
+| `supabase_poll_grant` | Single-shot status check. Escape hatch. |
+| `supabase_get_credentials` | Fetch the JWT + connection details for an active grant. |
+| `supabase_release_access` | Voluntarily release a grant before TTL. Idempotent. **Note:** the JWT is stateless — release marks the grant revoked but the token stays valid until its `exp`. |
+| `supabase_check_approval_channel` | Pre-flight Slack channel reachability for the project's approval channel. |
+| `supabase_list_projects` | Live inventory of enrolled Supabase projects. |
+
+See **[`docs/runbooks/supabase-broker-enrollment.md`](../../docs/runbooks/supabase-broker-enrollment.md)** for operator enrollment, the `augmented` JWT-claim → RLS-policy enforcement guide, and the policy-ceiling shape.
+
 ## Environment
 
 | Var | Purpose |
@@ -134,6 +151,57 @@ gcp_release_access({ grant_id: "..." })
 
 Same `pending` / direct-chat-push resolution semantics as AWS. The runtime resolves `secret_ref://gcp/runs/...` to `CLOUDSDK_AUTH_ACCESS_TOKEN` and `GOOGLE_OAUTH_ACCESS_TOKEN` at exec time, so `gcloud`, `gsutil`, and `bq` all pick it up automatically without the agent ever handling the raw token.
 
+## Worked example (Supabase)
+
+An agent that needs read-only access to two tables in `public`:
+
+```jsonc
+// 1. Inspect the envelope — which roles auto-approve, the schema ceiling, write gating.
+supabase_describe_scope({ project_ref: "abcdefghijklmnopqrst" })
+
+// 2. Dry-run.
+supabase_preview_request({
+  project_ref: "abcdefghijklmnopqrst",
+  role: "authenticated",
+  allowed_schemas: ["public"],
+  allowed_tables: ["public.agents", "public.runs"], // optional — absent = all tables in allowed_schemas
+  read_only: true,
+  ttl_seconds: 900
+})
+// → { "would": "auto_approve", "reason": null }
+
+// 3. Mint.
+supabase_request_access({
+  project_ref: "abcdefghijklmnopqrst",
+  role: "authenticated",
+  allowed_schemas: ["public"],
+  allowed_tables: ["public.agents", "public.runs"],
+  read_only: true,
+  ttl_seconds: 900,
+  reason: "read the agents + runs tables to answer the user's status question"
+})
+// → { "grant_id": "...", "status": "active", "secret_ref": "supabase:jwt:<grant_id>", "expires_at": "..." }
+//    `service_role` or write access (read_only:false, unless the project allows writes)
+//    returns "pending" instead and pages a human approver.
+
+// 4. Fetch the JWT + connection details.
+supabase_get_credentials({ grant_id: "..." })
+// → { "grant_id": "...", "expires_at": "...",
+//     "credentials": { "access_token": "<JWT>", "supabase_url": "https://<ref>.supabase.co",
+//                      "db_host": "aws-0-<region>.pooler.supabase.com", "project_ref": "<ref>" } }
+//
+//    REST (PostgREST):
+//      curl "$supabase_url/rest/v1/agents?select=*" \
+//        -H "apikey: <JWT>" -H "Authorization: Bearer <JWT>"
+//    psql (session pooler):
+//      psql "postgresql://postgres.<project_ref>:<JWT>@<db_host>:5432/postgres"
+
+// 5. (Optional) release early.
+supabase_release_access({ grant_id: "..." })
+```
+
+The grant's scope (`allowed_schemas` / `allowed_tables` / `read_only`) is carried in the JWT's `augmented` claim and is **only enforced if the project's RLS policies read that claim** — see the [enrollment runbook](../../docs/runbooks/supabase-broker-enrollment.md#enforcing-the-grant-scope-with-rls) for the policy patterns. Same `pending` / direct-chat-push resolution semantics as AWS.
+
 ## Running locally
 
 ```bash

package/dist/index.js

@@ -21574,7 +21574,7 @@ var supabaseListProjectsShape = supabaseListProjectsSchema.shape;
 // package.json
 var package_default = {
   name: "@integrity-labs/cloud-broker",
-  version: "0.7.3",
+  version: "0.7.4",
   description: "Cloud Access Broker \u2014 MCP server that mints scoped, TTL-bounded cloud credentials per agent task. Ships AWS support (aws_request_access, aws_poll_grant, aws_release_access, aws_describe_scope, aws_preview_request, aws_get_credentials \u2014 STS AssumeRole under the hood); GCP, Azure, and Cloudflare land alongside in the same package as the broker grows.",
   type: "module",
   bin: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@integrity-labs/cloud-broker",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "Cloud Access Broker — MCP server that mints scoped, TTL-bounded cloud credentials per agent task. Ships AWS support (aws_request_access, aws_poll_grant, aws_release_access, aws_describe_scope, aws_preview_request, aws_get_credentials — STS AssumeRole under the hood); GCP, Azure, and Cloudflare land alongside in the same package as the broker grows.",
   "type": "module",
   "bin": {