@integrity-labs/cloud-broker 0.7.3 → 0.7.5

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

@@ -20985,6 +20985,26 @@ var StdioServerTransport = class {
   }
 };
 
+// src/turn-initiator-marker.ts
+import { readFileSync } from "fs";
+var TURN_INITIATOR_MAX_AGE_MS = 5 * 60 * 1e3;
+function readTurnInitiator(maxAgeMs = TURN_INITIATOR_MAX_AGE_MS) {
+  const file = process.env["AGT_TURN_INITIATOR_FILE"];
+  if (!file) return null;
+  try {
+    const raw = readFileSync(file, "utf8");
+    const m = JSON.parse(raw);
+    if (typeof m.channel !== "string" || !m.channel) return null;
+    if (typeof m.sender_id !== "string" || !m.sender_id) return null;
+    if (typeof m.ts !== "number" || !Number.isFinite(m.ts)) return null;
+    const age = Date.now() - m.ts;
+    if (age < 0 || age > maxAgeMs) return null;
+    return { channel: m.channel, sender_id: m.sender_id };
+  } catch {
+    return null;
+  }
+}
+
 // src/broker-client.ts
 function makeBrokerError(status, message, detail) {
   const err = new Error(message);
@@ -21123,7 +21143,15 @@ var BrokerClient = class {
     if (!runId) {
       throw makeBrokerError(400, "BrokerClient.requestAccess requires run_id (pass it in args, or set runId on BrokerClientConfig)");
     }
-    const body = { ...args, agent_id: agentId, run_id: runId };
+    const turnInitiator = readTurnInitiator();
+    const { turn_initiator: _ignoredForged, ...safeArgs } = args;
+    void _ignoredForged;
+    const body = {
+      ...safeArgs,
+      agent_id: agentId,
+      run_id: runId,
+      ...turnInitiator ? { turn_initiator: turnInitiator } : {}
+    };
     return this.request("POST", `${this.apiPathPrefix}/grants`, { body });
   }
   pollGrant(args) {
@@ -21574,7 +21602,7 @@ var supabaseListProjectsShape = supabaseListProjectsSchema.shape;
 // package.json
 var package_default = {
   name: "@integrity-labs/cloud-broker",
-  version: "0.7.3",
+  version: "0.7.5",
   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.5",
   "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": {