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.
- package/README-zh.md +13 -15
- package/README.md +32 -22
- package/THIRD-PARTY-NOTICES.md +1 -1
- package/bin/advisers.js +2769 -183
- 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/customer-read.js +524 -0
- package/lib/error-codes.js +516 -7
- package/lib/evidence.js +928 -120
- 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/ledger-read.js +109 -1
- 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 +397 -11
- 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 +283 -26
- 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 +501 -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/tui/labels.js +1 -1
- package/lib/tui/render.js +1 -1
- package/lib/urgency.js +467 -0
- 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
|
+
}
|