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,468 @@
1
+ /**
2
+ * Pure policy engine (0.4 subset): evaluate(facts) -> decision.
3
+ *
4
+ * Invariants:
5
+ * - no I/O, no network, no wall-clock reads, no user content: the decision is a
6
+ * deterministic function of the facts only (same facts -> same bytes);
7
+ * - deny > confirm > allow; unknown/unregistered paths fail closed;
8
+ * - reasons never echo quotes, titles or absolute paths: only classes/labels;
9
+ * - effectDigest binds the decision to the exact effect metadata, so a caller
10
+ * cannot get an allow for one recipient/secret level and execute another.
11
+ *
12
+ * The 0.4 subset implements R-P04-01..10 (see POLICY_RULES). Its real threat
13
+ * model is "a new code path forgot to call the gate", not a same-user process
14
+ * that can read HOME / rewrite the source (docs/SECURITY.md #8).
15
+ */
16
+ import { createHash } from 'node:crypto'
17
+
18
+ import { POLICY_CODES, policyCodeFor } from './errors.js'
19
+ import {
20
+ CLEARANCE_ACTIONS,
21
+ DATA_CLASSES,
22
+ EGRESS_ACTIONS,
23
+ PATH_ACTIONS,
24
+ POLICY_ACTIONS,
25
+ POLICY_VERSION,
26
+ RULESET_VERSION,
27
+ SAFETY_REQUIRED_ACTIONS,
28
+ SIDE_EFFECT_ACTIONS,
29
+ TOS_REQUIRED_ACTIONS,
30
+ getSurface,
31
+ normalizeSurface,
32
+ surfaceSupportsAction,
33
+ } from './surfaces.js'
34
+
35
+ /** Rule catalogue (stable ids; docs and tests refer to them). */
36
+ export const POLICY_RULES = Object.freeze([
37
+ Object.freeze({ id: 'R-P04-00', title: 'facts must be well formed (pre-rule, fail closed)' }),
38
+ Object.freeze({ id: 'R-P04-01', title: 'registered surface + action only; not-wired surfaces disabled' }),
39
+ Object.freeze({ id: 'R-P04-02', title: 'current TOS accepted (version/hash match)' }),
40
+ Object.freeze({ id: 'R-P04-03', title: 'egress of a protected matter is blocked' }),
41
+ Object.freeze({ id: 'R-P04-04', title: 'read/export respects per-record clearance' }),
42
+ Object.freeze({ id: 'R-P04-05', title: 'model egress of mail/KB content requires consent' }),
43
+ Object.freeze({ id: 'R-P04-06', title: 'tainted content driving fs/send/exec needs interactive confirmation' }),
44
+ Object.freeze({ id: 'R-P04-07', title: 'side effects require a writable intent/result audit' }),
45
+ Object.freeze({ id: 'R-P04-08', title: 'protected/persistence paths and workspace escapes are blocked' }),
46
+ Object.freeze({ id: 'R-P04-09', title: 'content safety: blocked content denied; missing verdict fails closed' }),
47
+ Object.freeze({ id: 'R-P04-10', title: 'default allow with obligations' }),
48
+ ])
49
+
50
+ /** Keys that make up the effect digest (anything else is ignored on purpose). */
51
+ export const EFFECT_DIGEST_FIELDS = Object.freeze([
52
+ 'surface', 'action', 'path', 'recipient', 'subject', 'provider', 'dataClass', 'recordKind', 'recordSecrecy',
53
+ ])
54
+
55
+ const TRUSTED_PATH_KINDS = Object.freeze(['workspace', 'normal', 'allowed'])
56
+ const DENIED_PATH_KINDS = Object.freeze(['sensitive', 'persistence', 'outside'])
57
+ const PATH_KIND_ALIASES = Object.freeze({
58
+ SENSITIVE_PATH: 'sensitive',
59
+ PERSISTENCE_WRITE: 'persistence',
60
+ OUTSIDE_WORKSPACE: 'outside',
61
+ SYMLINK_ESCAPE: 'outside',
62
+ WORKSPACE_MISMATCH: 'outside',
63
+ sensitive: 'sensitive',
64
+ persistence: 'persistence',
65
+ outside: 'outside',
66
+ workspace: 'workspace',
67
+ normal: 'normal',
68
+ allowed: 'allowed',
69
+ })
70
+
71
+ const CONSENT_DATA_CLASSES = Object.freeze(['mail', 'kb'])
72
+
73
+ function isPlainObject(value) {
74
+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
75
+ }
76
+
77
+ function trimmed(value) {
78
+ return typeof value === 'string' ? value.trim() : ''
79
+ }
80
+
81
+ /** Deterministic JSON: sorted keys at every depth, undefined dropped. */
82
+ export function canonicalJson(value) {
83
+ const normalize = (input) => {
84
+ if (input === undefined) return null
85
+ if (Array.isArray(input)) return input.map(normalize)
86
+ if (input && typeof input === 'object') {
87
+ const out = {}
88
+ for (const key of Object.keys(input).sort()) {
89
+ if (input[key] === undefined) continue
90
+ out[key] = normalize(input[key])
91
+ }
92
+ return out
93
+ }
94
+ if (typeof input === 'number' && !Number.isFinite(input)) return null
95
+ return input
96
+ }
97
+ return JSON.stringify(normalize(value))
98
+ }
99
+
100
+ function sha256Hex(text) {
101
+ return createHash('sha256').update(text, 'utf8').digest('hex')
102
+ }
103
+
104
+ function effectField(effect, key) {
105
+ if (!isPlainObject(effect)) return undefined
106
+ if (key === 'path') {
107
+ const path = effect.path
108
+ if (typeof path === 'string') return path
109
+ if (isPlainObject(path)) return typeof path.kind === 'string' ? path.kind : undefined
110
+ return undefined
111
+ }
112
+ if (key === 'recordKind' || key === 'recordSecrecy') {
113
+ const record = isPlainObject(effect.record) ? effect.record : null
114
+ if (record) return record[key === 'recordKind' ? 'kind' : 'secrecy']
115
+ return effect[key]
116
+ }
117
+ return effect[key]
118
+ }
119
+
120
+ /**
121
+ * SHA-256 over the canonical effect metadata: surface, action, path class,
122
+ * recipient, subject, provider, dataClass, record kind/secrecy. Callers pass
123
+ * the same object to consumeDecision(); unknown keys are ignored.
124
+ */
125
+ export function effectDigestOf(effect) {
126
+ const payload = {}
127
+ for (const key of EFFECT_DIGEST_FIELDS) {
128
+ const value = effectField(effect, key)
129
+ if (value === undefined || value === null || value === '') continue
130
+ payload[key] = value
131
+ }
132
+ return 'sha256:' + sha256Hex(canonicalJson(payload))
133
+ }
134
+
135
+ function normalizePathFact(raw) {
136
+ if (raw === undefined || raw === null || raw === '') return { path: null }
137
+ let kind = ''
138
+ let legacyCode = ''
139
+ if (typeof raw === 'string') {
140
+ kind = raw
141
+ } else if (isPlainObject(raw)) {
142
+ kind = typeof raw.kind === 'string' ? raw.kind : ''
143
+ legacyCode = trimmed(raw.code ?? raw.legacyCode)
144
+ if (!kind && legacyCode) kind = legacyCode
145
+ } else {
146
+ return { error: 'path must be a classification string or {kind}' }
147
+ }
148
+ const canonical = PATH_KIND_ALIASES[kind] ?? PATH_KIND_ALIASES[trimmed(kind)] ?? null
149
+ if (!canonical) return { error: 'unknown path classification "' + trimmed(kind).slice(0, 40) + '"' }
150
+ const path = { kind: canonical }
151
+ if (legacyCode) path.code = legacyCode.slice(0, 40)
152
+ return { path }
153
+ }
154
+
155
+ function normalizeRecordFact(raw) {
156
+ if (raw === undefined || raw === null) return { record: null }
157
+ if (!isPlainObject(raw)) return { error: 'record must be an object or null' }
158
+ let secrecy = 0
159
+ if (raw.secrecy !== undefined && raw.secrecy !== null) {
160
+ const value = Number(raw.secrecy)
161
+ secrecy = Number.isFinite(value) ? value : Number.POSITIVE_INFINITY
162
+ }
163
+ const kind = trimmed(raw.kind) || 'record'
164
+ return { record: { kind: kind.slice(0, 40), secrecy } }
165
+ }
166
+
167
+ function normalizeTosFact(raw) {
168
+ if (raw === undefined || raw === null) return { tos: null }
169
+ if (!isPlainObject(raw)) return { error: 'tos must be an object or null' }
170
+ const tos = {
171
+ accepted: raw.accepted === true,
172
+ version: trimmed(raw.version),
173
+ currentVersion: trimmed(raw.currentVersion),
174
+ hashOk: raw.hashOk === undefined || raw.hashOk === null ? null : raw.hashOk === true,
175
+ }
176
+ return { tos }
177
+ }
178
+
179
+ function normalizeConsentFact(raw) {
180
+ if (raw === undefined || raw === null) return { consent: null }
181
+ if (!isPlainObject(raw)) return { error: 'consent must be an object or null' }
182
+ return {
183
+ consent: {
184
+ dataClass: trimmed(raw.dataClass),
185
+ provider: trimmed(raw.provider),
186
+ baseUrl: trimmed(raw.baseUrl),
187
+ granted: raw.granted === true,
188
+ surface: trimmed(raw.surface),
189
+ revoked: raw.revokedAt !== undefined && raw.revokedAt !== null && trimmed(raw.revokedAt) !== '',
190
+ },
191
+ }
192
+ }
193
+
194
+ function normalizeSafetyFact(raw) {
195
+ if (raw === undefined || raw === null) return { safety: null }
196
+ if (isPlainObject(raw)) {
197
+ const action = trimmed(raw.action).toLowerCase()
198
+ if (!action) return { error: 'safety.action is required' }
199
+ return { safety: { action } }
200
+ }
201
+ if (typeof raw === 'string') return { safety: { action: raw.trim().toLowerCase() } }
202
+ return { error: 'safety must be an object or null' }
203
+ }
204
+
205
+ function normalizeAuditFact(raw) {
206
+ if (raw === undefined || raw === null) return { audit: null }
207
+ if (!isPlainObject(raw)) return { error: 'audit must be an object or null' }
208
+ return { audit: { available: raw.available === true } }
209
+ }
210
+
211
+ function normalizeTrustFact(raw) {
212
+ if (raw === undefined || raw === null) return { trust: null }
213
+ if (!isPlainObject(raw)) return { error: 'trust must be an object or null' }
214
+ const kinds = Array.isArray(raw.sourceKinds) ? raw.sourceKinds.filter((item) => typeof item === 'string').slice(0, 20) : []
215
+ return { trust: { tainted: raw.tainted === true, sourceKinds: kinds } }
216
+ }
217
+
218
+ function normalizeDataClass(raw, surfaceRow) {
219
+ const explicit = trimmed(raw)
220
+ if (explicit) return DATA_CLASSES.includes(explicit) ? explicit : { error: 'unknown dataClass' }
221
+ return surfaceRow ? surfaceRow.dataClass : 'unknown'
222
+ }
223
+
224
+ /**
225
+ * Validate/normalise facts. Structural problems are returned as errors (the
226
+ * caller converts them into a fail-closed deny); they are never guessed away.
227
+ */
228
+ export function canonicalFacts(input) {
229
+ const errors = []
230
+ if (!isPlainObject(input)) return { ok: false, errors: ['facts must be an object'], facts: null }
231
+ if (input.v !== undefined && input.v !== 1) errors.push('facts.v must be 1')
232
+ const surfaceRaw = input.surface
233
+ if (typeof surfaceRaw !== 'string' || !surfaceRaw.trim()) errors.push('surface is required')
234
+ const surface = normalizeSurface(surfaceRaw)
235
+ const action = trimmed(input.action)
236
+ if (!action) errors.push('action is required')
237
+ const surfaceRow = surface ? getSurface(surface) : null
238
+ const dataClass = normalizeDataClass(input.dataClass, surfaceRow)
239
+ if (isPlainObject(dataClass)) errors.push(dataClass.error)
240
+ const record = normalizeRecordFact(input.record)
241
+ if (record.error) errors.push(record.error)
242
+ const tos = normalizeTosFact(input.tos)
243
+ if (tos.error) errors.push(tos.error)
244
+ const consent = normalizeConsentFact(input.consent)
245
+ if (consent.error) errors.push(consent.error)
246
+ const safety = normalizeSafetyFact(input.safety)
247
+ if (safety.error) errors.push(safety.error)
248
+ const audit = normalizeAuditFact(input.audit)
249
+ if (audit.error) errors.push(audit.error)
250
+ const trust = normalizeTrustFact(input.trust)
251
+ if (trust.error) errors.push(trust.error)
252
+ const path = normalizePathFact(input.path)
253
+ if (path.error) errors.push(path.error)
254
+ let clearance = 0
255
+ if (input.clearance !== undefined && input.clearance !== null) {
256
+ clearance = Number(input.clearance)
257
+ if (!Number.isFinite(clearance) || clearance < 0) errors.push('clearance must be a non-negative number')
258
+ }
259
+ if (errors.length) return { ok: false, errors, facts: null }
260
+ return {
261
+ ok: true,
262
+ errors: [],
263
+ facts: {
264
+ v: 1,
265
+ surface: surface || trimmed(surfaceRaw).toLowerCase().slice(0, 60),
266
+ surfaceRegistered: Boolean(surface),
267
+ action: action.slice(0, 60),
268
+ actor: trimmed(input.actor) || 'cli',
269
+ interactive: input.interactive === true,
270
+ confirmed: input.confirmed === true,
271
+ dataClass: isPlainObject(dataClass) ? 'unknown' : dataClass,
272
+ record: record.record,
273
+ clearance,
274
+ path: path.path,
275
+ safety: safety.safety,
276
+ tos: tos.tos,
277
+ consent: consent.consent,
278
+ audit: audit.audit,
279
+ trust: trust.trust,
280
+ },
281
+ }
282
+ }
283
+
284
+ function hit(ruleId, severity, policyCode, reason, extra) {
285
+ const entry = POLICY_CODES[policyCode]
286
+ const out = {
287
+ ruleId,
288
+ severity,
289
+ policyCode,
290
+ code: entry ? entry.code : policyCodeFor(policyCode),
291
+ reason,
292
+ }
293
+ if (extra && typeof extra === 'object') Object.assign(out, extra)
294
+ return out
295
+ }
296
+
297
+ const OBLIGATION_ORDER = Object.freeze(['audit.intent', 'audit.result', 'consent.record', 'confirm'])
298
+
299
+ function collectHits(facts) {
300
+ const hits = []
301
+ const row = facts.surfaceRegistered ? getSurface(facts.surface) : null
302
+
303
+ // R-P04-01: registered surface + declared action; not-wired surfaces stay off.
304
+ if (!row) {
305
+ hits.push(hit('R-P04-01', 'deny', 'POLICY_UNKNOWN_SURFACE', 'surface is not registered in the policy surface registry'))
306
+ } else if (!surfaceSupportsAction(row.surface, facts.action)) {
307
+ hits.push(hit('R-P04-01', 'deny', 'POLICY_UNKNOWN_SURFACE', 'action is not declared for surface ' + row.surface))
308
+ } else if (row.gate === 'not-wired') {
309
+ hits.push(hit('R-P04-01', 'deny', 'POLICY_SURFACE_NOT_ENABLED', 'surface ' + row.surface + ' is registered but not wired/enabled in this release'))
310
+ }
311
+
312
+ // R-P04-02: TOS acceptance facts (E_TOS_REQUIRED keeps exit 3).
313
+ if (TOS_REQUIRED_ACTIONS.includes(facts.action)) {
314
+ const tos = facts.tos
315
+ if (!tos || tos.accepted !== true) {
316
+ hits.push(hit('R-P04-02', 'deny', 'POLICY_TOS_REQUIRED', 'the current terms of service have not been accepted'))
317
+ } else if (tos.version && tos.currentVersion && tos.version !== tos.currentVersion) {
318
+ hits.push(hit('R-P04-02', 'deny', 'POLICY_TOS_REQUIRED', 'the accepted terms version does not match the current version'))
319
+ } else if (tos.hashOk === false) {
320
+ hits.push(hit('R-P04-02', 'deny', 'POLICY_TOS_REQUIRED', 'the accepted terms text hash does not match the packaged text'))
321
+ }
322
+ }
323
+
324
+ // R-P04-03: no egress from a protected matter (per-item secrecy).
325
+ if (EGRESS_ACTIONS.includes(facts.action) && facts.record && facts.record.secrecy > 0) {
326
+ hits.push(hit('R-P04-03', 'deny', 'POLICY_SECRECY_BLOCKED', 'egress of a record from a protected matter is blocked'))
327
+ }
328
+
329
+ // R-P04-04: read/export clearance.
330
+ if (CLEARANCE_ACTIONS.includes(facts.action) && facts.record && facts.record.secrecy > facts.clearance) {
331
+ hits.push(hit('R-P04-04', 'deny', 'POLICY_SECRECY_BLOCKED', 'record secrecy is above the requested clearance'))
332
+ }
333
+
334
+ // R-P04-05: model egress of mail/KB content requires a consent record.
335
+ if (facts.action === 'model-egress' && CONSENT_DATA_CLASSES.includes(facts.dataClass)) {
336
+ const consent = facts.consent
337
+ if (!consent || consent.granted !== true || consent.revoked) {
338
+ hits.push(hit('R-P04-05', 'deny', 'POLICY_CONSENT_REQUIRED', 'model egress of ' + facts.dataClass + ' content requires an explicit consent record'))
339
+ } else if (consent.dataClass && consent.dataClass !== facts.dataClass) {
340
+ hits.push(hit('R-P04-05', 'deny', 'POLICY_CONSENT_REQUIRED', 'consent data class does not match the content being sent'))
341
+ } else if (!consent.provider) {
342
+ hits.push(hit('R-P04-05', 'deny', 'POLICY_CONSENT_REQUIRED', 'consent record does not name the model provider'))
343
+ } else if (consent.surface && row && consent.surface !== row.surface) {
344
+ hits.push(hit('R-P04-05', 'deny', 'POLICY_CONSENT_REQUIRED', 'consent was granted for a different surface'))
345
+ }
346
+ }
347
+
348
+ // R-P04-06: tainted content must not drive fs/send/exec without confirmation.
349
+ if (facts.trust && facts.trust.tainted && ['write-fs', 'send', 'exec'].includes(facts.action)) {
350
+ if (!facts.interactive) {
351
+ hits.push(hit('R-P04-06', 'deny', 'POLICY_CONFIRMATION_UNAVAILABLE', 'untrusted content would drive a side effect and no interactive confirmation is available'))
352
+ } else if (!facts.confirmed) {
353
+ hits.push(hit('R-P04-06', 'confirm', 'POLICY_CONFIRMATION_UNAVAILABLE', 'untrusted content would drive a side effect; interactive confirmation is required'))
354
+ }
355
+ }
356
+
357
+ // R-P04-07: side effects need a writable audit channel (fail closed).
358
+ if (SIDE_EFFECT_ACTIONS.includes(facts.action) && !(facts.audit && facts.audit.available === true)) {
359
+ hits.push(hit('R-P04-07', 'deny', 'POLICY_AUDIT_UNAVAILABLE', 'the intent/result audit is unavailable; refusing the side effect'))
360
+ }
361
+
362
+ // R-P04-08: path classification.
363
+ if (facts.path) {
364
+ if (facts.path.kind === 'sensitive' || facts.path.kind === 'persistence') {
365
+ hits.push(hit('R-P04-08', 'deny', 'POLICY_PROTECTED_PATH', 'the target path is a protected or persistence location', { legacyCode: facts.path.code || undefined }))
366
+ } else if (facts.path.kind === 'outside') {
367
+ hits.push(hit('R-P04-08', 'deny', 'POLICY_WORKSPACE_ESCAPE', 'the target path escapes the workspace boundary', { legacyCode: facts.path.code || undefined }))
368
+ }
369
+ } else if (PATH_ACTIONS.includes(facts.action)) {
370
+ hits.push(hit('R-P04-08', 'deny', 'POLICY_INVALID_FACTS', 'this action requires a path classification fact'))
371
+ }
372
+
373
+ // R-P04-09: content safety.
374
+ if (facts.safety && (facts.safety.action === 'block' || facts.safety.action === 'blocked')) {
375
+ hits.push(hit('R-P04-09', 'deny', 'POLICY_CONTENT_SAFETY_BLOCKED', 'the content safety classifier blocked the content'))
376
+ } else if (SAFETY_REQUIRED_ACTIONS.includes(facts.action) && !facts.safety) {
377
+ hits.push(hit('R-P04-09', 'deny', 'POLICY_SAFETY_REQUIRED', 'a content-safety verdict is required before this action but was not supplied'))
378
+ } else if (facts.safety && facts.safety.action !== 'allow') {
379
+ hits.push(hit('R-P04-09', 'deny', 'POLICY_SAFETY_REQUIRED', 'the content-safety verdict is not a recognised allow'))
380
+ }
381
+
382
+ return hits
383
+ }
384
+
385
+ function obligationsFor(facts, decision) {
386
+ const obligations = new Set()
387
+ if (decision === 'confirm') obligations.add('confirm')
388
+ if (decision === 'allow') {
389
+ if (SIDE_EFFECT_ACTIONS.includes(facts.action)) {
390
+ obligations.add('audit.intent')
391
+ obligations.add('audit.result')
392
+ }
393
+ if (facts.action === 'model-egress' && CONSENT_DATA_CLASSES.includes(facts.dataClass)) obligations.add('consent.record')
394
+ }
395
+ return OBLIGATION_ORDER.filter((item) => obligations.has(item))
396
+ }
397
+
398
+ function refused(facts, decision, hits, extra) {
399
+ const ordered = [...hits].sort((a, b) => a.ruleId.localeCompare(b.ruleId))
400
+ const decisive =
401
+ decision === 'deny'
402
+ ? ordered.find((item) => item.severity === 'deny')
403
+ : decision === 'confirm'
404
+ ? ordered.find((item) => item.severity === 'confirm')
405
+ : null
406
+ return {
407
+ v: 1,
408
+ policyVersion: POLICY_VERSION,
409
+ rulesetVersion: RULESET_VERSION,
410
+ surface: facts.surface,
411
+ action: facts.action,
412
+ dataClass: facts.dataClass,
413
+ decision,
414
+ code: decisive ? decisive.code : null,
415
+ policyCode: decisive ? decisive.policyCode : null,
416
+ ruleIds: ordered.map((item) => item.ruleId),
417
+ obligations: obligationsFor(facts, decision),
418
+ reason: decisive ? decisive.reason : 'allowed by policy',
419
+ effectDigest: effectDigestOf({
420
+ surface: facts.surface,
421
+ action: facts.action,
422
+ path: facts.path,
423
+ dataClass: facts.dataClass,
424
+ record: facts.record,
425
+ }),
426
+ ...(extra && typeof extra === 'object' ? extra : {}),
427
+ }
428
+ }
429
+
430
+ /**
431
+ * Evaluate policy facts. Pure and total: malformed facts produce a deny, never
432
+ * an exception. The result is JSON-ready and contains no user content.
433
+ *
434
+ * @param {object} facts see lib/policy/README-equivalent header docs in docs/ARCHITECTURE.md
435
+ * @returns {{v: 1, decision: 'allow'|'confirm'|'deny', code: string|null,
436
+ * policyCode: string|null, ruleIds: string[], obligations: string[],
437
+ * reason: string, effectDigest: string, surface: string, action: string,
438
+ * dataClass: string, policyVersion: number, rulesetVersion: string}}
439
+ */
440
+ export function evaluate(facts) {
441
+ const normalized = canonicalFacts(facts)
442
+ if (!normalized.ok) {
443
+ const surface = isPlainObject(facts) && typeof facts.surface === 'string' ? facts.surface.slice(0, 60) : 'unknown'
444
+ const action = isPlainObject(facts) && typeof facts.action === 'string' ? facts.action.slice(0, 60) : 'unknown'
445
+ return {
446
+ v: 1,
447
+ policyVersion: POLICY_VERSION,
448
+ rulesetVersion: RULESET_VERSION,
449
+ surface,
450
+ action,
451
+ dataClass: 'unknown',
452
+ decision: 'deny',
453
+ code: policyCodeFor('POLICY_INVALID_FACTS'),
454
+ policyCode: 'POLICY_INVALID_FACTS',
455
+ ruleIds: ['R-P04-00'],
456
+ obligations: [],
457
+ reason: 'policy facts are malformed: ' + normalized.errors.slice(0, 3).join('; '),
458
+ effectDigest: effectDigestOf({ surface, action }),
459
+ }
460
+ }
461
+ const hits = collectHits(normalized.facts)
462
+ const denied = hits.find((item) => item.severity === 'deny')
463
+ if (denied) return refused(normalized.facts, 'deny', hits)
464
+ const needsConfirm = hits.find((item) => item.severity === 'confirm')
465
+ if (needsConfirm) return refused(normalized.facts, 'confirm', hits)
466
+ const allowHit = hit('R-P04-10', 'allow', null, 'allowed by policy')
467
+ return refused(normalized.facts, 'allow', [allowHit])
468
+ }
@@ -0,0 +1,141 @@
1
+ /**
2
+ * Policy surface registry (0.4 subset).
3
+ *
4
+ * The 0.2/0.3 "six surfaces" list in docs/ARCHITECTURE.md is a design sketch;
5
+ * 0.4 ships a registry instead, because mail/KB/TUI/notify add data surfaces and
6
+ * a matrix must be generated, never hand-maintained. Every row records the
7
+ * honest gate state for that surface in 0.4:
8
+ *
9
+ * enforced-policy goes through lib/policy evaluate()/authorize()
10
+ * legacy-gate pre-0.4 gate only (active-matter egress, TOS, clearance)
11
+ * self-attested local-only path with no egress; the docs claim no more
12
+ * not-wired registered but not enabled in 0.4 (default off)
13
+ *
14
+ * Modules are pure data: no I/O, no network, no timestamps. lib/policy/index.js
15
+ * publishes surfaceMatrix() for `privacy --matrix` and for docs/contract gates.
16
+ */
17
+
18
+ export const POLICY_VERSION = 1
19
+ export const RULESET_VERSION = '2026.11.4'
20
+
21
+ /** Gate states; kept in sync with docs/ARCHITECTURE.md and SECURITY.md rows. */
22
+ export const SURFACE_GATES = Object.freeze(['enforced-policy', 'legacy-gate', 'self-attested', 'not-wired'])
23
+
24
+ /** Default enablement of a surface in 0.4. */
25
+ export const SURFACE_DEFAULTS = Object.freeze(['on', 'off'])
26
+
27
+ /**
28
+ * One row per surface.
29
+ *
30
+ * actions canonical policy actions the surface may request
31
+ * dataClass the most sensitive data class the surface can carry
32
+ * sink where data can leave the process ('none' for read-only)
33
+ * default on = usable after the normal gates; off = requires an explicit
34
+ * local enablement (consent entry / config flag)
35
+ * gate honest wiring state in 0.4 (see header)
36
+ * tosRef clause covering this surface (docs/TOS.md)
37
+ * doc user-facing documentation
38
+ */
39
+ export const SURFACE_REGISTRY = Object.freeze([
40
+ Object.freeze({ surface: 'chat', description: 'interactive model chat', actions: Object.freeze(['model-egress']), dataClass: 'conversation', sink: 'model', default: 'on', gate: 'legacy-gate', tosRef: 'docs/TOS.md#9.3', doc: 'docs/ARCHITECTURE.md' }),
41
+ Object.freeze({ surface: 'capture', description: 'model-assisted candidate extraction', actions: Object.freeze(['model-egress']), dataClass: 'conversation', sink: 'model', default: 'on', gate: 'legacy-gate', tosRef: 'docs/TOS.md#9.3', doc: 'docs/SOURCE-SCHEMA.md' }),
42
+ Object.freeze({ surface: 'research', description: 'web research via the configured model', actions: Object.freeze(['model-egress']), dataClass: 'conversation', sink: 'model', default: 'on', gate: 'legacy-gate', tosRef: 'docs/TOS.md#9.3', doc: 'docs/ARCHITECTURE.md' }),
43
+ Object.freeze({ surface: 'agent', description: 'agent tool loop (read/write/exec)', actions: Object.freeze(['read', 'write-fs', 'write-ledger', 'exec', 'model-egress']), dataClass: 'tool', sink: 'spawn', default: 'on', gate: 'legacy-gate', tosRef: 'docs/TOS.md#5', doc: 'docs/SAFETY.md' }),
44
+ Object.freeze({ surface: 'mcp', description: 'MCP read-only projection', actions: Object.freeze(['read']), dataClass: 'ledger', sink: 'none', default: 'on', gate: 'enforced-policy', tosRef: 'docs/TOS.md#9.3', doc: 'docs/MCP.md' }),
45
+ Object.freeze({ surface: 'dsh', description: 'DeepSeek Harness read-only projection', actions: Object.freeze(['read']), dataClass: 'ledger', sink: 'none', default: 'on', gate: 'enforced-policy', tosRef: 'docs/TOS.md#9.3', doc: 'docs/PLUGIN-BOUNDARY.md' }),
46
+ Object.freeze({ surface: 'pet-brief', description: 'portable brief for consumer agents', actions: Object.freeze(['read', 'export']), dataClass: 'ledger', sink: 'fs', default: 'on', gate: 'legacy-gate', tosRef: 'docs/TOS.md#9.3', doc: 'docs/PET-BRIEF-CONSUMERS.md' }),
47
+ Object.freeze({ surface: 'export', description: 'evidence/export packs and delivery receipts', actions: Object.freeze(['export']), dataClass: 'ledger', sink: 'fs', default: 'on', gate: 'enforced-policy', tosRef: 'docs/TOS.md#9.3', doc: 'docs/DELIVERY-RECEIPT.md' }),
48
+ Object.freeze({ surface: 'mail.sync', description: 'IMAP sync to the user-configured mailbox', actions: Object.freeze(['net-egress']), dataClass: 'mail', sink: 'net', default: 'on', gate: 'legacy-gate', tosRef: 'docs/TOS.md#9.3', doc: 'docs/ARCHITECTURE.md' }),
49
+ Object.freeze({ surface: 'mail.extract', description: 'mail candidate extraction (local rules or explicit model opt-in)', actions: Object.freeze(['read', 'model-egress']), dataClass: 'mail', sink: 'model', default: 'off', gate: 'enforced-policy', tosRef: 'docs/TOS.md#9.3', doc: 'docs/ARCHITECTURE.md' }),
50
+ Object.freeze({ surface: 'kb.ingest', description: 'local KB ingest (no egress)', actions: Object.freeze(['read', 'write-ledger']), dataClass: 'kb', sink: 'fs', default: 'on', gate: 'self-attested', tosRef: 'docs/TOS.md#9.3', doc: 'docs/ARCHITECTURE.md' }),
51
+ Object.freeze({ surface: 'kb.search', description: 'local KB search (clearance-filtered)', actions: Object.freeze(['read']), dataClass: 'kb', sink: 'none', default: 'on', gate: 'enforced-policy', tosRef: 'docs/TOS.md#9.3', doc: 'docs/ARCHITECTURE.md' }),
52
+ Object.freeze({ surface: 'kb.ask', description: 'model-assisted KB answers (explicit opt-in)', actions: Object.freeze(['read', 'model-egress']), dataClass: 'kb', sink: 'model', default: 'off', gate: 'enforced-policy', tosRef: 'docs/TOS.md#9.3', doc: 'docs/ARCHITECTURE.md' }),
53
+ Object.freeze({ surface: 'notify.webhook', description: 'outbound notification webhook', actions: Object.freeze(['net-egress']), dataClass: 'reminder', sink: 'net', default: 'off', gate: 'legacy-gate', tosRef: 'docs/TOS.md#9.3', doc: 'docs/REMINDERS.md' }),
54
+ Object.freeze({ surface: 'bridge', description: 'Hermes bridge file exchange', actions: Object.freeze(['read', 'net-egress', 'send']), dataClass: 'conversation', sink: 'net', default: 'off', gate: 'legacy-gate', tosRef: 'docs/TOS.md#9.3', doc: 'docs/PLUGIN-BOUNDARY.md' }),
55
+ Object.freeze({ surface: 'tui', description: 'TUI shell dispatch (no data egress of its own)', actions: Object.freeze(['read']), dataClass: 'ledger', sink: 'none', default: 'on', gate: 'self-attested', tosRef: 'docs/TOS.md#9.3', doc: 'docs/TUI.md' }),
56
+ ])
57
+
58
+ /** Canonical policy actions understood by evaluate(). */
59
+ export const POLICY_ACTIONS = Object.freeze([
60
+ 'read', 'write-ledger', 'write-fs', 'exec', 'send', 'model-egress', 'net-egress', 'export', 'delete',
61
+ ])
62
+
63
+ /** Canonical data classes carried by a policy decision. */
64
+ export const DATA_CLASSES = Object.freeze([
65
+ 'conversation', 'ledger', 'mail', 'kb', 'attachment', 'reminder', 'web', 'tool', 'credential', 'unknown',
66
+ ])
67
+
68
+ /** Actions that need a TOS acceptance fact before they are allowed. */
69
+ export const TOS_REQUIRED_ACTIONS = Object.freeze([
70
+ 'read', 'write-ledger', 'write-fs', 'exec', 'send', 'model-egress', 'net-egress', 'export', 'delete',
71
+ ])
72
+
73
+ /** Actions that leave the process / mutate durable state (audit + fail-closed). */
74
+ export const SIDE_EFFECT_ACTIONS = Object.freeze([
75
+ 'write-ledger', 'write-fs', 'exec', 'send', 'model-egress', 'net-egress', 'export', 'delete',
76
+ ])
77
+
78
+ /** Actions that egress data to a model or the network. */
79
+ export const EGRESS_ACTIONS = Object.freeze(['model-egress', 'net-egress', 'send'])
80
+
81
+ /** Read-only projections that respect per-record clearance. */
82
+ export const CLEARANCE_ACTIONS = Object.freeze(['read', 'export'])
83
+
84
+ /**
85
+ * Actions whose input content must carry a safety verdict before they are
86
+ * allowed. Legacy (0.4) call sites that already ran inspectCaptureText / the
87
+ * safety classifier pass {action:'allow'}; new data surfaces fail closed when
88
+ * the verdict is absent.
89
+ */
90
+ export const SAFETY_REQUIRED_ACTIONS = Object.freeze(['model-egress', 'send', 'export'])
91
+
92
+ /** Actions whose target path must be classified (workspace boundary enforcement). */
93
+ export const PATH_ACTIONS = Object.freeze(['write-fs', 'delete'])
94
+
95
+ const SURFACE_BY_NAME = new Map(SURFACE_REGISTRY.map((row) => [row.surface, row]))
96
+
97
+ /** Canonical surface name or null (case/space tolerant, never guesses). */
98
+ export function normalizeSurface(value) {
99
+ if (typeof value !== 'string') return null
100
+ const text = value.trim().toLowerCase()
101
+ if (!text) return null
102
+ return SURFACE_BY_NAME.has(text) ? text : null
103
+ }
104
+
105
+ /** Surface registry row or null. */
106
+ export function getSurface(value) {
107
+ const name = normalizeSurface(value)
108
+ return name ? SURFACE_BY_NAME.get(name) : null
109
+ }
110
+
111
+ /** True when the surface declares the action. */
112
+ export function surfaceSupportsAction(surface, action) {
113
+ const row = getSurface(surface)
114
+ if (!row || typeof action !== 'string') return false
115
+ return row.actions.includes(action)
116
+ }
117
+
118
+ /** True when the surface is gate 'not-wired' (registered but disabled in 0.4). */
119
+ export function surfaceNotWired(surface) {
120
+ const row = getSurface(surface)
121
+ return Boolean(row) && row.gate === 'not-wired'
122
+ }
123
+
124
+ /** Deterministic JSON-ready matrix (used by privacy --matrix and docs gates). */
125
+ export function surfaceMatrix() {
126
+ return {
127
+ policyVersion: POLICY_VERSION,
128
+ rulesetVersion: RULESET_VERSION,
129
+ rows: SURFACE_REGISTRY.map((row) => ({
130
+ surface: row.surface,
131
+ description: row.description,
132
+ actions: [...row.actions],
133
+ dataClass: row.dataClass,
134
+ sink: row.sink,
135
+ default: row.default,
136
+ gate: row.gate,
137
+ tosRef: row.tosRef,
138
+ doc: row.doc,
139
+ })),
140
+ }
141
+ }