@raytio/mcp-server 3.0.0 → 3.4.0

package/README.md

@@ -145,13 +145,14 @@ Restart Codex CLI after editing the config. Inside a session, `/mcp` lists loade
 
 ### Tool domain selection
 
-The server decides which tools to expose using the following precedence:
+The server decides which tools to expose in two layers:
 
-1. **`RAYTIO_TOOL_DOMAINS` env var** (static override) — if set and non-empty, this value is used directly. No backend query is made.
-2. **Dynamic role resolution** — if `RAYTIO_TOOL_DOMAINS` is not set, the server queries the authenticated user's roles via `fnd_authz_user_groups()` at startup and maps them to tool domains automatically.
-3. **All domains** (fallback) — if the role query fails or returns no recognised roles, every domain is exposed (matching pre-v1.4.0 behaviour).
+1. **Role-domain filter** (coarse) — at startup the server queries the authenticated user's roles via `fnd_authz_user_groups()` and maps them to tool domains. The `RAYTIO_TOOL_DOMAINS` env var can further restrict this set but never expand it.
+2. **Effective-capability filter** (fine) — the server then calls the Persist RPC `fnd_get_effective_capabilities()` and drops any tool whose declared `(resource_group, resource_name, operation, scope)` requirement is not satisfied. `OWN_RECORDS` grants NEVER silently satisfy `ALL_RECORDS` requirements.
 
-The server logs which path was taken at startup (to stderr).
+Both layers **fail closed**: if the role query or capability RPC fails, or returns no recognised roles / no capabilities for a gated tool, that tool is not exposed. Dispatch re-checks capabilities at call time, so a stale `ListTools` result cannot bypass the check.
+
+The server logs which path was taken and how many tools were hidden at startup (to stderr).
 
 #### How dynamic resolution works
 

package/dist/authorization.d.ts

@@ -1,4 +1,6 @@
+import { EffectiveCapabilityIndex } from './capabilities/effective-capabilities.js';
 import { RaytioApiClient } from './raytio/api-client.js';
+import { Tool } from './tools/registry.js';
 /**
  * Result of resolving the effective tool domain set for the authenticated
  * user. When `authorized` is `false`, the caller MUST expose no tools.
@@ -10,20 +12,43 @@ export interface AuthorizationResult {
     reason: string;
     /** `true` when the caller should expose tools. `false` means fail closed — expose nothing. */
     authorized: boolean;
+    /**
+     * Immutable index over the caller's effective Persist capabilities.
+     * Present only when the effective-capabilities RPC was fetched and
+     * validated successfully. Consumers use this both to filter the
+     * advertised tool list and to gate `CallTool` dispatch.
+     */
+    capabilities?: EffectiveCapabilityIndex;
 }
 type StderrLogger = Pick<Console, 'error'>;
 /**
  * Resolve the tool domain surface for the authenticated user.
  *
  * Behaviour:
- *  - Always queries the backend for the user's resolved roles. On any
- *    failure, fails closed and exposes no tools.
+ *  - Always queries the backend for the user's resolved roles AND
+ *    effective Persist capabilities. On any failure of either query,
+ *    fails closed and exposes no tools.
  *  - The static `RAYTIO_TOOL_DOMAINS` override may only *restrict* the
  *    user's resolved domain set. It never grants access to domains the
  *    user does not have.
  *  - If the intersection is empty (or the user has no recognised roles),
  *    fails closed.
+ *  - The returned `capabilities` index is used downstream by
+ *    {@link filterToolsByCapabilities} and by the dispatch layer to
+ *    enforce per-tool authorisation at both advertisement and call time.
  */
 export declare function resolveToolDomains(apiClient: RaytioApiClient, envSpec: string | undefined, logger?: StderrLogger): Promise<AuthorizationResult>;
