@integrity-labs/cloud-broker 0.7.11 → 0.7.13

package/README.md

@@ -39,7 +39,9 @@ See the PRDs ([AWS](../../docs/prds/aws-ephemeral-access.md), [GCP](../../docs/p
 
 ### 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.
+Since ENG-7326 the agent **holds no credential**: it queries Supabase through server-side proxy tools that run the call under the grant's scope. `supabase_rest` (PostgREST, read + write) is the primary path; `supabase_query` runs read-only SQL. The operator stores, on the enrolment, the project's REST api_key (a **new-format `sb_secret_…` key** - legacy anon/service_role keys are disabled) and/or a scoped read-only Postgres connection string; the broker injects whichever the call needs at exec time. The scope (`allowed_tables` / `read_only`) is enforced at the broker, independent of RLS.
+
+The legacy `supabase_get_credentials` still mints a short-lived Supabase JWT for direct PostgREST/`psql` use, but the proxy tools are preferred (they never hand the agent a secret, and they don't depend on RLS to enforce scope).
 
 | Tool | Purpose |
 |---|---|
@@ -47,12 +49,15 @@ Credentials returned are a short-lived **Supabase JWT** (+ `supabase_url`, `db_h
 | `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_describe` | Inspect what an **active grant** can do (role, allowed schemas/tables, read_only, and whether server-side SQL is enrolled) before querying. |
+| `supabase_rest` | **Primary.** Call the project's PostgREST API (read + write) server-side under the grant's scope. The broker injects the api_key; the agent holds nothing. `rpc/` is blocked. |
+| `supabase_query` | Run **read-only SQL** server-side under the grant's scoped DB role (READ ONLY transaction + statement timeout). For system tables / joins REST can't express. Requires a DB connection string on the enrolment. |
+| `supabase_get_credentials` | **Legacy.** Fetch a short-lived Supabase JWT + connection details for an active grant (direct PostgREST/`psql`). Prefer the proxy tools. |
+| `supabase_release_access` | Voluntarily release a grant before TTL. Idempotent. (For the legacy JWT path 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.
+See **[`docs/runbooks/supabase-broker-enrollment.md`](../../docs/runbooks/supabase-broker-enrollment.md)** for operator enrollment (storing the REST api_key + DB connection string), the policy-ceiling shape, and the legacy `augmented` JWT-claim → RLS-policy enforcement guide.
 
 ## Environment
 
@@ -180,27 +185,28 @@ supabase_request_access({
   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": "..." }
+// → { "grant_id": "...", "status": "active", "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"
+// 4. Learn your scope (recommended - also tells you if server-side SQL is enrolled).
+supabase_describe({ grant_id: "..." })
+// → { role, allowed_schemas, allowed_tables, read_only, sql_query: { available, ... } }
 
-// 5. (Optional) release early.
+// 5. Query. You hold NO credential - the broker runs the call server-side and injects the key.
+//    REST (primary, read + write):
+supabase_rest({ grant_id: "...", method: "GET", path: "agents?select=*&limit=10" })
+// → { ok: true, status: 200, body: [ ... ] }
+//    Read-only SQL (system tables / joins REST can't express; needs a DB connection string enrolled):
+supabase_query({ grant_id: "...", sql: "select count(*) from runs" })
+// → { ok: true, rows: [{ count: 42 }], row_count: 1 }
+//    Both return { ok: false, error_code } on a denial - branch on error_code, don't treat it as a tool failure.
+
+// 6. (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.
+With the proxy tools the grant's scope (`allowed_tables` / `read_only`) is enforced **at the broker** - read-only grants reject writes, calls outside `allowed_tables` are denied, and `rpc/` is blocked - independent of RLS. (For the legacy `supabase_get_credentials` JWT path, scope instead rides the JWT's `augmented` claim and is only enforced if the project's RLS policies read it - see the [enrollment runbook](../../docs/runbooks/supabase-broker-enrollment.md#enforcing-the-grant-scope-with-rls) for those policy patterns.) Same `pending` / direct-chat-push resolution semantics as AWS.
 
 ## Running locally
 

package/dist/index.js

@@ -20987,10 +20987,41 @@ var StdioServerTransport = class {
 
 // src/turn-initiator-marker.ts
 import { readFileSync } from "fs";
+import { dirname, join } from "path";
 var TURN_INITIATOR_MAX_AGE_MS = 5 * 60 * 1e3;
+var TURN_INITIATOR_LEDGER_FILENAME = ".turn-initiator-ledger.json";
+function readTurnInitiatorFromLedger(file, maxAgeMs) {
+  const ledgerFile = join(dirname(file), TURN_INITIATOR_LEDGER_FILENAME);
+  let entries;
+  try {
+    const parsed = JSON.parse(readFileSync(ledgerFile, "utf8"));
+    if (!parsed || parsed.v !== 1 || !Array.isArray(parsed.entries)) return "no-ledger";
+    entries = parsed.entries;
+  } catch {
+    return "no-ledger";
+  }
+  const now = Date.now();
+  const fresh = entries.filter(
+    (e) => e && typeof e.channel === "string" && e.channel && typeof e.sender_id === "string" && e.sender_id && typeof e.ts === "number" && Number.isFinite(e.ts) && now - e.ts >= 0 && now - e.ts <= maxAgeMs
+  );
+  if (fresh.length === 1) {
+    const e = fresh[0];
+    return { channel: e.channel, sender_id: e.sender_id };
+  }
+  if (fresh.length >= 2) {
+    process.stderr.write(
+      `turn-initiator: ambiguous (${fresh.length} fresh senders), withholding initiator
+`
+    );
+    return null;
+  }
+  return "no-ledger";
+}
 function readTurnInitiator(maxAgeMs = TURN_INITIATOR_MAX_AGE_MS) {
   const file = process.env["AGT_TURN_INITIATOR_FILE"];
   if (!file) return null;
+  const fromLedger = readTurnInitiatorFromLedger(file, maxAgeMs);
+  if (fromLedger !== "no-ledger") return fromLedger;
   try {
     const raw = readFileSync(file, "utf8");
     const m = JSON.parse(raw);
@@ -21644,7 +21675,7 @@ var supabaseRestShape = supabaseRestSchema.shape;
 // package.json
 var package_default = {
   name: "@integrity-labs/cloud-broker",
-  version: "0.7.11",
+  version: "0.7.13",
   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: {
@@ -21667,7 +21698,7 @@ var package_default = {
   scripts: {
     build: "tsup",
     dev: "tsx watch src/index.ts",
-    typecheck: "tsc --noEmit",
+    typecheck: "bash ../../scripts/typecheck-guard.sh tsc --noEmit",
     test: "vitest run",
     clean: "rm -rf dist",
     "publish:templates": "bash cloudformation/publish.sh",
@@ -22137,7 +22168,7 @@ server.tool(
 );
 server.tool(
   "supabase_query",
-  "Run READ-ONLY SQL against a Supabase project for an ACTIVE grant. THIS is how you query Supabase - you do NOT get or hold a database credential, and the supabase_get_credentials JWT cannot run SQL. The broker executes your SQL server-side under the grant's scoped database role, inside a READ ONLY transaction with a statement timeout, and returns rows. Args: { grant_id, sql }. Returns on success { grant_id, ok: true, rows, row_count, truncated } (truncated=true means the row cap was hit - add LIMIT/aggregate). On failure returns { ok: false, error_code, error } where error_code is one of READ_ONLY (you attempted a write - this capability is read-only), SCOPE_DENIED (your grant's role can't access that object - try supabase_describe to see your scope), OBJECT_NOT_FOUND (no such relation/schema, or not visible to your grant), TIMEOUT (query too slow), SYNTAX_ERROR, UNREACHABLE, SQL_NOT_CONFIGURED (no scoped DB credential enrolled - tell the user to ask their operator to configure it), or a grant-state code GRANT_NOT_ACTIVE / GRANT_EXPIRED / GRANT_RELEASED (re-request access). Writes are always rejected. Call supabase_describe first if unsure what you can read. All of these come back in the { ok:false, error_code } envelope on a normal response - branch on error_code, do not treat them as tool failures." + NO_DIRECT_SUPABASE_HTTP_BLOCK,
+  "Run READ-ONLY SQL against a Supabase project for an ACTIVE grant. THIS is how you query Supabase - you do NOT get or hold a database credential, and the supabase_get_credentials JWT cannot run SQL. The broker executes your SQL server-side under the grant's scoped database role, inside a READ ONLY transaction with a statement timeout, and returns rows. Args: { grant_id, sql }. Returns on success { grant_id, ok: true, rows, row_count, truncated } (truncated=true means the row cap was hit - add LIMIT/aggregate). On failure returns { ok: false, error_code, error } where error_code is one of READ_ONLY (you attempted a write - this capability is read-only), SCOPE_DENIED (your grant's role can't access that object - try supabase_describe to see your scope), OBJECT_NOT_FOUND (no such relation/schema, or not visible to your grant), TIMEOUT (query too slow), SYNTAX_ERROR, AUTH_FAILED (the database rejected the enrolled credentials - not something you can fix, tell the user to ask their operator to re-check the stored connection string), UNREACHABLE (the broker cannot reach the database over the network - also an operator fix, not a query fix), SQL_NOT_CONFIGURED (no scoped DB credential enrolled - tell the user to ask their operator to configure it), or a grant-state code GRANT_NOT_ACTIVE / GRANT_EXPIRED / GRANT_RELEASED (re-request access). Writes are always rejected. Call supabase_describe first if unsure what you can read. All of these come back in the { ok:false, error_code } envelope on a normal response - branch on error_code, do not treat them as tool failures." + NO_DIRECT_SUPABASE_HTTP_BLOCK,
   supabaseQueryShape,
   async (args) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@integrity-labs/cloud-broker",
-  "version": "0.7.11",
+  "version": "0.7.13",
   "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": {
@@ -23,7 +23,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsx watch src/index.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "bash ../../scripts/typecheck-guard.sh tsc --noEmit",
     "test": "vitest run",
     "clean": "rm -rf dist",
     "publish:templates": "bash cloudformation/publish.sh",