test(authz): dogfood proof for the MCP tool-execution identity gate (#3167)

Upgrades the `mcp-tool-exec-identity` conformance row from cited-tests-only to
a real end-to-end boundary proof (ADR-0096 D4 requires one for an agent/
external-reachable surface). `showcase-mcp-identity.dogfood.test.ts` boots the
showcase with MCPServerPlugin registered (via the harness `extraPlugins` — the
verify harness boots the plugin set directly, not through the CLI capability
push) and asserts on the real in-process HTTP stack:
  - anonymous POST /mcp (tools/list) → 401 (fail-closed: not 404/501, so the
    surface IS served and the service IS registered — the denial is identity);
  - an authenticated member clears the gate (not 401);
  - GET /mcp/skill → 200 (surface served default-on while tool-exec is gated).

Wires it in as the row's `proof:` and adds the row to the test's HIGH_RISK set
(so the surface must carry a proof). Adds @objectstack/mcp to the private
@objectstack/dogfood dev deps (lockfile updated).

Validated locally: `pnpm --filter @objectstack/dogfood test` authz-conformance
+ showcase-mcp-identity → 10/10 pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0155A3k1CMJQb44V4iwTLUcH

Author: claude

packages/qa/dogfood/package.json

@@ -14,6 +14,7 @@
     "@objectstack/connector-rest": "workspace:*",
     "@objectstack/example-crm": "workspace:*",
     "@objectstack/example-showcase": "workspace:*",
+    "@objectstack/mcp": "workspace:*",
     "@objectstack/objectql": "workspace:*",
     "@objectstack/plugin-audit": "workspace:*",
     "@objectstack/plugin-auth": "workspace:*",

packages/qa/dogfood/test/authz-conformance.matrix.ts

@@ -99,7 +99,8 @@ export const AUTHZ_CONFORMANCE: AuthzPrimitive[] = [
   { id: 'mcp-tool-exec-identity', summary: 'MCP tool execution runs under the caller principal, fail-closed on the default-on /api/v1/mcp surface (#3167 D1, ADR-0096 D4, ADR-0100)', state: 'enforced',
     enforcement: 'runtime/http-dispatcher.ts handleMcp — 401 fail-closed unless the request resolves a real principal (ec.userId || ec.isSystem; a guest context has no userId → 401, no dev-admin fallback, no fall-open), then the OAuth scope→tool-family gate (#2698: no MCP scope → 403 insufficient_scope). buildMcpBridge binds every object-CRUD/query/aggregate + action call to the caller ExecutionContext via callData(..., ec) — the same RLS/FLS/permission path REST /data uses; principal resolved by runtime/security/resolve-execution-context.ts (osk_ API-key owner / better-auth session human / OAuth agent-on-behalf-of-human = ADR-0090 D10 ceiling∩user). Business actions additionally gated at invoke time by ai.exposed (#2849) + the ADR-0066 D4 capability gate; bodies run trusted by design (#2964).',
     covers: ['mcp:http-dispatcher.ts:handleMcp(identity-fail-closed)', 'mcp:http-dispatcher.ts:buildMcpBridge(context-threaded)'],
-    note: 'Surface posture: user (caller identity), ENFORCED and live — this is the default-on serve-side surface (unlike the latent graphql-identity-thread / realtime-delivery-authz D4 rows). Answers the ADR-0096 Evidence row "REST/MCP object CRUD — caller ExecutionContext, threaded" as a checked property. Fail-closed 401 unit-proven in runtime/http-dispatcher.mcp.test.ts (anonymous) + http-dispatcher.mcp-oauth.test.ts (scope gate); the principal-bound identity binding + capability + ai.exposed gates are exercised end-to-end against the real buildMcpBridge over JSON-RPC in examples/app-todo/test/mcp-actions.e2e.ts; OAuth tool-family narrowing in packages/mcp mcp-http-tools.scopes.test.ts. A dedicated dogfood-boot proof is the natural M2 follow-up (same latency the graphql D4 row carries). Removing the 401 gate or the bridge threading makes a covers key STALE → red CI.' },
+    proof: 'showcase-mcp-identity.dogfood.test.ts',
+    note: 'Surface posture: user (caller identity), ENFORCED and live — this is the default-on serve-side surface (unlike the latent graphql-identity-thread / realtime-delivery-authz D4 rows). Answers the ADR-0096 Evidence row "REST/MCP object CRUD — caller ExecutionContext, threaded" as a checked property. Default-on + fail-closed posture proven on a real showcase boot in the proof (anonymous POST /mcp → 401 not 404/501, an authenticated member clears the gate, public GET /mcp/skill → 200). Also unit-proven in runtime/http-dispatcher.mcp.test.ts (anonymous 401) + http-dispatcher.mcp-oauth.test.ts (scope gate); the principal-bound identity binding + capability + ai.exposed gates are exercised end-to-end against the real buildMcpBridge over JSON-RPC in examples/app-todo/test/mcp-actions.e2e.ts; OAuth tool-family narrowing in packages/mcp mcp-http-tools.scopes.test.ts. Removing the 401 gate or the bridge threading makes a covers key STALE → red CI.' },
   { id: 'mcp-stdio-resource-read', summary: 'stdio MCP resource reads (record_by_id / bridgeResources) run context-less — trusted local process only, NOT on the default HTTP surface (#3167, ADR-0096 E1, ADR-0100 D1/D3)', state: 'experimental',
     covers: ['mcp:mcp-server-runtime.ts:record_by_id(stdio-context-less-read)'],
     note: 'Surface posture: system (trusted-implicit), opt-in. The persistent MCPServerRuntime.bridgeResources record_by_id template calls dataEngine.findOne with NO ExecutionContext (mcp/src/mcp-server-runtime.ts) → the plugin-security empty-principal skip = full-authority cross-tenant read (ADR-0096 Evidence E1). Reachable ONLY over the stdio transport, which the dispatcher NEVER exposes on the network and which auto-starts only under explicit opt-in (MCPServerPlugin autoStart / OS_MCP_SERVER_ENABLED=true). The default-on surface is HTTP-only and builds a fresh per-request McpServer with ONLY the principal-bound object/action tools (buildMcpBridge) — never these resources. NOT patched with an ad-hoc { isSystem: true } literal (ADR-0096 D2 retires those; the systemContext(reason) constructor does not exist yet). ADMISSION REQUIREMENT before stdio is ever networked or default-wired: thread the caller/session ExecutionContext (or an explicit ADR-0096 D2 grant) into the resource reads. The probe on dataEngine.findOne( keeps this classified so the fall-open cannot silently ride onto a networked transport; ADR-0100 D3 keeps stdio explicit-opt-in for exactly this reason.' },

packages/qa/dogfood/test/authz-conformance.test.ts

@@ -167,6 +167,9 @@ const HIGH_RISK = [
   // is false compliance (declared ≠ enforced) and approval/status columns are
   // one direct PATCH away from self-approval.
   'readonly-static-write',
+  // #3167 — the MCP tool-execution surface is agent/external-reachable and
+  // default-on, so it must carry an end-to-end boundary proof (ADR-0096 D4).
+  'mcp-tool-exec-identity',
 ];
 
 describe('ADR-0056 D10 — authorization conformance matrix', () => {

packages/qa/dogfood/test/showcase-mcp-identity.dogfood.test.ts

@@ -0,0 +1,82 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// #3167 / ADR-0096 D4 / ADR-0100 — the serve-side MCP tool-execution surface
+// (@objectstack/mcp) is DEFAULT-ON and agent/external-reachable, so its identity
+// posture is a checked property (the `mcp-tool-exec-identity` authz-conformance
+// row), not incidental prose. The matrix row + source probes pin the code; this
+// proof pins the runtime BEHAVIOUR on a real showcase boot: the /api/v1/mcp
+// surface is served by default, yet tool execution is FAIL-CLOSED on identity —
+// a principal-less caller gets 401, never a fall-open. The MCPServerPlugin is
+// registered via `extraPlugins` because the verify harness boots the plugin set
+// directly (it does not run the CLI capability push at serve.ts that wires MCP
+// in `os dev`/`serve`); registering it here reproduces the default-on surface.
+//
+// The authenticated principal-bound execution path (tools run AS the caller's
+// ExecutionContext through buildMcpBridge, RLS/FLS-bounded, with the ai.exposed
+// + ADR-0066 D4 capability action gates) is exercised end-to-end against the
+// real bridge in examples/app-todo/test/mcp-actions.e2e.ts; here we assert the
+// complementary property a real HTTP boot uniquely shows — the fail-closed gate
+// and the default-on service resolution.
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import showcaseStack from '@objectstack/example-showcase';
+import { bootStack, type VerifyStack } from '@objectstack/verify';
+import { MCPServerPlugin } from '@objectstack/mcp';
+
+const MCP = '/mcp';
+const TOOLS_LIST = { jsonrpc: '2.0', id: 1, method: 'tools/list' } as const;
+const MCP_HEADERS = {
+  'content-type': 'application/json',
+  // The Streamable-HTTP transport advertises both JSON and SSE responses.
+  accept: 'application/json, text/event-stream',
+} as const;
+
+describe('showcase: serve-side MCP tool execution is default-on and fail-closed on identity (#3167 / ADR-0100)', () => {
+  let stack: VerifyStack;
+  let memberToken: string;
+
+  beforeAll(async () => {
+    // Platform default (deny anonymous) + the default-on MCP surface registered
+    // exactly as `os dev`/`serve` would via the isMcpServerEnabled() capability push.
+    stack = await bootStack(showcaseStack, { extraPlugins: [new MCPServerPlugin()] });
+    await stack.signIn(); // seed the dev admin (first user)
+    memberToken = await stack.signUp('mcp-identity-member@verify.test');
+  }, 60_000);
+
+  afterAll(async () => {
+    await stack?.stop();
+  });
+
+  // ── The gate: no principal → no tool execution (fail-closed, not fall-open) ──
+  it('anonymous POST /mcp (tools/list) is denied 401 — no dev-admin fallback, no fall-open', async () => {
+    const r = await stack.api(MCP, {
+      method: 'POST',
+      headers: MCP_HEADERS,
+      body: JSON.stringify(TOOLS_LIST),
+    });
+    // 401 (not 404/501): the surface IS served and the service IS registered —
+    // the denial is the identity gate, exactly what mcp-tool-exec-identity pins.
+    expect(r.status, 'a principal-less MCP tool call must be 401').toBe(401);
+  });
+
+  it('an authenticated member clears the MCP identity gate (not 401)', async () => {
+    // Past the gate the transport may 200/400/406 depending on the exact MCP
+    // handshake — the point is it is NOT the anonymous 401. Mirrors the #2567
+    // GraphQL "authenticated clears the gate" assertion.
+    const r = await stack.api(MCP, {
+      method: 'POST',
+      headers: { ...MCP_HEADERS, Authorization: `Bearer ${memberToken}` },
+      body: JSON.stringify(TOOLS_LIST),
+    });
+    expect(r.status, 'an authenticated MCP caller must clear the 401 identity gate').not.toBe(401);
+  });
+
+  // ── Default-on: the public SKILL.md download proves the surface is advertised
+  // even though tool execution is gated (isMcpServerEnabled() default true). ──
+  it('GET /mcp/skill is served publicly (surface is default-on)', async () => {
+    const r = await stack.api(`${MCP}/skill`, { method: 'GET' });
+    expect(r.status, 'the public MCP SKILL.md must be served (default-on surface)').toBe(200);
+    const body = await r.text();
+    expect(body.length, 'SKILL.md must have content').toBeGreaterThan(0);
+  });
+});