feat(#462): add federation list verb

apps/gateway/src/federation/federation.module.ts

@@ -7,10 +7,12 @@ import { FederationController } from './federation.controller.js';
 import { CapabilitiesController } from './server/verbs/capabilities.controller.js';
 import { GrantsService } from './grants.service.js';
 import { FederationClientService, QuerySourceService } from './client/index.js';
-import { FederationAuthGuard } from './server/index.js';
+import { FederationAuthGuard, FederationScopeService } from './server/index.js';
+import { ListController } from './server/verbs/list.controller.js';
+import { FederationListQueryService } from './server/verbs/list-query.service.js';
 
 @Module({
-  controllers: [EnrollmentController, FederationController, CapabilitiesController],
+  controllers: [EnrollmentController, FederationController, CapabilitiesController, ListController],
   providers: [
     AdminGuard,
     CaService,
@@ -19,6 +21,8 @@ import { FederationAuthGuard } from './server/index.js';
     FederationClientService,
     QuerySourceService,
     FederationAuthGuard,
+    FederationScopeService,
+    FederationListQueryService,
   ],
   exports: [
     CaService,
@@ -27,6 +31,8 @@ import { FederationAuthGuard } from './server/index.js';
     FederationClientService,
     QuerySourceService,
     FederationAuthGuard,
+    FederationScopeService,
+    FederationListQueryService,
   ],
 })
 export class FederationModule {}

apps/gateway/src/federation/server/__tests__/scope.service.spec.ts

@@ -0,0 +1,324 @@
+/**
+ * Unit tests for FederationScopeService (FED-M3-04).
+ *
+ * Coverage:
+ *  - resource allowlist deny
+ *  - excluded resource deny
+ *  - invalid scope deny
+ *  - invalid requested limit deny
+ *  - native RBAC deny as subjectUserId
+ *  - scope/native filter intersection for personal and team rows
+ *  - native RBAC personal deny wins over scope include_personal allow/default
+ *  - max_rows_per_query cap
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { FederationScopeService, type FederationNativeRbacEvaluator } from '../scope.service.js';
+import type { FederationContext } from '../federation-context.js';
+
+const GRANT_ID = 'grant-1';
+const PEER_ID = 'peer-1';
+const SUBJECT_USER_ID = 'user-1';
+
+function makeContext(scope: Record<string, unknown>): FederationContext {
+  return {
+    grantId: GRANT_ID,
+    peerId: PEER_ID,
+    subjectUserId: SUBJECT_USER_ID,
+    scope,
+  };
+}
+
+function makeNativeRbac(
+  result: Awaited<ReturnType<FederationNativeRbacEvaluator['evaluateReadAccess']>>,
+): FederationNativeRbacEvaluator {
+  return {
+    evaluateReadAccess: vi.fn().mockResolvedValue(result),
+  };
+}
+
+describe('FederationScopeService', () => {
+  let service: FederationScopeService;
+
+  beforeEach(() => {
+    service = new FederationScopeService();
+  });
+
+  it('allows a granted resource and returns a capped query filter', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: ['team-1', 'team-2'] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['tasks'],
+        filters: { tasks: { include_teams: ['team-1', 'team-3'], include_personal: true } },
+        max_rows_per_query: 50,
+      }),
+      resource: 'tasks',
+      requestedLimit: 500,
+      nativeRbac,
+    });
+
+    expect(result).toEqual({
+      allowed: true,
+      filter: {
+        resource: 'tasks',
+        subjectUserId: SUBJECT_USER_ID,
+        includePersonal: true,
+        teamIds: ['team-1'],
+        limit: 50,
+        maxRowsPerQuery: 50,
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).toHaveBeenCalledWith({
+      grantId: GRANT_ID,
+      peerId: PEER_ID,
+      subjectUserId: SUBJECT_USER_ID,
+      resource: 'tasks',
+    });
+  });
+
+  it('defaults absent resource filters to native RBAC personal and team visibility', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['notes'], max_rows_per_query: 100 }),
+      resource: 'notes',
+      nativeRbac: makeNativeRbac({
+        allowed: true,
+        access: { includePersonal: true, teamIds: ['team-1', 'team-2'] },
+      }),
+    });
+
+    expect(result).toMatchObject({
+      allowed: true,
+      filter: {
+        includePersonal: true,
+        teamIds: ['team-1', 'team-2'],
+        limit: 100,
+      },
+    });
+  });
+
+  it('honors include_personal false even when native RBAC allows personal rows', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['memory'],
+        filters: { memory: { include_personal: false } },
+        max_rows_per_query: 25,
+      }),
+      resource: 'memory',
+      nativeRbac: makeNativeRbac({
+        allowed: true,
+        access: { includePersonal: true, teamIds: [] },
+      }),
+    });
+
+    expect(result).toMatchObject({
+      allowed: true,
+      filter: {
+        includePersonal: false,
+        teamIds: [],
+      },
+    });
+  });
+
+  it('does not leak personal rows when scope allows personal but native RBAC denies personal', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['tasks'],
+        filters: { tasks: { include_personal: true } },
+        max_rows_per_query: 25,
+      }),
+      resource: 'tasks',
+      nativeRbac: makeNativeRbac({
+        allowed: true,
+        access: { includePersonal: false, teamIds: ['team-1'] },
+      }),
+    });
+
+    expect(result).toMatchObject({
+      allowed: true,
+      filter: {
+        includePersonal: false,
+        teamIds: ['team-1'],
+      },
+    });
+  });
+
+  it('does not widen native RBAC when scope includes teams the user cannot access', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['tasks'],
+        filters: { tasks: { include_teams: ['team-2'], include_personal: false } },
+        max_rows_per_query: 25,
+      }),
+      resource: 'tasks',
+      nativeRbac: makeNativeRbac({
+        allowed: true,
+        access: { includePersonal: true, teamIds: ['team-1'] },
+      }),
+    });
+
+    expect(result).toMatchObject({
+      allowed: true,
+      filter: {
+        includePersonal: false,
+        teamIds: [],
+      },
+    });
+  });
+
+  it('denies invalid grant scope before RBAC evaluation', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: [], max_rows_per_query: 100 }),
+      resource: 'tasks',
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'invalid_scope',
+        stage: 'scope_parse',
+        statusCode: 400,
+        grantId: GRANT_ID,
+        subjectUserId: SUBJECT_USER_ID,
+        resource: 'tasks',
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies unsupported resource names before RBAC evaluation', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
+      resource: 'unknown_resource',
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'invalid_resource',
+        stage: 'resource_allowlist',
+        statusCode: 403,
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies resources explicitly present in excluded_resources before allowlist miss', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({
+        resources: ['tasks'],
+        excluded_resources: ['credentials'],
+        max_rows_per_query: 100,
+      }),
+      resource: 'credentials',
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'resource_excluded',
+        stage: 'resource_exclusion',
+        statusCode: 403,
+        resource: 'credentials',
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies supported resources that are not granted by scope', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
+      resource: 'notes',
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'resource_not_granted',
+        stage: 'resource_allowlist',
+        statusCode: 403,
+        resource: 'notes',
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies invalid requested row limits before RBAC evaluation', async () => {
+    const nativeRbac = makeNativeRbac({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
+      resource: 'tasks',
+      requestedLimit: 0,
+      nativeRbac,
+    });
+
+    expect(result).toMatchObject({
+      allowed: false,
+      deny: {
+        code: 'invalid_limit',
+        stage: 'row_cap',
+        statusCode: 400,
+        details: { requestedLimit: 0 },
+      },
+    });
+    expect(nativeRbac.evaluateReadAccess).not.toHaveBeenCalled();
+  });
+
+  it('denies when native RBAC rejects subjectUserId access to the resource', async () => {
+    const result = await service.evaluateAccess({
+      context: makeContext({ resources: ['tasks'], max_rows_per_query: 100 }),
+      resource: 'tasks',
+      nativeRbac: makeNativeRbac({
+        allowed: false,
+        reason: 'read:tasks denied',
+        details: { permission: 'tasks:read' },
+      }),
+    });
+
+    expect(result).toEqual({
+      allowed: false,
+      deny: {
+        code: 'native_rbac_denied',
+        stage: 'native_rbac',
+        statusCode: 403,
+        message: 'read:tasks denied',
+        grantId: GRANT_ID,
+        peerId: PEER_ID,
+        subjectUserId: SUBJECT_USER_ID,
+        resource: 'tasks',
+        details: { permission: 'tasks:read' },
+      },
+    });
+  });
+});

apps/gateway/src/federation/server/index.ts

@@ -10,4 +10,22 @@
  */
 
 export { FederationAuthGuard } from './federation-auth.guard.js';
+export { FederationScopeService } from './scope.service.js';
 export type { FederationContext } from './federation-context.js';
+export type {
+  FederationNativeRbacAccess,
+  FederationNativeRbacAllowedResult,
+  FederationNativeRbacDeniedResult,
+  FederationNativeRbacEvaluator,
+  FederationNativeRbacRequest,
+  FederationNativeRbacResult,
+  FederationScopeAllowedResult,
+  FederationScopeDeniedResult,
+  FederationScopeDenyCode,
+  FederationScopeDenyDetails,
+  FederationScopeDenyReason,
+  FederationScopeDenyStage,
+  FederationScopeEvaluationInput,
+  FederationScopeEvaluationResult,
+  FederationScopeQueryFilter,
+} from './scope.service.js';

apps/gateway/src/federation/server/scope.service.ts

@@ -0,0 +1,272 @@
+/**
+ * FederationScopeService — M3 server-side scope enforcement pipeline.
+ *
+ * Pure trust-boundary service: it validates the grant scope, asks an injected
+ * native RBAC evaluator what the subject user can read locally, intersects that
+ * answer with the federation scope filters, and returns a query filter for the
+ * verb controllers. The service performs no DB calls directly.
+ */
+
+import { Injectable } from '@nestjs/common';
+import {
+  FEDERATION_RESOURCE_VALUES,
+  type FederationResource,
+  FederationScopeError,
+  parseFederationScope,
+} from '../scope-schema.js';
+import type { FederationContext } from './federation-context.js';
+
+const federationResourceSet: ReadonlySet<string> = new Set<string>(FEDERATION_RESOURCE_VALUES);
+
+export type FederationScopeDenyStage =
+  | 'scope_parse'
+  | 'resource_allowlist'
+  | 'resource_exclusion'
+  | 'native_rbac'
+  | 'row_cap';
+
+export type FederationScopeDenyCode =
+  | 'invalid_scope'
+  | 'invalid_resource'
+  | 'resource_not_granted'
+  | 'resource_excluded'
+  | 'native_rbac_denied'
+  | 'invalid_limit';
+
+export type FederationScopeDenyStatus = 400 | 403;
+
+export interface FederationScopeDenyDetails {
+  readonly [key: string]: string | number | boolean | readonly string[];
+}
+
+export interface FederationScopeDenyReason {
+  readonly code: FederationScopeDenyCode;
+  readonly stage: FederationScopeDenyStage;
+  readonly statusCode: FederationScopeDenyStatus;
+  readonly message: string;
+  readonly grantId: string;
+  readonly peerId: string;
+  readonly subjectUserId: string;
+  readonly resource: string;
+  readonly details?: FederationScopeDenyDetails;
+}
+
+export interface FederationNativeRbacRequest {
+  readonly grantId: string;
+  readonly peerId: string;
+  readonly subjectUserId: string;
+  readonly resource: FederationResource;
+}
+
+export interface FederationNativeRbacAccess {
+  /** Whether this user may read personal rows for this resource. */
+  readonly includePersonal: boolean;
+
+  /** Team IDs this user may read for this resource under native RBAC. */
+  readonly teamIds: readonly string[];
+}
+
+export interface FederationNativeRbacAllowedResult {
+  readonly allowed: true;
+  readonly access: FederationNativeRbacAccess;
+}
+
+export interface FederationNativeRbacDeniedResult {
+  readonly allowed: false;
+  readonly reason?: string;
+  readonly details?: FederationScopeDenyDetails;
+}
+
+export type FederationNativeRbacResult =
+  | FederationNativeRbacAllowedResult
+  | FederationNativeRbacDeniedResult;
+
+export interface FederationNativeRbacEvaluator {
+  evaluateReadAccess(request: FederationNativeRbacRequest): Promise<FederationNativeRbacResult>;
+}
+
+export interface FederationScopeEvaluationInput {
+  readonly context: FederationContext;
+  readonly resource: string;
+  readonly requestedLimit?: number;
+  readonly nativeRbac: FederationNativeRbacEvaluator;
+}
+
+export interface FederationScopeQueryFilter {
+  readonly resource: FederationResource;
+  readonly subjectUserId: string;
+  readonly includePersonal: boolean;
+  readonly teamIds: readonly string[];
+  readonly limit: number;
+  readonly maxRowsPerQuery: number;
+}
+
+export interface FederationScopeAllowedResult {
+  readonly allowed: true;
+  readonly filter: FederationScopeQueryFilter;
+}
+
+export interface FederationScopeDeniedResult {
+  readonly allowed: false;
+  readonly deny: FederationScopeDenyReason;
+}
+
+export type FederationScopeEvaluationResult =
+  | FederationScopeAllowedResult
+  | FederationScopeDeniedResult;
+
+function isFederationResource(resource: string): resource is FederationResource {
+  return federationResourceSet.has(resource);
+}
+
+function uniqueStrings(values: readonly string[]): readonly string[] {
+  return Array.from(new Set<string>(values));
+}
+
+function intersectTeamIds(
+  nativeTeamIds: readonly string[],
+  scopedTeamIds: readonly string[] | undefined,
+): readonly string[] {
+  const uniqueNativeTeamIds = uniqueStrings(nativeTeamIds);
+
+  if (scopedTeamIds === undefined) {
+    return uniqueNativeTeamIds;
+  }
+
+  const nativeSet = new Set<string>(uniqueNativeTeamIds);
+  return uniqueStrings(scopedTeamIds).filter((teamId: string): boolean => nativeSet.has(teamId));
+}
+
+function makeDenyReason(params: {
+  readonly code: FederationScopeDenyCode;
+  readonly stage: FederationScopeDenyStage;
+  readonly statusCode?: FederationScopeDenyStatus;
+  readonly message: string;
+  readonly context: FederationContext;
+  readonly resource: string;
+  readonly details?: FederationScopeDenyDetails;
+}): FederationScopeDeniedResult {
+  return {
+    allowed: false,
+    deny: {
+      code: params.code,
+      stage: params.stage,
+      statusCode: params.statusCode ?? 403,
+      message: params.message,
+      grantId: params.context.grantId,
+      peerId: params.context.peerId,
+      subjectUserId: params.context.subjectUserId,
+      resource: params.resource,
+      ...(params.details !== undefined ? { details: params.details } : {}),
+    },
+  };
+}
+
+@Injectable()
+export class FederationScopeService {
+  async evaluateAccess(
+    input: FederationScopeEvaluationInput,
+  ): Promise<FederationScopeEvaluationResult> {
+    const { context, resource, requestedLimit, nativeRbac } = input;
+
+    let scope: ReturnType<typeof parseFederationScope>;
+    try {
+      scope = parseFederationScope(context.scope);
+    } catch (error: unknown) {
+      const message =
+        error instanceof FederationScopeError
+          ? 'Federation grant scope is invalid'
+          : 'Federation grant scope could not be parsed';
+      const details = error instanceof Error ? { reason: error.message } : undefined;
+      return makeDenyReason({
+        code: 'invalid_scope',
+        stage: 'scope_parse',
+        statusCode: 400,
+        message,
+        context,
+        resource,
+        ...(details !== undefined ? { details } : {}),
+      });
+    }
+
+    if (!isFederationResource(resource)) {
+      return makeDenyReason({
+        code: 'invalid_resource',
+        stage: 'resource_allowlist',
+        message: 'Requested federation resource is not supported',
+        context,
+        resource,
+        details: { supportedResources: FEDERATION_RESOURCE_VALUES },
+      });
+    }
+
+    if (scope.excluded_resources.includes(resource)) {
+      return makeDenyReason({
+        code: 'resource_excluded',
+        stage: 'resource_exclusion',
+        message: 'Requested federation resource is explicitly excluded by grant scope',
+        context,
+        resource,
+      });
+    }
+
+    if (!scope.resources.includes(resource)) {
+      return makeDenyReason({
+        code: 'resource_not_granted',
+        stage: 'resource_allowlist',
+        message: 'Requested federation resource is not granted by scope',
+        context,
+        resource,
+        details: { grantedResources: scope.resources },
+      });
+    }
+
+    if (requestedLimit !== undefined && (!Number.isInteger(requestedLimit) || requestedLimit < 1)) {
+      return makeDenyReason({
+        code: 'invalid_limit',
+        stage: 'row_cap',
+        statusCode: 400,
+        message: 'Requested row limit must be a positive integer',
+        context,
+        resource,
+        details: { requestedLimit },
+      });
+    }
+
+    const nativeResult = await nativeRbac.evaluateReadAccess({
+      grantId: context.grantId,
+      peerId: context.peerId,
+      subjectUserId: context.subjectUserId,
+      resource,
+    });
+
+    if (!nativeResult.allowed) {
+      return makeDenyReason({
+        code: 'native_rbac_denied',
+        stage: 'native_rbac',
+        message: nativeResult.reason ?? 'Subject user is not allowed to read this resource',
+        context,
+        resource,
+        ...(nativeResult.details !== undefined ? { details: nativeResult.details } : {}),
+      });
+    }
+
+    const scopeFilter = scope.filters?.[resource];
+    const includePersonal =
+      Boolean(scopeFilter?.include_personal ?? true) && nativeResult.access.includePersonal;
+    const teamIds = intersectTeamIds(nativeResult.access.teamIds, scopeFilter?.include_teams);
+    const limit = Math.min(requestedLimit ?? scope.max_rows_per_query, scope.max_rows_per_query);
+
+    return {
+      allowed: true,
+      filter: {
+        resource,
+        subjectUserId: context.subjectUserId,
+        includePersonal,
+        teamIds,
+        limit,
+        maxRowsPerQuery: scope.max_rows_per_query,
+      },
+    };
+  }
+}

apps/gateway/src/federation/server/verbs/__tests__/list-query.service.spec.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Db } from '@mosaicstack/db';
+import type { FederationScopeQueryFilter } from '../../scope.service.js';
+import { FederationListQueryService } from '../list-query.service.js';
+
+const TASK_FILTER: FederationScopeQueryFilter = {
+  resource: 'tasks',
+  subjectUserId: 'user-1',
+  includePersonal: true,
+  teamIds: [],
+  limit: 2,
+  maxRowsPerQuery: 2,
+};
+
+function makeService() {
+  return new FederationListQueryService({} as Db);
+}
+
+function stubRows(
+  service: FederationListQueryService,
+  ...pages: Array<Array<Record<string, unknown>>>
+) {
+  const mock = vi.fn();
+  for (const page of pages) {
+    mock.mockResolvedValueOnce(page);
+  }
+  (
+    service as unknown as {
+      listAllRows: (
+        _filter: FederationScopeQueryFilter,
+        _rowLimit: number,
+        _cursor: unknown,
+      ) => Promise<Array<Record<string, unknown>>>;
+    }
+  ).listAllRows = mock;
+  return mock;
+}
+
+describe('FederationListQueryService', () => {
+  it('denies sensitive resources in native RBAC for M3 list reads', async () => {
+    const service = makeService();
+
+    await expect(
+      service.evaluateReadAccess({
+        grantId: 'grant-1',
+        peerId: 'peer-1',
+        subjectUserId: 'user-1',
+        resource: 'credentials',
+      }),
+    ).resolves.toMatchObject({
+      allowed: false,
+      reason: 'credentials federation list access is not implemented in M3',
+    });
+  });
+
+  it('allows personal memory reads without requiring team lookup', async () => {
+    const service = makeService();
+
+    await expect(
+      service.evaluateReadAccess({
+        grantId: 'grant-1',
+        peerId: 'peer-1',
+        subjectUserId: 'user-1',
+        resource: 'memory',
+      }),
+    ).resolves.toEqual({
+      allowed: true,
+      access: { includePersonal: true, teamIds: [] },
+    });
+  });
+
+  it('applies the scope row cap and returns an opaque next cursor when truncated', async () => {
+    const service = makeService();
+    const listAllRows = stubRows(
+      service,
+      [
+        { id: '3', createdAt: new Date('2026-06-24T03:00:00.000Z') },
+        { id: '2', createdAt: new Date('2026-06-24T02:00:00.000Z') },
+        { id: '1', createdAt: new Date('2026-06-24T01:00:00.000Z') },
+      ],
+      [{ id: '1', createdAt: new Date('2026-06-24T01:00:00.000Z') }],
+    );
+
+    const firstPage = await service.list({ filter: TASK_FILTER });
+
+    expect(firstPage).toEqual({
+      items: [
+        { id: '3', createdAt: new Date('2026-06-24T03:00:00.000Z') },
+        { id: '2', createdAt: new Date('2026-06-24T02:00:00.000Z') },
+      ],
+      truncated: true,
+      nextCursor: expect.any(String),
+    });
+
+    expect(listAllRows).toHaveBeenNthCalledWith(1, TASK_FILTER, 3, undefined);
+
+    const secondPage = await service.list({ filter: TASK_FILTER, cursor: firstPage.nextCursor });
+    expect(secondPage).toEqual({
+      items: [{ id: '1', createdAt: new Date('2026-06-24T01:00:00.000Z') }],
+      truncated: false,
+    });
+    expect(listAllRows).toHaveBeenNthCalledWith(
+      2,
+      TASK_FILTER,
+      3,
+      expect.objectContaining({ id: '2' }),
+    );
+  });
+
+  it('rejects invalid cursors instead of falling back to the first page', async () => {
+    const service = makeService();
+    stubRows(service, [{ id: '1' }]);
+
+    await expect(service.list({ filter: TASK_FILTER, cursor: 'not-base64-json' })).rejects.toThrow(
+      'Invalid federation list cursor',
+    );
+  });
+});

