advisers 0.2.0-preview.71 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,624 @@
1
+ /**
2
+ * Offline verifier for Advisers delivery receipt packs (format v1.1).
3
+ *
4
+ * A receipt pack is a directory produced by buildReceiptPack in lib/evidence.js:
5
+ *
6
+ * manifest.json deliveries (relative path / size / SHA-256), generator
7
+ * environment, verify results, recipient, anchors, evidence
8
+ * README.txt human summary + verification instructions
9
+ * receipt.docx generated delivery receipt (DOCX)
10
+ * SHA256SUMS lowercase sha256 + two spaces + relative path, for every
11
+ * file above and every deliveries/... artifact
12
+ * deliveries/... byte-for-byte copies of the delivered artifacts
13
+ *
14
+ * verifyReceiptPackDir() needs no network and no ~/.advisers database: it reads
15
+ * only the given directory. It detects edits, missing files, extra files,
16
+ * duplicate/unsafe SHA256SUMS entries, bad paths, malformed JSON and schema
17
+ * drift. It cannot detect a forger who rewrites the whole pack and recomputes
18
+ * every checksum — that is what an external signature/anchor would add, and the
19
+ * README must disclose when there is none.
20
+ *
21
+ * The verifier deliberately does not trust manifest.json before SHA256SUMS
22
+ * matches: checksums are verified first, then the manifest schema is checked.
23
+ */
24
+
25
+ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
26
+ import { join, resolve } from 'node:path'
27
+ import {
28
+ MAX_QUOTE_CHARS,
29
+ RECEIPT_DELIVERIES_PREFIX,
30
+ RECEIPT_MANIFEST_FORMAT,
31
+ RECEIPT_MANIFEST_VERSION,
32
+ RECEIPT_REQUIRED_FILES,
33
+ RECEIPT_SHA256SUMS_FILE,
34
+ isUnsafePackPath,
35
+ sha256Hex,
36
+ } from './evidence.js'
37
+
38
+ const MAX_ERRORS = 300
39
+ const SUMS_LINE_RE = /^([0-9a-f]{64}) (.+)$/
40
+ const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/
41
+
42
+ function addError(errors, message) {
43
+ if (errors.length < MAX_ERRORS) errors.push(message)
44
+ else if (errors.length === MAX_ERRORS) errors.push('... too many errors; further details suppressed')
45
+ }
46
+
47
+ function isPlainObject(value) {
48
+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
49
+ }
50
+
51
+ function isSha256Hex(value) {
52
+ return typeof value === 'string' && /^[0-9a-f]{64}$/.test(value)
53
+ }
54
+
55
+ function isIsoDate(value) {
56
+ if (typeof value !== 'string' || !ISO_DATE_RE.test(value)) return false
57
+ const date = new Date(value)
58
+ return !Number.isNaN(date.getTime()) && date.toISOString() === value
59
+ }
60
+
61
+ function isNonNegativeInteger(value) {
62
+ return Number.isInteger(value) && value >= 0
63
+ }
64
+
65
+ /**
66
+ * Parse the strict receipt-pack SHA256SUMS format. SHA256SUMS must not list
67
+ * itself (it cannot contain its own digest).
68
+ *
69
+ * @returns {{entries: Map<string, string>, errors: string[]}}
70
+ */
71
+ export function parseReceiptSums(text) {
72
+ const entries = new Map()
73
+ const errors = []
74
+ if (typeof text !== 'string') {
75
+ addError(errors, 'SHA256SUMS is missing or unreadable')
76
+ return { entries, errors }
77
+ }
78
+ const lines = text.split(/\r?\n/)
79
+ lines.forEach((raw, index) => {
80
+ const lineNumber = index + 1
81
+ if (raw === '') return
82
+ if (raw.trim() !== raw) {
83
+ addError(errors, 'SHA256SUMS line ' + lineNumber + ': leading/trailing whitespace')
84
+ return
85
+ }
86
+ const match = SUMS_LINE_RE.exec(raw)
87
+ if (!match) {
88
+ addError(errors, 'malformed SHA256SUMS line ' + lineNumber + ': ' + raw.slice(0, 80))
89
+ return
90
+ }
91
+ const name = match[2]
92
+ if (name === RECEIPT_SHA256SUMS_FILE) {
93
+ addError(errors, 'SHA256SUMS must not list itself')
94
+ return
95
+ }
96
+ if (isUnsafePackPath(name)) {
97
+ addError(errors, 'unsafe path in SHA256SUMS: ' + name)
98
+ return
99
+ }
100
+ if (entries.has(name)) {
101
+ addError(errors, 'duplicate entry in SHA256SUMS: ' + name)
102
+ return
103
+ }
104
+ entries.set(name, match[1])
105
+ })
106
+ return { entries, errors }
107
+ }
108
+
109
+ function walkPackFiles(root) {
110
+ const files = []
111
+ const errors = []
112
+ const stack = ['']
113
+ while (stack.length) {
114
+ const relativeDir = stack.pop()
115
+ const directory = relativeDir ? join(root, ...relativeDir.split('/')) : root
116
+ let dirents
117
+ try {
118
+ dirents = readdirSync(directory, { withFileTypes: true })
119
+ } catch (error) {
120
+ addError(errors, 'cannot read directory ' + (relativeDir || '.') + ': ' + (error.code || error.message))
121
+ continue
122
+ }
123
+ for (const dirent of dirents) {
124
+ const relativePath = relativeDir ? relativeDir + '/' + dirent.name : dirent.name
125
+ if (dirent.isSymbolicLink()) {
126
+ addError(errors, 'symbolic links are not allowed in a receipt pack: ' + relativePath)
127
+ continue
128
+ }
129
+ if (dirent.isDirectory()) {
130
+ stack.push(relativePath)
131
+ continue
132
+ }
133
+ if (!dirent.isFile()) {
134
+ addError(errors, 'unsupported file type in receipt pack: ' + relativePath)
135
+ continue
136
+ }
137
+ files.push(relativePath)
138
+ }
139
+ }
140
+ files.sort()
141
+ return { files, errors }
142
+ }
143
+
144
+ // --- manifest schema (format v1; keep it in sync with buildReceiptPack) ------
145
+
146
+ function validateGenerator(generator, errors) {
147
+ if (!isPlainObject(generator)) {
148
+ addError(errors, 'schema: manifest.generator must be an object')
149
+ return
150
+ }
151
+ for (const key of ['advisersVersion', 'templateName', 'templateVersion', 'command']) {
152
+ if (!(key in generator)) addError(errors, 'schema: manifest.generator.' + key + ' is missing')
153
+ else if (!(generator[key] === null || typeof generator[key] === 'string')) {
154
+ addError(errors, 'schema: manifest.generator.' + key + ' must be a string or null')
155
+ }
156
+ }
157
+ if (typeof generator.nodeVersion !== 'string' || !generator.nodeVersion) {
158
+ addError(errors, 'schema: manifest.generator.nodeVersion must be a non-empty string')
159
+ }
160
+ if (typeof generator.platform !== 'string' || !generator.platform) {
161
+ addError(errors, 'schema: manifest.generator.platform must be a non-empty string')
162
+ }
163
+ }
164
+
165
+ function validateRecipient(recipient, errors) {
166
+ if (recipient === null) return
167
+ if (!isPlainObject(recipient)) {
168
+ addError(errors, 'schema: manifest.recipient must be null or an object')
169
+ return
170
+ }
171
+ for (const key of ['name', 'email', 'note']) {
172
+ if (!(key in recipient)) addError(errors, 'schema: manifest.recipient.' + key + ' is missing')
173
+ else if (!(recipient[key] === null || typeof recipient[key] === 'string')) {
174
+ addError(errors, 'schema: manifest.recipient.' + key + ' must be a string or null')
175
+ }
176
+ }
177
+ }
178
+
179
+ function validateDelivery(delivery, index, sums, deliveryFiles, errors) {
180
+ const where = 'manifest.deliveries[' + index + ']'
181
+ if (!isPlainObject(delivery)) {
182
+ addError(errors, 'schema: ' + where + ' must be an object')
183
+ return
184
+ }
185
+ if (typeof delivery.id !== 'string' || !delivery.id) addError(errors, 'schema: ' + where + '.id must be a non-empty string')
186
+ if (!('title' in delivery) || !(delivery.title === null || typeof delivery.title === 'string')) {
187
+ addError(errors, 'schema: ' + where + '.title must be a string or null')
188
+ }
189
+ if (!('tool' in delivery) || !(delivery.tool === null || typeof delivery.tool === 'string')) {
190
+ addError(errors, 'schema: ' + where + '.tool must be a string or null')
191
+ }
192
+ if (!('validation' in delivery) || !(delivery.validation === null || typeof delivery.validation === 'string')) {
193
+ addError(errors, 'schema: ' + where + '.validation must be a string or null')
194
+ }
195
+ if (!('createdAt' in delivery) || !(delivery.createdAt === null || isIsoDate(delivery.createdAt))) {
196
+ addError(errors, 'schema: ' + where + '.createdAt must be null or an ISO-8601 UTC timestamp')
197
+ }
198
+ if (!Array.isArray(delivery.files) || delivery.files.length === 0) {
199
+ addError(errors, 'schema: ' + where + '.files must be a non-empty array')
200
+ return
201
+ }
202
+ delivery.files.forEach((file, fileIndex) => {
203
+ const fileWhere = where + '.files[' + fileIndex + ']'
204
+ if (!isPlainObject(file)) {
205
+ addError(errors, 'schema: ' + fileWhere + ' must be an object')
206
+ return
207
+ }
208
+ if (typeof file.path !== 'string' || isUnsafePackPath(file.path)) {
209
+ addError(errors, 'schema: ' + fileWhere + '.path must be a safe relative path')
210
+ return
211
+ }
212
+ if (!file.path.startsWith(RECEIPT_DELIVERIES_PREFIX)) {
213
+ addError(errors, 'schema: ' + fileWhere + '.path must start with ' + RECEIPT_DELIVERIES_PREFIX)
214
+ }
215
+ if (typeof file.name !== 'string' || !file.name) addError(errors, 'schema: ' + fileWhere + '.name must be a non-empty string')
216
+ if (!isNonNegativeInteger(file.size)) addError(errors, 'schema: ' + fileWhere + '.size must be a non-negative integer')
217
+ if (!isSha256Hex(file.sha256)) addError(errors, 'schema: ' + fileWhere + '.sha256 must be 64 lowercase hex characters')
218
+ const listed = sums.get(file.path)
219
+ if (listed === undefined) addError(errors, 'file referenced by manifest is not covered by SHA256SUMS: ' + file.path)
220
+ else if (isSha256Hex(file.sha256) && listed !== file.sha256) {
221
+ addError(errors, 'manifest digest disagrees with SHA256SUMS for ' + file.path)
222
+ }
223
+ if (deliveryFiles.has(file.path)) addError(errors, 'duplicate delivery file path in manifest: ' + file.path)
224
+ else deliveryFiles.set(file.path, file.sha256)
225
+ })
226
+ }
227
+
228
+ function validateVerifyResult(result, where, errors) {
229
+ if (!isPlainObject(result)) {
230
+ addError(errors, 'schema: ' + where + ' must be an object')
231
+ return false
232
+ }
233
+ if (!(result.source === null || typeof result.source === 'string')) addError(errors, 'schema: ' + where + '.source must be a string or null')
234
+ if (typeof result.ok !== 'boolean') addError(errors, 'schema: ' + where + '.ok must be a boolean')
235
+ if (!(result.checkedAt === null || isIsoDate(result.checkedAt))) addError(errors, 'schema: ' + where + '.checkedAt must be null or an ISO-8601 UTC timestamp')
236
+ if (!Array.isArray(result.errors) || result.errors.some((item) => typeof item !== 'string')) {
237
+ addError(errors, 'schema: ' + where + '.errors must be an array of strings')
238
+ }
239
+ if (!Array.isArray(result.checks)) {
240
+ addError(errors, 'schema: ' + where + '.checks must be an array')
241
+ } else {
242
+ result.checks.forEach((check, checkIndex) => {
243
+ const checkWhere = where + '.checks[' + checkIndex + ']'
244
+ if (!isPlainObject(check)) {
245
+ addError(errors, 'schema: ' + checkWhere + ' must be an object')
246
+ return
247
+ }
248
+ if (typeof check.id !== 'string' || !check.id) addError(errors, 'schema: ' + checkWhere + '.id must be a non-empty string')
249
+ if (typeof check.ok !== 'boolean') addError(errors, 'schema: ' + checkWhere + '.ok must be a boolean')
250
+ for (const key of ['severity', 'detail']) {
251
+ if (key in check && typeof check[key] !== 'string') addError(errors, 'schema: ' + checkWhere + '.' + key + ' must be a string')
252
+ }
253
+ if ('skipped' in check && typeof check.skipped !== 'boolean') addError(errors, 'schema: ' + checkWhere + '.skipped must be a boolean')
254
+ })
255
+ }
256
+ if (!(result.summary === null || typeof result.summary === 'string')) addError(errors, 'schema: ' + where + '.summary must be a string or null')
257
+ return result.ok === true
258
+ }
259
+
260
+ function validateAnchor(anchor, index, sums, errors) {
261
+ const where = 'manifest.anchors[' + index + ']'
262
+ if (!isPlainObject(anchor)) {
263
+ addError(errors, 'schema: ' + where + ' must be an object')
264
+ return
265
+ }
266
+ if (typeof anchor.file !== 'string' || isUnsafePackPath(anchor.file)) addError(errors, 'schema: ' + where + '.file must be a safe relative path')
267
+ if (!isSha256Hex(anchor.fileSha256)) addError(errors, 'schema: ' + where + '.fileSha256 must be 64 lowercase hex characters')
268
+ if (typeof anchor.adapterId !== 'string' || !anchor.adapterId) addError(errors, 'schema: ' + where + '.adapterId must be a non-empty string')
269
+ if (!(anchor.issuedAt === null || isIsoDate(anchor.issuedAt))) addError(errors, 'schema: ' + where + '.issuedAt must be null or an ISO-8601 UTC timestamp')
270
+ if (typeof anchor.proof !== 'string' || !anchor.proof.length) addError(errors, 'schema: ' + where + '.proof must be a non-empty string')
271
+ if (typeof anchor.file === 'string' && !isUnsafePackPath(anchor.file)) {
272
+ const listed = sums.get(anchor.file)
273
+ if (listed === undefined) addError(errors, 'anchor file is not covered by SHA256SUMS: ' + anchor.file)
274
+ else if (isSha256Hex(anchor.fileSha256) && listed !== anchor.fileSha256) {
275
+ addError(errors, 'anchor fileSha256 disagrees with SHA256SUMS for ' + anchor.file)
276
+ }
277
+ }
278
+ }
279
+
280
+ function validateEvidenceSource(source, where, errors) {
281
+ if (!isPlainObject(source)) {
282
+ addError(errors, 'schema: ' + where + ' must be an object')
283
+ return
284
+ }
285
+ if (typeof source.sessionId !== 'string') addError(errors, 'schema: ' + where + '.sessionId must be a string')
286
+ if (typeof source.turnId !== 'string') addError(errors, 'schema: ' + where + '.turnId must be a string')
287
+ if (typeof source.quote !== 'string') addError(errors, 'schema: ' + where + '.quote must be a string')
288
+ else {
289
+ if (Array.from(source.quote).length > MAX_QUOTE_CHARS) {
290
+ addError(errors, 'schema: ' + where + '.quote is longer than ' + MAX_QUOTE_CHARS + ' characters')
291
+ }
292
+ if (!isSha256Hex(source.quoteSha256)) addError(errors, 'schema: ' + where + '.quoteSha256 must be 64 lowercase hex characters')
293
+ else if (typeof source.quote === 'string' && sha256Hex(source.quote) !== source.quoteSha256) {
294
+ addError(errors, 'evidence quoteSha256 mismatch at ' + where)
295
+ }
296
+ }
297
+ if (!isNonNegativeInteger(source.quoteChars)) addError(errors, 'schema: ' + where + '.quoteChars must be a non-negative integer')
298
+ else if (typeof source.quote === 'string' && source.quoteChars < Array.from(source.quote).length) {
299
+ addError(errors, 'schema: ' + where + '.quoteChars is smaller than the stored quote')
300
+ }
301
+ if (typeof source.truncated !== 'boolean') addError(errors, 'schema: ' + where + '.truncated must be a boolean')
302
+ if ('turnSeq' in source && !Number.isInteger(source.turnSeq)) addError(errors, 'schema: ' + where + '.turnSeq must be an integer')
303
+ if ('turnRole' in source && typeof source.turnRole !== 'string') addError(errors, 'schema: ' + where + '.turnRole must be a string')
304
+ }
305
+
306
+ function validateEvidenceEntry(entry, index, errors) {
307
+ const where = 'manifest.evidence.entries[' + index + ']'
308
+ if (!isPlainObject(entry)) {
309
+ addError(errors, 'schema: ' + where + ' must be an object')
310
+ return
311
+ }
312
+ if (typeof entry.kind !== 'string' || !entry.kind) addError(errors, 'schema: ' + where + '.kind must be a non-empty string')
313
+ if (typeof entry.id !== 'string') addError(errors, 'schema: ' + where + '.id must be a string')
314
+ if (typeof entry.found !== 'boolean') addError(errors, 'schema: ' + where + '.found must be a boolean')
315
+ if (!Array.isArray(entry.sources)) addError(errors, 'schema: ' + where + '.sources must be an array')
316
+ else entry.sources.forEach((source, sourceIndex) => validateEvidenceSource(source, where + '.sources[' + sourceIndex + ']', errors))
317
+ if (!Array.isArray(entry.missing)) addError(errors, 'schema: ' + where + '.missing must be an array')
318
+ else {
319
+ entry.missing.forEach((item, itemIndex) => {
320
+ const itemWhere = where + '.missing[' + itemIndex + ']'
321
+ if (!isPlainObject(item)) {
322
+ addError(errors, 'schema: ' + itemWhere + ' must be an object')
323
+ return
324
+ }
325
+ if (typeof item.reason !== 'string' || !item.reason) addError(errors, 'schema: ' + itemWhere + '.reason must be a non-empty string')
326
+ for (const key of ['id', 'ref', 'sessionId', 'turnId']) {
327
+ if (key in item && typeof item[key] !== 'string') addError(errors, 'schema: ' + itemWhere + '.' + key + ' must be a string')
328
+ }
329
+ if ('quote' in item) {
330
+ if (typeof item.quote !== 'string') addError(errors, 'schema: ' + itemWhere + '.quote must be a string')
331
+ else {
332
+ if (Array.from(item.quote).length > MAX_QUOTE_CHARS) {
333
+ addError(errors, 'schema: ' + itemWhere + '.quote is longer than ' + MAX_QUOTE_CHARS + ' characters')
334
+ }
335
+ if (!isSha256Hex(item.quoteSha256) || sha256Hex(item.quote) !== item.quoteSha256) {
336
+ addError(errors, 'evidence quoteSha256 mismatch at ' + itemWhere)
337
+ }
338
+ }
339
+ }
340
+ })
341
+ }
342
+ }
343
+
344
+ function validateEvidence(evidence, errors) {
345
+ if (!isPlainObject(evidence)) {
346
+ addError(errors, 'schema: manifest.evidence must be an object')
347
+ return
348
+ }
349
+ if (typeof evidence.format !== 'string' || !evidence.format) addError(errors, 'schema: manifest.evidence.format must be a non-empty string')
350
+ if (!Number.isInteger(evidence.version) || evidence.version < 1) addError(errors, 'schema: manifest.evidence.version must be a positive integer')
351
+ if (!Array.isArray(evidence.entries)) {
352
+ addError(errors, 'schema: manifest.evidence.entries must be an array')
353
+ return
354
+ }
355
+ evidence.entries.forEach((entry, index) => validateEvidenceEntry(entry, index, errors))
356
+ if (evidence.entryCount !== evidence.entries.length) {
357
+ addError(errors, 'schema: manifest.evidence.entryCount must equal the number of entries')
358
+ }
359
+ if (!isNonNegativeInteger(evidence.sourceCount)) addError(errors, 'schema: manifest.evidence.sourceCount must be a non-negative integer')
360
+ if (!isNonNegativeInteger(evidence.missingCount)) addError(errors, 'schema: manifest.evidence.missingCount must be a non-negative integer')
361
+ const actualCounts = {}
362
+ let sourceCount = 0
363
+ let missingCount = 0
364
+ for (const entry of evidence.entries) {
365
+ if (!isPlainObject(entry)) continue
366
+ actualCounts[entry.kind] = (actualCounts[entry.kind] || 0) + 1
367
+ if (Array.isArray(entry.sources)) sourceCount += entry.sources.length
368
+ if (Array.isArray(entry.missing)) missingCount += entry.missing.length
369
+ }
370
+ if (isNonNegativeInteger(evidence.sourceCount) && evidence.sourceCount !== sourceCount) {
371
+ addError(errors, 'schema: manifest.evidence.sourceCount disagrees with the entries')
372
+ }
373
+ if (isNonNegativeInteger(evidence.missingCount) && evidence.missingCount !== missingCount) {
374
+ addError(errors, 'schema: manifest.evidence.missingCount disagrees with the entries')
375
+ }
376
+ if (!isPlainObject(evidence.counts)) {
377
+ addError(errors, 'schema: manifest.evidence.counts must be an object')
378
+ } else {
379
+ let declared = 0
380
+ for (const [kind, value] of Object.entries(actualCounts)) {
381
+ if (evidence.counts[kind] !== value) addError(errors, 'schema: manifest.evidence.counts.' + kind + ' disagrees with the entries')
382
+ }
383
+ for (const value of Object.values(evidence.counts)) {
384
+ if (!isNonNegativeInteger(value)) {
385
+ addError(errors, 'schema: manifest.evidence.counts values must be non-negative integers')
386
+ break
387
+ }
388
+ declared += value
389
+ }
390
+ if (declared !== evidence.entries.length) addError(errors, 'schema: manifest.evidence.counts do not sum to entryCount')
391
+ }
392
+ }
393
+
394
+ function validateReceiptManifest(manifest, sums, errors) {
395
+ if (!isPlainObject(manifest)) {
396
+ addError(errors, 'schema: manifest.json must be a JSON object')
397
+ return
398
+ }
399
+ if (manifest.format !== RECEIPT_MANIFEST_FORMAT) {
400
+ addError(errors, 'schema: manifest.format must be ' + RECEIPT_MANIFEST_FORMAT)
401
+ }
402
+ if (manifest.version !== RECEIPT_MANIFEST_VERSION) {
403
+ addError(errors, 'schema: manifest.version must be ' + RECEIPT_MANIFEST_VERSION)
404
+ }
405
+ if (!isIsoDate(manifest.createdAt)) addError(errors, 'schema: manifest.createdAt must be an ISO-8601 UTC timestamp')
406
+ validateGenerator(manifest.generator, errors)
407
+ validateRecipient(manifest.recipient, errors)
408
+
409
+ const deliveryFiles = new Map()
410
+ if (!Array.isArray(manifest.deliveries) || manifest.deliveries.length === 0) {
411
+ addError(errors, 'schema: manifest.deliveries must be a non-empty array')
412
+ } else {
413
+ const ids = new Set()
414
+ manifest.deliveries.forEach((delivery, index) => {
415
+ if (isPlainObject(delivery) && typeof delivery.id === 'string' && delivery.id) {
416
+ if (ids.has(delivery.id)) addError(errors, 'schema: manifest.deliveries[' + index + '].id is duplicated: ' + delivery.id)
417
+ else ids.add(delivery.id)
418
+ }
419
+ validateDelivery(delivery, index, sums, deliveryFiles, errors)
420
+ })
421
+ }
422
+
423
+ if (!isPlainObject(manifest.receipt)) {
424
+ addError(errors, 'schema: manifest.receipt must be an object')
425
+ } else {
426
+ if (manifest.receipt.path !== 'receipt.docx') addError(errors, 'schema: manifest.receipt.path must be "receipt.docx"')
427
+ if (!isNonNegativeInteger(manifest.receipt.size)) addError(errors, 'schema: manifest.receipt.size must be a non-negative integer')
428
+ if (!isSha256Hex(manifest.receipt.sha256)) addError(errors, 'schema: manifest.receipt.sha256 must be 64 lowercase hex characters')
429
+ const listed = sums.get('receipt.docx')
430
+ if (listed === undefined) addError(errors, 'receipt.docx is not covered by SHA256SUMS')
431
+ else if (isSha256Hex(manifest.receipt.sha256) && listed !== manifest.receipt.sha256) {
432
+ addError(errors, 'manifest digest disagrees with SHA256SUMS for receipt.docx')
433
+ }
434
+ }
435
+
436
+ let expectedStatus = 'not-recorded'
437
+ if (!Array.isArray(manifest.verify)) {
438
+ addError(errors, 'schema: manifest.verify must be an array')
439
+ } else {
440
+ let allOk = true
441
+ manifest.verify.forEach((result, index) => {
442
+ if (isPlainObject(result) && result.ok === true) {
443
+ validateVerifyResult(result, 'manifest.verify[' + index + ']', errors)
444
+ } else {
445
+ allOk = false
446
+ validateVerifyResult(result, 'manifest.verify[' + index + ']', errors)
447
+ }
448
+ })
449
+ if (manifest.verify.length) expectedStatus = allOk ? 'passed' : 'failed'
450
+ }
451
+ if (manifest.verifyStatus !== expectedStatus) {
452
+ addError(errors, 'schema: manifest.verifyStatus is ' + JSON.stringify(manifest.verifyStatus) + ' but the verify array implies ' + JSON.stringify(expectedStatus))
453
+ }
454
+
455
+ if (!Array.isArray(manifest.anchors)) addError(errors, 'schema: manifest.anchors must be an array')
456
+ else manifest.anchors.forEach((anchor, index) => validateAnchor(anchor, index, sums, errors))
457
+
458
+ validateEvidence(manifest.evidence, errors)
459
+
460
+ const expectedFileCount = RECEIPT_REQUIRED_FILES.length + deliveryFiles.size
461
+ if (manifest.fileCount !== expectedFileCount) {
462
+ addError(errors, 'schema: manifest.fileCount is ' + manifest.fileCount + ' but manifest lists ' + expectedFileCount + ' files')
463
+ }
464
+ if (manifest.fileCount !== sums.size) {
465
+ addError(errors, 'schema: manifest.fileCount is ' + manifest.fileCount + ' but SHA256SUMS has ' + sums.size + ' entries')
466
+ }
467
+ for (const required of RECEIPT_REQUIRED_FILES) {
468
+ if (!sums.has(required)) addError(errors, 'SHA256SUMS does not cover ' + required)
469
+ }
470
+ }
471
+
472
+ // --- directory verifier ------------------------------------------------------
473
+
474
+ /**
475
+ * Verify a receipt pack directory offline.
476
+ *
477
+ * @param {string} dir pack directory produced by buildReceiptPack({outDir})
478
+ * @returns {{ok: boolean, errors: string[], warnings: string[], dir: string,
479
+ * fileCount: number, checksumCount: number, files: string[],
480
+ * checksums: Record<string, string>, manifest: object|null}}
481
+ */
482
+ export function verifyReceiptPackDir(dir) {
483
+ const errors = []
484
+ const warnings = []
485
+ const files = []
486
+ const result = {
487
+ ok: false,
488
+ errors,
489
+ warnings,
490
+ dir: String(dir),
491
+ fileCount: 0,
492
+ checksumCount: 0,
493
+ files,
494
+ checksums: {},
495
+ manifest: null,
496
+ }
497
+ let root
498
+ try {
499
+ root = resolve(String(dir))
500
+ } catch (error) {
501
+ addError(errors, 'invalid receipt pack path: ' + (error.message || error))
502
+ return result
503
+ }
504
+ result.dir = root
505
+ if (!existsSync(root)) {
506
+ addError(errors, 'receipt pack directory not found: ' + root)
507
+ return result
508
+ }
509
+ let rootStat
510
+ try {
511
+ rootStat = statSync(root)
512
+ } catch (error) {
513
+ addError(errors, 'cannot stat receipt pack directory: ' + (error.code || error.message))
514
+ return result
515
+ }
516
+ if (!rootStat.isDirectory()) {
517
+ addError(errors, 'receipt pack path is not a directory: ' + root)
518
+ return result
519
+ }
520
+
521
+ const walked = walkPackFiles(root)
522
+ for (const error of walked.errors) addError(errors, error)
523
+ for (const file of walked.files) files.push(file)
524
+ result.fileCount = files.length
525
+ const fileSet = new Set(files)
526
+
527
+ const sumsPath = join(root, RECEIPT_SHA256SUMS_FILE)
528
+ if (!fileSet.has(RECEIPT_SHA256SUMS_FILE)) {
529
+ addError(errors, 'missing file: ' + RECEIPT_SHA256SUMS_FILE)
530
+ return result
531
+ }
532
+ let sumsText
533
+ try {
534
+ sumsText = readFileSync(sumsPath, 'utf8')
535
+ } catch (error) {
536
+ addError(errors, 'cannot read SHA256SUMS: ' + (error.code || error.message))
537
+ return result
538
+ }
539
+ const parsed = parseReceiptSums(sumsText)
540
+ for (const error of parsed.errors) addError(errors, error)
541
+ result.checksumCount = parsed.entries.size
542
+ result.checksums = Object.fromEntries([...parsed.entries.entries()].sort((left, right) => (left[0] < right[0] ? -1 : 1)))
543
+
544
+ for (const required of RECEIPT_REQUIRED_FILES) {
545
+ if (!parsed.entries.has(required)) addError(errors, 'SHA256SUMS does not cover ' + required)
546
+ if (!fileSet.has(required)) addError(errors, 'missing file: ' + required)
547
+ }
548
+ for (const name of parsed.entries.keys()) {
549
+ if (!fileSet.has(name)) addError(errors, 'missing file: ' + name)
550
+ }
551
+ for (const name of fileSet) {
552
+ if (name === RECEIPT_SHA256SUMS_FILE) continue
553
+ if (!parsed.entries.has(name)) addError(errors, 'file not covered by SHA256SUMS: ' + name)
554
+ }
555
+
556
+ for (const [name, expected] of parsed.entries) {
557
+ if (!fileSet.has(name)) continue
558
+ const full = join(root, ...name.split('/'))
559
+ try {
560
+ const actual = sha256Hex(readFileSync(full))
561
+ if (actual !== expected) {
562
+ addError(errors, 'hash mismatch: ' + name + ' (expected ' + expected.slice(0, 12) + '..., computed ' + actual.slice(0, 12) + '...)')
563
+ }
564
+ } catch (error) {
565
+ addError(errors, 'cannot read file ' + name + ': ' + (error.code || error.message))
566
+ }
567
+ }
568
+
569
+ // receipt.docx structural smoke check (never call Office/WPS to verify it).
570
+ if (fileSet.has('receipt.docx')) {
571
+ try {
572
+ const bytes = readFileSync(join(root, 'receipt.docx'))
573
+ if (bytes.length < 4 || bytes[0] !== 0x50 || bytes[1] !== 0x4b) {
574
+ addError(errors, 'receipt.docx is not a ZIP/DOCX file')
575
+ } else if (!bytes.includes(Buffer.from('word/document.xml', 'utf8'))) {
576
+ addError(errors, 'receipt.docx is missing word/document.xml')
577
+ }
578
+ } catch (error) {
579
+ addError(errors, 'cannot read receipt.docx: ' + (error.code || error.message))
580
+ }
581
+ }
582
+
583
+ if (!fileSet.has('manifest.json')) return result
584
+ let manifest = null
585
+ try {
586
+ manifest = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8'))
587
+ } catch (error) {
588
+ addError(errors, 'manifest.json is not valid JSON: ' + (error.message || error))
589
+ return result
590
+ }
591
+ result.manifest = manifest
592
+ validateReceiptManifest(manifest, parsed.entries, errors)
593
+
594
+ // Size statements in the manifest must match the bytes on disk.
595
+ if (isPlainObject(manifest)) {
596
+ const sizeRecords = []
597
+ if (Array.isArray(manifest.deliveries)) {
598
+ for (const delivery of manifest.deliveries) {
599
+ if (isPlainObject(delivery) && Array.isArray(delivery.files)) {
600
+ for (const file of delivery.files) if (isPlainObject(file)) sizeRecords.push(file)
601
+ }
602
+ }
603
+ }
604
+ if (isPlainObject(manifest.receipt)) sizeRecords.push(manifest.receipt)
605
+ for (const record of sizeRecords) {
606
+ if (typeof record.path !== 'string' || isUnsafePackPath(record.path) || !fileSet.has(record.path)) continue
607
+ try {
608
+ const size = statSync(join(root, ...record.path.split('/'))).size
609
+ if (isNonNegativeInteger(record.size) && size !== record.size) {
610
+ addError(errors, 'schema: manifest size disagrees with the file on disk for ' + record.path)
611
+ }
612
+ } catch (error) {
613
+ addError(errors, 'cannot stat ' + record.path + ': ' + (error.code || error.message))
614
+ }
615
+ }
616
+ if (Array.isArray(manifest.anchors) && manifest.anchors.length === 0) {
617
+ warnings.push('pack is not externally anchored: SHA-256 proves internal consistency only')
618
+ }
619
+ if (manifest.verifyStatus === 'not-recorded') warnings.push('no verify results were recorded in this pack')
620
+ }
621
+
622
+ result.ok = errors.length === 0
623
+ return result
624
+ }