advisers 0.3.2 → 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.
- package/README-zh.md +13 -14
- package/README.md +32 -23
- package/THIRD-PARTY-NOTICES.md +1 -1
- package/bin/advisers.js +2180 -92
- package/index.js +1 -1
- package/lib/brief-archive.js +267 -0
- package/lib/client-pack.js +1016 -0
- package/lib/consent.js +390 -0
- package/lib/credentials.js +195 -0
- package/lib/error-codes.js +516 -7
- package/lib/evidence.js +697 -113
- package/lib/kb-extract.js +626 -0
- package/lib/kb-facts.js +429 -0
- package/lib/kb-pages.js +1084 -0
- package/lib/kb.js +1036 -0
- package/lib/mail-errors.js +46 -0
- package/lib/mail-extract.js +351 -0
- package/lib/mail-imap.js +446 -0
- package/lib/mail-import.js +176 -0
- package/lib/mail-parse.js +223 -0
- package/lib/mail-store.js +731 -0
- package/lib/mail.js +506 -0
- package/lib/mcp-server.js +196 -10
- package/lib/notify.js +265 -7
- package/lib/policy/decision.js +315 -0
- package/lib/policy/egress.js +268 -0
- package/lib/policy/errors.js +71 -0
- package/lib/policy/index.js +99 -0
- package/lib/policy/rules.js +468 -0
- package/lib/policy/surfaces.js +141 -0
- package/lib/receipt-verify.js +199 -19
- package/lib/receivables.js +1653 -0
- package/lib/scheduler.js +453 -9
- package/lib/shell.js +1406 -0
- package/lib/source.js +98 -3
- package/lib/sqlite.js +366 -49
- package/lib/tos/index.js +2 -2
- package/lib/tos/manifest.json +6 -6
- package/lib/tos/privacy.zh-CN.md +33 -20
- package/lib/tos/safety.zh-CN.md +7 -6
- package/lib/tos/summary.zh-CN.md +3 -2
- package/lib/tos/terms.zh-CN.md +31 -16
- package/lib/urgency.js +467 -0
- 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
|
+
})
|