+/**
+ * Drop any tool whose declared `capabilities` are not satisfied by the
+ * caller's effective capability set. Tools that have no `capabilities`
+ * declaration pass through unchanged — they are gated only by the
+ * coarser role-domain filter until they are migrated onto the pinned
+ * Persist resource contract (see WI-0003500 onward).
+ *
+ * A tool with an empty `capabilities` array is treated as declaring
+ * "requires no permission" and passes through — the empty list is an
+ * explicit affirmation, not a fallthrough.
+ */
+export declare function filterToolsByCapabilities(tools: readonly Tool[], capabilities: EffectiveCapabilityIndex, logger?: StderrLogger): Tool[];
 export {};
 //# sourceMappingURL=authorization.d.ts.map

package/dist/authorization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,mHAAmH;IACnH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,KAAK,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAgD3C;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,GAAE,YAAsB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CAyC9B"}
+{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,wBAAwB,EAEzB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAG3C;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,mHAAmH;IACnH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,wBAAwB,CAAC;CACzC;AAED,KAAK,YAAY,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAgD3C;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,GAAE,YAAsB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,CAqE9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,YAAY,EAAE,wBAAwB,EACtC,MAAM,GAAE,YAAsB,GAC7B,IAAI,EAAE,CA8BR"}

package/dist/authorization.js

@@ -1,3 +1,4 @@
+import { EffectiveCapabilityError, fetchEffectiveCapabilities, } from './capabilities/effective-capabilities.js';
 import { resolveUserDomains } from './tools/role-mapping.js';
 /**
  * Domains that a static override may resolve to when the user only holds
@@ -44,13 +45,17 @@ function restrictToUserDomains(staticDomains, userDomains) {
  * Resolve the tool domain surface for the authenticated user.
  *
  * Behaviour:
- *  - Always queries the backend for the user's resolved roles. On any
- *    failure, fails closed and exposes no tools.
+ *  - Always queries the backend for the user's resolved roles AND
+ *    effective Persist capabilities. On any failure of either query,
+ *    fails closed and exposes no tools.
  *  - The static `RAYTIO_TOOL_DOMAINS` override may only *restrict* the
  *    user's resolved domain set. It never grants access to domains the
  *    user does not have.
  *  - If the intersection is empty (or the user has no recognised roles),
  *    fails closed.
+ *  - The returned `capabilities` index is used downstream by
+ *    {@link filterToolsByCapabilities} and by the dispatch layer to
+ *    enforce per-tool authorisation at both advertisement and call time.
  */
 export async function resolveToolDomains(apiClient, envSpec, logger = console) {
     const staticDomains = parseSpec(envSpec);
@@ -69,10 +74,28 @@ export async function resolveToolDomains(apiClient, envSpec, logger = console) {
         logger.error(`Raytio MCP: ${reason} — exposing no tools (fail closed)`);
         return { domainSpec: undefined, reason, authorized: false };
     }
+    let capabilities;
+    try {
+        capabilities = await fetchEffectiveCapabilities(apiClient);
+    }
+    catch (err) {
+        const detail = err instanceof EffectiveCapabilityError
+            ? err.message
+            : `unexpected error: ${err.message}`;
+        const reason = `effective capabilities discovery failed: ${detail}`;
+        logger.error(`Raytio MCP: ${reason} — exposing no tools (fail closed)`);
+        return { domainSpec: undefined, reason, authorized: false };
+    }
+    logger.error(`Raytio MCP: fetched ${capabilities.size} effective capability rows for authenticated user`);
     if (staticDomains.length === 0) {
         const spec = userDomains.join(',');
         logger.error(`Raytio MCP: resolved domains from user roles: ${spec}`);
-        return { domainSpec: spec, reason: 'resolved from user roles', authorized: true };
+        return {
+            domainSpec: spec,
+            reason: 'resolved from user roles',
+            authorized: true,
+            capabilities,
+        };
     }
     const allowed = restrictToUserDomains(staticDomains, userDomains);
     if (allowed.length === 0) {
@@ -82,6 +105,46 @@ export async function resolveToolDomains(apiClient, envSpec, logger = console) {
     }
     const spec = allowed.join(',');
     logger.error(`Raytio MCP: static RAYTIO_TOOL_DOMAINS restricted user roles (${userDomains.join(',')}) to ${spec}`);
-    return { domainSpec: spec, reason: 'restricted by static override', authorized: true };
+    return {
+        domainSpec: spec,
+        reason: 'restricted by static override',
+        authorized: true,
+        capabilities,
+    };
+}
+/**
+ * Drop any tool whose declared `capabilities` are not satisfied by the
+ * caller's effective capability set. Tools that have no `capabilities`
+ * declaration pass through unchanged — they are gated only by the
+ * coarser role-domain filter until they are migrated onto the pinned
+ * Persist resource contract (see WI-0003500 onward).
+ *
+ * A tool with an empty `capabilities` array is treated as declaring
+ * "requires no permission" and passes through — the empty list is an
+ * explicit affirmation, not a fallthrough.
+ */
+export function filterToolsByCapabilities(tools, capabilities, logger = console) {
+    const allowed = [];
+    let hidden = 0;
+    for (const tool of tools) {
+        if (!tool.capabilities || tool.capabilities.length === 0) {
+            allowed.push(tool);
+            continue;
+        }
+        const missing = tool.capabilities.filter((req) => !capabilities.satisfies(req));
+        if (missing.length === 0) {
+            allowed.push(tool);
+            continue;
+        }
+        hidden += 1;
+        const detail = missing
+            .map((r) => `${r.resourceGroup}.${r.resourceName}#${r.operation}@${r.scope ?? 'OWN_RECORDS'}`)
+            .join(', ');
+        logger.error(`Raytio MCP: hiding tool "${tool.name}" — missing capability: ${detail}`);
+    }
+    if (hidden > 0) {
+        logger.error(`Raytio MCP: capability filter hid ${hidden}/${tools.length} tools`);
+    }
+    return allowed;
 }
 //# sourceMappingURL=authorization.js.map

package/dist/authorization.js.map

@@ -1 +1 @@
-{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EAExB,0BAA0B,GAC3B,MAAM,0CAA0C,CAAC;AAGlD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAwB7D;;;;;GAKG;AACH,MAAM,gBAAgB,GAA2B;IAC/C,cAAc,EAAE,KAAK;IACrB,cAAc,EAAE,KAAK;IACrB,cAAc,EAAE,KAAK;CACtB,CAAC;AAEF,SAAS,SAAS,CAAC,IAA+B;IAChD,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,OAAO,IAAI;SACR,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,qBAAqB,CAC5B,aAAuB,EACvB,WAAqB;IAErB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;IACrC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QAC9B,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChB,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;QACnC,IAAI,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAClC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAA0B,EAC1B,OAA2B,EAC3B,SAAuB,OAAO;IAE9B,MAAM,aAAa,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAEzC,IAAI,WAA+B,CAAC;IACpC,IAAI,CAAC;QACH,WAAW,GAAG,MAAM,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,MAAM,MAAM,GAAG,sBAAsB,GAAG,EAAE,OAAO,IAAI,GAAG,EAAE,CAAC;QAC3D,MAAM,CAAC,KAAK,CACV,gDAAgD,MAAM,qCAAqC,CAC5F,CAAC;QACF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC9D,CAAC;IAED,MAAM,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;IAE3C,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,8BAA8B,CAAC;QAC9C,MAAM,CAAC,KAAK,CACV,eAAe,MAAM,oCAAoC,CAC1D,CAAC;QACF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC9D,CAAC;IAED,IAAI,YAAsC,CAAC;IAC3C,IAAI,CAAC;QACH,YAAY,GAAG,MAAM,0BAA0B,CAAC,SAAS,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GACV,GAAG,YAAY,wBAAwB;YACrC,CAAC,CAAC,GAAG,CAAC,OAAO;YACb,CAAC,CAAC,qBAAsB,GAAa,CAAC,OAAO,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,4CAA4C,MAAM,EAAE,CAAC;QACpE,MAAM,CAAC,KAAK,CACV,eAAe,MAAM,oCAAoC,CAC1D,CAAC;QACF,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC9D,CAAC;IACD,MAAM,CAAC,KAAK,CACV,uBAAuB,YAAY,CAAC,IAAI,mDAAmD,CAC5F,CAAC;IAEF,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,CAAC,KAAK,CAAC,iDAAiD,IAAI,EAAE,CAAC,CAAC;QACtE,OAAO;YACL,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,0BAA0B;YAClC,UAAU,EAAE,IAAI;YAChB,YAAY;SACb,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,qBAAqB,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IAClE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,+BAA+B,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,oCAAoC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QAClI,MAAM,CAAC,KAAK,CAAC,eAAe,MAAM,oCAAoC,CAAC,CAAC;QACxE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC9D,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,CAAC,KAAK,CACV,iEAAiE,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CACrG,CAAC;IACF,OAAO;QACL,UAAU,EAAE,IAAI;QAChB,MAAM,EAAE,+BAA+B;QACvC,UAAU,EAAE,IAAI;QAChB,YAAY;KACb,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAsB,EACtB,YAAsC,EACtC,SAAuB,OAAO;IAE9B,MAAM,OAAO,GAAW,EAAE,CAAC;IAC3B,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QAChF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,SAAS;QACX,CAAC;QACD,MAAM,IAAI,CAAC,CAAC;QACZ,MAAM,MAAM,GAAG,OAAO;aACnB,GAAG,CACF,CAAC,CAAC,EAAE,EAAE,CACJ,GAAG,CAAC,CAAC,aAAa,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,KAAK,IAAI,aAAa,EAAE,CACpF;aACA,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,CAAC,KAAK,CACV,4BAA4B,IAAI,CAAC,IAAI,2BAA2B,MAAM,EAAE,CACzE,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CACV,qCAAqC,MAAM,IAAI,KAAK,CAAC,MAAM,QAAQ,CACpE,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/capabilities/effective-capabilities.d.ts

@@ -0,0 +1,248 @@
+import { z } from 'zod';
+import { RaytioApiClient } from '../raytio/api-client.js';
+/**
+ * Client and index for the supported Persist "effective capabilities" RPC
+ * (`public.fnd_get_effective_capabilities()`), owned by WI-0003499.
+ *
+ * The RPC returns one row per (resource_group, resource_name, operation)
+ * tuple that the authenticated user may exercise. MCP uses that set to
+ * authorise both tool advertisement (`ListTools`) and tool dispatch
+ * (`CallTool`).
+ *
+ * Row semantics — see `docs/mcp-effective-capabilities.md` in the Persist
+ * repository:
+ *
+ *  - `resource_group` — 3-letter module code (e.g. `HRM`, `DSM`, `FAR`).
+ *    Matches `resources[*].permission.resource_group` in the pinned MCP
+ *    resource contract.
+ *  - `resource_name` — resource-scoped code (e.g. `ACCESS_APPLICATIONS`),
+ *    or `null` for a domain-level permission that applies to every
+ *    resource in the group. Persist suppresses domain rows when
+ *    table-specific entries exist for the same (group, operation) —
+ *    MCP relies on that shadowing and does not re-check it here.
+ *  - `operation` — one of `SELECT`, `INSERT`, `UPDATE`, `DELETE`, or a
+ *    semantic operation seeded into the `HRM_PERMISSIONS_OPERATION`
+ *    lookup.
+ *  - `scope` — exactly one of `ALL_RECORDS` or `ROW_BOUNDED` on the wire.
+ *    `ALL_RECORDS` means "verified unbounded HRM access". `ROW_BOUNDED`
+ *    means "the HRM grant exists at OWN_RECORDS scope but real access is
+ *    via ownership / ReBAC / row filters — treat as informational". A
+ *    `NULL` scope is coerced to `ROW_BOUNDED` inside the RPC, never to
+ *    unbounded. MCP normalises `ROW_BOUNDED` to the pre-existing internal
+ *    alias `OWN_RECORDS` on ingress (see {@link CAPABILITY_SCOPES}); both
+ *    names refer to the same "not verified unbounded" semantic, so the
+ *    rest of the MCP code path — CapabilityRequirement, satisfies(),
+ *    dispatch — is unchanged. Reconciled in WI-0003661.
+ *  - `advisory` — `TRUE` iff `scope = ROW_BOUNDED`; `FALSE` for
+ *    `ALL_RECORDS`. Redundant with `scope` today; accepted (optional) on
+ *    the wire so a producer-side addition remains non-breaking.
+ *
+ * When the caller reaches the same capability at both `ALL_RECORDS` and
+ * `ROW_BOUNDED`, the RPC collapses the row to `ALL_RECORDS`. MCP relies
+ * on that guarantee — the client does not attempt its own scope merge.
+ *
+ * MCP fails closed on any of:
+ *  - HTTP transport failure,
+ *  - JSON that does not parse or does not match the schema below,
+ *  - unknown values in `operation` or `scope`,
+ *  - a required tool capability that is not present in the returned set.
+ *
+ * `OWN_RECORDS` MUST NEVER silently become `ALL_RECORDS` — the tool
+ * declaration carries the scope its handler is safe with, and a broader
+ * effective capability satisfies it; a narrower one does not.
+ *
+ * ---
+ *
+ * Deliberate deviation from Persist's interpretation invariant
+ * (WI-0003661):
+ *
+ * Persist's contract states that "absence means unknown — ask the
+ * database" and that `ROW_BOUNDED` rows are informational, not a
+ * deny-side authorisation gate. MCP intentionally departs from that on
+ * the tool-advertisement path:
+ *
+ *  - {@link filterToolsByCapabilities} HIDES any tool whose declared
+ *    capabilities are missing from the caller's returned set.
+ *  - {@link EffectiveCapabilityIndex.satisfies} returns `false` when the
+ *    caller holds no matching row.
+ *
+ * The rationale is fail-closed advertisement: exposing a tool a caller
+ * cannot execute is a poor UX and leaks the shape of the denied surface.
+ * The database still enforces at call time — HRM permissions, ownership,
+ * and ReBAC all continue to gate the underlying query — so any tool
+ * whose actual access path is via ownership or ReBAC (never surfaced by
+ * this RPC) will be hidden until an explicit capability is granted or
+ * the tool's declaration is loosened. This is a design choice, not an
+ * oversight; revisit if MCP ever needs to advertise
+ * ownership/ReBAC-only tools.
+ */
+/**
+ * Wire-side scope vocabulary the RPC emits (per Persist's
+ * `docs/mcp-effective-capabilities.md`, WI-0003499):
+ *
+ *   - `ALL_RECORDS` — verified unbounded HRM access.
+ *   - `ROW_BOUNDED` — advisory HRM row; actual access via
+ *     ownership / ReBAC / row filters.
+ *
+ * The legacy `OWN_RECORDS` label — the pre-rename name for `ROW_BOUNDED`
+ * — is still accepted for transitional deployments of Persist; both
+ * legacy and current values are normalised to the internal
+ * `OWN_RECORDS` alias.
+ */
+export declare const WIRE_CAPABILITY_SCOPES: readonly ["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"];
+export type WireCapabilityScope = (typeof WIRE_CAPABILITY_SCOPES)[number];
+/**
+ * MCP-internal scope vocabulary used by {@link CapabilityRequirement}
+ * declarations and by the scope stored inside
+ * {@link EffectiveCapabilityIndex}. Persist's `ROW_BOUNDED` is
+ * normalised to `OWN_RECORDS` on ingress — the two names encode the
+ * same semantic ("not a verified unbounded HRM grant — enforcement of
+ * access is via ownership / ReBAC / row filters at call time").
+ *
+ * Vocabulary decision (WI-0003678): the internal alias is permanent.
+ * WI-0003661 deferred the internal `OWN_RECORDS → ROW_BOUNDED` rename
+ * on the grounds that no tool declared a scope yet. WI-0003678 changed
+ * that — every tool in {@link Tool.capabilities} now declares
+ * requirements through the contract-derived {@link cap} helper, and
+ * OWN_RECORDS is the default scope that helper produces. Renaming at
+ * this point would touch every capability declaration for no wire-side
+ * benefit (the wire vocabulary is already `ROW_BOUNDED` in Persist and
+ * the transform on ingress hides that from the rest of the code path).
+ * Keep {@link CAPABILITY_SCOPES} as-is; do not add a `ROW_BOUNDED`
+ * alias inside MCP.
+ */
+export declare const CAPABILITY_SCOPES: readonly ["ALL_RECORDS", "OWN_RECORDS"];
+export type CapabilityScope = (typeof CAPABILITY_SCOPES)[number];
+/**
+ * Zod schema for one row returned by `fnd_get_effective_capabilities()`.
+ * The RPC guarantees a `NOT NULL` `resource_group`, `operation`, and
+ * `scope`; `resource_name` may be `NULL` for a domain-level permission.
+ *
+ * Any structural drift here is a hard error — MCP MUST NOT accept an
+ * unknown scope value, empty operation, or malformed resource_group.
+ */
+export declare const effectiveCapabilityRowSchema: z.ZodObject<{
+    resource_group: z.ZodString;
+    resource_name: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    scope: z.ZodEffects<z.ZodEnum<["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"]>, "ALL_RECORDS" | "OWN_RECORDS", "ALL_RECORDS" | "ROW_BOUNDED" | "OWN_RECORDS">;
+    advisory: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    resource_group: z.ZodString;
+    resource_name: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    scope: z.ZodEffects<z.ZodEnum<["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"]>, "ALL_RECORDS" | "OWN_RECORDS", "ALL_RECORDS" | "ROW_BOUNDED" | "OWN_RECORDS">;
+    advisory: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    resource_group: z.ZodString;
+    resource_name: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    scope: z.ZodEffects<z.ZodEnum<["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"]>, "ALL_RECORDS" | "OWN_RECORDS", "ALL_RECORDS" | "ROW_BOUNDED" | "OWN_RECORDS">;
+    advisory: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>;
+export type EffectiveCapabilityRow = z.infer<typeof effectiveCapabilityRowSchema>;
+export declare const effectiveCapabilityResponseSchema: z.ZodArray<z.ZodObject<{
+    resource_group: z.ZodString;
+    resource_name: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    scope: z.ZodEffects<z.ZodEnum<["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"]>, "ALL_RECORDS" | "OWN_RECORDS", "ALL_RECORDS" | "ROW_BOUNDED" | "OWN_RECORDS">;
+    advisory: z.ZodOptional<z.ZodBoolean>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    resource_group: z.ZodString;
+    resource_name: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    scope: z.ZodEffects<z.ZodEnum<["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"]>, "ALL_RECORDS" | "OWN_RECORDS", "ALL_RECORDS" | "ROW_BOUNDED" | "OWN_RECORDS">;
+    advisory: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    resource_group: z.ZodString;
+    resource_name: z.ZodNullable<z.ZodString>;
+    operation: z.ZodString;
+    scope: z.ZodEffects<z.ZodEnum<["ALL_RECORDS", "ROW_BOUNDED", "OWN_RECORDS"]>, "ALL_RECORDS" | "OWN_RECORDS", "ALL_RECORDS" | "ROW_BOUNDED" | "OWN_RECORDS">;
+    advisory: z.ZodOptional<z.ZodBoolean>;
+}, z.ZodTypeAny, "passthrough">>, "many">;
+/**
+ * The declared capability requirement for a tool. A tool is authorised iff
+ * every requirement in its list is satisfied by the caller's effective
+ * capability set.
+ *
+ * The requirement is intentionally narrow — no wildcards, no "any op". A
+ * tool that reads and writes must declare both requirements. This keeps
+ * the authorisation graph auditable and cheap to reason about.
+ */
+export interface CapabilityRequirement {
+    /**
+     * Persist resource group (e.g. `WRM`). Compared case-insensitively
+     * against the RPC's `resource_group`.
+     */
+    resourceGroup: string;
+    /**
+     * Persist resource name (e.g. `ROLES`). Compared case-insensitively
+     * against the RPC's `resource_name`. A domain-level row
+     * (`resource_name: null`) satisfies any resource in the same group.
+     */
+    resourceName: string;
+    /** Operation code (e.g. `SELECT`). Compared case-insensitively. */
+    operation: string;
+    /**
+     * The minimum scope the tool's handler is safe with. `OWN_RECORDS`
+     * (the default) is satisfied by either `OWN_RECORDS` or `ALL_RECORDS`
+     * capabilities. `ALL_RECORDS` requires an `ALL_RECORDS` capability —
+     * an `OWN_RECORDS` capability is NOT sufficient, so an own-record
+     * grant can never silently become an all-record grant.
+     */
+    scope?: CapabilityScope;
+}
+/**
+ * Immutable index over the caller's effective capability set. Answers
+ * "does the user hold capability X at scope Y?" in O(1). Domain-level
+ * rows (`resource_name: null`) are pre-expanded so table-specific lookups
+ * still hit the map.
+ */
+export declare class EffectiveCapabilityIndex {
+    /**
+     * Map keys are `${GROUP}|${NAME|*}|${OPERATION}` (uppercase). The value
+     * is the strongest scope observed for that tuple.
+     *
+     * Domain-level rows are stored with `resource_name = "*"` — table-level
+     * lookups probe both the specific name and the wildcard.
+     */
+    private readonly index;
+    constructor(rows: EffectiveCapabilityRow[]);
+    /** Total number of effective (group, name, operation) rows held. */
+    get size(): number;
+    /**
+     * Return the strongest scope the caller holds for the (group, name,
+     * operation) tuple, or `undefined` if they hold no matching capability.
+     *
+     * A domain-level grant (`resource_name = null`) satisfies any resource
+     * in the same group.
+     */
+    lookup(resourceGroup: string, resourceName: string, operation: string): CapabilityScope | undefined;
+    /**
+     * `true` iff the caller holds a capability that satisfies the
+     * requirement. `OWN_RECORDS` requirements are satisfied by any grant.
+     * `ALL_RECORDS` requirements are satisfied only by an `ALL_RECORDS`
+     * grant — an `OWN_RECORDS` grant does NOT silently upgrade.
+     */
+    satisfies(requirement: CapabilityRequirement): boolean;
+}
+/**
+ * Error thrown when the RPC cannot be fetched, decoded, or validated.
+ * Callers MUST fail closed (expose no tools) on this error.
+ */
+export declare class EffectiveCapabilityError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** PostgREST path to the Persist RPC. */
+export declare const EFFECTIVE_CAPABILITIES_RPC_PATH = "/db/v1/rpc/fnd_get_effective_capabilities";
+/**
+ * Fetch the caller's effective capabilities from Persist, validate the
+ * response shape, and return an index ready for constant-time lookup.
+ *
+ * Throws {@link EffectiveCapabilityError} on any transport, decode, or
+ * validation failure. Callers MUST fail closed on that error — never fall
+ * back to a permissive default.
+ */
+export declare function fetchEffectiveCapabilities(apiClient: RaytioApiClient): Promise<EffectiveCapabilityIndex>;
+//# sourceMappingURL=effective-capabilities.d.ts.map

package/dist/capabilities/effective-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effective-capabilities.d.ts","sourceRoot":"","sources":["../../src/capabilities/effective-capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,wDAIzB,CAAC;AACX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,yCAA0C,CAAC;AACzE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAQjE;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;gCAuBzB,CAAC;AAEjB,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;yCAAwC,CAAC;AAEvF;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,wBAAwB;IACnC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;gBAEzC,IAAI,EAAE,sBAAsB,EAAE;IAgB1C,oEAAoE;IACpE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,MAAM,CACJ,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,eAAe,GAAG,SAAS;IAW9B;;;;;OAKG;IACH,SAAS,CAAC,WAAW,EAAE,qBAAqB,GAAG,OAAO;CAWvD;AAED;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAAzC,OAAO,EAAE,MAAM,EAAW,KAAK,CAAC,EAAE,OAAO,YAAA;CAItD;AAED,yCAAyC;AACzC,eAAO,MAAM,+BAA+B,8CACC,CAAC;AAE9C;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,eAAe,GACzB,OAAO,CAAC,wBAAwB,CAAC,CAmBnC"}