apps/gateway/src/federation/server/verbs/__tests__/list.controller.spec.ts

@@ -0,0 +1,170 @@
+import 'reflect-metadata';
+import { RequestMethod } from '@nestjs/common';
+import type { FastifyRequest } from 'fastify';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { FederationAuthGuard } from '../../federation-auth.guard.js';
+import type {
+  FederationScopeEvaluationResult,
+  FederationScopeQueryFilter,
+} from '../../scope.service.js';
+import { ListController } from '../list.controller.js';
+import type { FederationListQueryResult } from '../list-query.service.js';
+
+const FEDERATION_CONTEXT = {
+  grantId: 'grant-1',
+  peerId: 'peer-1',
+  subjectUserId: 'user-1',
+  scope: { resources: ['tasks'], max_rows_per_query: 25 },
+};
+
+const TASK_FILTER: FederationScopeQueryFilter = {
+  resource: 'tasks',
+  subjectUserId: 'user-1',
+  includePersonal: true,
+  teamIds: ['team-1'],
+  limit: 10,
+  maxRowsPerQuery: 25,
+};
+
+function makeRequest(): FastifyRequest {
+  return { federationContext: FEDERATION_CONTEXT } as unknown as FastifyRequest;
+}
+
+function allowedScope(
+  filter: FederationScopeQueryFilter = TASK_FILTER,
+): FederationScopeEvaluationResult {
+  return { allowed: true, filter };
+}
+
+function makeController(opts?: {
+  scopeResult?: FederationScopeEvaluationResult;
+  queryResult?: FederationListQueryResult;
+}) {
+  const scope = {
+    evaluateAccess: vi.fn().mockResolvedValue(opts?.scopeResult ?? allowedScope()),
+  };
+  const query = {
+    evaluateReadAccess: vi.fn(),
+    list: vi.fn().mockResolvedValue(
+      opts?.queryResult ?? {
+        items: [
+          {
+            id: 'task-1',
+            title: 'Federated task',
+            createdAt: new Date('2026-06-24T00:00:00.000Z'),
+          },
+        ],
+        truncated: false,
+      },
+    ),
+  };
+
+  return {
+    controller: new ListController(scope as never, query as never),
+    scope,
+    query,
+  };
+}
+
+describe('ListController', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('declares POST /api/federation/v1/list/:resource protected only by FederationAuthGuard', () => {
+    expect(Reflect.getMetadata('path', ListController)).toBe('api/federation/v1/list');
+    expect(Reflect.getMetadata('path', ListController.prototype.list)).toBe(':resource');
+    expect(Reflect.getMetadata('method', ListController.prototype.list)).toBe(RequestMethod.POST);
+    expect(Reflect.getMetadata('__guards__', ListController)).toEqual([FederationAuthGuard]);
+  });
+
+  it('runs AuthGuard context through ScopeService and returns local-source tagged rows', async () => {
+    const { controller, scope, query } = makeController();
+
+    const response = await controller.list('tasks', makeRequest(), { limit: 10 });
+
+    expect(scope.evaluateAccess).toHaveBeenCalledWith({
+      context: FEDERATION_CONTEXT,
+      resource: 'tasks',
+      requestedLimit: 10,
+      nativeRbac: query,
+    });
+    expect(query.list).toHaveBeenCalledWith({ filter: TASK_FILTER, cursor: undefined });
+    expect(response).toEqual({
+      items: [
+        {
+          id: 'task-1',
+          title: 'Federated task',
+          createdAt: new Date('2026-06-24T00:00:00.000Z'),
+          _source: 'local',
+        },
+      ],
+    });
+  });
+
+  it('preserves pagination metadata when row cap truncates the query layer result', async () => {
+    const { controller } = makeController({
+      queryResult: {
+        items: [{ id: 'task-1' }],
+        nextCursor: 'cursor-2',
+        truncated: true,
+      },
+    });
+
+    const response = await controller.list('tasks', makeRequest(), { cursor: 'cursor-1' });
+
+    expect(response).toEqual({
+      items: [{ id: 'task-1', _source: 'local' }],
+      nextCursor: 'cursor-2',
+      _truncated: true,
+    });
+  });
+
+  it('returns a federation error envelope when scope evaluation denies access', async () => {
+    const { controller, query } = makeController({
+      scopeResult: {
+        allowed: false,
+        deny: {
+          code: 'resource_excluded',
+          stage: 'resource_exclusion',
+          statusCode: 403,
+          message: 'Requested federation resource is explicitly excluded by grant scope',
+          grantId: 'grant-1',
+          peerId: 'peer-1',
+          subjectUserId: 'user-1',
+          resource: 'credentials',
+        },
+      },
+    });
+
+    await expect(controller.list('credentials', makeRequest(), {})).rejects.toMatchObject({
+      response: {
+        error: {
+          code: 'scope_violation',
+          message: 'Requested federation resource is explicitly excluded by grant scope',
+        },
+      },
+      status: 403,
+    });
+    expect(query.list).not.toHaveBeenCalled();
+  });
+
+  it('rejects malformed request body fields before querying storage', async () => {
+    const { controller, scope, query } = makeController();
+
+    await expect(controller.list('tasks', makeRequest(), { cursor: 123 })).rejects.toMatchObject({
+      response: { error: { code: 'invalid_request' } },
+      status: 400,
+    });
+    await expect(controller.list('tasks', makeRequest(), { limit: false })).rejects.toMatchObject({
+      response: { error: { code: 'invalid_request' } },
+      status: 400,
+    });
+    await expect(controller.list('tasks', makeRequest(), { limit: 'abc' })).rejects.toMatchObject({
+      response: { error: { code: 'invalid_request' } },
+      status: 400,
+    });
+    expect(scope.evaluateAccess).not.toHaveBeenCalled();
+    expect(query.list).not.toHaveBeenCalled();
+  });
+});

