@cloakapi/conformance 0.0.0-stage → 0.1.4
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/LICENSE +202 -0
- package/NOTICE +9 -0
- package/README.md +128 -2
- package/THIRD-PARTY-NOTICES.md +9 -0
- package/TRADEMARKS.md +23 -0
- package/badge/attestation.js +47 -0
- package/badge/badge.html +40 -0
- package/badge/make-variants.mjs +40 -0
- package/badge/verified-by-cloakapi-dark.svg +16 -0
- package/badge/verified-by-cloakapi-light.svg +16 -0
- package/badge/verified-by-cloakapi.svg +43 -0
- package/bin/cloakapi-conformance.js +150 -0
- package/fixtures/chain-broken.json +74 -0
- package/fixtures/chain-pass.json +74 -0
- package/fixtures/countersigned-forged.json +52 -0
- package/fixtures/countersigned-pass.json +52 -0
- package/fixtures/engine-hashes-unpublished.json +8 -0
- package/fixtures/engine-hashes.json +10 -0
- package/fixtures/jwks.json +13 -0
- package/fixtures/receipt-bad-token-hash.json +36 -0
- package/fixtures/receipt-future-engine.json +36 -0
- package/fixtures/receipt-no-egress-claim.json +35 -0
- package/fixtures/receipt-pass.json +36 -0
- package/fixtures/receipt-raw-pii.json +36 -0
- package/fixtures/receipt-spoofed-hash.json +36 -0
- package/fixtures/receipt-stale-engine.json +36 -0
- package/fixtures/receipt-tampered.json +36 -0
- package/package.json +56 -4
- package/src/checks.js +570 -0
- package/src/index.js +120 -0
- package/vendor/cloakapi-verify.d.ts +121 -0
- package/vendor/cloakapi-verify.js +1350 -0
- package/vendor/strict-json.js +143 -0
package/src/checks.js
ADDED
|
@@ -0,0 +1,570 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @cloakapi/conformance — the individual conformance CHECKS.
|
|
3
|
+
*
|
|
4
|
+
* A conformance run proves the VERIFIABLE ARTIFACTS a third-party integration
|
|
5
|
+
* produces (its OpenReceipt v3 receipts + declared engine identity) behave
|
|
6
|
+
* correctly. CloakAPI is a BLIND pure-relay (ADR-0014 §3): we cannot inspect a
|
|
7
|
+
* builder's server, so correctness is made FALSIFIABLE via the receipts, not
|
|
8
|
+
* "trusted" (ADR-0014 §5 #6). Every check therefore states plainly what it
|
|
9
|
+
* proves AND what it structurally CANNOT prove.
|
|
10
|
+
*
|
|
11
|
+
* ALL cryptography is REUSED from the shipped @cloakapi/verify-widget
|
|
12
|
+
* (verifyDeviceReceipt / verifyCountersigned / verifyChain / receiptHash) — the
|
|
13
|
+
* same JCS → SHA-256 → P-256 raw-r||s path as the reference signer. This file
|
|
14
|
+
* hand-rolls NO signature verification.
|
|
15
|
+
*
|
|
16
|
+
* The verifier is a byte copy of
|
|
17
|
+
* sdk/typescript/src/browser/verify/cloakapi-verify.js, written by
|
|
18
|
+
* sync-copies.mjs, so this package ships self-contained on npm. Do not
|
|
19
|
+
* hand-edit vendor/cloakapi-verify.js.
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
import {
|
|
23
|
+
verifyDeviceReceipt,
|
|
24
|
+
verifyCountersigned,
|
|
25
|
+
verifyChain,
|
|
26
|
+
isCountersignedResult,
|
|
27
|
+
} from '../vendor/cloakapi-verify.js';
|
|
28
|
+
|
|
29
|
+
/** Absence of safety_classifier_verdict means the classifier did not run. */
|
|
30
|
+
function safetyClassifierStatus(claim) {
|
|
31
|
+
const verdict = claim && typeof claim === 'object' ? claim.safety_classifier_verdict : undefined;
|
|
32
|
+
if (verdict === 'pass' || verdict === 'warn' || verdict === 'block') {
|
|
33
|
+
return { kind: verdict, verdict };
|
|
34
|
+
}
|
|
35
|
+
return { kind: 'not-run' };
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export { isCountersignedResult } from '../vendor/cloakapi-verify.js';
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Check status vocabulary.
|
|
42
|
+
*
|
|
43
|
+
* * `pass` — the artifacts prove the thing.
|
|
44
|
+
* * `fail` — the artifacts disprove it.
|
|
45
|
+
* * `unknown` — structurally unprovable (blind relay): we DO NOT KNOW.
|
|
46
|
+
* * `not-run` — ⛔ SAK 198: the artifacts positively STATE the step did not
|
|
47
|
+
* run. This is knowledge, not ignorance, and must never be
|
|
48
|
+
* reported as `unknown`. It does not make a run inconclusive.
|
|
49
|
+
*/
|
|
50
|
+
export const STATUS = Object.freeze({
|
|
51
|
+
PASS: 'pass',
|
|
52
|
+
FAIL: 'fail',
|
|
53
|
+
UNKNOWN: 'unknown',
|
|
54
|
+
NOT_RUN: 'not-run',
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
/** Pull the v3 attestation off a bare envelope / countersigned-result / chain-tail. */
|
|
58
|
+
export function attestationOf(input) {
|
|
59
|
+
const env = Array.isArray(input)
|
|
60
|
+
? input[input.length - 1]
|
|
61
|
+
: isCountersignedResult(input)
|
|
62
|
+
? input.receipt
|
|
63
|
+
: input;
|
|
64
|
+
const a = env && env.claims && env.claims['v3-attestation'];
|
|
65
|
+
return a && typeof a === 'object' ? a : null;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Envelopes as a flat list (chain → members; single → [it]; countersigned → [.receipt]). */
|
|
69
|
+
export function envelopesOf(input) {
|
|
70
|
+
if (Array.isArray(input)) return input;
|
|
71
|
+
if (isCountersignedResult(input)) return [input.receipt];
|
|
72
|
+
return [input];
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** A well-formed lowercase-or-upper 64-char SHA-256 hex digest. */
|
|
76
|
+
const HEX64 = /^[0-9a-f]{64}$/i;
|
|
77
|
+
/** A plausible semantic version: `x.y` or `x.y.z`, tolerant of a leading v. */
|
|
78
|
+
const SEMVER_SHAPE = /^v?\d+\.\d+(\.\d+)?$/i;
|
|
79
|
+
const ZERO64 = '0'.repeat(64);
|
|
80
|
+
|
|
81
|
+
/** Is `s` a syntactically valid 64-char hex SHA-256 digest? */
|
|
82
|
+
export function isHex64(s) {
|
|
83
|
+
return typeof s === 'string' && HEX64.test(s);
|
|
84
|
+
}
|
|
85
|
+
/** A hash that is well-formed AND not an all-zero placeholder. */
|
|
86
|
+
export function isMeaningfulHash(s) {
|
|
87
|
+
return isHex64(s) && s.toLowerCase() !== ZERO64;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Plaintext tier. The wire value is the word `off`; padding, case, NBSP and
|
|
92
|
+
* zero-width characters do not make it a different tier. Without this, a
|
|
93
|
+
* signed receipt with `privacy_tier: "off "` is reported CONFORMANT.
|
|
94
|
+
*/
|
|
95
|
+
function isOffTier(value) {
|
|
96
|
+
const s = String(value ?? '')
|
|
97
|
+
.replace(/[\u200B-\u200D\uFEFF]/g, '')
|
|
98
|
+
.trim()
|
|
99
|
+
.toLowerCase();
|
|
100
|
+
return s === 'off';
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Q47 / sak 2137 — the set of engine hashes the register marks WITHDRAWN.
|
|
105
|
+
*
|
|
106
|
+
* Read from BOTH shapes the gateway publishes: `withdrawn_binary_hashes` (the
|
|
107
|
+
* document-level set) and `engines[].withdrawn` (the per-ENTRY row). Q8 measured
|
|
108
|
+
* why both are needed — a status can be present on the document and missing
|
|
109
|
+
* from the rows a client actually reads, and «the field exists in the register»
|
|
110
|
+
* is then true of the document and false of the entry.
|
|
111
|
+
*
|
|
112
|
+
* A register with neither field yields the EMPTY set, so an older gateway can
|
|
113
|
+
* never silently withdraw anything (absence is not a withdrawal).
|
|
114
|
+
*/
|
|
115
|
+
export function withdrawnSetOf(engineHashes) {
|
|
116
|
+
const out = new Set();
|
|
117
|
+
if (!engineHashes || typeof engineHashes !== 'object') return out;
|
|
118
|
+
const doc = Array.isArray(engineHashes.withdrawn_binary_hashes) ? engineHashes.withdrawn_binary_hashes : [];
|
|
119
|
+
for (const h of doc) {
|
|
120
|
+
const s = String(h).toLowerCase();
|
|
121
|
+
if (isHex64(s)) out.add(s);
|
|
122
|
+
}
|
|
123
|
+
const rows = Array.isArray(engineHashes.engines) ? engineHashes.engines : [];
|
|
124
|
+
for (const r of rows) {
|
|
125
|
+
if (!r || typeof r !== 'object' || r.withdrawn !== true) continue;
|
|
126
|
+
const s = String(r.sha256 ?? '').toLowerCase();
|
|
127
|
+
if (isHex64(s)) out.add(s);
|
|
128
|
+
}
|
|
129
|
+
return out;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** Minimal, dependency-free semver compare (major.minor.patch, tolerant of a leading v).
|
|
133
|
+
* A missing component is 0, so `1.4` and `1.4.0` are the same release. Leaving
|
|
134
|
+
* the missing component `undefined` made `1.4` compare as newer than `1.4.0`. */
|
|
135
|
+
export function semverCompare(a, b) {
|
|
136
|
+
const norm = (s) => {
|
|
137
|
+
const parts = String(s ?? '').trim().replace(/^v/i, '').split('.');
|
|
138
|
+
const nums = [];
|
|
139
|
+
for (let i = 0; i < 3; i++) {
|
|
140
|
+
const part = parts[i];
|
|
141
|
+
nums.push(part == null || part === '' ? 0 : parseInt(part, 10) || 0);
|
|
142
|
+
}
|
|
143
|
+
return nums;
|
|
144
|
+
};
|
|
145
|
+
const [a0, a1, a2] = norm(a);
|
|
146
|
+
const [b0, b1, b2] = norm(b);
|
|
147
|
+
if (a0 !== b0) return a0 < b0 ? -1 : 1;
|
|
148
|
+
if (a1 !== b1) return a1 < b1 ? -1 : 1;
|
|
149
|
+
if (a2 !== b2) return a2 < b2 ? -1 : 1;
|
|
150
|
+
return 0;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/**
|
|
154
|
+
* CHECK 1 — Receipts are cryptographically VALID (+ chain-consistent).
|
|
155
|
+
* Reuses the widget verifier verbatim. A bare v3 envelope is verified against
|
|
156
|
+
* the public key embedded in its own signed bytes (tamper-evident). A
|
|
157
|
+
* countersigned result additionally checks the gateway signature (needs JWKS)
|
|
158
|
+
* and the hash-binding. An array is verified as a hash-linked chain.
|
|
159
|
+
*/
|
|
160
|
+
export async function checkSignatures(input, { jwksJson = null } = {}) {
|
|
161
|
+
const base = { id: 'receipt-signatures', title: 'Receipts are cryptographically valid' };
|
|
162
|
+
try {
|
|
163
|
+
if (Array.isArray(input)) {
|
|
164
|
+
const r = await verifyChain(input);
|
|
165
|
+
if (r.ok) {
|
|
166
|
+
return { ...base, status: STATUS.PASS, detail: `All ${input.length} receipts verify and form an unbroken, hash-linked chain.` };
|
|
167
|
+
}
|
|
168
|
+
return { ...base, status: STATUS.FAIL, detail: `Chain verification failed at index ${r.index}: ${r.reason}` };
|
|
169
|
+
}
|
|
170
|
+
if (isCountersignedResult(input)) {
|
|
171
|
+
const cs = await verifyCountersigned(input, jwksJson);
|
|
172
|
+
if (!cs.deviceVerified) {
|
|
173
|
+
return { ...base, status: STATUS.FAIL, detail: 'The on-device receipt signature did not verify — the receipt was altered or was never validly signed.' };
|
|
174
|
+
}
|
|
175
|
+
// Hash-binding needs NO key: the countersignature's receipt_hash must equal
|
|
176
|
+
// the SHA-256 of the receipt it claims to cover. A mismatch means the
|
|
177
|
+
// countersignature was pasted onto a different receipt — reject offline.
|
|
178
|
+
if (!cs.hashBound) {
|
|
179
|
+
return { ...base, status: STATUS.FAIL, detail: 'Countersignature receipt_hash does NOT match the receipt it is attached to — spliced/mismatched countersigned result.' };
|
|
180
|
+
}
|
|
181
|
+
// If a JWKS was supplied the gateway countersignature MUST verify against it.
|
|
182
|
+
if (jwksJson && !cs.gatewayVerified) {
|
|
183
|
+
return { ...base, status: STATUS.FAIL, detail: `Gateway countersignature did NOT verify against the supplied JWKS (${cs.gatewayKid || 'unknown kid'}) — forged or wrong-key countersignature.` };
|
|
184
|
+
}
|
|
185
|
+
const detail = [
|
|
186
|
+
'Device signature verifies against the key embedded in the signed receipt.',
|
|
187
|
+
jwksJson
|
|
188
|
+
? `Gateway countersignature verifies against the published JWKS (${cs.gatewayKid || 'gateway key'}) — issuer identity is gateway-anchored (not merely self-asserted).`
|
|
189
|
+
: 'No JWKS supplied: device proof stands on its own, but the ISSUER IDENTITY is self-asserted — supply --jwks to cryptographically anchor it to the gateway.',
|
|
190
|
+
'Gateway signed the exact receipt hash (tamper-proof binding confirmed).',
|
|
191
|
+
].join(' ');
|
|
192
|
+
return { ...base, status: STATUS.PASS, detail };
|
|
193
|
+
}
|
|
194
|
+
const r = await verifyDeviceReceipt(input);
|
|
195
|
+
return r.ok
|
|
196
|
+
? { ...base, status: STATUS.PASS, detail: 'Signature verifies against the public key embedded in the signed receipt (tamper-evident). NOTE: for a self-signed device receipt the ISSUER IDENTITY is self-asserted — only a gateway countersignature (--jwks) anchors it to CloakAPI.' }
|
|
197
|
+
: { ...base, status: STATUS.FAIL, detail: r.reason };
|
|
198
|
+
} catch (err) {
|
|
199
|
+
return { ...base, status: STATUS.FAIL, detail: (err && err.message) || String(err) };
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* CHECK 2 — The declared engine is CURRENT (ruleset at/above the published floor).
|
|
205
|
+
* Compares each receipt's `engine_ruleset_version` against the ruleset the
|
|
206
|
+
* gateway publishes at GET /api/v1/engine/hashes (or an explicit floor override).
|
|
207
|
+
* This is the #5 fix-distribution signal: an integration below the floor is
|
|
208
|
+
* running an uncertified/outdated tokeniser.
|
|
209
|
+
*/
|
|
210
|
+
export function checkEngineCurrent(input, engineHashes, { floorOverride = null } = {}) {
|
|
211
|
+
const base = { id: 'engine-current', title: 'Declared engine ruleset is at/above the current published floor' };
|
|
212
|
+
const floor = floorOverride || (engineHashes && engineHashes.ruleset_version) || '';
|
|
213
|
+
if (!floor) {
|
|
214
|
+
return { ...base, status: STATUS.UNKNOWN, detail: 'No published ruleset floor available (offline / not supplied) — cannot evaluate.' };
|
|
215
|
+
}
|
|
216
|
+
const envs = envelopesOf(input);
|
|
217
|
+
// Keep a present-but-blank version. `filter(Boolean)` dropped `""` and
|
|
218
|
+
// `null`, so a signed receipt with an empty ruleset string skipped the
|
|
219
|
+
// floor check and could still be CONFORMANT. A v3 attestation that omits
|
|
220
|
+
// the field entirely, sitting next to one that has it, was skipped the
|
|
221
|
+
// same way and the check PASSed.
|
|
222
|
+
const versions = [];
|
|
223
|
+
let attestations = 0;
|
|
224
|
+
let missingVersion = 0;
|
|
225
|
+
for (const e of envs) {
|
|
226
|
+
const a = e && e.claims && e.claims['v3-attestation'];
|
|
227
|
+
if (!a || typeof a !== 'object') continue;
|
|
228
|
+
attestations++;
|
|
229
|
+
if (!Object.prototype.hasOwnProperty.call(a, 'engine_ruleset_version')) {
|
|
230
|
+
missingVersion++;
|
|
231
|
+
continue;
|
|
232
|
+
}
|
|
233
|
+
versions.push(a.engine_ruleset_version);
|
|
234
|
+
}
|
|
235
|
+
if (attestations > 0 && missingVersion > 0 && missingVersion < attestations) {
|
|
236
|
+
return {
|
|
237
|
+
...base,
|
|
238
|
+
status: STATUS.FAIL,
|
|
239
|
+
detail: `${missingVersion} of ${attestations} v3 attestation(s) omit engine_ruleset_version, so the set is not at the published floor.`,
|
|
240
|
+
};
|
|
241
|
+
}
|
|
242
|
+
if (versions.length === 0) {
|
|
243
|
+
return { ...base, status: STATUS.UNKNOWN, detail: 'No engine_ruleset_version present in the receipt(s) — nothing to floor-check.' };
|
|
244
|
+
}
|
|
245
|
+
// Reject a garbage / non-semver version string outright (a spoof signal).
|
|
246
|
+
const malformed = versions.filter((v) => !SEMVER_SHAPE.test(String(v).trim()));
|
|
247
|
+
if (malformed.length > 0) {
|
|
248
|
+
return { ...base, status: STATUS.FAIL, detail: `Engine ruleset version ${[...new Set(malformed)].map((v) => JSON.stringify(v)).join(', ')} is not a valid semantic version — malformed/forged attestation.` };
|
|
249
|
+
}
|
|
250
|
+
const below = versions.filter((v) => semverCompare(v, floor) < 0);
|
|
251
|
+
if (below.length > 0) {
|
|
252
|
+
return { ...base, status: STATUS.FAIL, detail: `Engine ruleset ${[...new Set(below)].join(', ')} is BELOW the published floor ${floor}. Update the CloakAPI client/SDK.` };
|
|
253
|
+
}
|
|
254
|
+
// When we know the CURRENT published ruleset (not a manual floor override), a
|
|
255
|
+
// receipt claiming a ruleset NEWER than any the gateway has ever published is
|
|
256
|
+
// impossible — it is a fabricated version string. Reject it.
|
|
257
|
+
const publishedCurrent = !floorOverride && engineHashes && engineHashes.ruleset_version ? engineHashes.ruleset_version : null;
|
|
258
|
+
if (publishedCurrent) {
|
|
259
|
+
const ahead = versions.filter((v) => semverCompare(v, publishedCurrent) > 0);
|
|
260
|
+
if (ahead.length > 0) {
|
|
261
|
+
return { ...base, status: STATUS.FAIL, detail: `Engine ruleset ${[...new Set(ahead)].join(', ')} claims to be NEWER than the latest published ruleset ${publishedCurrent} — no such engine exists; fabricated version string.` };
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
return { ...base, status: STATUS.PASS, detail: `Declared ruleset ${[...new Set(versions)].join(', ')} is at/above the published floor ${floor}${publishedCurrent ? ` and not newer than the published current ${publishedCurrent}` : ''}.` };
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
/**
|
|
268
|
+
* CHECK 3 — The DECLARED engine binary hash is on the published allowlist.
|
|
269
|
+
*
|
|
270
|
+
* This is a membership check on a value the client reports about itself, and
|
|
271
|
+
* it is exactly what the gateway's `genuine_engine` means
|
|
272
|
+
* (EngineProvenance::genuineFor()): "the declared hash is on our official
|
|
273
|
+
* allowlist". It does NOT prove which engine actually ran — the gateway never
|
|
274
|
+
* sees the engine, and the allowlist is public, so a client can declare a
|
|
275
|
+
* listed hash without running that build. A PASS rules out a malformed or
|
|
276
|
+
* unlisted declaration; it is not binary attestation.
|
|
277
|
+
* If the allowlist has not been published yet (empty), this is honestly UNKNOWN.
|
|
278
|
+
*/
|
|
279
|
+
export function checkGenuineEngine(input, engineHashes, { allowlistOverride = null } = {}) {
|
|
280
|
+
const base = { id: 'engine-genuine', title: 'Declared engine binary hash is on the published official allowlist' };
|
|
281
|
+
const rawAllowlist = allowlistOverride ?? (engineHashes && engineHashes.engine_binary_hashes);
|
|
282
|
+
if (rawAllowlist != null && !Array.isArray(rawAllowlist)) {
|
|
283
|
+
return {
|
|
284
|
+
...base,
|
|
285
|
+
status: STATUS.UNKNOWN,
|
|
286
|
+
detail: 'Official engine-binary allowlist has an invalid shape — membership of the declared hash cannot be checked.',
|
|
287
|
+
};
|
|
288
|
+
}
|
|
289
|
+
const allow = (rawAllowlist ?? []).map((h) => String(h).toLowerCase());
|
|
290
|
+
// Q47 / sak 2137 — the THIRD question. `engine_binary_hashes` answers «did
|
|
291
|
+
// CloakAPI build this?» and nothing else; a build we have withdrawn stays on
|
|
292
|
+
// it forever, because removing it would make the register claim we never
|
|
293
|
+
// built a binary we signed ourselves. So the withdrawal is read from the
|
|
294
|
+
// register's own withdrawn set / per-entry rows, not inferred from absence.
|
|
295
|
+
const withdrawn = withdrawnSetOf(engineHashes);
|
|
296
|
+
if (allow.length === 0) {
|
|
297
|
+
return {
|
|
298
|
+
...base,
|
|
299
|
+
status: STATUS.UNKNOWN,
|
|
300
|
+
detail: 'Official engine-binary allowlist is not published yet — allowlist membership of the declared hash cannot be checked (this matches genuine_engine=false).',
|
|
301
|
+
};
|
|
302
|
+
}
|
|
303
|
+
const envs = envelopesOf(input);
|
|
304
|
+
const atts = envs.map((e) => e && e.claims && e.claims['v3-attestation']).filter((a) => a && typeof a === 'object');
|
|
305
|
+
const withHash = atts.filter((a) => a.engine_binary_hash != null);
|
|
306
|
+
if (withHash.length === 0) {
|
|
307
|
+
return { ...base, status: STATUS.UNKNOWN, detail: 'No engine_binary_hash present in the receipt(s).' };
|
|
308
|
+
}
|
|
309
|
+
const problems = [];
|
|
310
|
+
const okHashes = new Set();
|
|
311
|
+
for (const a of withHash) {
|
|
312
|
+
const raw = String(a.engine_binary_hash);
|
|
313
|
+
const h = raw.toLowerCase();
|
|
314
|
+
const genuineFlag = a.genuine_engine;
|
|
315
|
+
if (!isHex64(h)) {
|
|
316
|
+
problems.push(`engine_binary_hash ${JSON.stringify(raw)} is not a valid 64-char SHA-256 digest — malformed/forged`);
|
|
317
|
+
continue;
|
|
318
|
+
}
|
|
319
|
+
const onList = allow.includes(h);
|
|
320
|
+
if (!onList) {
|
|
321
|
+
problems.push(`${h.slice(0, 12)}…: declared hash is NOT on the official allowlist — not a published CloakAPI build (claims genuine_engine=${JSON.stringify(genuineFlag)})`);
|
|
322
|
+
continue;
|
|
323
|
+
}
|
|
324
|
+
// On the allowlist but not marked true. `false` used to be reported as
|
|
325
|
+
// "the gateway did not find the declared hash" before membership was
|
|
326
|
+
// checked, which is false when the hash is on the list.
|
|
327
|
+
if (genuineFlag !== true) {
|
|
328
|
+
problems.push(`${h.slice(0, 12)}…: declared hash is on the allowlist but genuine_engine is ${JSON.stringify(genuineFlag)} (expected true) — inconsistent attestation`);
|
|
329
|
+
continue;
|
|
330
|
+
}
|
|
331
|
+
// Q47 — genuine AND withdrawn. Reported as its own sentence, saying both
|
|
332
|
+
// halves: the build IS ours (so `genuine_engine: true` is correct and the
|
|
333
|
+
// hash correctly stays on the allowlist), and it must not be in use.
|
|
334
|
+
if (withdrawn.has(h)) {
|
|
335
|
+
problems.push(
|
|
336
|
+
`${h.slice(0, 12)}…: declared hash is GENUINE (a published CloakAPI build, correctly on the official allowlist) but WITHDRAWN — ` +
|
|
337
|
+
'it must not be used (genuine=true, current=false, withdrawn=true). Update to the canonical engine' +
|
|
338
|
+
(engineHashes && Array.isArray(engineHashes.canonical_binary_hashes) && engineHashes.canonical_binary_hashes.length
|
|
339
|
+
? ` (${String(engineHashes.canonical_binary_hashes[0]).slice(0, 12)}…)`
|
|
340
|
+
: ''),
|
|
341
|
+
);
|
|
342
|
+
continue;
|
|
343
|
+
}
|
|
344
|
+
okHashes.add(h);
|
|
345
|
+
}
|
|
346
|
+
if (problems.length > 0) {
|
|
347
|
+
return { ...base, status: STATUS.FAIL, detail: problems.join('; ') + '.' };
|
|
348
|
+
}
|
|
349
|
+
return { ...base, status: STATUS.PASS, detail: `Every declared engine binary hash (${[...okHashes].map((h) => h.slice(0, 12) + '…').join(', ')}) is on the official published allowlist and self-consistently marked genuine_engine=true. This checks the DECLARED hash only; it does not prove which engine actually ran (the gateway does not see the engine, and the allowlist is public).` };
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* CHECK 4 — Validate the receipt's CLIENT-SIDE tokenisation claim.
|
|
354
|
+
*
|
|
355
|
+
* ⛔⛔ `no_raw_pii_egress` HAS THREE STATES, NOT TWO — AND THE THIRD IS THE
|
|
356
|
+
* HONEST ONE.
|
|
357
|
+
*
|
|
358
|
+
* The field is a POSTURE claim (Rolf, 2026-08-25, binding): it says the
|
|
359
|
+
* cloaking pipeline RAN for these bytes. It is NOT a recall claim, and the
|
|
360
|
+
* producer that signs it says so on itself
|
|
361
|
+
* (`repo/sdk/typescript/src/browser/sign-receipt.ts:231-247`): the claim is
|
|
362
|
+
* derived from `NerCoverage` when the caller hands over the evidence, and
|
|
363
|
+
* **OMITTED when they do not** — "a reader gets UNKNOWN instead of a signed
|
|
364
|
+
* claim nobody checked".
|
|
365
|
+
*
|
|
366
|
+
* This check used to read `a.no_raw_pii_egress !== true` — one predicate over
|
|
367
|
+
* two states — so ABSENT and `false` collapsed into the same FAIL sentence,
|
|
368
|
+
* *"raw PII may have egressed"*. Measured 2026-09-14
|
|
369
|
+
* (`goal-run/F-BEVIS/HZ-KVITTERING-PERSON-RAN-2026-09-14.md` §2.4): the eight
|
|
370
|
+
* suites that deliberately omit the field — cloakcv · cloakdocs · cloakmeet ·
|
|
371
|
+
* cloakpost · cloakredact · cloakscan · cloaktranslate · cloakwrite, i.e.
|
|
372
|
+
* **8 of 8**, the most honest producer family we have — were reported as
|
|
373
|
+
* NON-CONFORMANT with that sentence, while a receipt signed `true` over a
|
|
374
|
+
* person name that got a company surrogate was reported PASS.
|
|
375
|
+
*
|
|
376
|
+
* ⛔ That is the EIGHTH FORM: a guard that goes red exactly when you do the
|
|
377
|
+
* honest thing teaches the author to set the field to `true`. The cheapest way
|
|
378
|
+
* out of this check was to sign an unmeasured absolute claim about our own
|
|
379
|
+
* behaviour — which is the one thing R21 forbids.
|
|
380
|
+
*
|
|
381
|
+
* So, three states, each with its own sentence:
|
|
382
|
+
*
|
|
383
|
+
* `true` → the posture claim is made. Evaluate it, then the substantive
|
|
384
|
+
* evidence (tokenised_body_hash, privacy_tier) as before.
|
|
385
|
+
* `false` → a FINDING. The receipt itself states a model-backed layer did
|
|
386
|
+
* not run before egress.
|
|
387
|
+
* ABSENT → NOT ATTESTED ⇒ `unknown` ⇒ the run is INCONCLUSIVE (exit 2),
|
|
388
|
+
* never NON-CONFORMANT (exit 1).
|
|
389
|
+
*
|
|
390
|
+
* ⛔ ABSENT IS `unknown`, NOT `not-run` (sak 198). `not-run` means the
|
|
391
|
+
* artifacts POSITIVELY STATE the step did not happen. Absence here states
|
|
392
|
+
* nothing of the kind: these surfaces DO tokenise client-side — they decline
|
|
393
|
+
* to sign a claim they did not measure. We are ignorant of the posture, and
|
|
394
|
+
* `unknown` is the only word for that. Calling it `not-run` would assert on
|
|
395
|
+
* the customer's behalf that the pipeline did not run, which is a second
|
|
396
|
+
* invented claim on top of the first.
|
|
397
|
+
*
|
|
398
|
+
* ⛔ WHAT THIS CHECK MEASURES, SAID IN ITS OWN OUTPUT: whether the receipts
|
|
399
|
+
* CARRY the attestation — provenance, not recall. A PASS never means "no PII
|
|
400
|
+
* escaped"; it means every supplied receipt states the pipeline ran and backs
|
|
401
|
+
* it with a real tokenised-body digest. The detail string says so, because a
|
|
402
|
+
* check that is read as answering a bigger question than it asks is how the
|
|
403
|
+
* consumer wording in the verify widget went wrong in the first place.
|
|
404
|
+
*
|
|
405
|
+
* The substantive evidence (`tokenised_body_hash`, `privacy_tier`) is graded
|
|
406
|
+
* for EVERY v3 envelope, attested or not: a forged/placeholder digest is a
|
|
407
|
+
* finding whether or not the posture field is there.
|
|
408
|
+
*
|
|
409
|
+
* Falls back to legacy tokenisation claims (output_hash + level) for v1/v2.
|
|
410
|
+
*/
|
|
411
|
+
export function checkClientSideTokenisation(input) {
|
|
412
|
+
const base = { id: 'client-side-tokenisation', title: 'Receipts contain a client-side tokenisation claim (Level-1)' };
|
|
413
|
+
const envs = envelopesOf(input);
|
|
414
|
+
const problems = [];
|
|
415
|
+
const notAttested = [];
|
|
416
|
+
let evaluated = 0;
|
|
417
|
+
let attested = 0;
|
|
418
|
+
const missingClaims = [];
|
|
419
|
+
for (const e of envs) {
|
|
420
|
+
const a = e && e.claims && e.claims['v3-attestation'];
|
|
421
|
+
if (a) {
|
|
422
|
+
evaluated++;
|
|
423
|
+
const id = e.jti || '(receipt)';
|
|
424
|
+
// ⛔ Read the field as THREE states. `has` is the only place absence is
|
|
425
|
+
// decided; never test `!== true`, which re-creates the conflation.
|
|
426
|
+
const has = Object.prototype.hasOwnProperty.call(a, 'no_raw_pii_egress') && a.no_raw_pii_egress !== undefined && a.no_raw_pii_egress !== null;
|
|
427
|
+
if (has && a.no_raw_pii_egress !== true) {
|
|
428
|
+
problems.push(
|
|
429
|
+
`${id}: no_raw_pii_egress is attested FALSE — the receipt itself states the cloaking pipeline did not fully run before egress (NOT Level-1)`,
|
|
430
|
+
);
|
|
431
|
+
} else if (has) {
|
|
432
|
+
attested++;
|
|
433
|
+
} else {
|
|
434
|
+
notAttested.push(id);
|
|
435
|
+
}
|
|
436
|
+
// Substantive evidence is graded for EVERY v3 envelope, including one
|
|
437
|
+
// that already attested FALSE. A `continue` here hid a forged digest.
|
|
438
|
+
if (!a.tokenised_body_hash) problems.push(`${id}: no tokenised_body_hash — no proof the egressed body was the tokenised one`);
|
|
439
|
+
else if (!isMeaningfulHash(a.tokenised_body_hash)) problems.push(`${id}: tokenised_body_hash ${JSON.stringify(String(a.tokenised_body_hash))} is not a valid non-zero SHA-256 digest — placeholder/forged tokenisation proof`);
|
|
440
|
+
else if (isOffTier(a.privacy_tier)) problems.push(`${id}: privacy tier is 'off' (plaintext) — not Level-1`);
|
|
441
|
+
continue;
|
|
442
|
+
}
|
|
443
|
+
const tok = e && e.claims && e.claims.tokenisation; // legacy v1/v2
|
|
444
|
+
if (tok) {
|
|
445
|
+
evaluated++;
|
|
446
|
+
const id = e.jti || '(receipt)';
|
|
447
|
+
if (!tok.output_hash) problems.push(`${id}: legacy receipt has no tokenisation.output_hash`);
|
|
448
|
+
else if (!isMeaningfulHash(tok.output_hash)) problems.push(`${id}: legacy tokenisation.output_hash is not a valid non-zero SHA-256 digest — placeholder/forged`);
|
|
449
|
+
else if (isOffTier(tok.level)) problems.push(`${id}: legacy tokenisation level is 'off'`);
|
|
450
|
+
else attested++;
|
|
451
|
+
} else {
|
|
452
|
+
missingClaims.push((e && e.jti) || '(receipt)');
|
|
453
|
+
}
|
|
454
|
+
}
|
|
455
|
+
if (evaluated === 0) {
|
|
456
|
+
return { ...base, status: STATUS.UNKNOWN, detail: 'No tokenisation attestation found in the receipt(s).' };
|
|
457
|
+
}
|
|
458
|
+
if (problems.length > 0) {
|
|
459
|
+
return { ...base, status: STATUS.FAIL, detail: problems.join('; ') };
|
|
460
|
+
}
|
|
461
|
+
if (missingClaims.length > 0) {
|
|
462
|
+
return {
|
|
463
|
+
...base,
|
|
464
|
+
status: STATUS.UNKNOWN,
|
|
465
|
+
detail: `${missingClaims.length} of ${envs.length} receipt(s) carry no tokenisation claim (${missingClaims.map((i) => String(i).slice(0, 12)).join(', ')}); this run cannot confirm client-side tokenisation for every supplied receipt.`,
|
|
466
|
+
};
|
|
467
|
+
}
|
|
468
|
+
// ⛔ NOT ATTESTED ≠ DISPROVED. The substantive evidence above is clean; what
|
|
469
|
+
// is missing is the posture CLAIM, and a verifier may not invent it.
|
|
470
|
+
if (notAttested.length > 0) {
|
|
471
|
+
return {
|
|
472
|
+
...base,
|
|
473
|
+
status: STATUS.UNKNOWN,
|
|
474
|
+
detail:
|
|
475
|
+
`${notAttested.length} of ${evaluated} receipt(s) not attested — they do NOT ATTEST no_raw_pii_egress (${notAttested.map((i) => String(i).slice(0, 12)).join(', ')}) — the field is absent, so this run cannot confirm the posture claim. ` +
|
|
476
|
+
'That is not a finding: "not attested" is honest absence, not a statement that raw PII egressed. ' +
|
|
477
|
+
`Their tokenised-body digests and privacy tiers ARE present and valid${attested > 0 ? `, and ${attested} receipt(s) do attest` : ''}. ` +
|
|
478
|
+
'To turn this into a PASS the producer must hand the signer real coverage evidence (NerCoverage), not set the field by hand.',
|
|
479
|
+
};
|
|
480
|
+
}
|
|
481
|
+
return {
|
|
482
|
+
...base,
|
|
483
|
+
status: STATUS.PASS,
|
|
484
|
+
detail: `All ${evaluated} receipt(s) contain a signed claim that on-device tokenisation ran before egress, each backed by a valid tokenised-body digest. This validates submitted claims only; it does not prove that a detector or specific binary ran, or how much PII the detector found.`,
|
|
485
|
+
};
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
/**
|
|
489
|
+
* ⛔ SAK 198 — the safety-classifier field, read with ABSENCE SEMANTICS.
|
|
490
|
+
*
|
|
491
|
+
* `claims.tokenisation.safety_classifier_verdict` is a THREE-value wire enum
|
|
492
|
+
* (`pass|warn|block`) that cannot be widened — measured in production: the
|
|
493
|
+
* Rust signing sidecar answered `parse error: unknown variant 'not_run'` and
|
|
494
|
+
* the receipt was then not written AT ALL. So the fourth state lives in the
|
|
495
|
+
* field's ABSENCE, and this check is where a conformance run reads it.
|
|
496
|
+
*
|
|
497
|
+
* The rule: the field is present **iff** a classifier ran. Therefore
|
|
498
|
+
*
|
|
499
|
+
* * absent → `not-run` — a positive statement, reported as such, NOT
|
|
500
|
+
* `unknown` and NOT a conformance failure. A
|
|
501
|
+
* receipt honestly saying "no judge ran" is a
|
|
502
|
+
* CONFORMANT receipt.
|
|
503
|
+
* * present → the verdict, with `block` treated as a FAIL (the customer's
|
|
504
|
+
* own device said do not send, and the call went out anyway).
|
|
505
|
+
*
|
|
506
|
+
* ⛔ Reporting this as `unknown` would be a lie in the other direction: we
|
|
507
|
+
* are not ignorant here, the receipt told us. That conflation IS sak 198.
|
|
508
|
+
*/
|
|
509
|
+
export function checkSafetyClassifier(input) {
|
|
510
|
+
const base = {
|
|
511
|
+
id: 'safety-classifier',
|
|
512
|
+
title: 'Local safety-classifier verdict is stated unambiguously (sak 198)',
|
|
513
|
+
};
|
|
514
|
+
const envs = envelopesOf(input);
|
|
515
|
+
const counts = { 'not-run': 0, pass: 0, warn: 0, block: 0 };
|
|
516
|
+
let evaluated = 0;
|
|
517
|
+
for (const e of envs) {
|
|
518
|
+
const tok = e && e.claims && e.claims.tokenisation;
|
|
519
|
+
if (!tok || typeof tok !== 'object') continue;
|
|
520
|
+
evaluated++;
|
|
521
|
+
counts[safetyClassifierStatus(tok).kind]++;
|
|
522
|
+
}
|
|
523
|
+
if (evaluated === 0) {
|
|
524
|
+
// No tokenisation claim at all — THIS is genuine ignorance. Distinct
|
|
525
|
+
// from `not-run`, and reported distinctly.
|
|
526
|
+
return {
|
|
527
|
+
...base,
|
|
528
|
+
status: STATUS.UNKNOWN,
|
|
529
|
+
detail:
|
|
530
|
+
'No tokenisation claim found in the receipt(s), so there is no field to read — this is unknown, not a stated "did not run".',
|
|
531
|
+
};
|
|
532
|
+
}
|
|
533
|
+
if (counts.block > 0) {
|
|
534
|
+
return {
|
|
535
|
+
...base,
|
|
536
|
+
status: STATUS.FAIL,
|
|
537
|
+
detail: `${counts.block} of ${evaluated} receipt(s) carry a 'block' verdict: the customer's own device judged the message unsafe to send, yet a receipt exists for the call.`,
|
|
538
|
+
};
|
|
539
|
+
}
|
|
540
|
+
if (counts['not-run'] === evaluated) {
|
|
541
|
+
return {
|
|
542
|
+
...base,
|
|
543
|
+
status: STATUS.NOT_RUN,
|
|
544
|
+
detail: `All ${evaluated} receipt(s) state that no local safety classifier ran (the field is absent, and absence is defined to mean "did not run" — it is NOT "unknown"). The deterministic tokeniser remains the primary gate; this optional second look did not run.`,
|
|
545
|
+
};
|
|
546
|
+
}
|
|
547
|
+
const ranParts = [];
|
|
548
|
+
if (counts.pass) ranParts.push(`${counts.pass} pass`);
|
|
549
|
+
if (counts.warn) ranParts.push(`${counts.warn} warn`);
|
|
550
|
+
if (counts['not-run']) ranParts.push(`${counts['not-run']} did not run`);
|
|
551
|
+
return {
|
|
552
|
+
...base,
|
|
553
|
+
status: STATUS.PASS,
|
|
554
|
+
detail: `${evaluated} receipt(s), each stating unambiguously whether a local safety classifier ran: ${ranParts.join(', ')}.`,
|
|
555
|
+
};
|
|
556
|
+
}
|
|
557
|
+
|
|
558
|
+
/**
|
|
559
|
+
* The honest limits of what a conformance run can establish. CloakAPI is blind
|
|
560
|
+
* to a builder's server, so these are structurally unprovable from artifacts and
|
|
561
|
+
* are stated plainly. NEVER a "100%"/"fully safe" claim (ADR-0014 §3).
|
|
562
|
+
*/
|
|
563
|
+
export const HONEST_LIMITATIONS = Object.freeze([
|
|
564
|
+
'This is SELF-ATTESTED conformance, not third-party certification: you run this check on receipts YOUR OWN integration produced. There is no hosted issuer signing off on the result — a CONFORMANT verdict is your own evidence-backed attestation.',
|
|
565
|
+
'A self-signed device receipt is verified against the public key embedded inside it (tamper-evident), so the CONTENT cannot be altered after signing — but the ISSUER IDENTITY is self-asserted. Only a gateway countersignature (run with --jwks) cryptographically anchors the receipt to CloakAPI; without one, a receipt could in principle be produced by any key.',
|
|
566
|
+
'CloakAPI is a blind pure-relay: this suite verifies the RECEIPTS + declared engine identity your integration emits, not your server internals — we cannot and do not inspect your server.',
|
|
567
|
+
'PII DETECTION is best-effort and can miss content. A passing run validates signed claims in the supplied receipts; it does not prove that a tokeniser ran or that every possible PII token was caught.',
|
|
568
|
+
'A receipt proves what the CLIENT can cryptographically witness. Gateway-witnessed facts (actual relay provider/model) require a gateway countersignature; without one, destination is client-asserted.',
|
|
569
|
+
'This suite checks the artifacts you SUPPLY. It cannot prove your integration emits a receipt for EVERY request — pair it with the end-user verify-widget so your users can check their own sessions live.',
|
|
570
|
+
]);
|