advisers 0.3.1 → 0.4.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.
Files changed (48) hide show
  1. package/README-zh.md +13 -15
  2. package/README.md +32 -22
  3. package/THIRD-PARTY-NOTICES.md +1 -1
  4. package/bin/advisers.js +2769 -183
  5. package/index.js +1 -1
  6. package/lib/brief-archive.js +267 -0
  7. package/lib/client-pack.js +1016 -0
  8. package/lib/consent.js +390 -0
  9. package/lib/credentials.js +195 -0
  10. package/lib/customer-read.js +524 -0
  11. package/lib/error-codes.js +516 -7
  12. package/lib/evidence.js +928 -120
  13. package/lib/kb-extract.js +626 -0
  14. package/lib/kb-facts.js +429 -0
  15. package/lib/kb-pages.js +1084 -0
  16. package/lib/kb.js +1036 -0
  17. package/lib/ledger-read.js +109 -1
  18. package/lib/mail-errors.js +46 -0
  19. package/lib/mail-extract.js +351 -0
  20. package/lib/mail-imap.js +446 -0
  21. package/lib/mail-import.js +176 -0
  22. package/lib/mail-parse.js +223 -0
  23. package/lib/mail-store.js +731 -0
  24. package/lib/mail.js +506 -0
  25. package/lib/mcp-server.js +397 -11
  26. package/lib/notify.js +265 -7
  27. package/lib/policy/decision.js +315 -0
  28. package/lib/policy/egress.js +268 -0
  29. package/lib/policy/errors.js +71 -0
  30. package/lib/policy/index.js +99 -0
  31. package/lib/policy/rules.js +468 -0
  32. package/lib/policy/surfaces.js +141 -0
  33. package/lib/receipt-verify.js +283 -26
  34. package/lib/receivables.js +1653 -0
  35. package/lib/scheduler.js +453 -9
  36. package/lib/shell.js +1406 -0
  37. package/lib/source.js +98 -3
  38. package/lib/sqlite.js +501 -49
  39. package/lib/tos/index.js +2 -2
  40. package/lib/tos/manifest.json +6 -6
  41. package/lib/tos/privacy.zh-CN.md +33 -20
  42. package/lib/tos/safety.zh-CN.md +7 -6
  43. package/lib/tos/summary.zh-CN.md +3 -2
  44. package/lib/tos/terms.zh-CN.md +31 -16
  45. package/lib/tui/labels.js +1 -1
  46. package/lib/tui/render.js +1 -1
  47. package/lib/urgency.js +467 -0
  48. package/package.json +4 -4
