diff --git a/docs/contracts/catalog-field-consumer-2207.md b/docs/contracts/catalog-field-consumer-2207.md index d54d4f8e3..f37c3f5e8 100644 --- a/docs/contracts/catalog-field-consumer-2207.md +++ b/docs/contracts/catalog-field-consumer-2207.md @@ -136,3 +136,15 @@ Required consumer assertions, once gates allow implementation: exactly one descr Concrete source-inspection anchors for gate3: `save_context_metadata` in Database `supabase/migrations/20260920040000_context_guests.sql` accepts supplied URL/topic; `complete_context_enrichment` in `20260923070000_context_enrichment_scope.sql` writes supplied source items and accepts results. These are starting points for reserved-family guards, not an exhaustive writer/grant audit. At this API pin, no `read_binding`, `reconcile_retention` or `stream_binding_proposal` call exists under `app/` or `lib/`. Gate5's actual raw-history consumer is `lib/sessions/chats/getSessionChatHandler.ts`, which selects saved message parts following session/chat authorization without the proposed per-field source check. Next action: root/UI review this exact contract and schema ownership. Runtime work is blocked by selection origin, callable deployed authority and publication/history gates; document approval alone does not unblock a live implementation. + +## History withholding source increment — November 19, 2026 + +The existing session-chat GET handler now calls the [retained-field history +gate](../../lib/sessions/chats/retained-field/README.md) with the authenticated +account and validated session/chat/database-message anchors. Until a reviewed +current-source transport and publication protocol exist, marked retained-field +messages are omitted in full, including sibling text/numeric projections and +metadata. This is a default-denied history consumer, not a positive authority +implementation or activation of the proposed producer. Legacy raw-report +messages and controls retain their existing behavior. It does not qualify other +disclosure paths or derive provenance for unmarked text in separate messages. diff --git a/lib/sessions/chats/__tests__/getSessionChatHandler.test.ts b/lib/sessions/chats/__tests__/getSessionChatHandler.test.ts index b6c4c2ee3..cd587409f 100644 --- a/lib/sessions/chats/__tests__/getSessionChatHandler.test.ts +++ b/lib/sessions/chats/__tests__/getSessionChatHandler.test.ts @@ -23,9 +23,10 @@ function makeReq(): NextRequest { } function mockValidated(chatOverrides: Parameters[0] = {}) { - vi.mocked(validateGetSessionChatRequest).mockResolvedValue( - baseChatRow({ id: "chat_1", session_id: "sess_1", ...chatOverrides }), - ); + vi.mocked(validateGetSessionChatRequest).mockResolvedValue({ + chat: baseChatRow({ id: "chat_1", session_id: "sess_1", ...chatOverrides }), + actorAccountId: "actual-actor", + }); } describe("getSessionChatHandler", () => { diff --git a/lib/sessions/chats/__tests__/getSessionChatRoute.readFailure.test.ts b/lib/sessions/chats/__tests__/getSessionChatRoute.readFailure.test.ts index 5178156c9..905c20859 100644 --- a/lib/sessions/chats/__tests__/getSessionChatRoute.readFailure.test.ts +++ b/lib/sessions/chats/__tests__/getSessionChatRoute.readFailure.test.ts @@ -46,7 +46,10 @@ beforeEach(() => { mocks.from.mockImplementation(() => { throw new Error("Unexpected storage access"); }); - mocks.validate.mockResolvedValue(baseChatRow({ id: chatId, session_id: sessionId })); + mocks.validate.mockResolvedValue({ + chat: baseChatRow({ id: chatId, session_id: sessionId }), + actorAccountId: "actual-actor", + }); }); afterEach(() => { expect(fetch).not.toHaveBeenCalled(); @@ -82,9 +85,10 @@ it("preserves the saved UIMessage and streaming state", async () => { role: "assistant", parts: [{ type: "text", text: "Saved answer" }], }; - mocks.validate.mockResolvedValue( - baseChatRow({ id: chatId, session_id: sessionId, active_stream_id: "synthetic-run" }), - ); + mocks.validate.mockResolvedValue({ + chat: baseChatRow({ id: chatId, session_id: sessionId, active_stream_id: "synthetic-run" }), + actorAccountId: "actual-actor", + }); mockRead([{ parts: message }]); const response = await request(); expect(response.status).toBe(200); diff --git a/lib/sessions/chats/__tests__/retainedFieldHistory.test.ts b/lib/sessions/chats/__tests__/retainedFieldHistory.test.ts new file mode 100644 index 000000000..f1b36977a --- /dev/null +++ b/lib/sessions/chats/__tests__/retainedFieldHistory.test.ts @@ -0,0 +1,201 @@ +import { beforeEach, afterEach, expect, it, vi } from "vitest"; +import { NextRequest } from "next/server"; +import { baseSessionRow } from "@/lib/sessions/__tests__/baseSessionRow"; +import { baseChatRow } from "@/lib/sessions/__tests__/baseChatRow"; +import type { Tables } from "@/types/database.types"; +import * as disclosure from "@/lib/sessions/chats/retained-field/readRetainedFieldDisclosure"; +import { GET } from "@/app/api/sessions/[sessionId]/chats/[chatId]/route"; + +const mocks = vi.hoisted(() => ({ + auth: vi.fn(), + sessions: vi.fn(), + chats: vi.fn(), + messages: vi.fn(), +})); +vi.mock("@/lib/auth/validateAuthContext", () => ({ validateAuthContext: mocks.auth })); +vi.mock("@/lib/supabase/sessions/selectSessions", () => ({ selectSessions: mocks.sessions })); +vi.mock("@/lib/supabase/chats/selectChats", () => ({ selectChats: mocks.chats })); +vi.mock("@/lib/supabase/chat_messages/selectChatMessages", () => ({ + selectChatMessages: mocks.messages, +})); +vi.mock("@/lib/sessions/chats/patchSessionChatHandler", () => ({ + patchSessionChatHandler: vi.fn(), +})); +vi.mock("@/lib/sessions/chats/deleteSessionChatHandler", () => ({ + deleteSessionChatHandler: vi.fn(), +})); + +const companion = { + type: "data-retained-field-snapshot", + capability: "retained-field-companion/1", + data: { + fieldContext: { + contract: "catalog-retained-field-projection/1", + items: [{ value: { amount: 987654321 } }], + }, + surface: { schemaVersion: 1, fallbackText: "PRIVATE DERIVED 987654321" }, + }, +}; +const legacy = { + id: "legacy", + role: "assistant", + parts: [ + { + type: "data-catalog-snapshot", + data: { schemaVersion: 1, title: "Legacy report", controls: { sort: "streams" } }, + }, + { type: "text", text: "Legacy answer" }, + ], +}; +function row(parts: unknown, id = "retained"): Tables<"chat_messages"> { + return { + id, + chat_id: "chat_1", + role: "assistant", + parts: parts as Tables<"chat_messages">["parts"], + created_at: "2026-11-19T00:00:00Z", + }; +} +function request() { + return GET(new NextRequest("https://fixture.invalid/api/sessions/sess_1/chats/chat_1"), { + params: Promise.resolve({ sessionId: "sess_1", chatId: "chat_1" }), + }); +} +beforeEach(() => { + vi.restoreAllMocks(); + vi.clearAllMocks(); + vi.stubGlobal( + "fetch", + vi.fn(() => { + throw new Error("NETWORK FORBIDDEN"); + }), + ); + mocks.auth.mockResolvedValue({ accountId: "actual-actor", orgId: null, authToken: "synthetic" }); + mocks.sessions.mockResolvedValue([baseSessionRow({ account_id: "actual-actor" })]); + mocks.chats.mockResolvedValue([baseChatRow()]); +}); +afterEach(() => { + expect(fetch).not.toHaveBeenCalled(); + vi.unstubAllGlobals(); +}); +it("withholds whole retained messages including sibling text, numeric tables and metadata, preserving legacy order", async () => { + const retained = { + id: "retained", + role: "assistant", + metadata: { summary: "PRIVATE DERIVED 987654321" }, + parts: [ + { type: "text", text: "PRIVATE DERIVED 987654321" }, + companion, + { type: "data-table", data: { rows: [[987654321]] } }, + ], + }; + mocks.messages.mockResolvedValue([ + row(legacy, "legacy"), + row(retained), + row({ ...legacy, id: "after" }, "after"), + ]); + const response = await request(); + expect(response.status).toBe(200); + const body = await response.json(); + expect(body.messages).toEqual([legacy, { ...legacy, id: "after" }]); + expect(JSON.stringify(body)).not.toContain("987654321"); + expect(response.headers.get("Cache-Control")).toBe("private, no-store"); +}); +it.each([ + { ...companion, capability: "unknown-version" }, + { type: "data-retained-field-snapshot", data: null }, + { capability: "retained-field-companion/1", data: {} }, + { data: { fieldContext: { contract: "catalog-retained-field-projection/1" } } }, + { mode: "retained_field" }, +])( + "withholds malformed or unsupported family members without relying on successful schema parsing: %j", + async part => { + mocks.messages.mockResolvedValue([ + row({ + id: "retained", + role: "assistant", + parts: [{ type: "text", text: "PRIVATE DERIVED" }, part], + }), + ]); + expect((await (await request()).json()).messages).toEqual([]); + }, +); +it("also withholds legacy array-shaped stored parts when they contain the new family", async () => { + mocks.messages.mockResolvedValue([row([{ type: "text", text: "PRIVATE DERIVED" }, companion])]); + expect((await (await request()).json()).messages).toEqual([]); +}); +it("cached ready, successful preparation and local disclosure flags never permit history disclosure", async () => { + mocks.messages.mockResolvedValue([ + row({ + id: "retained", + role: "assistant", + state: "ready", + preparation: "ready", + disclosure: "available", + parts: [companion], + }), + ]); + expect((await (await request()).json()).messages).toEqual([]); +}); +it("preserves legacy text even when it mentions retained fields", async () => { + const message = { + id: "normal", + role: "assistant", + parts: [{ type: "text", text: "Explain data-retained-field-snapshot" }], + }; + mocks.messages.mockResolvedValue([row(message)]); + expect((await (await request()).json()).messages).toEqual([message]); +}); +it("does not read history for a different authenticated actor", async () => { + mocks.auth.mockResolvedValue({ accountId: "wrong-actor", orgId: null, authToken: "synthetic" }); + expect((await request()).status).toBe(403); + expect(mocks.messages).not.toHaveBeenCalled(); +}); + +it.each(["unavailable", "withdrawn", "stale", "error", "ready"])( + "denies the whole message for injected current-boundary result %s (including unsupported states)", + async state => { + const stored = { + id: "spoofed-message", + accountId: "forged-owner", + sessionId: "other-session", + chatId: "other-chat", + role: "assistant", + parts: [companion, { type: "text", text: "PRIVATE DERIVED" }], + }; + const read = vi + .spyOn(disclosure, "readRetainedFieldDisclosure") + .mockResolvedValue({ state } as never); + mocks.messages.mockResolvedValue([row(stored, "database-message-id")]); + const body = await (await request()).json(); + expect(body.messages).toEqual([]); + expect(read).toHaveBeenCalledExactlyOnceWith( + { + actorAccountId: "actual-actor", + sessionId: "sess_1", + chatId: "chat_1", + messageId: "database-message-id", + }, + stored, + ); + expect(JSON.stringify(body)).not.toContain("forged-owner"); + }, +); +it("withholds every projection on a thrown current-source error without retry or diagnostics", async () => { + const read = vi + .spyOn(disclosure, "readRetainedFieldDisclosure") + .mockRejectedValue(new Error("PRIVATE AUTHORITY ERROR")); + mocks.messages.mockResolvedValue([ + row({ id: "retained", parts: [companion, { type: "text", text: "PRIVATE DERIVED" }] }), + row(legacy, "legacy"), + ]); + const response = await request(); + expect((await response.json()).messages).toEqual([legacy]); + expect(read).toHaveBeenCalledTimes(1); +}); +it("does not invoke current-field authority for legacy reports or text", async () => { + const read = vi.spyOn(disclosure, "readRetainedFieldDisclosure"); + mocks.messages.mockResolvedValue([row(legacy)]); + expect((await (await request()).json()).messages).toEqual([legacy]); + expect(read).not.toHaveBeenCalled(); +}); diff --git a/lib/sessions/chats/__tests__/validateGetSessionChatRequest.test.ts b/lib/sessions/chats/__tests__/validateGetSessionChatRequest.test.ts index e3f4bc595..7025beb43 100644 --- a/lib/sessions/chats/__tests__/validateGetSessionChatRequest.test.ts +++ b/lib/sessions/chats/__tests__/validateGetSessionChatRequest.test.ts @@ -143,8 +143,9 @@ describe("validateGetSessionChatRequest", () => { const res = await validateGetSessionChatRequest(makeReq(), "sess_1", "chat_1"); expect(res).not.toBeInstanceOf(NextResponse); if (!(res instanceof NextResponse)) { - expect(res.id).toBe("chat_1"); - expect(res.session_id).toBe("sess_1"); + expect(res.chat.id).toBe("chat_1"); + expect(res.actorAccountId).toBe(accountId); + expect(res.chat.session_id).toBe("sess_1"); } expect(selectSessions).toHaveBeenCalledWith({ id: "sess_1" }); expect(selectChats).toHaveBeenCalledWith({ id: "chat_1" }); diff --git a/lib/sessions/chats/getSessionChatHandler.ts b/lib/sessions/chats/getSessionChatHandler.ts index 23ee6be1c..9a85c854d 100644 --- a/lib/sessions/chats/getSessionChatHandler.ts +++ b/lib/sessions/chats/getSessionChatHandler.ts @@ -4,6 +4,7 @@ import { getCorsHeaders } from "@/lib/networking/getCorsHeaders"; import { toChatResponse } from "@/lib/sessions/toChatResponse"; import { validateGetSessionChatRequest } from "@/lib/sessions/chats/validateGetSessionChatRequest"; import { selectChatMessages } from "@/lib/supabase/chat_messages/selectChatMessages"; +import { filterRetainedFieldHistory } from "./retained-field/filterRetainedFieldHistory"; export interface SessionChatResponse { chat: ReturnType; @@ -17,7 +18,8 @@ export interface SessionChatResponse { * persisted UI message stream — enough for both initial render and * in-tab refresh. * - * `messages` is the raw `parts` JSON for each row (chat messages are + * Retained-field messages are withheld as a whole until current-source disclosure + * is implemented. Other `messages` retain the raw `parts` JSON (chat messages are * stored as the full UIMessage; the caller deserializes back into * its UIMessage type). * @@ -31,10 +33,11 @@ export async function getSessionChatHandler( sessionId: string, chatId: string, ): Promise { - const chat = await validateGetSessionChatRequest(request, sessionId, chatId); - if (chat instanceof NextResponse) { - return chat; + const validated = await validateGetSessionChatRequest(request, sessionId, chatId); + if (validated instanceof NextResponse) { + return validated; } + const { chat, actorAccountId } = validated; const messages = await selectChatMessages({ chatId, orderBy: { createdAt: "asc" } }); if (messages === null) return errorResponse("Failed to load messages", 500); @@ -43,8 +46,11 @@ export async function getSessionChatHandler( { chat: toChatResponse(chat), isStreaming: chat.active_stream_id !== null, - messages: messages.map(row => row.parts), + messages: await filterRetainedFieldHistory( + { actorAccountId, sessionId: chat.session_id, chatId: chat.id }, + messages, + ), } satisfies SessionChatResponse, - { status: 200, headers: getCorsHeaders() }, + { status: 200, headers: { ...getCorsHeaders(), "Cache-Control": "private, no-store" } }, ); } diff --git a/lib/sessions/chats/retained-field/README.md b/lib/sessions/chats/retained-field/README.md new file mode 100644 index 000000000..19cb5a530 --- /dev/null +++ b/lib/sessions/chats/retained-field/README.md @@ -0,0 +1,64 @@ +# Retained-field history withholding (2207) + +The existing GET `/api/sessions/{sessionId}/chats/{chatId}` now invokes this gate +before serializing saved messages. It does not activate retained-field production +or grant disclosure. The current-authority boundary has no implementation and +returns unavailable. There is deliberately no positive release branch, including +for an unexpected or cached `ready` value. + +## Actual call graph + +`route.GET` → `getSessionChatHandler` → `validateGetSessionChatRequest` +(authenticated account, session ownership, chat membership) → `selectChatMessages` +→ `filterRetainedFieldHistory` → `hasRetainedFieldContent` → +`readRetainedFieldDisclosure` → omission of the entire marked message. + +The validator returns the actual authenticated account separately from the chat. +The gate passes that account, validated session/chat IDs and database message ID; +none comes from the saved message's claimed owner, workspace, actor or anchors. +The saved content remains untrusted input to any future authority implementation. +No workspace authority is inferred from session ownership. + +`persistAssistantMessage` stores a full AI SDK UIMessage in `chat_messages.parts`. +Removing only its companion would leak sibling text, tables or metadata. The gate +therefore omits the whole stored message. Legacy array-shaped parts are inspected +as well. Unrelated messages retain their original values and order. A successful +response is explicitly private/no-store; empty filtered history remains a 200. +Existing auth and storage error behavior is preserved. + +## Reserved family and limits + +The proposed App envelope is `data-retained-field-snapshot` with capability +`retained-field-companion/1`, holding the unchanged schema-v1 surface alongside +`catalog-retained-field-projection/1`. Detection examines structured discriminants +throughout the saved JSON, including malformed payloads and unknown versions in +these reserved families. It also recognizes structured `mode: retained_field`. +It does not parse text, infer numeric meaning or extend schema-v1. This is a deny +classifier, not an admission schema or producer negotiation implementation. + +This default-denied source integration intentionally withholds even a legitimate +historical retained-field message. Current-source read and publication locking, +exact selection/method/projection validation, batch authorization and a reviewed +transport are still required before any positive branch can be added. A callback, +local flag or successful earlier computation cannot replace them. + +The boundary never fetches latest, re-keys, retains, expands, calls a provider or +falls back to legacy raw-report authority. No SQL, grants, flags or routes are +introduced. Frozen API1291/Database143 consumers are not imported or modified. + +This qualifies this GET history consumer only. It cannot identify unmarked prose +in a separate message as derived, revoke an already delivered client object, or +qualify initial-send/replay/export/model inputs and other history endpoints. Those +paths and a provenance-preserving producer remain separate activation gates. + +## Negative acceptance + +The route tests invoke the real GET, handler, validator and gate with synthetic +auth/storage boundaries, prohibit network access and verify whole-message removal, +mixed text/numeric projections, malformed/unsupported family markers, stored ready +and local disclosure flags, real actor/anchor propagation, thrown failure with no +retry, and unchanged legacy reports/controls. Injected withdrawn/stale/ready states +are adversarial boundary results, not claims of actual SQL withdrawal qualification. +No authenticated production/history request is executed. + +Run `pnpm exec vitest run lib/sessions/chats/__tests__`. diff --git a/lib/sessions/chats/retained-field/filterRetainedFieldHistory.ts b/lib/sessions/chats/retained-field/filterRetainedFieldHistory.ts new file mode 100644 index 000000000..26e9df464 --- /dev/null +++ b/lib/sessions/chats/retained-field/filterRetainedFieldHistory.ts @@ -0,0 +1,28 @@ +import type { Tables } from "@/types/database.types"; +import { hasRetainedFieldContent } from "./hasRetainedFieldContent"; +import { + readRetainedFieldDisclosure, + type RetainedFieldDisclosureScope, +} from "./readRetainedFieldDisclosure"; + +/** Withhold the entire stored message, including sibling text, tables and metadata. */ +export async function filterRetainedFieldHistory( + scope: Omit, + rows: Tables<"chat_messages">[], +): Promise { + const messages: unknown[] = []; + for (const row of rows) { + if (!hasRetainedFieldContent(row.parts)) { + messages.push(row.parts); + continue; + } + try { + await readRetainedFieldDisclosure({ ...scope, messageId: row.id }, row.parts); + } catch { + // Operational failure cannot release any projection or existence diagnostics. + } + // No positive transport/publication protocol is adopted. Even a surprising + // cached "ready" result cannot authorize returning stored projections. + } + return messages; +} diff --git a/lib/sessions/chats/retained-field/hasRetainedFieldContent.ts b/lib/sessions/chats/retained-field/hasRetainedFieldContent.ts new file mode 100644 index 000000000..794e262e6 --- /dev/null +++ b/lib/sessions/chats/retained-field/hasRetainedFieldContent.ts @@ -0,0 +1,24 @@ +/** Recognize the reserved family even if malformed; validation must not become a disclosure bypass. */ +export function hasRetainedFieldContent(message: unknown): boolean { + const pending: unknown[] = [message]; + while (pending.length) { + const value = pending.pop(); + if (!value || typeof value !== "object") continue; + if (Array.isArray(value)) { + for (const child of value) pending.push(child); + continue; + } + const record = value as Record; + if ( + (typeof record.type === "string" && record.type.startsWith("data-retained-field-")) || + (typeof record.capability === "string" && + record.capability.startsWith("retained-field-companion/")) || + (typeof record.contract === "string" && + record.contract.startsWith("catalog-retained-field-projection/")) || + record.mode === "retained_field" + ) + return true; + for (const child of Object.values(record)) pending.push(child); + } + return false; +} diff --git a/lib/sessions/chats/retained-field/readRetainedFieldDisclosure.ts b/lib/sessions/chats/retained-field/readRetainedFieldDisclosure.ts new file mode 100644 index 000000000..91a93b562 --- /dev/null +++ b/lib/sessions/chats/retained-field/readRetainedFieldDisclosure.ts @@ -0,0 +1,17 @@ +export type RetainedFieldDisclosureScope = { + actorAccountId: string; + sessionId: string; + chatId: string; + messageId: string; +}; +/** + * No reviewed current-authority transport exists. This boundary cannot grant disclosure. + * The saved message is untrusted source selection/projection, never an authority receipt. + * No network, latest selection, re-key, retain, expansion or cached-ready fallback. + */ +export async function readRetainedFieldDisclosure( + _scope: RetainedFieldDisclosureScope, + _savedMessage: unknown, +): Promise<{ state: "unavailable" | "error" }> { + return { state: "unavailable" }; +} diff --git a/lib/sessions/chats/validateGetSessionChatRequest.ts b/lib/sessions/chats/validateGetSessionChatRequest.ts index 9324cc215..ac2c0be68 100644 --- a/lib/sessions/chats/validateGetSessionChatRequest.ts +++ b/lib/sessions/chats/validateGetSessionChatRequest.ts @@ -14,18 +14,18 @@ import type { Tables } from "@/types/database.types"; * 3. Loads the chat and confirms it belongs to the session * * Returns either a 401/403/404 NextResponse describing the first - * failure, or the resolved chat row for the handler to render. + * failure, or the resolved chat and authenticated account for the handler. * * @param request - The incoming request. * @param sessionId - The id of the parent session. * @param chatId - The id of the chat being fetched. - * @returns A NextResponse on failure, or the chat row on success. + * @returns A NextResponse on failure, or the chat and actual authenticated account on success. */ export async function validateGetSessionChatRequest( request: NextRequest, sessionId: string, chatId: string, -): Promise> { +): Promise; actorAccountId: string }> { const auth = await validateAuthContext(request); if (auth instanceof NextResponse) { return auth; @@ -59,5 +59,5 @@ export async function validateGetSessionChatRequest( ); } - return chat; + return { chat, actorAccountId: auth.accountId }; }