feat(security): enforce live-but-ungated access gaps — agent access & object API exposure (ADR-0049)

PR B of the #1878 P0 cluster: the items where the feature already exists but the
gate was missing or bypassed (vs PR A, which neutralised dangling spec promises).

#1884 — agent access control was a no-op. The chat route only enforced the
static route-level permissions; each agent's own `access`/`permissions` were
never consulted, so "who can chat with this agent" enforced nothing. Adds a pure
`evaluateAgentAccess` (required-permissions ALL, allow-list match by userId/role,
fail-closed on missing user) wired into the chat route after the active check.
`visibility` (organization/private) is intentionally not enforced here — the
request context carries no tenant/owner — and that gap is documented rather than
half-enforced.

#1889 — object `apiEnabled`/`apiMethods` were ignored by the HTTP/MCP data
dispatch; an object could not be hidden from the API nor its methods restricted.
Adds a pure `checkApiExposure` gate in `callData`: `apiEnabled:false` → 404,
non-whitelisted op → 405. System/internal contexts bypass; an unresolvable
definition falls open to the schema defaults (apiEnabled defaults true), so the
gate is a pure additive restriction with no regression.

Both helpers are unit-tested (agent-access 9, api-exposure 8). The action
`disabled`-CEL gap (#1885) lives in the objectui renderer and is fixed there in
a separate commit.

Refs #1878 #1884 #1889
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

packages/runtime/src/api-exposure.test.ts

@@ -0,0 +1,52 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { checkApiExposure } from './api-exposure.js';
+
+describe('checkApiExposure (#1889)', () => {
+  it('falls open when the definition is unresolvable', () => {
+    expect(checkApiExposure(undefined, 'get').allowed).toBe(true);
+    expect(checkApiExposure(null, 'create').allowed).toBe(true);
+  });
+
+  it('allows by default (apiEnabled defaults true, no whitelist)', () => {
+    expect(checkApiExposure({}, 'query').allowed).toBe(true);
+    expect(checkApiExposure({ apiEnabled: true }, 'delete').allowed).toBe(true);
+  });
+
+  it('hides the object (404) when apiEnabled is false', () => {
+    const d = checkApiExposure({ apiEnabled: false }, 'get');
+    expect(d.allowed).toBe(false);
+    expect(d.status).toBe(404);
+  });
+
+  describe('apiMethods whitelist', () => {
+    it('allows a whitelisted operation', () => {
+      // query maps to ApiMethod 'list'
+      expect(checkApiExposure({ apiMethods: ['list', 'get'] }, 'query').allowed).toBe(true);
+      expect(checkApiExposure({ apiMethods: ['list', 'get'] }, 'get').allowed).toBe(true);
+    });
+
+    it('blocks a non-whitelisted operation (405)', () => {
+      const d = checkApiExposure({ apiMethods: ['list', 'get'] }, 'create');
+      expect(d.allowed).toBe(false);
+      expect(d.status).toBe(405);
+      expect(d.reason).toContain('create');
+    });
+
+    it('maps delete/update/create/find correctly', () => {
+      const ro = { apiMethods: ['list', 'get'] };
+      expect(checkApiExposure(ro, 'delete').allowed).toBe(false);
+      expect(checkApiExposure(ro, 'update').allowed).toBe(false);
+      expect(checkApiExposure(ro, 'find').allowed).toBe(true); // find → list
+    });
+
+    it('an empty whitelist is treated as no restriction', () => {
+      expect(checkApiExposure({ apiMethods: [] }, 'create').allowed).toBe(true);
+    });
+
+    it('does not gate actions with no ApiMethod mapping', () => {
+      expect(checkApiExposure({ apiMethods: ['list'] }, 'somethingCustom').allowed).toBe(true);
+    });
+  });
+});

packages/runtime/src/api-exposure.ts

@@ -0,0 +1,72 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Object-level API exposure gate (ADR-0049, #1889).
+ *
+ * Objects declare `apiEnabled` (default true) and an optional `apiMethods`
+ * whitelist, but the HTTP/MCP data dispatch previously ignored both — an object
+ * could not actually be hidden from the API, nor could its allowed operations
+ * be restricted. This module decides, for a given data action, whether the
+ * object's declared exposure permits it.
+ *
+ * Both fields are *additive restrictions* over a default-allow surface
+ * (`apiEnabled` defaults true; absent `apiMethods` means "all operations").
+ * Therefore an unresolvable object definition fails OPEN here — that matches
+ * the schema defaults and avoids breaking traffic when metadata is briefly
+ * unavailable. The gate is a no-op for system/internal contexts (callers pass
+ * `isSystem` and skip this check entirely).
+ */
+
+/** The exposure-relevant slice of an object definition. */
+export interface ObjectApiDef {
+  apiEnabled?: boolean;
+  apiMethods?: string[] | null;
+}
+
+export interface ApiExposureDecision {
+  allowed: boolean;
+  /** HTTP status to return when denied (404 hides, 405 = method not allowed). */
+  status?: number;
+  reason?: string;
+}
+
+/**
+ * Map an internal `callData` action onto the spec `ApiMethod` vocabulary
+ * (`object.zod.ts` → `ApiMethod`). Actions with no mapping are not gated by
+ * `apiMethods` (they still respect `apiEnabled`).
+ */
+const ACTION_TO_API_METHOD: Record<string, string> = {
+  create: 'create',
+  get: 'get',
+  update: 'update',
+  delete: 'delete',
+  query: 'list',
+  find: 'list',
+  batch: 'bulk',
+};
+
+export function checkApiExposure(def: ObjectApiDef | null | undefined, action: string): ApiExposureDecision {
+  // Unresolvable definition → fall open to the schema defaults.
+  if (!def) return { allowed: true };
+
+  // `apiEnabled: false` hides the object from the API entirely → 404.
+  if (def.apiEnabled === false) {
+    return { allowed: false, status: 404, reason: 'object is not exposed via the API' };
+  }
+
+  // `apiMethods` whitelist (when present and non-empty) restricts operations.
+  const whitelist = def.apiMethods;
+  if (Array.isArray(whitelist) && whitelist.length > 0) {
+    const method = ACTION_TO_API_METHOD[action];
+    // Only gate actions that map to a known ApiMethod; unmapped actions pass.
+    if (method && !whitelist.includes(method)) {
+      return {
+        allowed: false,
+        status: 405,
+        reason: `API operation '${method}' is not allowed for this object`,
+      };
+    }
+  }
+
+  return { allowed: true };
+}

packages/runtime/src/http-dispatcher.ts

@@ -5,6 +5,7 @@ import { CoreServiceName } from '@objectstack/spec/system';
 import { pluralToSingular, PLURAL_TO_SINGULAR } from '@objectstack/spec/shared';
 import type { ExecutionContext } from '@objectstack/spec/kernel';
 import { setPackageDisabled } from './package-state-store.js';
+import { checkApiExposure } from './api-exposure.js';
 
 /** Minimal local interface — full EnvironmentScopeManager was removed in Phase R. */
 interface EnvironmentScopeManager {
@@ -258,6 +259,24 @@ export class HttpDispatcher {
         scopeId?: string,
         executionContext?: ExecutionContext,
     ): Promise<any> {
+        // ── Object-level API exposure gate (ADR-0049, #1889) ─────
+        // Honour the object's `apiEnabled` / `apiMethods` declarations for
+        // external traffic. System/internal contexts bypass — these flags
+        // govern API *exposure*, not internal engine self-writes.
+        if (!executionContext?.isSystem && params?.object) {
+            let def: any;
+            try {
+                const meta = await this.resolveService('metadata', scopeId);
+                def = await (meta as any)?.getObject?.(params.object);
+            } catch {
+                def = undefined; // fall open to schema defaults (apiEnabled=true)
+            }
+            const gate = checkApiExposure(def, action);
+            if (!gate.allowed) {
+                throw { statusCode: gate.status ?? 403, message: gate.reason ?? 'API access denied' };
+            }
+        }
+
         const protocol = await this.resolveService('protocol', scopeId);
         const qlService = dataDriver ?? await this.getObjectQLService(scopeId);
         const ql = qlService ?? await this.resolveService('objectql', scopeId);

packages/services/service-ai/src/routes/agent-access.test.ts

@@ -0,0 +1,65 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import { evaluateAgentAccess } from './agent-access.js';
+
+describe('evaluateAgentAccess (#1884)', () => {
+  const user = (over: Partial<{ userId: string; roles: string[]; permissions: string[] }> = {}) => ({
+    userId: 'u1',
+    roles: [] as string[],
+    permissions: [] as string[],
+    ...over,
+  });
+
+  it('allows when the agent declares no access/permissions', () => {
+    expect(evaluateAgentAccess({}, user()).allowed).toBe(true);
+    expect(evaluateAgentAccess({ visibility: 'private' }, user()).allowed).toBe(true);
+  });
+
+  it('fails closed when the user is missing', () => {
+    const d = evaluateAgentAccess({ access: ['u1'] }, undefined);
+    expect(d.allowed).toBe(false);
+  });
+
+  describe('required permissions (must hold ALL)', () => {
+    it('denies when a required permission is missing', () => {
+      const d = evaluateAgentAccess({ permissions: ['hr:read', 'hr:write'] }, user({ permissions: ['hr:read'] }));
+      expect(d.allowed).toBe(false);
+      expect(d.reason).toContain('hr:write');
+    });
+
+    it('allows when all are held via permissions', () => {
+      expect(evaluateAgentAccess({ permissions: ['hr:read'] }, user({ permissions: ['hr:read'] })).allowed).toBe(true);
+    });
+
+    it('satisfies a required entry via roles too (permissions OR roles)', () => {
+      expect(evaluateAgentAccess({ permissions: ['manager'] }, user({ roles: ['manager'] })).allowed).toBe(true);
+    });
+  });
+
+  describe('access allow-list (must match one)', () => {
+    it('allows a listed user id', () => {
+      expect(evaluateAgentAccess({ access: ['u1', 'u2'] }, user()).allowed).toBe(true);
+    });
+
+    it('allows a listed role', () => {
+      expect(evaluateAgentAccess({ access: ['support'] }, user({ roles: ['support'] })).allowed).toBe(true);
+    });
+
+    it('denies a caller not on the list', () => {
+      const d = evaluateAgentAccess({ access: ['u2', 'admins'] }, user({ userId: 'u1', roles: ['sales'] }));
+      expect(d.allowed).toBe(false);
+      expect(d.reason).toMatch(/access list/);
+    });
+  });
+
+  it('enforces permissions AND allow-list together', () => {
+    const agent = { permissions: ['ai:beta'], access: ['vip'] };
+    // has permission but not on allow-list
+    expect(evaluateAgentAccess(agent, user({ permissions: ['ai:beta'], roles: [] })).allowed).toBe(false);
+    // on allow-list but missing permission
+    expect(evaluateAgentAccess(agent, user({ roles: ['vip'], permissions: [] })).allowed).toBe(false);
+    // both satisfied
+    expect(evaluateAgentAccess(agent, user({ roles: ['vip'], permissions: ['ai:beta'] })).allowed).toBe(true);
+  });
+});

packages/services/service-ai/src/routes/agent-access.ts

@@ -0,0 +1,87 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { RouteUserContext } from './ai-routes.js';
+
+/**
+ * The subset of an agent definition relevant to "who can chat with it".
+ * Kept structural (not the full Agent type) so the check is decoupled from the
+ * runtime's loaded-agent shape and trivially unit-testable.
+ */
+export interface AgentAccessSpec {
+  /** Allow-list of user IDs or role names permitted to chat. */
+  access?: string[];
+  /** Permissions or roles the caller must ALL hold to use the agent. */
+  permissions?: string[];
+  /** Declared scope. Only `private` is gate-able at the route layer today. */
+  visibility?: 'global' | 'organization' | 'private';
+}
+
+export interface AgentAccessDecision {
+  allowed: boolean;
+  /** Human-readable reason when denied (safe to surface in a 403). */
+  reason?: string;
+}
+
+/**
+ * Enforce per-agent access control (ADR-0049, #1884).
+ *
+ * Before this check the chat route only enforced the coarse, static route-level
+ * permissions (`['ai:chat','ai:agents']`) — every agent's `access`/`permissions`
+ * were a no-op, so "who can chat with this agent" enforced nothing. This closes
+ * that gap for the two fields that concretely express it:
+ *
+ *   - `permissions` (required): the caller must hold EVERY listed entry. An
+ *     entry is satisfied if it appears in the caller's `permissions` OR `roles`
+ *     (the spec field is "Required permissions or roles"). Empty → no extra
+ *     requirement beyond the route-level gate.
+ *   - `access` (allow-list): when present and non-empty, the caller must match
+ *     at least one entry, by `userId` or by membership in `roles`. Empty/absent
+ *     → not restricted by allow-list.
+ *
+ * `visibility` (`organization`/`private`) is intentionally NOT enforced here:
+ * the request context carries no tenant id or agent-owner, so a correct
+ * organization/private gate needs auth-middleware changes (tracked separately).
+ * Enforcing a partial/guessed version would risk both lock-out and false
+ * security, so we enforce only what the context can decide.
+ *
+ * Fails CLOSED on a malformed user (no userId) — an unauthenticated caller that
+ * slipped past the route gate is denied rather than defaulted-open.
+ */
+export function evaluateAgentAccess(
+  agent: AgentAccessSpec,
+  user: RouteUserContext | undefined,
+): AgentAccessDecision {
+  const required = agent.permissions ?? [];
+  const allowList = agent.access ?? [];
+
+  // No per-agent restriction declared → allowed (route-level gate already passed).
+  if (required.length === 0 && allowList.length === 0) {
+    return { allowed: true };
+  }
+
+  if (!user || !user.userId) {
+    return { allowed: false, reason: 'authentication required to chat with this agent' };
+  }
+
+  const held = new Set<string>([...(user.permissions ?? []), ...(user.roles ?? [])]);
+
+  // Required permissions: caller must hold ALL.
+  const missing = required.filter((p) => !held.has(p));
+  if (missing.length > 0) {
+    return {
+      allowed: false,
+      reason: `missing required permission(s): ${missing.join(', ')}`,
+    };
+  }
+
+  // Allow-list: caller must match by userId or role.
+  if (allowList.length > 0) {
+    const roles = new Set<string>(user.roles ?? []);
+    const matched = allowList.some((entry) => entry === user.userId || roles.has(entry));
+    if (!matched) {
+      return { allowed: false, reason: 'not in this agent’s access list' };
+    }
+  }
+
+  return { allowed: true };
+}

packages/services/service-ai/src/routes/agent-routes.ts

@@ -9,6 +9,7 @@ import type { RouteDefinition } from './ai-routes.js';
 import type { AgentChatQuota } from '../quota/agent-chat-quota.js';
 import { normalizeMessage, validateMessageContent } from './message-utils.js';
 import { encodeVercelDataStream } from '../stream/vercel-stream-encoder.js';
+import { evaluateAgentAccess } from './agent-access.js';
 
 /**
  * Allowed message roles for the agent chat endpoint.
@@ -143,6 +144,18 @@ export function buildAgentRoutes(
           return { status: 403, body: { error: `Agent "${agentName}" is not active` } };
         }
 
+        // ── Per-agent access control (ADR-0049, #1884) ───────────
+        // The route-level `permissions` gate above is the same for every
+        // agent; it does NOT honour this agent's own `access`/`permissions`.
+        // Enforce those here so "who can chat with this agent" is real.
+        const access = evaluateAgentAccess(agent, req.user);
+        if (!access.allowed) {
+          return {
+            status: 403,
+            body: { error: `Access to agent "${agentName}" denied: ${access.reason}` },
+          };
+        }
+
         // ── Per-turn quota gate (optional) ───────────────────────
         // Refusal is HONEST at the moment of impact (ADR-0040 §5): why, when
         // it recovers, and the way out. Streaming clients get the copy as a