|
| 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