apps/gateway/src/federation/server/verbs/list-query.service.ts

@@ -0,0 +1,365 @@
+/**
+ * Federation list query layer (FED-M3-05).
+ *
+ * Read-only DB adapter used by ListController after FederationAuthGuard and
+ * FederationScopeService have established the subject user, allowed resource,
+ * native-RBAC intersection, and row cap. Audit writes are intentionally
+ * deferred to M4.
+ */
+
+import { Inject, Injectable } from '@nestjs/common';
+import {
+  and,
+  desc,
+  eq,
+  inArray,
+  insights,
+  isNotNull,
+  lt,
+  missionTasks,
+  missions,
+  or,
+  preferences,
+  projects,
+  tasks,
+  teamMembers,
+  type Db,
+} from '@mosaicstack/db';
+import type {
+  FederationNativeRbacEvaluator,
+  FederationNativeRbacRequest,
+  FederationNativeRbacResult,
+  FederationScopeQueryFilter,
+} from '../scope.service.js';
+import { DB } from '../../../database/database.module.js';
+
+export interface FederationListQueryRequest {
+  readonly filter: FederationScopeQueryFilter;
+  readonly cursor?: string;
+}
+
+export interface FederationListQueryResult<T extends object = Record<string, unknown>> {
+  readonly items: T[];
+  readonly nextCursor?: string;
+  readonly truncated: boolean;
+}
+
+type RowObject = Record<string, unknown>;
+
+interface KeysetCursor {
+  readonly createdAt: Date;
+  readonly id: string;
+}
+
+function encodeCursor(row: RowObject): string | undefined {
+  const createdAt = row['createdAt'];
+  const id = row['id'];
+  if (!(createdAt instanceof Date) || typeof id !== 'string') {
+    return undefined;
+  }
+
+  return Buffer.from(JSON.stringify({ createdAt: createdAt.toISOString(), id }), 'utf8').toString(
+    'base64url',
+  );
+}
+
+function decodeCursor(cursor: string | undefined): KeysetCursor | undefined {
+  if (cursor === undefined) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as unknown;
+    if (typeof parsed !== 'object' || parsed === null) {
+      throw new Error('cursor must be an object');
+    }
+
+    const { createdAt, id } = parsed as { createdAt?: unknown; id?: unknown };
+    if (typeof createdAt !== 'string' || typeof id !== 'string' || id.length === 0) {
+      throw new Error('cursor is missing createdAt or id');
+    }
+
+    const date = new Date(createdAt);
+    if (Number.isNaN(date.getTime())) {
+      throw new Error('cursor createdAt is invalid');
+    }
+
+    return { createdAt: date, id };
+  } catch {
+    throw new Error('Invalid federation list cursor');
+  }
+}
+
+function paginate<T extends RowObject>(rows: T[], limit: number): FederationListQueryResult<T> {
+  const page = rows.slice(0, limit);
+  const hasMore = rows.length > limit;
+  const nextCursor = hasMore ? encodeCursor(page[page.length - 1] ?? {}) : undefined;
+
+  return {
+    items: page,
+    truncated: hasMore,
+    ...(nextCursor !== undefined ? { nextCursor } : {}),
+  };
+}
+
+function sortRows(rows: RowObject[]): RowObject[] {
+  return [...rows].sort((a, b) => {
+    const aTime = a['createdAt'] instanceof Date ? a['createdAt'].getTime() : 0;
+    const bTime = b['createdAt'] instanceof Date ? b['createdAt'].getTime() : 0;
+    if (aTime !== bTime) {
+      return bTime - aTime;
+    }
+    return String(b['id'] ?? '').localeCompare(String(a['id'] ?? ''));
+  });
+}
+
+@Injectable()
+export class FederationListQueryService implements FederationNativeRbacEvaluator {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  async evaluateReadAccess(
+    request: FederationNativeRbacRequest,
+  ): Promise<FederationNativeRbacResult> {
+    if (request.resource === 'credentials' || request.resource === 'api_keys') {
+      return {
+        allowed: false,
+        reason: `${request.resource} federation list access is not implemented in M3`,
+        details: { resource: request.resource },
+      };
+    }
+
+    if (request.resource === 'memory') {
+      return { allowed: true, access: { includePersonal: true, teamIds: [] } };
+    }
+
+    const teamIds = await this.listSubjectTeamIds(request.subjectUserId);
+    return { allowed: true, access: { includePersonal: true, teamIds } };
+  }
+
+  async list<T extends RowObject = RowObject>(
+    request: FederationListQueryRequest,
+  ): Promise<FederationListQueryResult<T>> {
+    const cursor = decodeCursor(request.cursor);
+    const rows = await this.listAllRows(request.filter, request.filter.limit + 1, cursor);
+    return paginate(rows as T[], request.filter.limit);
+  }
+
+  private async listAllRows(
+    filter: FederationScopeQueryFilter,
+    rowLimit: number,
+    cursor: KeysetCursor | undefined,
+  ): Promise<RowObject[]> {
+    switch (filter.resource) {
+      case 'tasks':
+        return this.listTasks(filter, rowLimit, cursor);
+      case 'notes':
+        return this.listNotes(filter, rowLimit, cursor);
+      case 'memory':
+        return this.listMemory(filter, rowLimit, cursor);
+      case 'credentials':
+      case 'api_keys':
+        return [];
+    }
+  }
+
+  private async listSubjectTeamIds(subjectUserId: string): Promise<string[]> {
+    const rows = await this.db
+      .select({ teamId: teamMembers.teamId })
+      .from(teamMembers)
+      .where(eq(teamMembers.userId, subjectUserId));
+
+    return rows.map((row) => row.teamId);
+  }
+
+  private async listAccessibleProjectIds(filter: FederationScopeQueryFilter): Promise<string[]> {
+    const clauses = [];
+    if (filter.includePersonal) {
+      clauses.push(and(eq(projects.ownerType, 'user'), eq(projects.ownerId, filter.subjectUserId)));
+    }
+    if (filter.teamIds.length > 0) {
+      clauses.push(
+        and(eq(projects.ownerType, 'team'), inArray(projects.teamId, [...filter.teamIds])),
+      );
+    }
+
+    if (clauses.length === 0) {
+      return [];
+    }
+
+    const rows = await this.db
+      .select({ id: projects.id })
+      .from(projects)
+      .where(clauses.length === 1 ? clauses[0] : or(...clauses));
+
+    return rows.map((row) => row.id);
+  }
+
+  private async listMissionIds(projectIds: readonly string[]): Promise<string[]> {
+    if (projectIds.length === 0) {
+      return [];
+    }
+
+    const rows = await this.db
+      .select({ id: missions.id })
+      .from(missions)
+      .where(inArray(missions.projectId, [...projectIds]));
+
+    return rows.map((row) => row.id);
+  }
+
+  private async listTasks(
+    filter: FederationScopeQueryFilter,
+    rowLimit: number,
+    cursor: KeysetCursor | undefined,
+  ): Promise<RowObject[]> {
+    const projectIds = await this.listAccessibleProjectIds(filter);
+    const missionIds = await this.listMissionIds(projectIds);
+    const clauses = [];
+
+    if (projectIds.length > 0) {
+      clauses.push(inArray(tasks.projectId, projectIds));
+    }
+    if (missionIds.length > 0) {
+      clauses.push(inArray(tasks.missionId, missionIds));
+    }
+
+    if (clauses.length === 0) {
+      return [];
+    }
+
+    const scopeClause = clauses.length === 1 ? clauses[0] : or(...clauses);
+    const cursorClause = cursor
+      ? or(
+          lt(tasks.createdAt, cursor.createdAt),
+          and(eq(tasks.createdAt, cursor.createdAt), lt(tasks.id, cursor.id)),
+        )
+      : undefined;
+
+    const rows = await this.db
+      .select({
+        id: tasks.id,
+        title: tasks.title,
+        description: tasks.description,
+        status: tasks.status,
+        priority: tasks.priority,
+        projectId: tasks.projectId,
+        missionId: tasks.missionId,
+        assignee: tasks.assignee,
+        tags: tasks.tags,
+        dueDate: tasks.dueDate,
+        metadata: tasks.metadata,
+        createdAt: tasks.createdAt,
+        updatedAt: tasks.updatedAt,
+      })
+      .from(tasks)
+      .where(and(scopeClause, cursorClause))
+      .orderBy(desc(tasks.createdAt), desc(tasks.id))
+      .limit(rowLimit);
+
+    return sortRows(rows as RowObject[]);
+  }
+
+  private async listNotes(
+    filter: FederationScopeQueryFilter,
+    rowLimit: number,
+    cursor: KeysetCursor | undefined,
+  ): Promise<RowObject[]> {
+    const projectIds = await this.listAccessibleProjectIds(filter);
+    const missionIds = await this.listMissionIds(projectIds);
+    const clauses = [];
+
+    if (filter.includePersonal) {
+      clauses.push(eq(missionTasks.userId, filter.subjectUserId));
+    }
+    if (missionIds.length > 0) {
+      clauses.push(inArray(missionTasks.missionId, missionIds));
+    }
+
+    if (clauses.length === 0) {
+      return [];
+    }
+
+    const scopeClause = clauses.length === 1 ? clauses[0] : or(...clauses);
+    const cursorClause = cursor
+      ? or(
+          lt(missionTasks.createdAt, cursor.createdAt),
+          and(eq(missionTasks.createdAt, cursor.createdAt), lt(missionTasks.id, cursor.id)),
+        )
+      : undefined;
+
+    const rows = await this.db
+      .select({
+        id: missionTasks.id,
+        missionId: missionTasks.missionId,
+        taskId: missionTasks.taskId,
+        status: missionTasks.status,
+        content: missionTasks.notes,
+        createdAt: missionTasks.createdAt,
+        updatedAt: missionTasks.updatedAt,
+      })
+      .from(missionTasks)
+      .where(and(scopeClause, cursorClause, isNotNull(missionTasks.notes)))
+      .orderBy(desc(missionTasks.createdAt), desc(missionTasks.id))
+      .limit(rowLimit);
+
+    return sortRows(rows.filter((row) => row.content !== '') as RowObject[]);
+  }
+
+  private async listMemory(
+    filter: FederationScopeQueryFilter,
+    rowLimit: number,
+    cursor: KeysetCursor | undefined,
+  ): Promise<RowObject[]> {
+    if (!filter.includePersonal) {
+      return [];
+    }
+
+    const insightCursorClause = cursor
+      ? or(
+          lt(insights.createdAt, cursor.createdAt),
+          and(eq(insights.createdAt, cursor.createdAt), lt(insights.id, cursor.id)),
+        )
+      : undefined;
+    const preferenceCursorClause = cursor
+      ? or(
+          lt(preferences.createdAt, cursor.createdAt),
+          and(eq(preferences.createdAt, cursor.createdAt), lt(preferences.id, cursor.id)),
+        )
+      : undefined;
+
+    const [insightRows, preferenceRows] = await Promise.all([
+      this.db
+        .select({
+          id: insights.id,
+          kind: insights.source,
+          content: insights.content,
+          category: insights.category,
+          relevanceScore: insights.relevanceScore,
+          metadata: insights.metadata,
+          createdAt: insights.createdAt,
+          updatedAt: insights.updatedAt,
+        })
+        .from(insights)
+        .where(and(eq(insights.userId, filter.subjectUserId), insightCursorClause))
+        .orderBy(desc(insights.createdAt), desc(insights.id))
+        .limit(rowLimit),
+      this.db
+        .select({
+          id: preferences.id,
+          kind: preferences.category,
+          key: preferences.key,
+          value: preferences.value,
+          source: preferences.source,
+          mutable: preferences.mutable,
+          createdAt: preferences.createdAt,
+          updatedAt: preferences.updatedAt,
+        })
+        .from(preferences)
+        .where(and(eq(preferences.userId, filter.subjectUserId), preferenceCursorClause))
+        .orderBy(desc(preferences.createdAt), desc(preferences.id))
+        .limit(rowLimit),
+    ]);
+
+    return sortRows([...(insightRows as RowObject[]), ...(preferenceRows as RowObject[])]);
+  }
+}