@@ -0,0 +1,1016 @@
1
+ /**
2
+ * Client status pack v2 - the offline-verifiable directory form of
3
+ * client export (0.4.0; design 48-customer-v2 section 3.5).
4
+ *
5
+ * A pack is a directory produced by exportClientStatusPack:
6
+ *
7
+ * manifest.json format "advisers-client-status-pack", version 1,
8
+ * scope "client", subject {kind,id,name}, generatedAt,
9
+ * counts, verificationBasis "local-checksums-only",
10
+ * files [{path,size,sha256}], generator, fileCount
11
+ * status.md the human status sheet (same content as client export)
12
+ * status.json the machine status payload (client export --json minus the
13
+ * self-referencing out/bytes/sha256 fields)
14
+ * README.txt scope, disclaimer and verification steps
15
+ * SHA256SUMS coreutils format, every pack file except itself
16
+ *
17
+ * 0.4.0 deliberately contains NO receivable/payment amounts. includeReceivables
18
+ * is reserved for 0.4.1 after legal sign-off: buildClientStatusPack accepts the
19
+ * option only when false/undefined and fails closed otherwise. A status.json
20
+ * that carries money-like fields is rejected by both the builder and the
21
+ * verifier, so an accidental client-show receivables block can never leak into
22
+ * an external pack in this format version.
23
+ *
24
+ * verifyClientStatusPackDir() is the independent offline verifier (it shares no
25
+ * code with the delivery-receipt verifier): it needs no network and no
26
+ * ~/.advisers database. It detects edits, missing files, extra files,
27
+ * duplicate/unsafe SHA256SUMS entries, malformed JSON, schema drift and
28
+ * manifest/checksum disagreement. Like the receipt verifier it cannot detect a
29
+ * forger who rewrites the whole pack and recomputes every checksum; the
30
+ * verificationBasis field exists so no surface claims more than internal
31
+ * consistency. bin/advisers.js dispatches evidence verify by
32
+ * manifest.format (see readClientPackManifestHeader).
33
+ *
34
+ * Resource limits mirror the untrusted-receipt-pack contract: a counterparty
35
+ * pack is walked and hashed with hard caps on entries, depth, single-file size,
36
+ * total bytes, SHA256SUMS and manifest/status bodies, so a hostile directory
37
+ * cannot exhaust memory or time before an integrity verdict is produced.
38
+ */
39
+
40
+ import { createHash } from 'node:crypto'
41
+ import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, writeFileSync } from 'node:fs'
42
+ import { dirname, join, resolve } from 'node:path'
43
+
44
+ import { entityError } from './sqlite.js'
45
+
46
+ /* -------------------------------------------------------------------------- */
47
+ /* constants */
48
+ /* -------------------------------------------------------------------------- */
49
+
50
+ const LF = String.fromCharCode(10)
51
+ const BS = String.fromCharCode(92)
52
+
53
+ /** Manifest format string; evidence verify dispatches on this value. */
54
+ export const CLIENT_PACK_MANIFEST_FORMAT = 'advisers-client-status-pack'
55
+ /** Current (and only) manifest version. */
56
+ export const CLIENT_PACK_MANIFEST_VERSION = 1
57
+ /** The pack contains exactly one client's data. */
58
+ export const CLIENT_PACK_SCOPE = 'client'
59
+ /** Offline verification basis: internal consistency + SHA-256 only. */
60
+ export const CLIENT_PACK_VERIFICATION_BASIS = 'local-checksums-only'
61
+ /** Files every status pack must carry (SHA256SUMS covers all of them). */
62
+ export const CLIENT_PACK_REQUIRED_FILES = Object.freeze(['manifest.json', 'status.md', 'status.json', 'README.txt'])
63
+ /** Checksums file name. */
64
+ export const CLIENT_PACK_SHA256SUMS_FILE = 'SHA256SUMS'
65
+ /** Pack files are owner-read/write only. */
66
+ export const CLIENT_PACK_FILE_MODE = 0o600
67
+ /** Pack directory is owner-only. */
68
+ export const CLIENT_PACK_DIR_MODE = 0o700
69
+ /** Stable error code for a pack that exceeds a resource cap. */
70
+ export const CLIENT_PACK_LIMIT_CODE = 'E_CLIENT_PACK_LIMIT'
71
+ /**
72
+ * Resource limits for building and verifying a pack. A received pack is
73
+ * untrusted input; a normal pack is orders of magnitude below every limit.
74
+ */
75
+ export const CLIENT_PACK_LIMIT_DEFAULTS = Object.freeze({
76
+ maxEntries: 1000,
77
+ maxDepth: 6,
78
+ maxFileBytes: 16 * 1024 * 1024,
79
+ maxTotalBytes: 64 * 1024 * 1024,
80
+ maxSumsBytes: 64 * 1024,
81
+ maxManifestBytes: 512 * 1024,
82
+ })
83
+ const LIMIT_LABELS = Object.freeze({
84
+ maxEntries: 'entry count',
85
+ maxDepth: 'directory depth',
86
+ maxFileBytes: 'single file size',
87
+ maxTotalBytes: 'total pack size',
88
+ maxSumsBytes: 'SHA256SUMS size',
89
+ maxManifestBytes: 'manifest size',
90
+ })
91
+ /** Money-like keys a client status pack v1 must never contain. */
92
+ const FORBIDDEN_MONEY_KEYS = Object.freeze([
93
+ 'receivables', 'payments', 'amountMinor', 'amount', 'paidMinor', 'paid',
94
+ 'outstandingMinor', 'outstanding', 'overdueMinor', 'overpaidMinor', 'unmatchedMinor', 'currency',
95
+ ])
96
+ const DISCLAIMER_ZH = '本文件是状态说明,不是对账单、催款函、发票、收据、合同、法律意见或送达证明;本地生成、无签名、未锚定(仅本地自证)。SHA-256 仅用于检测生成后的改动。'
97
+ const DISCLAIMER_EN = 'This is a status summary, not a statement of account, dunning letter, invoice, receipt, contract, legal opinion or proof of delivery. It is generated locally, unsigned and unanchored; SHA-256 only detects edits made after generation.'
98
+
99
+ /* -------------------------------------------------------------------------- */
100
+ /* small helpers */
101
+ /* -------------------------------------------------------------------------- */
102
+
103
+ function packError(message, hint) {
104
+ return entityError('E_CLIENT_PACK_INVALID', message, hint)
105
+ }
106
+
107
+ function isPlainObject(value) {
108
+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
109
+ }
110
+
111
+ function addError(errors, message) {
112
+ if (errors.length < 300) errors.push(message)
113
+ else if (errors.length === 300) errors.push('... too many errors; further details suppressed')
114
+ }
115
+
116
+ function isDateText(value) {
117
+ if (typeof value !== 'string' || !value) return false
118
+ return Number.isFinite(Date.parse(value))
119
+ }
120
+
121
+ function isNonNegativeInteger(value) {
122
+ return typeof value === 'number' && Number.isInteger(value) && value >= 0
123
+ }
124
+
125
+ function sha256Hex(data) {
126
+ return createHash('sha256').update(data).digest('hex')
127
+ }
128
+
129
+ function toBuffer(value) {
130
+ if (typeof value === 'string') return Buffer.from(value, 'utf8')
131
+ if (Buffer.isBuffer(value)) return value
132
+ if (value instanceof Uint8Array) return Buffer.from(value)
133
+ throw packError('client status pack file content must be a string, Buffer or Uint8Array')
134
+ }
135
+
136
+ /** Deterministic JSON text (object keys sorted, two-space indent, trailing LF). */
137
+ function stableStringify(value) {
138
+ return JSON.stringify(canonicalize(value), null, 2) + LF
139
+ }
140
+
141
+ function canonicalize(value) {
142
+ if (Array.isArray(value)) return value.map(canonicalize)
143
+ if (isPlainObject(value)) {
144
+ const out = {}
145
+ for (const key of Object.keys(value).sort()) out[key] = canonicalize(value[key])
146
+ return out
147
+ }
148
+ return value
149
+ }
150
+
151
+ /** Absolute/backslash/traversal path guard; only forward-slash relative paths. */
152
+ export function isUnsafeClientPackPath(name) {
153
+ if (typeof name !== 'string' || !name) return true
154
+ if (name.startsWith('/') || name.startsWith(BS)) return true
155
+ if (name.includes(BS)) return true
156
+ const parts = name.split('/')
157
+ for (const part of parts) {
158
+ if (!part || part === '.' || part === '..') return true
159
+ }
160
+ if (parts.length > 1 && name.endsWith('/')) return true
161
+ const first = parts[0]
162
+ if (first.length === 2 && first.charCodeAt(1) === 58) return true
163
+ return false
164
+ }
165
+
166
+ function isHexLower(value) {
167
+ if (typeof value !== 'string' || value.length !== 64) return false
168
+ for (let i = 0; i < 64; i += 1) {
169
+ const code = value.charCodeAt(i)
170
+ if ((code >= 48 && code <= 57) || (code >= 97 && code <= 102)) continue
171
+ return false
172
+ }
173
+ return true
174
+ }
175
+
176
+ function normalizeLimits(input) {
177
+ const limits = { ...CLIENT_PACK_LIMIT_DEFAULTS }
178
+ if (!isPlainObject(input)) return limits
179
+ for (const key of Object.keys(CLIENT_PACK_LIMIT_DEFAULTS)) {
180
+ if (!(key in input)) continue
181
+ const value = Number(input[key])
182
+ if (Number.isFinite(value) && value > 0) limits[key] = Math.floor(value)
183
+ }
184
+ return limits
185
+ }
186
+
187
+ function makeViolation(limits, limit, actual, file) {
188
+ return { code: CLIENT_PACK_LIMIT_CODE, limit, max: limits[limit], actual, file: file ?? null }
189
+ }
190
+
191
+ function limitMessage(violation) {
192
+ const label = LIMIT_LABELS[violation.limit] ?? violation.limit
193
+ return CLIENT_PACK_LIMIT_CODE + ': client status pack ' + label + ' exceeded the limit ' + violation.max +
194
+ ' (actual ' + violation.actual + (violation.file ? ', first at ' + violation.file : '') + '); refusing to read a pack that could exhaust memory or time.'
195
+ }
196
+
197
+ /** Find the first money-like key in a status payload (depth-capped). */
198
+ function findMoneyField(value, path = '', depth = 0) {
199
+ if (depth > 8) return null
200
+ if (Array.isArray(value)) {
201
+ for (let index = 0; index < value.length; index += 1) {
202
+ const hit = findMoneyField(value[index], path + '[' + index + ']', depth + 1)
203
+ if (hit) return hit
204
+ }
205
+ return null
206
+ }
207
+ if (!isPlainObject(value)) return null
208
+ for (const key of Object.keys(value)) {
209
+ if (FORBIDDEN_MONEY_KEYS.includes(key)) return path ? path + '.' + key : key
210
+ const hit = findMoneyField(value[key], path ? path + '.' + key : key, depth + 1)
211
+ if (hit) return hit
212
+ }
213
+ return null
214
+ }
215
+
216
+ function advisersVersion(options) {
217
+ const supplied = options?.env?.advisersVersion
218
+ if (typeof supplied === 'string' && supplied) return supplied
219
+ try {
220
+ const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
221
+ return typeof pkg.version === 'string' && pkg.version ? pkg.version : null
222
+ } catch {
223
+ return null
224
+ }
225
+ }
226
+
227
+ /* -------------------------------------------------------------------------- */
228
+ /* file map -> manifest/checksums */
229
+ /* -------------------------------------------------------------------------- */
230
+
231
+ function buildSums(fileContents) {
232
+ const names = [...fileContents.keys()].filter((name) => name !== CLIENT_PACK_SHA256SUMS_FILE).sort()
233
+ const lines = []
234
+ for (const name of names) {
235
+ if (isUnsafeClientPackPath(name)) throw packError('unsafe pack path: ' + name)
236
+ const bytes = toBuffer(fileContents.get(name))
237
+ lines.push(sha256Hex(bytes) + ' ' + name)
238
+ }
239
+ return lines.length ? lines.join(LF) + LF : ''
240
+ }
241
+
242
+ function fileRecords(fileContents) {
243
+ const records = []
244
+ for (const name of [...fileContents.keys()].sort()) {
245
+ if (name === CLIENT_PACK_SHA256SUMS_FILE) continue
246
+ const bytes = toBuffer(fileContents.get(name))
247
+ records.push({ path: name, size: bytes.length, sha256: sha256Hex(bytes) })
248
+ }
249
+ return records
250
+ }
251
+
252
+ /* -------------------------------------------------------------------------- */
253
+ /* status markdown fallback */
254
+ /* -------------------------------------------------------------------------- */
255
+
256
+ function renderStatusMarkdown(status) {
257
+ const subject = status?.subject ?? {}
258
+ const lines = [
259
+ '# 客户状态包 · ' + String(subject.name ?? ''),
260
+ '',
261
+ '> 范围:本文件只含客户 ' + String(subject.id ?? '') + '(' + String(subject.name ?? '') + ')的数据;其他客户数据、全局 facts/preferences、对话原文、证据 quote 与备注正文不在本文件内。',
262
+ '> ' + DISCLAIMER_ZH,
263
+ '',
264
+ ]
265
+ const counts = isPlainObject(status?.counts) ? status.counts : {}
266
+ if (Object.keys(counts).length) {
267
+ lines.push('## 概况', '')
268
+ lines.push(Object.keys(counts).sort().map((key) => key + ': ' + String(counts[key])).join(' · '))
269
+ lines.push('')
270
+ }
271
+ if (Array.isArray(status?.timeline) && status.timeline.length) {
272
+ lines.push('## 最近时间线', '')
273
+ for (const item of status.timeline.slice(0, 20)) {
274
+ lines.push('- ' + String(item?.at ?? '') + ' ' + String(item?.kind ?? '') + ' ' + String(item?.title ?? ''))
275
+ }
276
+ lines.push('')
277
+ }
278
+ lines.push('## 边界与校验', '')
279
+ lines.push('- 生成时间:' + String(status?.generatedAt ?? '') + ' · clearance=0 · verificationBasis=' + CLIENT_PACK_VERIFICATION_BASIS)
280
+ lines.push('- ' + DISCLAIMER_EN)
281
+ return lines.join(LF) + LF
282
+ }
283
+
284
+ /* -------------------------------------------------------------------------- */
285
+ /* README */
286
+ /* -------------------------------------------------------------------------- */
287
+
288
+ function renderReadme({ subject, generatedAt, version, counts, fileCount }) {
289
+ const countLines = isPlainObject(counts) && Object.keys(counts).length
290
+ ? Object.keys(counts).sort().map((key) => ' ' + key + ': ' + String(counts[key]))
291
+ : [' (none recorded)']
292
+ return [
293
+ 'Advisers client status pack',
294
+ '===========================',
295
+ '',
296
+ 'Subject: ' + String(subject.name ?? '') + ' (' + String(subject.id ?? '') + ')',
297
+ 'Generated at: ' + generatedAt,
298
+ 'Generator: advisers ' + (version ?? 'unknown'),
299
+ 'Format: ' + CLIENT_PACK_MANIFEST_FORMAT + ' v' + CLIENT_PACK_MANIFEST_VERSION + ' · scope=' + CLIENT_PACK_SCOPE,
300
+ 'Verification basis: ' + CLIENT_PACK_VERIFICATION_BASIS,
301
+ '',
302
+ 'Contents',
303
+ '--------',
304
+ 'manifest.json subject, scope, counts, file list and sha256 of every file',
305
+ 'status.md human-readable status summary',
306
+ 'status.json machine-readable status payload (no self-referencing path/hash)',
307
+ 'README.txt this file',
308
+ 'SHA256SUMS sha256 of every other file in this directory',
309
+ 'File count: ' + fileCount,
310
+ '',
311
+ 'Counts',
312
+ '------',
313
+ ...countLines,
314
+ '',
315
+ 'Scope',
316
+ '-----',
317
+ 'This pack contains data for exactly one client (' + String(subject.id ?? '') + ').',
318
+ 'It does not contain other clients, global facts/preferences, conversation',
319
+ 'transcripts, evidence quotes or note bodies. It does NOT contain receivable',
320
+ 'or payment amounts in 0.4.0: local bookkeeping amounts stay in the local',
321
+ 'database until a later format version is reviewed.',
322
+ '',
323
+ 'Disclaimer',
324
+ '----------',
325
+ DISCLAIMER_ZH,
326
+ DISCLAIMER_EN,
327
+ '',
328
+ 'Verify (offline; no ~/.advisers database needed)',
329
+ '------------------------------------------------',
330
+ '1. advisers evidence verify <this-directory>',
331
+ '2. or with coreutils: cd <this-directory> && sha256sum -c SHA256SUMS',
332
+ '',
333
+ 'The checksums detect edits made after generation. They are not a signature,',
334
+ 'not a trusted timestamp and not notarization: anyone able to rewrite the whole',
335
+ 'pack can recompute them. Offline verification proves that the pack is',
336
+ 'internally consistent; it does not prove who generated it or when.',
337
+ '',
338
+ 'Privacy',
339
+ '-------',
340
+ '- Built locally; no network calls; verification does not open the ledger.',
341
+ '- Contains SHA-256 digests and a bounded status summary; no full ledger dump.',
342
+ '- Deleting this pack does not modify the local ledger or database.',
343
+ ].join(LF) + LF
344
+ }
345
+
346
+ /* -------------------------------------------------------------------------- */
347
+ /* builder */
348
+ /* -------------------------------------------------------------------------- */
349
+
350
+ function normalizeSubject(raw) {
351
+ if (!isPlainObject(raw)) throw packError('a client status pack requires a subject {kind:"client", id, name}')
352
+ if (raw.kind !== 'client') throw packError('client status pack subject kind must be "client"')
353
+ const id = typeof raw.id === 'string' ? raw.id.trim() : ''
354
+ const name = typeof raw.name === 'string' ? raw.name.trim() : ''
355
+ if (!id) throw packError('client status pack subject id is required')
356
+ if (!name) throw packError('client status pack subject name is required')
357
+ if (Array.from(name).length > 200) throw packError('client status pack subject name is too long')
358
+ return { kind: 'client', id, name }
359
+ }
360
+
361
+ /**
362
+ * Build the pack file map in memory (no disk writes, no ~/.advisers access).
363
+ *
364
+ * @param {object} options
365
+ * @param {object} options.status the client export --json payload (client
366
+ * subject, counts, timeline, ...); out/bytes/sha256 are stripped from
367
+ * status.json. Money-like keys are rejected.
368
+ * @param {string} [options.markdown] the status sheet markdown; when omitted a
369
+ * deterministic fallback summary is rendered from status.
370
+ * @param {Buffer|Uint8Array} [options.docx] optional status.docx bytes.
371
+ * @param {string|Date} [options.generatedAt] defaults to now.
372
+ * @param {{advisersVersion?:string, nodeVersion?:string, command?:string}} [options.env]
373
+ * @param {boolean} [options.includeReceivables=false] reserved for 0.4.1; true
374
+ * fails closed in 0.4.0 (legal review pending).
375
+ * @returns {{files: Map<string, Buffer>, manifest: object, manifestText: string,
376
+ * manifestDigest: string, summary: object}}
377
+ */
378
+ export function buildClientStatusPack(options = {}) {
379
+ if (!isPlainObject(options)) throw new TypeError('buildClientStatusPack expects an options object')
380
+ if (options.includeReceivables !== undefined && typeof options.includeReceivables !== 'boolean') {
381
+ throw packError('includeReceivables must be a boolean')
382
+ }
383
+ if (options.includeReceivables === true) {
384
+ throw entityError(
385
+ 'E_CLIENT_PACK_RECEIVABLES_UNSUPPORTED',
386
+ 'client status pack v1 does not include receivable/payment amounts',
387
+ 'amounts stay local in 0.4.0; --include-receivables is reserved until legal review (0.4.1)',
388
+ )
389
+ }
390
+ const statusInput = options.status
391
+ if (!isPlainObject(statusInput)) throw packError('a client status payload (status object) is required')
392
+ const generatedAt = options.generatedAt === undefined || options.generatedAt === null
393
+ ? new Date().toISOString()
394
+ : (options.generatedAt instanceof Date ? options.generatedAt.toISOString() : String(options.generatedAt))
395
+ if (!isDateText(generatedAt)) throw packError('generatedAt must be an ISO date-time')
396
+ const subject = normalizeSubject(options.subject ?? statusInput.subject)
397
+ const counts = isPlainObject(statusInput.counts) ? statusInput.counts : {}
398
+ const version = advisersVersion(options)
399
+ const generator = {
400
+ advisersVersion: version,
401
+ nodeVersion: process.version,
402
+ command: options.env?.command ?? 'client export --pack',
403
+ }
404
+ const statusJson = { ...statusInput }
405
+ delete statusJson.out
406
+ delete statusJson.bytes
407
+ delete statusJson.sha256
408
+ const moneyPath = findMoneyField(statusJson)
409
+ if (moneyPath) {
410
+ throw packError('client status pack v1 must not contain money fields (found "' + moneyPath + '")', 'keep receivable/payment amounts out of export --pack')
411
+ }
412
+ const statusJsonText = stableStringify(statusJson)
413
+ const markdown = typeof options.markdown === 'string' && options.markdown.trim()
414
+ ? (options.markdown.endsWith(LF) ? options.markdown : options.markdown + LF)
415
+ : renderStatusMarkdown({ ...statusJson, generatedAt })
416
+ const fileContents = new Map()
417
+ fileContents.set('status.json', Buffer.from(statusJsonText, 'utf8'))
418
+ fileContents.set('status.md', Buffer.from(markdown, 'utf8'))
419
+ if (options.docx !== undefined && options.docx !== null) {
420
+ fileContents.set('status.docx', toBuffer(options.docx))
421
+ }
422
+ const dataFileCount = fileContents.size
423
+ fileContents.set('README.txt', Buffer.from(renderReadme({
424
+ subject,
425
+ generatedAt,
426
+ version,
427
+ counts,
428
+ fileCount: dataFileCount + 1,
429
+ }), 'utf8'))
430
+ const dataRecords = fileRecords(fileContents)
431
+ const manifest = {
432
+ format: CLIENT_PACK_MANIFEST_FORMAT,
433
+ version: CLIENT_PACK_MANIFEST_VERSION,
434
+ scope: CLIENT_PACK_SCOPE,
435
+ subject,
436
+ generatedAt,
437
+ generator,
438
+ counts,
439
+ verificationBasis: CLIENT_PACK_VERIFICATION_BASIS,
440
+ disclaimer: true,
441
+ fileCount: dataRecords.length,
442
+ files: dataRecords,
443
+ }
444
+ const manifestText = stableStringify(manifest)
445
+ fileContents.set('manifest.json', Buffer.from(manifestText, 'utf8'))
446
+ fileContents.set(CLIENT_PACK_SHA256SUMS_FILE, Buffer.from(buildSums(fileContents), 'utf8'))
447
+ const manifestDigest = sha256Hex(manifestText)
448
+ return {
449
+ files: fileContents,
450
+ manifest,
451
+ manifestText,
452
+ manifestDigest,
453
+ summary: {
454
+ format: CLIENT_PACK_MANIFEST_FORMAT,
455
+ version: CLIENT_PACK_MANIFEST_VERSION,
456
+ scope: CLIENT_PACK_SCOPE,
457
+ subject,
458
+ generatedAt,
459
+ counts,
460
+ verificationBasis: CLIENT_PACK_VERIFICATION_BASIS,
461
+ fileCount: dataRecords.length,
462
+ checksumCount: fileContents.size - 1,
463
+ files: dataRecords,
464
+ manifestDigest,
465
+ includeReceivables: false,
466
+ },
467
+ }
468
+ }
469
+
470
+ /**
471
+ * Write a built pack atomically: staging directory 0700 / files 0600, verify the
472
+ * bytes that reached the disk, then rename into place. A non-empty target is
473
+ * refused unless overwrite is true; when overwriting, the old tree is moved
474
+ * aside (.replaced-<timestamp>) instead of deleted.
475
+ */
476
+ export function writeClientStatusPackDir(outDir, built, options = {}) {
477
+ if (!isPlainObject(built) || !(built.files instanceof Map)) throw new TypeError('writeClientStatusPackDir expects the buildClientStatusPack result')
478
+ if (typeof outDir !== 'string' || !outDir.trim()) throw packError('a pack output directory is required')
479
+ const overwrite = options?.overwrite === true
480
+ const target = resolve(outDir)
481
+ mkdirSync(dirname(target), { recursive: true })
482
+ const fileContents = built.files
483
+ for (const name of fileContents.keys()) {
484
+ if (isUnsafeClientPackPath(name)) throw packError('refusing to write unsafe pack path: ' + name)
485
+ }
486
+ let replaced = null
487
+ if (existsSync(target)) {
488
+ const info = statSync(target)
489
+ if (!info.isDirectory()) throw packError('client status pack output exists and is not a directory: ' + target)
490
+ const entries = readdirSync(target)
491
+ if (entries.length && !overwrite) {
492
+ throw packError('client status pack output directory is not empty: ' + target, 'choose a fresh directory or pass overwrite: true')
493
+ }
494
+ if (entries.length) {
495
+ replaced = target + '.replaced-' + new Date().toISOString().replace(/[:.]/g, '-')
496
+ renameSync(target, replaced)
497
+ } else {
498
+ rmdirSync(target)
499
+ }
500
+ }
501
+ const staging = target + '.tmp-' + process.pid + '-' + createHash('sha256').update(String(Math.random())).digest('hex').slice(0, 8)
502
+ mkdirSync(staging, { recursive: true, mode: CLIENT_PACK_DIR_MODE })
503
+ try { chmodSync(staging, CLIENT_PACK_DIR_MODE) } catch {}
504
+ try {
505
+ for (const path of [...fileContents.keys()].sort()) {
506
+ const bytes = toBuffer(fileContents.get(path))
507
+ const full = join(staging, ...path.split('/'))
508
+ mkdirSync(dirname(full), { recursive: true, mode: CLIENT_PACK_DIR_MODE })
509
+ writeFileSync(full, bytes, { mode: CLIENT_PACK_FILE_MODE })
510
+ try { chmodSync(full, CLIENT_PACK_FILE_MODE) } catch {}
511
+ }
512
+ // Verify what actually reached the disk, not the in-memory strings.
513
+ for (const [path, content] of fileContents) {
514
+ const expected = toBuffer(content)
515
+ const full = join(staging, ...path.split('/'))
516
+ const actual = readFileSync(full)
517
+ if (actual.length !== expected.length) throw packError('written pack file has the wrong size: ' + path)
518
+ if (sha256Hex(actual) !== sha256Hex(expected)) throw packError('written pack file hash mismatch: ' + path)
519
+ if (process.platform !== 'win32' && (statSync(full).mode & 0o777) !== CLIENT_PACK_FILE_MODE) {
520
+ throw packError('written pack file mode is not 0600: ' + path)
521
+ }
522
+ }
523
+ renameSync(staging, target)
524
+ } catch (error) {
525
+ try { rmSync(staging, { recursive: true, force: true }) } catch {}
526
+ if (replaced) {
527
+ try { renameSync(replaced, target) } catch {
528
+ error.message = error.message + ' (previous pack contents are preserved at ' + replaced + ')'
529
+ }
530
+ }
531
+ throw error
532
+ }
533
+ try { chmodSync(target, CLIENT_PACK_DIR_MODE) } catch {}
534
+ return { outDir: target, replaced }
535
+ }
536
+
537
+ /**
538
+ * Build + write + offline-verify a client status pack directory. This is the
539
+ * one call bin/advisers.js needs for 'client export <id> --pack'.
540
+ *
541
+ * @returns {object} JSON summary: format/version/scope/subject/out/generatedAt/
542
+ * fileCount/checksumCount/bytes/manifestDigest/files/verification/replaced
543
+ */
544
+ export function exportClientStatusPack(options = {}) {
545
+ if (!isPlainObject(options)) throw new TypeError('exportClientStatusPack expects an options object')
546
+ if (typeof options.outDir !== 'string' || !options.outDir.trim()) throw packError('outDir is required for exportClientStatusPack')
547
+ const built = buildClientStatusPack(options)
548
+ const written = writeClientStatusPackDir(options.outDir, built, { overwrite: options.overwrite === true })
549
+ const verification = verifyClientStatusPackDir(written.outDir, { limits: options.limits })
550
+ if (!verification.ok) {
551
+ throw packError('written client status pack failed verification: ' + verification.errors.slice(0, 3).join(' | '))
552
+ }
553
+ const totalBytes = [...built.files.values()].reduce((sum, content) => sum + toBuffer(content).length, 0)
554
+ return {
555
+ ok: true,
556
+ format: CLIENT_PACK_MANIFEST_FORMAT,
557
+ version: CLIENT_PACK_MANIFEST_VERSION,
558
+ scope: CLIENT_PACK_SCOPE,
559
+ subject: built.summary.subject,
560
+ out: written.outDir,
561
+ replaced: written.replaced,
562
+ generatedAt: built.summary.generatedAt,
563
+ counts: built.summary.counts,
564
+ verificationBasis: CLIENT_PACK_VERIFICATION_BASIS,
565
+ fileCount: built.summary.fileCount,
566
+ checksumCount: built.summary.checksumCount,
567
+ bytes: totalBytes,
568
+ manifestDigest: built.manifestDigest,
569
+ includeReceivables: false,
570
+ files: built.summary.files.map((record) => ({ path: record.path, size: record.size, sha256: record.sha256 })),
571
+ verification,
572
+ }
573
+ }
574
+
575
+ /* -------------------------------------------------------------------------- */
576
+ /* verifier */
577
+ /* -------------------------------------------------------------------------- */
578
+
579
+ /**
580
+ * Parse the strict coreutils-style SHA256SUMS of a client status pack.
581
+ * Every non-empty line must be 64 lowercase hex + two spaces + safe relative
582
+ * path; SHA256SUMS must not list itself and no path may repeat.
583
+ */
584
+ export function parseClientPackSums(text) {
585
+ const entries = new Map()
586
+ const errors = []
587
+ if (typeof text !== 'string') {
588
+ addError(errors, 'SHA256SUMS is missing or unreadable')
589
+ return { entries, errors }
590
+ }
591
+ const lines = text.split(LF)
592
+ lines.forEach((rawLine, index) => {
593
+ const lineNumber = index + 1
594
+ const line = rawLine.endsWith(String.fromCharCode(13)) ? rawLine.slice(0, -1) : rawLine
595
+ if (line === '') return
596
+ if (line.length < 67 || line.charAt(64) !== ' ' || line.charAt(65) !== ' ') {
597
+ addError(errors, 'malformed SHA256SUMS line ' + lineNumber + ': ' + line.slice(0, 80))
598
+ return
599
+ }
600
+ const digest = line.slice(0, 64)
601
+ const name = line.slice(66)
602
+ if (!isHexLower(digest)) {
603
+ addError(errors, 'malformed SHA256SUMS digest on line ' + lineNumber)
604
+ return
605
+ }
606
+ if (line.trim() !== line) {
607
+ addError(errors, 'SHA256SUMS line ' + lineNumber + ': leading/trailing whitespace')
608
+ return
609
+ }
610
+ if (name === CLIENT_PACK_SHA256SUMS_FILE) {
611
+ addError(errors, 'SHA256SUMS must not list itself')
612
+ return
613
+ }
614
+ if (isUnsafeClientPackPath(name)) {
615
+ addError(errors, 'unsafe path in SHA256SUMS: ' + name)
616
+ return
617
+ }
618
+ if (entries.has(name)) {
619
+ addError(errors, 'duplicate entry in SHA256SUMS: ' + name)
620
+ return
621
+ }
622
+ entries.set(name, digest)
623
+ })
624
+ return { entries, errors }
625
+ }
626
+
627
+ function walkPackFiles(root, limits) {
628
+ const files = []
629
+ const errors = []
630
+ const stack = [{ relativeDir: '', depth: 0 }]
631
+ let entryCount = 0
632
+ let totalBytes = 0
633
+ let violation = null
634
+ const trip = (limit, actual, file) => {
635
+ violation = makeViolation(limits, limit, actual, file)
636
+ addError(errors, limitMessage(violation))
637
+ }
638
+ while (stack.length && !violation) {
639
+ const { relativeDir, depth } = stack.pop()
640
+ const directory = relativeDir ? join(root, ...relativeDir.split('/')) : root
641
+ let entries
642
+ try {
643
+ entries = readdirSync(directory, { withFileTypes: true })
644
+ } catch (error) {
645
+ addError(errors, 'cannot read directory ' + (relativeDir || '.') + ': ' + (error.code || error.message))
646
+ continue
647
+ }
648
+ for (const entry of entries) {
649
+ entryCount += 1
650
+ const relativePath = relativeDir ? relativeDir + '/' + entry.name : entry.name
651
+ if (entryCount > limits.maxEntries) { trip('maxEntries', entryCount, relativePath); break }
652
+ if (entry.isSymbolicLink()) {
653
+ addError(errors, 'symbolic links are not allowed in a client status pack: ' + relativePath)
654
+ continue
655
+ }
656
+ if (entry.isDirectory()) {
657
+ const childDepth = depth + 1
658
+ if (childDepth > limits.maxDepth) { trip('maxDepth', childDepth, relativePath); break }
659
+ stack.push({ relativeDir: relativePath, depth: childDepth })
660
+ continue
661
+ }
662
+ if (!entry.isFile()) {
663
+ addError(errors, 'unsupported file type in client status pack: ' + relativePath)
664
+ continue
665
+ }
666
+ let info
667
+ try {
668
+ info = statSync(join(root, ...relativePath.split('/')))
669
+ } catch (error) {
670
+ addError(errors, 'cannot stat ' + relativePath + ': ' + (error.code || error.message))
671
+ continue
672
+ }
673
+ if (info.size > limits.maxFileBytes) { trip('maxFileBytes', info.size, relativePath); break }
674
+ totalBytes += info.size
675
+ if (totalBytes > limits.maxTotalBytes) { trip('maxTotalBytes', totalBytes, relativePath); break }
676
+ files.push(relativePath)
677
+ }
678
+ }
679
+ if (!violation) files.sort()
680
+ return { files, errors, violation, totalBytes, entryCount }
681
+ }
682
+
683
+ function hashFileWithLimit(file, limits) {
684
+ const hash = createHash('sha256')
685
+ const buffer = Buffer.allocUnsafe(1024 * 1024)
686
+ let bytes = 0
687
+ const fd = openSync(file, 'r')
688
+ try {
689
+ for (;;) {
690
+ const count = readSync(fd, buffer, 0, buffer.length, null)
691
+ if (!count) break
692
+ bytes += count
693
+ if (bytes > limits.maxFileBytes) return { violation: makeViolation(limits, 'maxFileBytes', bytes, null) }
694
+ hash.update(buffer.subarray(0, count))
695
+ }
696
+ } finally {
697
+ try { closeSync(fd) } catch {}
698
+ }
699
+ return { sha256: hash.digest('hex'), bytes }
700
+ }
701
+
702
+ function readBoundedText(file, limits, label) {
703
+ const info = statSync(file)
704
+ if (info.size > limits.maxFileBytes) {
705
+ return { error: limitMessage(makeViolation(limits, 'maxFileBytes', info.size, label)), violation: makeViolation(limits, 'maxFileBytes', info.size, label) }
706
+ }
707
+ return { text: readFileSync(file, 'utf8') }
708
+ }
709
+
710
+ function validateManifest(manifest, fileSet, entries, limits, result, errors, warnings) {
711
+ if (!isPlainObject(manifest)) {
712
+ addError(errors, 'manifest.json must be a JSON object')
713
+ return
714
+ }
715
+ if (manifest.format !== CLIENT_PACK_MANIFEST_FORMAT) addError(errors, 'manifest.format must be "' + CLIENT_PACK_MANIFEST_FORMAT + '"')
716
+ if (manifest.version !== CLIENT_PACK_MANIFEST_VERSION) addError(errors, 'manifest.version must be ' + CLIENT_PACK_MANIFEST_VERSION)
717
+ if (manifest.scope !== CLIENT_PACK_SCOPE) addError(errors, 'manifest.scope must be "' + CLIENT_PACK_SCOPE + '"')
718
+ if (manifest.verificationBasis !== CLIENT_PACK_VERIFICATION_BASIS) addError(errors, 'manifest.verificationBasis must be "' + CLIENT_PACK_VERIFICATION_BASIS + '"')
719
+ if (!isDateText(manifest.generatedAt)) addError(errors, 'manifest.generatedAt must be an ISO date-time')
720
+ if (!isPlainObject(manifest.counts)) addError(errors, 'manifest.counts must be an object')
721
+ if (!isPlainObject(manifest.subject) || manifest.subject.kind !== 'client' || typeof manifest.subject.id !== 'string' || !manifest.subject.id || typeof manifest.subject.name !== 'string' || !manifest.subject.name) {
722
+ addError(errors, 'manifest.subject must be {kind:"client", id, name}')
723
+ }
724
+ if (!Array.isArray(manifest.files)) {
725
+ addError(errors, 'manifest.files must be an array')
726
+ return
727
+ }
728
+ if (!isNonNegativeInteger(manifest.fileCount)) addError(errors, 'manifest.fileCount must be a non-negative integer')
729
+ else if (manifest.fileCount !== manifest.files.length) addError(errors, 'manifest.fileCount does not match manifest.files.length')
730
+ const listed = new Set()
731
+ for (const record of manifest.files) {
732
+ if (!isPlainObject(record)) { addError(errors, 'manifest.files entries must be objects'); continue }
733
+ if (typeof record.path !== 'string' || isUnsafeClientPackPath(record.path)) { addError(errors, 'manifest.files has an unsafe path'); continue }
734
+ if (record.path === CLIENT_PACK_SHA256SUMS_FILE || record.path === 'manifest.json') { addError(errors, 'manifest.files must not list ' + record.path); continue }
735
+ if (listed.has(record.path)) { addError(errors, 'manifest.files lists ' + record.path + ' twice'); continue }
736
+ listed.add(record.path)
737
+ if (!entries.has(record.path)) addError(errors, 'manifest.files lists ' + record.path + ' but SHA256SUMS does not cover it')
738
+ if (!isNonNegativeInteger(record.size)) addError(errors, 'manifest.files size for ' + record.path + ' must be a non-negative integer')
739
+ if (!isHexLower(record.sha256)) addError(errors, 'manifest.files sha256 for ' + record.path + ' must be 64 lowercase hex')
740
+ else if (entries.has(record.path) && entries.get(record.path) !== record.sha256) addError(errors, 'manifest sha256 disagrees with SHA256SUMS for ' + record.path)
741
+ if (fileSet.has(record.path)) {
742
+ try {
743
+ const info = statSync(join(result.dir, ...record.path.split('/')))
744
+ if (isNonNegativeInteger(record.size) && info.size !== record.size) addError(errors, 'manifest size disagrees with the file on disk for ' + record.path)
745
+ } catch (error) {
746
+ addError(errors, 'cannot stat ' + record.path + ': ' + (error.code || error.message))
747
+ }
748
+ }
749
+ }
750
+ for (const name of entries.keys()) {
751
+ if (name === 'manifest.json') continue
752
+ if (!listed.has(name)) addError(errors, 'SHA256SUMS covers ' + name + ' but manifest.files does not list it')
753
+ }
754
+ const expectedChecksums = entries.size - 1
755
+ if (manifest.fileCount !== expectedChecksums) addError(errors, 'manifest.fileCount is ' + manifest.fileCount + ' but SHA256SUMS covers ' + expectedChecksums + ' data file(s)')
756
+ // status.json / status.md are part of the contracted layout.
757
+ for (const required of CLIENT_PACK_REQUIRED_FILES) {
758
+ if (!entries.has(required)) addError(errors, 'SHA256SUMS does not cover ' + required)
759
+ if (!fileSet.has(required)) addError(errors, 'missing file: ' + required)
760
+ }
761
+ // status.json must describe the same subject and must not smuggle money in.
762
+ if (fileSet.has('status.json')) {
763
+ let statusJson = null
764
+ try {
765
+ const read = readBoundedText(join(result.dir, 'status.json'), limits, 'status.json')
766
+ if (read.violation) return read.violation
767
+ statusJson = JSON.parse(read.text)
768
+ } catch (error) {
769
+ addError(errors, 'status.json is not valid JSON: ' + (error.message || error))
770
+ }
771
+ if (isPlainObject(statusJson)) {
772
+ const statusSubject = isPlainObject(statusJson.subject) ? statusJson.subject : null
773
+ if (statusSubject && isPlainObject(manifest.subject)) {
774
+ if (statusSubject.id !== manifest.subject.id) addError(errors, 'status.json subject id disagrees with manifest.subject.id')
775
+ if (typeof statusSubject.kind === 'string' && statusSubject.kind !== manifest.subject.kind) addError(errors, 'status.json subject kind disagrees with manifest.subject.kind')
776
+ } else {
777
+ warnings.push('status.json has no subject block to cross-check against manifest.subject')
778
+ }
779
+ const moneyPath = findMoneyField(statusJson)
780
+ if (moneyPath) addError(errors, 'status.json contains money fields (found "' + moneyPath + '") which format v1 forbids')
781
+ }
782
+ }
783
+ if (fileSet.has('status.md')) {
784
+ try {
785
+ const read = readBoundedText(join(result.dir, 'status.md'), limits, 'status.md')
786
+ if (read.violation) return read.violation
787
+ if (!read.text.trim()) addError(errors, 'status.md is empty')
788
+ } catch (error) {
789
+ addError(errors, 'cannot read status.md: ' + (error.code || error.message))
790
+ }
791
+ }
792
+ if (fileSet.has('README.txt')) {
793
+ try {
794
+ const read = readBoundedText(join(result.dir, 'README.txt'), limits, 'README.txt')
795
+ if (read.violation) return read.violation
796
+ if (!read.text.includes(CLIENT_PACK_SHA256SUMS_FILE)) warnings.push('README.txt does not mention ' + CLIENT_PACK_SHA256SUMS_FILE)
797
+ } catch (error) {
798
+ addError(errors, 'cannot read README.txt: ' + (error.code || error.message))
799
+ }
800
+ }
801
+ return null
802
+ }
803
+
804
+ /**
805
+ * Verify a client status pack directory offline.
806
+ *
807
+ * @param {string} dir pack directory produced by exportClientStatusPack
808
+ * @param {{limits?: Partial<typeof CLIENT_PACK_LIMIT_DEFAULTS>}} [options]
809
+ * @returns {{ok:boolean, code:string|null, errors:string[], warnings:string[],
810
+ * dir:string, format:string|null, version:number|null,
811
+ * subject:object|null, scope:string|null, verificationBasis:string|null,
812
+ * fileCount:number, checksumCount:number, files:string[],
813
+ * checksums:Record<string,string>, manifest:object|null,
814
+ * totalBytes:number, limits:object, limitViolation:object|null}}
815
+ */
816
+ export function verifyClientStatusPackDir(dir, options = {}) {
817
+ const errors = []
818
+ const warnings = []
819
+ const files = []
820
+ const limits = normalizeLimits(options?.limits)
821
+ const result = {
822
+ ok: false,
823
+ code: null,
824
+ errors,
825
+ warnings,
826
+ dir: String(dir),
827
+ format: null,
828
+ version: null,
829
+ subject: null,
830
+ scope: null,
831
+ verificationBasis: null,
832
+ fileCount: 0,
833
+ checksumCount: 0,
834
+ files,
835
+ checksums: {},
836
+ manifest: null,
837
+ totalBytes: 0,
838
+ limits: { ...limits },
839
+ limitViolation: null,
840
+ }
841
+ const failLimit = (violation) => {
842
+ result.code = CLIENT_PACK_LIMIT_CODE
843
+ result.limitViolation = violation
844
+ result.ok = false
845
+ return result
846
+ }
847
+ if (typeof dir !== 'string' || !dir.trim()) {
848
+ addError(errors, 'a client status pack directory is required')
849
+ return result
850
+ }
851
+ let root
852
+ try {
853
+ root = resolve(dir)
854
+ } catch (error) {
855
+ addError(errors, 'invalid client status pack path: ' + (error.message || error))
856
+ return result
857
+ }
858
+ result.dir = root
859
+ if (!existsSync(root)) {
860
+ addError(errors, 'client status pack directory not found: ' + root)
861
+ return result
862
+ }
863
+ let rootStat
864
+ try {
865
+ rootStat = statSync(root)
866
+ } catch (error) {
867
+ addError(errors, 'cannot stat client status pack directory: ' + (error.code || error.message))
868
+ return result
869
+ }
870
+ if (!rootStat.isDirectory()) {
871
+ addError(errors, 'client status pack path is not a directory: ' + root)
872
+ return result
873
+ }
874
+ const walked = walkPackFiles(root, limits)
875
+ for (const error of walked.errors) addError(errors, error)
876
+ for (const file of walked.files) files.push(file)
877
+ result.fileCount = files.length
878
+ result.totalBytes = walked.totalBytes
879
+ if (walked.violation) return failLimit(walked.violation)
880
+ const fileSet = new Set(files)
881
+
882
+ if (!fileSet.has(CLIENT_PACK_SHA256SUMS_FILE)) {
883
+ addError(errors, 'missing file: ' + CLIENT_PACK_SHA256SUMS_FILE)
884
+ return result
885
+ }
886
+ let sumsText
887
+ try {
888
+ const info = statSync(join(root, CLIENT_PACK_SHA256SUMS_FILE))
889
+ if (info.size > limits.maxSumsBytes) {
890
+ const violation = makeViolation(limits, 'maxSumsBytes', info.size, CLIENT_PACK_SHA256SUMS_FILE)
891
+ addError(errors, limitMessage(violation))
892
+ return failLimit(violation)
893
+ }
894
+ sumsText = readFileSync(join(root, CLIENT_PACK_SHA256SUMS_FILE), 'utf8')
895
+ } catch (error) {
896
+ addError(errors, 'cannot read SHA256SUMS: ' + (error.code || error.message))
897
+ return result
898
+ }
899
+ const parsed = parseClientPackSums(sumsText)
900
+ for (const error of parsed.errors) addError(errors, error)
901
+ result.checksumCount = parsed.entries.size
902
+ result.checksums = Object.fromEntries([...parsed.entries.entries()].sort((left, right) => (left[0] < right[0] ? -1 : 1)))
903
+
904
+ for (const required of CLIENT_PACK_REQUIRED_FILES) {
905
+ if (!parsed.entries.has(required)) addError(errors, 'SHA256SUMS does not cover ' + required)
906
+ if (!fileSet.has(required)) addError(errors, 'missing file: ' + required)
907
+ }
908
+ for (const name of parsed.entries.keys()) if (!fileSet.has(name)) addError(errors, 'missing file: ' + name)
909
+ for (const name of fileSet) {
910
+ if (name === CLIENT_PACK_SHA256SUMS_FILE) continue
911
+ if (!parsed.entries.has(name)) addError(errors, 'file not covered by SHA256SUMS: ' + name)
912
+ }
913
+
914
+ let hashedTotal = 0
915
+ for (const [name, expected] of parsed.entries) {
916
+ if (!fileSet.has(name)) continue
917
+ const full = join(root, ...name.split('/'))
918
+ try {
919
+ const hashed = hashFileWithLimit(full, limits)
920
+ if (hashed.violation) {
921
+ hashed.violation.file = name
922
+ addError(errors, limitMessage(hashed.violation))
923
+ return failLimit(hashed.violation)
924
+ }
925
+ hashedTotal += hashed.bytes
926
+ if (hashedTotal > limits.maxTotalBytes) {
927
+ const violation = makeViolation(limits, 'maxTotalBytes', hashedTotal, name)
928
+ addError(errors, limitMessage(violation))
929
+ return failLimit(violation)
930
+ }
931
+ if (hashed.sha256 !== expected) addError(errors, 'hash mismatch: ' + name + ' (expected ' + expected.slice(0, 12) + '..., computed ' + hashed.sha256.slice(0, 12) + '...)')
932
+ } catch (error) {
933
+ addError(errors, 'cannot read file ' + name + ': ' + (error.code || error.message))
934
+ }
935
+ }
936
+
937
+ if (!fileSet.has('manifest.json')) return result
938
+ let manifest = null
939
+ try {
940
+ const info = statSync(join(root, 'manifest.json'))
941
+ if (info.size > limits.maxManifestBytes) {
942
+ const violation = makeViolation(limits, 'maxManifestBytes', info.size, 'manifest.json')
943
+ addError(errors, limitMessage(violation))
944
+ return failLimit(violation)
945
+ }
946
+ manifest = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8'))
947
+ } catch (error) {
948
+ addError(errors, 'manifest.json is not valid JSON: ' + (error.message || error))
949
+ return result
950
+ }
951
+ result.manifest = manifest
952
+ if (isPlainObject(manifest)) {
953
+ result.format = typeof manifest.format === 'string' ? manifest.format : null
954
+ result.version = Number.isInteger(manifest.version) ? manifest.version : null
955
+ result.scope = typeof manifest.scope === 'string' ? manifest.scope : null
956
+ result.verificationBasis = typeof manifest.verificationBasis === 'string' ? manifest.verificationBasis : null
957
+ result.subject = isPlainObject(manifest.subject) ? manifest.subject : null
958
+ }
959
+ const violation = validateManifest(manifest, fileSet, parsed.entries, limits, result, errors, warnings)
960
+ if (violation) return failLimit(violation)
961
+ warnings.push('verification basis is ' + CLIENT_PACK_VERIFICATION_BASIS + ': SHA-256 proves pack internal consistency only, not authorship or generation time')
962
+ result.ok = errors.length === 0
963
+ return result
964
+ }
965
+
966
+ /**
967
+ * Read only manifest.format/version from a directory (bounded). bin/evidence
968
+ * verify uses this to dispatch between the receipt verifier and this pack
969
+ * verifier without trusting the rest of the manifest.
970
+ *
971
+ * @returns {{ok:boolean, format:string|null, version:number|null, error:string|null}}
972
+ */
973
+ export function readClientPackManifestHeader(dir, options = {}) {
974
+ const limits = normalizeLimits(options?.limits)
975
+ const out = { ok: false, format: null, version: null, error: null }
976
+ if (typeof dir !== 'string' || !dir.trim()) { out.error = 'a pack directory is required'; return out }
977
+ let root
978
+ try { root = resolve(dir) } catch { out.error = 'invalid path'; return out }
979
+ if (!existsSync(root)) { out.error = 'directory not found'; return out }
980
+ const manifestPath = join(root, 'manifest.json')
981
+ if (!existsSync(manifestPath)) { out.error = 'manifest.json not found'; return out }
982
+ try {
983
+ const info = statSync(manifestPath)
984
+ if (!info.isFile()) { out.error = 'manifest.json is not a file'; return out }
985
+ if (info.size > limits.maxManifestBytes) { out.error = 'manifest.json exceeds the size limit'; return out }
986
+ const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'))
987
+ if (!isPlainObject(parsed)) { out.error = 'manifest.json is not an object'; return out }
988
+ out.format = typeof parsed.format === 'string' ? parsed.format : null
989
+ out.version = Number.isInteger(parsed.version) ? parsed.version : null
990
+ out.ok = Boolean(out.format)
991
+ return out
992
+ } catch (error) {
993
+ out.error = String(error?.message ?? error)
994
+ return out
995
+ }
996
+ }
997
+
998
+ export default Object.freeze({
999
+ CLIENT_PACK_MANIFEST_FORMAT,
1000
+ CLIENT_PACK_MANIFEST_VERSION,
1001
+ CLIENT_PACK_SCOPE,
1002
+ CLIENT_PACK_VERIFICATION_BASIS,
1003
+ CLIENT_PACK_REQUIRED_FILES,
1004
+ CLIENT_PACK_SHA256SUMS_FILE,
1005
+ CLIENT_PACK_FILE_MODE,
1006
+ CLIENT_PACK_DIR_MODE,
1007
+ CLIENT_PACK_LIMIT_CODE,
1008
+ CLIENT_PACK_LIMIT_DEFAULTS,
1009
+ isUnsafeClientPackPath,
1010
+ buildClientStatusPack,
1011
+ writeClientStatusPackDir,
1012
+ exportClientStatusPack,
1013
+ parseClientPackSums,
1014
+ verifyClientStatusPackDir,
1015
+ readClientPackManifestHeader,
1016
+ })