Skip to content

Commit 820f704

Browse files
committed
feat(audit): every data export writes a run-level sys_audit_log row, and the export action comes back with its writer
The REST export door (GET /data/:object/export) hands the `audit` slot one event per export it streamed; plugin-audit's new data-export writer turns it into an `export` row (record_id null, the object in object_name) carrying the format, row count, row limit, truncation, the filter as field names and operators only, whether a search term applied, and the outcome. The `export` value returns to sys_audit_log.action and to the config_changes view filter. Claude-Session: https://claude.ai/code/session_016WV4cxfxbKV82MKKQzizpP Co-authored-by: Claude <noreply@anthropic.com>
1 parent 6ddf827 commit 820f704

10 files changed

Lines changed: 1000 additions & 17 deletions

‎packages/plugins/plugin-audit/src/audit-plugin.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ import { installAuditWriters, type AuditI18nSurface, type MessagingEmitSurface }
3030
import { installReadAuditWriter, type ReadAuditWriterHandle } from './read-audit.js';
3131
import { createAuthEventAuditSink } from './auth-event-audit.js';
3232
import { createActionInvocationAuditWriter } from './action-invocation-audit.js';
33+
import { createDataExportAuditWriter } from './data-export-audit.js';
3334
import { installCommentAccessHooks, installCommentReadVisibility } from './comment-access-hooks.js';
3435
import {
3536
COMMENT_REACTION_REMOVE_ROUTE,
@@ -318,6 +319,11 @@ export class AuditPlugin implements Plugin {
318319
// (`recordActionInvocation`): the two action doors in `@objectstack/runtime`
319320
// resolve it per request and hand it one event per invocation, naming the
320321
// door it came through (ruling 6513869839 on #27681, parameter 3).
322+
//
323+
// [#30955] And the data-export writer (`recordDataExport`): the REST
324+
// export door resolves it per request and hands it one event per export
325+
// it streamed, so every export of every object, this ledger included,
326+
// leaves a run-level `export` row (`data-export-audit.ts`).
321327
const getLedgerEngine = (): IDataEngine | undefined => {
322328
try {
323329
return ctx.getService<IDataEngine>('objectql');
@@ -334,6 +340,7 @@ export class AuditPlugin implements Plugin {
334340
ctx.registerService('audit', {
335341
...createAuthEventAuditSink({ getEngine: getLedgerEngine, logger: ctx.logger }),
336342
...createActionInvocationAuditWriter({ getEngine: getLedgerEngine, logger: ctx.logger }),
343+
...createDataExportAuditWriter({ getEngine: getLedgerEngine, logger: ctx.logger }),
337344
});
338345

339346
// ADR-0029 D8 — contribute this plugin's object translations to the i18n
Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* [#30955] The `export` writer stores a REAL, READ-BACK ledger row for each
5+
* data export — and never an exported value.
6+
*
7+
* The slot cases boot the real composition this package ships in
8+
* (`ObjectQLPlugin` + `AuditPlugin` on a sqlite driver) and reach the writer
9+
* the way the REST export door does: through the `audit` service slot's
10+
* `recordDataExport`. Every assertion reads the row back through the engine,
11+
* for the reason `auth-event-audit.test.ts` records: every `sys_audit_log`
12+
* field is `readonly` and `validateRecord` skips readonly fields, so "the call
13+
* did not throw" is equally true when the row landed right, landed wrong, or
14+
* was never attempted. The door side — that the export door hands this writer
15+
* one event per export, and none for a refused request — is pinned in
16+
* `@objectstack/rest`'s `export-integration.test.ts`; the two halves together
17+
* on the showcase in the dogfood suite's `data-export-audit-row.dogfood.test.ts`.
18+
*/
19+
20+
import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
21+
import { ObjectKernel } from '@objectstack/core';
22+
import { ObjectQL, ObjectQLPlugin } from '@objectstack/objectql';
23+
import { SqliteWasmDriver } from '@objectstack/driver-sqlite-wasm';
24+
25+
import { AuditPlugin } from './audit-plugin.js';
26+
import {
27+
DATA_EXPORT_AUDIT_ACTION,
28+
EXPORT_FILTER_SUMMARY_MAX_TERMS,
29+
buildDataExportAuditRow,
30+
createDataExportAuditWriter,
31+
summarizeExportFilter,
32+
type DataExportAuditEvent,
33+
type DataExportAuditWriter,
34+
} from './data-export-audit.js';
35+
36+
const LEDGER = 'sys_audit_log';
37+
const SYS = { isSystem: true } as const;
38+
39+
/**
40+
* A cell value no field name, operator or code in this file spells: the
41+
* no-value pins seed it into every value position an export request has.
42+
*/
43+
const SECRET = 'Zq7-export-cell-value-4411';
44+
45+
/** An export as the door hands it, completed; each case overrides what it is about. */
46+
function exportEvent(overrides: Partial<DataExportAuditEvent> = {}): DataExportAuditEvent {
47+
return {
48+
context: { userId: 'u_exporter', tenantId: 'org_a' },
49+
objectName: 'dea_note',
50+
format: 'csv',
51+
rowCount: 2,
52+
limit: 10_000,
53+
requestedLimit: 10_000,
54+
limitCap: 50_000,
55+
truncated: false,
56+
outcome: 'succeeded',
57+
...overrides,
58+
};
59+
}
60+
61+
const metadataOf = (row: Record<string, unknown>): Record<string, any> => JSON.parse(String(row.metadata));
62+
63+
describe('[#30955] the export writer on the real `audit` slot', () => {
64+
let kernel: ObjectKernel;
65+
let engine: ObjectQL;
66+
let audit: DataExportAuditWriter;
67+
68+
/** The export rows at rest, oldest first. */
69+
const exportRows = async (): Promise<Array<Record<string, any>>> =>
70+
(await engine.find(LEDGER, { where: { action: DATA_EXPORT_AUDIT_ACTION }, orderBy: [{ field: 'created_at', order: 'asc' }], context: SYS } as any)) as any;
71+
72+
beforeAll(async () => {
73+
kernel = new ObjectKernel({ logger: { level: 'silent' } });
74+
await kernel.use(new ObjectQLPlugin());
75+
await kernel.use(new AuditPlugin());
76+
await kernel.bootstrap();
77+
engine = kernel.getService<ObjectQL>('objectql');
78+
const driver = new SqliteWasmDriver({ filename: ':memory:' });
79+
await driver.connect();
80+
engine.registerDriver(driver, true);
81+
await engine.syncSchemas();
82+
audit = kernel.getService<DataExportAuditWriter>('audit');
83+
}, 120_000);
84+
85+
afterAll(async () => {
86+
if (kernel) await Promise.race([kernel.shutdown(), new Promise<void>((r) => setTimeout(r, 10_000))]);
87+
}, 30_000);
88+
89+
it('the slot carries the writer beside the other ledger ingresses', () => {
90+
expect(typeof audit.recordDataExport).toBe('function');
91+
expect(typeof (audit as any).recordAuthEvent).toBe('function');
92+
expect(typeof (audit as any).recordActionInvocation).toBe('function');
93+
});
94+
95+
it('an export of an ordinary object writes ONE run-level row with its format and row count', async () => {
96+
const before = (await exportRows()).length;
97+
await audit.recordDataExport(exportEvent({ objectName: 'dea_note', format: 'xlsx', rowCount: 2 }));
98+
const rows = await exportRows();
99+
expect(rows).toHaveLength(before + 1);
100+
const row = rows[rows.length - 1];
101+
expect(row).toMatchObject({
102+
action: 'export',
103+
object_name: 'dea_note',
104+
record_id: null,
105+
user_id: 'u_exporter',
106+
actor: 'u_exporter',
107+
tenant_id: 'org_a',
108+
});
109+
expect(row.old_value ?? null).toBeNull();
110+
expect(row.new_value ?? null).toBeNull();
111+
expect(metadataOf(row)).toMatchObject({
112+
format: 'xlsx',
113+
row_count: 2,
114+
limit: 10_000,
115+
requested_limit: 10_000,
116+
limit_cap: 50_000,
117+
limit_capped: false,
118+
truncated: false,
119+
search: false,
120+
outcome: 'succeeded',
121+
});
122+
});
123+
124+
it('an export of the ledger itself writes ONE row about the ledger', async () => {
125+
const before = (await exportRows()).length;
126+
await audit.recordDataExport(exportEvent({ objectName: LEDGER, format: 'json', rowCount: 7 }));
127+
const rows = await exportRows();
128+
expect(rows).toHaveLength(before + 1);
129+
expect(rows[rows.length - 1]).toMatchObject({ action: 'export', object_name: LEDGER, record_id: null });
130+
expect(metadataOf(rows[rows.length - 1])).toMatchObject({ format: 'json', row_count: 7, outcome: 'succeeded' });
131+
});
132+
133+
it('a truncated export records the truncation and that the 50k cap clipped the request', async () => {
134+
await audit.recordDataExport(exportEvent({ rowCount: 50_000, limit: 50_000, requestedLimit: 80_000, truncated: true }));
135+
const rows = await exportRows();
136+
expect(metadataOf(rows[rows.length - 1])).toMatchObject({
137+
row_count: 50_000,
138+
limit: 50_000,
139+
requested_limit: 80_000,
140+
limit_cap: 50_000,
141+
limit_capped: true,
142+
truncated: true,
143+
});
144+
});
145+
146+
it('a failed export records its outcome, status and machine code', async () => {
147+
await audit.recordDataExport(exportEvent({ outcome: 'failed', status: 400, errorCode: 'INVALID_FIELD', rowCount: 0 }));
148+
const rows = await exportRows();
149+
expect(metadataOf(rows[rows.length - 1])).toMatchObject({
150+
outcome: 'failed',
151+
status: 400,
152+
error_code: 'INVALID_FIELD',
153+
row_count: 0,
154+
});
155+
});
156+
157+
it('the row never carries an exported cell value: not the filter comparands, not the search term', async () => {
158+
await audit.recordDataExport(exportEvent({
159+
query: {
160+
filter: {
161+
name: SECRET,
162+
$or: [
163+
{ code: { $in: [SECRET, `${SECRET}-2`] } },
164+
{ owner: { email: { $contains: SECRET } } },
165+
{ $not: { title: { $eq: SECRET } } },
166+
],
167+
},
168+
search: SECRET,
169+
searchFields: ['name', 'code'],
170+
},
171+
}));
172+
const rows = await exportRows();
173+
const row = rows[rows.length - 1];
174+
// Every column of the stored row, the metadata included, as one string.
175+
expect(JSON.stringify(row)).not.toContain(SECRET);
176+
// …while what the request ASKED is recorded: which fields, which operators.
177+
const meta = metadataOf(row);
178+
expect(meta.filter).toEqual([
179+
{ field: 'name', op: '$eq' },
180+
{ field: 'code', op: '$in' },
181+
{ field: 'owner.email', op: '$contains' },
182+
{ field: 'title', op: '$eq' },
183+
]);
184+
expect(meta.search).toBe(true);
185+
expect(meta.search_fields).toEqual(['name', 'code']);
186+
});
187+
});
188+
189+
describe('[#30955] the filter summary keeps names and operators, never a comparand', () => {
190+
it('reads the array dialect: comparison nodes, logic words and a list of conditions', () => {
191+
expect(summarizeExportFilter(['and', ['status', '=', SECRET], ['or', ['amount', '>', 5], ['code', 'in', [SECRET]]]])).toEqual({
192+
terms: [
193+
{ field: 'status', op: '=' },
194+
{ field: 'amount', op: '>' },
195+
{ field: 'code', op: 'in' },
196+
],
197+
omitted: 0,
198+
});
199+
expect(summarizeExportFilter([['a', '=', SECRET], 'or', ['b', 'contains', SECRET]]).terms).toEqual([
200+
{ field: 'a', op: '=' },
201+
{ field: 'b', op: 'contains' },
202+
]);
203+
});
204+
205+
it('records a field position that is not a machine-name path, and an operator token of no operator shape, as `?`', () => {
206+
const { terms } = summarizeExportFilter({ [SECRET]: 1, ok_field: { [`$${SECRET}`]: 1 } });
207+
expect(terms).toEqual([
208+
{ field: '?', op: '$eq' },
209+
{ field: 'ok_field', op: '?' },
210+
]);
211+
expect(JSON.stringify(terms)).not.toContain(SECRET);
212+
});
213+
214+
it('is bounded: terms past the bound are counted, not recorded', () => {
215+
const filter = Object.fromEntries(Array.from({ length: EXPORT_FILTER_SUMMARY_MAX_TERMS + 8 }, (_, i) => [`f_${i}`, SECRET]));
216+
const { terms, omitted } = summarizeExportFilter(filter);
217+
expect(terms).toHaveLength(EXPORT_FILTER_SUMMARY_MAX_TERMS);
218+
expect(omitted).toBe(8);
219+
const row = buildDataExportAuditRow(exportEvent({ query: { filter } }));
220+
expect(metadataOf(row).filter_terms_omitted).toBe(8);
221+
});
222+
223+
it('de-duplicates a repeated term', () => {
224+
expect(summarizeExportFilter({ $or: [{ a: 1 }, { a: 2 }, { a: { $eq: 3 } }] }).terms).toEqual([{ field: 'a', op: '$eq' }]);
225+
});
226+
});
227+
228+
describe('[#30955] the row attributes the export the way the other ledger rows do', () => {
229+
it('an agent-performed export names the client and the delegating user', () => {
230+
const row = buildDataExportAuditRow(exportEvent({
231+
context: { userId: 'u_human', tenantId: 'org_a', performedBy: { clientId: 'client_agent' } as any },
232+
}));
233+
expect(metadataOf(row)).toMatchObject({ performed_by: 'client_agent', on_behalf_of: 'u_human' });
234+
});
235+
236+
it('a service principal with no user is the actor', () => {
237+
const row = buildDataExportAuditRow(exportEvent({ context: { actor: 'svc:nightly', tenantId: 'org_a' } as any }));
238+
expect(row).toMatchObject({ user_id: null, actor: 'svc:nightly' });
239+
});
240+
241+
it('a ledger with no `actor` column gets no `actor` key', () => {
242+
const row = buildDataExportAuditRow(exportEvent(), () => false);
243+
expect('actor' in row).toBe(false);
244+
});
245+
});
246+
247+
describe('[#30955] a lost row is loud, once per cause, and never throws', () => {
248+
it('reports a refused ledger write at `error`, then `debug` for the same cause', async () => {
249+
const refusal = Object.assign(new Error('ledger refused'), { code: 'SQLITE_READONLY' });
250+
const engine = { insert: vi.fn(async () => { throw refusal; }) } as any;
251+
const logger = { error: vi.fn(), warn: vi.fn(), debug: vi.fn() };
252+
const writer = createDataExportAuditWriter({ getEngine: () => engine, logger });
253+
254+
await expect(writer.recordDataExport(exportEvent({ query: { filter: { name: SECRET }, search: SECRET } }))).resolves.toBeUndefined();
255+
await expect(writer.recordDataExport(exportEvent())).resolves.toBeUndefined();
256+
257+
expect(engine.insert).toHaveBeenCalledTimes(2);
258+
expect(logger.error).toHaveBeenCalledTimes(1);
259+
expect(String(logger.error.mock.calls[0][0])).toMatch(/^Data-export audit write FAILED/);
260+
expect(logger.debug).toHaveBeenCalledTimes(1);
261+
// The report names the object and the cause — never the export's query.
262+
expect(JSON.stringify([...logger.error.mock.calls, ...logger.debug.mock.calls])).not.toContain(SECRET);
263+
});
264+
265+
it('writes nothing, and says nothing, with no engine to write to', async () => {
266+
const logger = { error: vi.fn(), warn: vi.fn(), debug: vi.fn() };
267+
const writer = createDataExportAuditWriter({ getEngine: () => undefined, logger });
268+
await expect(writer.recordDataExport(exportEvent())).resolves.toBeUndefined();
269+
expect(logger.error).not.toHaveBeenCalled();
270+
});
271+
});

0 commit comments

Comments
 (0)