apps/gateway/src/federation/server/verbs/list.controller.ts

@@ -0,0 +1,143 @@
+/**
+ * Federation list verb (FED-M3-05).
+ *
+ * POST /api/federation/v1/list/:resource
+ *
+ * Pipeline: FederationAuthGuard attaches the active grant context, then
+ * FederationScopeService enforces grant scope + native RBAC intersection, then
+ * the read-only query layer returns capped rows tagged with `_source`. Read
+ * audit-log writes are deferred to M4; this controller does not persist request
+ * or response bodies.
+ */
+
+import {
+  Body,
+  Controller,
+  HttpException,
+  Inject,
+  Param,
+  Post,
+  Req,
+  UseGuards,
+} from '@nestjs/common';
+import type { FastifyRequest } from 'fastify';
+import {
+  FederationInvalidRequestError,
+  FederationScopeViolationError,
+  SOURCE_LOCAL,
+  tagWithSource,
+  type FederationListResponse,
+  type SourceTag,
+} from '@mosaicstack/types';
+import { FederationAuthGuard } from '../federation-auth.guard.js';
+import '../federation-context.js';
+import { FederationScopeService } from '../scope.service.js';
+import { FederationListQueryService } from './list-query.service.js';
+
+interface FederationListRequestBody {
+  readonly limit?: unknown;
+  readonly cursor?: unknown;
+}
+
+type FederatedRow = Record<string, unknown> & SourceTag;
+
+function parseLimit(body: FederationListRequestBody | undefined): number | undefined {
+  if (body?.limit === undefined) {
+    return undefined;
+  }
+
+  const parsed =
+    typeof body.limit === 'number'
+      ? body.limit
+      : typeof body.limit === 'string' && body.limit.trim().length > 0
+        ? Number(body.limit)
+        : Number.NaN;
+
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new HttpException(
+      new FederationInvalidRequestError(
+        'Federation list limit must be a positive integer',
+      ).toEnvelope(),
+      400,
+    );
+  }
+
+  return parsed;
+}
+
+function parseCursor(body: FederationListRequestBody | undefined): string | undefined {
+  if (body?.cursor === undefined) {
+    return undefined;
+  }
+  if (typeof body.cursor === 'string') {
+    return body.cursor;
+  }
+  throw new HttpException(
+    new FederationInvalidRequestError('Federation list cursor must be a string').toEnvelope(),
+    400,
+  );
+}
+
+@Controller('api/federation/v1/list')
+@UseGuards(FederationAuthGuard)
+export class ListController {
+  constructor(
+    @Inject(FederationScopeService) private readonly scope: FederationScopeService,
+    @Inject(FederationListQueryService) private readonly query: FederationListQueryService,
+  ) {}
+
+  @Post(':resource')
+  async list(
+    @Param('resource') resource: string,
+    @Req() request: FastifyRequest,
+    @Body() body?: FederationListRequestBody,
+  ): Promise<FederationListResponse<FederatedRow>> {
+    if (!request.federationContext) {
+      throw new Error('Federation context missing after auth guard');
+    }
+
+    const requestedLimit = parseLimit(body);
+    const cursor = parseCursor(body);
+    const scopeResult = await this.scope.evaluateAccess({
+      context: request.federationContext,
+      resource,
+      requestedLimit,
+      nativeRbac: this.query,
+    });
+
+    if (!scopeResult.allowed) {
+      const ErrorClass =
+        scopeResult.deny.statusCode === 400
+          ? FederationInvalidRequestError
+          : FederationScopeViolationError;
+      throw new HttpException(
+        new ErrorClass(scopeResult.deny.message, scopeResult.deny).toEnvelope(),
+        scopeResult.deny.statusCode,
+      );
+    }
+
+    let result: Awaited<ReturnType<FederationListQueryService['list']>>;
+    try {
+      result = await this.query.list({ filter: scopeResult.filter, cursor });
+    } catch (error: unknown) {
+      if (error instanceof Error && error.message === 'Invalid federation list cursor') {
+        throw new HttpException(
+          new FederationInvalidRequestError('Federation list cursor is invalid').toEnvelope(),
+          400,
+        );
+      }
+      throw error;
+    }
+
+    const response: FederationListResponse<FederatedRow> = {
+      items: tagWithSource(result.items, SOURCE_LOCAL),
+    };
+    if (result.nextCursor !== undefined) {
+      response.nextCursor = result.nextCursor;
+    }
+    if (result.truncated) {
+      response._truncated = true;
+    }
+    return response;
+  }
+}

docs/federation/TASKS.md

@@ -91,22 +91,22 @@ Goal: Two federated gateways exchange real data over mTLS. Inbound requests pass
 >
 > **Tracking issue:** #462.
 
-| id        | status      | description                                                                                                                                                                                                                                                                                            | issue | agent  | branch                               | depends_on       | estimate | notes                                                                                                                                                    |
+| id        | status      | description                                                                                                                                                                                                                                                                                            | issue | agent  | branch                               | depends_on                        | estimate | notes                                                                                                                                                    |
-| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ------------------------------------ | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ------------------------------------ | --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FED-M3-01 | done        | `packages/types/src/federation/` — request/response DTOs for `list`, `get`, `capabilities` verbs. Wire-format zod schemas + inferred TS types. Includes `FederationRequest`, `FederationListResponse<T>`, `FederationGetResponse<T>`, `FederationCapabilitiesResponse`, error envelope, `_source` tag. | #462  | sonnet | feat/federation-m3-types             | —                | 4K       | Reusable from gateway server + client + harness. Pure types — no I/O, no NestJS.                                                                         |
+| FED-M3-01 | done        | `packages/types/src/federation/` — request/response DTOs for `list`, `get`, `capabilities` verbs. Wire-format zod schemas + inferred TS types. Includes `FederationRequest`, `FederationListResponse<T>`, `FederationGetResponse<T>`, `FederationCapabilitiesResponse`, error envelope, `_source` tag. | #462  | sonnet | feat/federation-m3-types             | —                                 | 4K       | Reusable from gateway server + client + harness. Pure types — no I/O, no NestJS.                                                                         |
-| FED-M3-02 | done        | `tools/federation-harness/` scaffold: `docker-compose.two-gateways.yml` (Server A + Server B + step-CA), `seed.ts` (provisions grants, peers, sample tasks/notes/credentials per scope variant), `harness.ts` helper (boots stack, returns typed clients). README documents harness use.               | #462  | sonnet | feat/federation-m3-harness           | DEPLOY-04 (soft) | 8K       | Falls back to local docker-compose if `mos-test-1/-2` not yet redeployed (DEPLOY chain blocked on IMG-FIX). Permanent test infra used by M3+.            |
+| FED-M3-02 | done        | `tools/federation-harness/` scaffold: `docker-compose.two-gateways.yml` (Server A + Server B + step-CA), `seed.ts` (provisions grants, peers, sample tasks/notes/credentials per scope variant), `harness.ts` helper (boots stack, returns typed clients). README documents harness use.               | #462  | sonnet | feat/federation-m3-harness           | DEPLOY-04 (soft)                  | 8K       | Falls back to local docker-compose if `mos-test-1/-2` not yet redeployed (DEPLOY chain blocked on IMG-FIX). Permanent test infra used by M3+.            |
-| FED-M3-03 | done        | `apps/gateway/src/federation/server/federation-auth.guard.ts` (NestJS guard). Validates inbound client cert from Fastify TLS context, extracts `grantId` + `subjectUserId` from custom OIDs, loads grant from DB, asserts `status='active'`, attaches `FederationContext` to request.                  | #462  | sonnet | feat/federation-m3-auth-guard        | M3-01            | 8K       | Reuses OID parsing logic mirrored from `ca.service.ts` post-issuance verification. 401 on malformed/missing OIDs; 403 on revoked/expired/missing grant.  |
+| FED-M3-03 | done        | `apps/gateway/src/federation/server/federation-auth.guard.ts` (NestJS guard). Validates inbound client cert from Fastify TLS context, extracts `grantId` + `subjectUserId` from custom OIDs, loads grant from DB, asserts `status='active'`, attaches `FederationContext` to request.                  | #462  | sonnet | feat/federation-m3-auth-guard        | M3-01                             | 8K       | Reuses OID parsing logic mirrored from `ca.service.ts` post-issuance verification. 401 on malformed/missing OIDs; 403 on revoked/expired/missing grant.  |
-| FED-M3-04 | in-progress | `apps/gateway/src/federation/server/scope.service.ts`. Pipeline: (1) resource allowlist + excluded check, (2) native RBAC eval as `subjectUserId`, (3) scope filter intersection (`include_teams`, `include_personal`), (4) `max_rows_per_query` cap. Pure service — DB calls injected.                | #462  | sonnet | feat/federation-m3-scope-service     | M3-01            | 10K      | Hardest correctness target in M3. Reuses `parseFederationScope` (M2-03). Returns either `{ allowed: true, filter }` or structured deny reason for audit. |
+| FED-M3-04 | in-progress | `apps/gateway/src/federation/server/scope.service.ts`. Pipeline: (1) resource allowlist + excluded check, (2) native RBAC eval as `subjectUserId`, (3) scope filter intersection (`include_teams`, `include_personal`), (4) `max_rows_per_query` cap. Pure service — DB calls injected.                | #462  | sonnet | feat/federation-m3-scope-service     | M3-01                             | 10K      | Hardest correctness target in M3. Reuses `parseFederationScope` (M2-03). Returns either `{ allowed: true, filter }` or structured deny reason for audit. |
-| FED-M3-05 | not-started | `apps/gateway/src/federation/server/verbs/list.controller.ts`. Wires AuthGuard → ScopeService → tasks/notes/memory query layer; applies row cap; tags rows with `_source`. Resource selector via path param.                                                                                           | #462  | sonnet | feat/federation-m3-verb-list         | M3-03, M3-04     | 6K       | Routes: `POST /api/federation/v1/list/:resource`. No body persistence. Audit write deferred to M4.                                                       |
+| FED-M3-05 | in-progress | `apps/gateway/src/federation/server/verbs/list.controller.ts`. Wires AuthGuard → ScopeService → tasks/notes/memory query layer; applies row cap; tags rows with `_source`. Resource selector via path param.                                                                                           | #462  | sonnet | feat/federation-m3-verb-list         | M3-03, M3-04                      | 6K       | Routes: `POST /api/federation/v1/list/:resource`. No body persistence. Audit write deferred to M4.                                                       |
-| FED-M3-06 | not-started | `apps/gateway/src/federation/server/verbs/get.controller.ts`. Single-resource fetch by id; same pipeline as list. 404 on not-found, 403 on RBAC/scope deny — both audited the same way.                                                                                                                | #462  | sonnet | feat/federation-m3-verb-get          | M3-03, M3-04     | 6K       | `POST /api/federation/v1/get/:resource/:id`. Mirrors list controller patterns.                                                                           |
+| FED-M3-06 | not-started | `apps/gateway/src/federation/server/verbs/get.controller.ts`. Single-resource fetch by id; same pipeline as list. 404 on not-found, 403 on RBAC/scope deny — both audited the same way.                                                                                                                | #462  | sonnet | feat/federation-m3-verb-get          | M3-03, M3-04                      | 6K       | `POST /api/federation/v1/get/:resource/:id`. Mirrors list controller patterns.                                                                           |
-| FED-M3-07 | in-progress | `apps/gateway/src/federation/server/verbs/capabilities.controller.ts`. Read-only enumeration: returns `{ resources, excluded_resources, max_rows_per_query, supported_verbs }` derived from grant scope. Always allowed for an active grant — no RBAC eval.                                            | #462  | sonnet | feat/federation-m3-verb-capabilities | M3-03            | 4K       | `GET /api/federation/v1/capabilities`. Smallest verb; useful sanity check that mTLS + auth guard work end-to-end.                                        |
+| FED-M3-07 | done        | `apps/gateway/src/federation/server/verbs/capabilities.controller.ts`. Read-only enumeration: returns `{ resources, excluded_resources, max_rows_per_query, supported_verbs }` derived from grant scope. Always allowed for an active grant — no RBAC eval.                                            | #462  | sonnet | feat/federation-m3-verb-capabilities | M3-03                             | 4K       | `GET /api/federation/v1/capabilities`. Smallest verb; useful sanity check that mTLS + auth guard work end-to-end.                                        |
-| FED-M3-08 | done        | `apps/gateway/src/federation/client/federation-client.service.ts`. Outbound mTLS dialer: picks `(certPem, sealed clientKey)` from `federation_peers`, unwraps key, builds undici Agent with mTLS, calls peer verb, parses typed response, wraps non-2xx into `FederationClientError`.                  | #462  | sonnet | feat/federation-m3-client            | M3-01            | 8K       | Independent of server stream — can land in parallel with M3-03/04. Cert/key cached per-peer; flushed by future M5/M6 logic.                              |
+| FED-M3-08 | done        | `apps/gateway/src/federation/client/federation-client.service.ts`. Outbound mTLS dialer: picks `(certPem, sealed clientKey)` from `federation_peers`, unwraps key, builds undici Agent with mTLS, calls peer verb, parses typed response, wraps non-2xx into `FederationClientError`.                  | #462  | sonnet | feat/federation-m3-client            | M3-01                             | 8K       | Independent of server stream — can land in parallel with M3-03/04. Cert/key cached per-peer; flushed by future M5/M6 logic.                              |
-| FED-M3-09 | in-progress | `apps/gateway/src/federation/client/query-source.service.ts`. Accepts `source: "local" \| "federated:<host>" \| "all"` from gateway query layer; for `"all"` fans out to local + each peer in parallel; merges results; tags every row with `_source`.                                                 | #462  | sonnet | feat/federation-m3-query-source      | M3-08            | 8K       | Per-peer failure surfaces as `_partial: true` in response, not hard failure (sets up M5 offline UX). M5 adds caching + circuit breaker on top.           |
+| FED-M3-09 | done        | `apps/gateway/src/federation/client/query-source.service.ts`. Accepts `source: "local" \| "federated:<host>" \| "all"` from gateway query layer; for `"all"` fans out to local + each peer in parallel; merges results; tags every row with `_source`.                                                 | #462  | sonnet | feat/federation-m3-query-source      | M3-08                             | 8K       | Per-peer failure surfaces as `_partial: true` in response, not hard failure (sets up M5 offline UX). M5 adds caching + circuit breaker on top.           |
-| FED-M3-10 | not-started | Integration tests for MILESTONES.md M3 acceptance #6 (malformed OIDs → 401; valid cert + revoked grant → 403) and #7 (`max_rows_per_query` cap). Real PG, mocked TLS context (Fastify req shim).                                                                                                       | #462  | sonnet | feat/federation-m3-integration       | M3-05, M3-06     | 8K       | Vitest profile gated by `FEDERATED_INTEGRATION=1`. Single-gateway suite; no harness required.                                                            |
+| FED-M3-10 | not-started | Integration tests for MILESTONES.md M3 acceptance #6 (malformed OIDs → 401; valid cert + revoked grant → 403) and #7 (`max_rows_per_query` cap). Real PG, mocked TLS context (Fastify req shim).                                                                                                       | #462  | sonnet | feat/federation-m3-integration       | M3-05, M3-06                      | 8K       | Vitest profile gated by `FEDERATED_INTEGRATION=1`. Single-gateway suite; no harness required.                                                            |
-| FED-M3-11 | not-started | E2E tests for MILESTONES.md M3 acceptance #1, #2, #3, #4, #5, #8, #9, #10 (8 cases). Uses harness from M3-02; two real gateways, real Step-CA, real mTLS. Each test asserts both happy-path response and audit/no-persist invariants.                                                                  | #462  | sonnet | feat/federation-m3-e2e               | M3-02, M3-09     | 12K      | Largest single task. Each acceptance gets its own `it(...)` for clear failure attribution.                                                               |
+| FED-M3-11 | not-started | E2E tests for MILESTONES.md M3 acceptance #1, #2, #3, #4, #5, #8, #9, #10 (8 cases). Uses harness from M3-02; two real gateways, real Step-CA, real mTLS. Each test asserts both happy-path response and audit/no-persist invariants.                                                                  | #462  | sonnet | feat/federation-m3-e2e               | M3-02, M3-04, M3-05, M3-06, M3-09 | 12K      | Largest single task. Each acceptance gets its own `it(...)` for clear failure attribution.                                                               |
-| FED-M3-12 | not-started | Independent security review (sonnet, not author of M3-03/04/05/06/07/08/09): focus on cert-SAN spoofing, OID extraction edge cases, scope-bypass via filter manipulation, RBAC-bypass via subjectUser swap, response leakage when scope deny.                                                          | #462  | sonnet | feat/federation-m3-security-review   | M3-11            | 10K      | Two review rounds budgeted. PRD requires explicit test for every 401/403 path — review verifies coverage.                                                |
+| FED-M3-12 | not-started | Independent security review (sonnet, not author of M3-03/04/05/06/07/08/09): focus on cert-SAN spoofing, OID extraction edge cases, scope-bypass via filter manipulation, RBAC-bypass via subjectUser swap, response leakage when scope deny.                                                          | #462  | sonnet | feat/federation-m3-security-review   | M3-11                             | 10K      | Two review rounds budgeted. PRD requires explicit test for every 401/403 path — review verifies coverage.                                                |
-| FED-M3-13 | not-started | Docs update: `docs/federation/SETUP.md` mTLS handshake section, new `docs/federation/HARNESS.md` for federation-harness usage, OID reference table in SETUP.md, scope enforcement pipeline diagram. Runbook still M7-deferred.                                                                         | #462  | haiku  | feat/federation-m3-docs              | M3-12            | 5K       | One ASCII diagram for the auth-guard → scope → RBAC pipeline; helps future reviewers reason about denial paths.                                          |
+| FED-M3-13 | not-started | Docs update: `docs/federation/SETUP.md` mTLS handshake section, new `docs/federation/HARNESS.md` for federation-harness usage, OID reference table in SETUP.md, scope enforcement pipeline diagram. Runbook still M7-deferred.                                                                         | #462  | haiku  | feat/federation-m3-docs              | M3-12                             | 5K       | One ASCII diagram for the auth-guard → scope → RBAC pipeline; helps future reviewers reason about denial paths.                                          |
-| FED-M3-14 | not-started | PR aggregate close, CI green, merge to main, close #462. Release tag `fed-v0.3.0-m3`. Update mission manifest M3 row → done; M4 row → in-progress when work begins.                                                                                                                                    | #462  | sonnet | chore/federation-m3-close            | M3-13            | 3K       | Same close pattern as M1-12 / M2-13.                                                                                                                     |
+| FED-M3-14 | not-started | PR aggregate close, CI green, merge to main, close #462. Release tag `fed-v0.3.0-m3`. Update mission manifest M3 row → done; M4 row → in-progress when work begins.                                                                                                                                    | #462  | sonnet | chore/federation-m3-close            | M3-13                             | 3K       | Same close pattern as M1-12 / M2-13.                                                                                                                     |
 
 **M3 estimate:** ~100K tokens (vs MILESTONES.md 40K — same per-task breakdown pattern as M1/M2: tests, review, and docs split out from implementation cost). Largest milestone in the federation mission.
 
@@ -120,6 +120,8 @@ Goal: Two federated gateways exchange real data over mTLS. Inbound requests pass
 
 **Backlog sync — 2026-06-24 (orchestrator):** Status reconciled against `origin/main` (release 0.0.48). Landed on main: **FED-M3-01** (DTOs, PR #506), **FED-M3-02** (harness scaffold, PR #505), **FED-M3-03** (mTLS auth-guard, PR #509 — CRIT-1/2 + HIGH-1..4 remediated in-PR), **FED-M3-08** (outbound mTLS client, PR #508). With M3-01/03/08 merged, three cards became dependency-clear and were dispatched to the idle coder lane: **FED-M3-04** scope.service → coder0 (`feat/federation-m3-scope-service`); **FED-M3-09** query-source + **FED-M3-07** capabilities verb → coder1 (`feat/federation-m3-query-source` first). Reviewer warmed for the M3 trust-boundary PRs. Remaining blocked-by-DAG: M3-05/06 (await M3-04), M3-10 (await M3-05/06), M3-11 (await M3-09), M3-12→14 (tail). Deploy chain (DEPLOY-IMG-FIX → 03/04) still independent of M3 code — harness local docker-compose fallback covers M3-11.
 
+**Backlog sync #2 — 2026-06-24 (orchestrator):** **FED-M3-09** (query-source) merged via PR #673 and **FED-M3-07** (capabilities) merged via PR #674 — both squash-merged on independent agent review-of-record + green CI (formal Gitea approve unavailable under the shared service account; merge is not gated by the self-approve guard). **FED-M3-05** (list verb) dispatched to coder1 (based on the M3-04 branch, rebase onto main once #672 lands). **FED-M3-04** (scope.service, PR #672) is in review-changes (one include_personal no-leak test outstanding). **DAG fix:** corrected `FED-M3-11` depends_on from `M3-02, M3-09` → `M3-02, M3-04, M3-05, M3-06, M3-09` — the E2E acceptance cases (#1–#5, #8–#10) exercise list/get over mTLS, so the server verbs + scope service are hard prerequisites; the original edge set omitted them and caused a premature M3-11 dispatch. Note: M3 read-path invariant for M3-11 is **no-persist + existing enrollment audit only** — read-verb audit-log writes are deferred to M4 (see M3-05/06 notes), so M3-11 must not assert read-audit-log entries.
+
 ## Milestone 4 — search + audit + rate limit (FED-M4)
 
 _Deferred. Issue #463._

docs/scratchpads/462-fed-m3-04-scope-service.md

@@ -0,0 +1,60 @@
+# Scratchpad — FED-M3-04 Scope Service
+
+## Objective
+
+Implement `apps/gateway/src/federation/server/scope.service.ts` for the M3 inbound federation scope-enforcement pipeline.
+
+## Scope / Constraints
+
+- Task: FED-M3-04, issue #462.
+- Branch: `feat/federation-m3-scope-service` from `origin/main` @ 0.0.48.
+- Pure service: no direct DB access; native RBAC/data access is injected per evaluation call.
+- Reuse `parseFederationScope` from M2-03.
+- Workers do not edit `docs/federation/TASKS.md` per repo AGENTS.md.
+
+## Acceptance Criteria
+
+1. Resource allowlist and `excluded_resources` enforced.
+2. Native RBAC evaluated as `subjectUserId` through an injected evaluator.
+3. Scope filter intersection supports `include_teams` and `include_personal` without widening native RBAC.
+4. `max_rows_per_query` caps requested limits.
+5. Service returns `{ allowed: true, filter }` or a structured deny reason usable by M4 audit.
+6. Unit tests cover every deny path.
+
+## Plan
+
+1. Inspect existing federation scope/schema/auth guard contracts.
+2. Add pure `FederationScopeService` plus typed result/filter/deny interfaces.
+3. Add focused unit tests for happy paths, filter intersection, row cap, and deny paths.
+4. Export/register service for future verb controllers.
+5. Run situational tests, baseline gates, code review, then PR.
+
+## Budget
+
+- Provided model tier: sonnet.
+- Estimate from task row: 10K tokens.
+- Working cap assumption: keep implementation focused to FED-M3-04 surfaces only.
+
+## Progress
+
+- Intake complete; dirty base worktree avoided by creating isolated worktree at `/home/jarvis/src/mosaic-mono-v1-fed-m3-04`.
+- Project PRD and federation task spec reviewed.
+- Added `FederationScopeService` with structured allow/deny result types and injected native RBAC evaluator contract.
+- Added unit coverage for happy path, row cap, filter intersection, and every deny path.
+- Exported/registered the service for upcoming M3 verb controllers.
+
+## Verification Evidence
+
+- `pnpm --filter @mosaicstack/gateway test -- src/federation/server/__tests__/scope.service.spec.ts` — pass (10 tests before review update; 11 tests after adding include_personal no-leak coverage).
+- `pnpm build` — pass (23 successful tasks).
+- `pnpm typecheck` — pass (41 successful tasks; re-run after review update).
+- `pnpm lint` — pass (23 successful tasks; re-run after review update).
+- `pnpm format:check` — pass (re-run after review update).
+- `pnpm test` — pass after starting local `postgres`/`valkey` and running `pnpm --filter @mosaicstack/db db:push` for the DB-backed cross-user isolation suite (41 successful tasks; gateway 477 passed / 11 skipped).
+- Code review: `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings.
+- Security review: `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — risk none, 0 findings.
+
+## Risks / Blockers
+
+- Issue #462 is already closed in provider output; likely milestone tracking mismatch. Will still reference #462 in PR body unless orchestrator redirects.
+- Local full-test setup required `docker compose up -d postgres valkey` + `db:push`; containers were stopped with `docker compose down` after verification.

docs/scratchpads/672-fleet-personas-timeout.md

@@ -0,0 +1,25 @@
+# Scratchpad — fleet-personas spec timeout
+
+## Objective
+
+Raise the `@mosaicstack/mosaic` Vitest timeout to 30s at config level so filesystem-backed fleet drift-guard specs (`fleet-personas`, `fleet-profiles`, and siblings) stop false-reding under contended CI.
+
+## Plan
+
+1. Move timeout policy into `packages/mosaic/vitest.config.ts` with `testTimeout: 30_000`.
+2. Remove the narrower `fleet-personas.spec.ts` local override so PR #677 fixes the suite class, not one file.
+3. Run targeted fleet specs plus typecheck/lint/format gates.
+4. Commit, queue guard, push, PR update.
+
+## Evidence
+
+- `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet-personas.spec.ts` — pass (8 tests; initial narrow fix).
+- `pnpm typecheck` — pass (41 tasks; initial narrow fix).
+- `pnpm lint` — pass (23 tasks; initial narrow fix).
+- `pnpm format:check` — pass after formatting this scratchpad (initial narrow fix).
+- Package-wide timeout follow-up:
+  - `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet-personas.spec.ts src/commands/fleet-profiles.spec.ts` — pass (24 tests).
+  - `pnpm --filter @mosaicstack/mosaic test` — pass (44 files / 618 tests).
+  - `pnpm typecheck` — pass (41 tasks).
+  - `pnpm lint` — pass (23 tasks).
+  - `pnpm format:check` — pass.

docs/scratchpads/FED-M3-05-list-verb.md

@@ -0,0 +1,51 @@
+# FED-M3-05 — Federation List Verb Scratchpad
+
+## Objective
+
+Implement `POST /api/federation/v1/list/:resource`.
+
+## Scope
+
+- Wire `FederationAuthGuard` → `FederationScopeService` → read-only list query layer.
+- Apply `max_rows_per_query` row cap and return pagination metadata when truncated.
+- Tag returned rows with `_source: "local"`.
+- Keep audit writes deferred to M4.
+- No request/response body persistence.
+
+## Base / branch
+
+- Branch: `feat/federation-m3-verb-list`
+- Base: `feat/federation-m3-scope-service` (PR #672), per orchestrator, because M3-04 is not merged yet.
+- Rebase target after #672 merges: `main`.
+
+## Implementation notes
+
+- Added `ListController` under `apps/gateway/src/federation/server/verbs/`.
+- Added `FederationListQueryService` as the read-only query layer and native RBAC evaluator.
+- Query resources supported in M3 list path:
+  - `tasks`: project/mission scoped tasks visible through personal/team project access.
+  - `notes`: non-empty `mission_tasks.notes` rows visible through personal/team mission access.
+  - `memory`: user-owned `insights` and `preferences` rows.
+  - `credentials` / `api_keys`: denied by native RBAC in M3 even if present in scope; sensitive-resource implementation is not part of FED-M3-05.
+- Cursor pagination uses an opaque base64url keyset cursor over `(createdAt, id)`; DB reads fetch at most `limit + 1` rows per resource query.
+
+## Tests
+
+- `pnpm --filter @mosaicstack/gateway test -- list.controller.spec.ts list-query.service.spec.ts` — PASS (9 tests).
+- `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
+- `pnpm --filter @mosaicstack/gateway lint` — PASS.
+- `pnpm format:check` — PASS.
+- `pnpm typecheck` — PASS (41/41 turbo tasks).
+- `pnpm lint` — PASS (23/23 turbo tasks).
+- `pnpm --filter @mosaicstack/gateway test` — FAIL in pre-existing/live-DB integration suite: `apps/gateway/src/__tests__/cross-user-isolation.test.ts` cleanup cannot connect to local PostgreSQL on `localhost:5433`. New list tests pass; failure is outside FED-M3-05.
+
+## Review evidence
+
+- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — PASS after remediation; approve, no findings.
+- `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — PASS after cursor remediation; risk level none, no findings.
+- Security-review note: read-path audit logging remains intentionally deferred to M4 per orchestrator clarification and FED-M3-05 scope.
+
+## Risks / follow-up
+
+- This branch intentionally includes M3-04 diff until PR #672 lands; final PR must be rebased onto main after #672 merges.
+- Current branch base predates the M3-07 capabilities module registration; expect a small `FederationModule` rebase conflict once #672 and #674 are both on main.

eslint.config.mjs

@@ -30,6 +30,7 @@ export default tseslint.config(
             'apps/gateway/vitest.config.ts',
             'packages/db/vitest.config.ts',
             'packages/storage/vitest.config.ts',
+            'packages/mosaic/vitest.config.ts',
             'packages/mosaic/__tests__/*.ts',
             'tools/federation-harness/*.ts',
           ],

packages/mosaic/vitest.config.ts

@@ -4,5 +4,6 @@ export default defineConfig({
   test: {
     globals: true,
     environment: 'node',
+    testTimeout: 30_000,
   },
 });