@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/index.js
ADDED
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @cloakapi/conformance — programmatic API.
|
|
3
|
+
*
|
|
4
|
+
* A runnable tool a third-party builder points at the RECEIPTS their deployed
|
|
5
|
+
* CloakAPI integration produces, to PROVE the integration behaves correctly.
|
|
6
|
+
* Because CloakAPI is a blind pure-relay (ADR-0014 §3) we can't inspect a
|
|
7
|
+
* builder's server — so conformance is established from the verifiable artifacts
|
|
8
|
+
* (OpenReceipt v3 receipts + declared engine identity), and the report is honest
|
|
9
|
+
* about what it structurally cannot prove.
|
|
10
|
+
*
|
|
11
|
+
* Crypto is reused from @cloakapi/verify-widget (see ./checks.js). This module
|
|
12
|
+
* only orchestrates the checks + fetches the published engine floor.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import {
|
|
16
|
+
STATUS,
|
|
17
|
+
HONEST_LIMITATIONS,
|
|
18
|
+
checkSignatures,
|
|
19
|
+
checkEngineCurrent,
|
|
20
|
+
checkGenuineEngine,
|
|
21
|
+
checkClientSideTokenisation,
|
|
22
|
+
checkSafetyClassifier,
|
|
23
|
+
isCountersignedResult,
|
|
24
|
+
} from './checks.js';
|
|
25
|
+
|
|
26
|
+
export { STATUS, HONEST_LIMITATIONS } from './checks.js';
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Fetch the published engine floor from GET /api/v1/engine/hashes.
|
|
30
|
+
* Content-free + public (no auth). Returns null on failure (caller stays honest).
|
|
31
|
+
* @param {string} apiBase e.g. "https://api.cloakapi.io"
|
|
32
|
+
* @returns {Promise<object|null>}
|
|
33
|
+
*/
|
|
34
|
+
export async function fetchEngineHashes(apiBase = 'https://api.cloakapi.io', { timeoutMs = 8000 } = {}) {
|
|
35
|
+
const url = String(apiBase).replace(/\/$/, '') + '/api/v1/engine/hashes';
|
|
36
|
+
try {
|
|
37
|
+
const res = await fetch(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs) });
|
|
38
|
+
if (!res.ok) return null;
|
|
39
|
+
return await res.json();
|
|
40
|
+
} catch {
|
|
41
|
+
return null;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Run the full conformance suite over a set of receipts / a chain / a
|
|
47
|
+
* countersigned result.
|
|
48
|
+
*
|
|
49
|
+
* @param {object|Array} receipts bare v3 envelope · countersigned result · array (chain)
|
|
50
|
+
* @param {object} [opts]
|
|
51
|
+
* @param {object|null} [opts.engineHashes] a /engine/hashes response object (floor source)
|
|
52
|
+
* @param {string|null} [opts.jwksJson] gateway JWKS text (to also verify a countersignature)
|
|
53
|
+
* @param {string|null} [opts.floorOverride] explicit ruleset floor (skips engineHashes for the floor)
|
|
54
|
+
* @param {string[]|null} [opts.allowlistOverride] explicit engine-hash allowlist
|
|
55
|
+
* @returns {Promise<ConformanceReport>}
|
|
56
|
+
*/
|
|
57
|
+
export async function runConformance(receipts, opts = {}) {
|
|
58
|
+
const { engineHashes = null, jwksJson = null, floorOverride = null, allowlistOverride = null } = opts;
|
|
59
|
+
|
|
60
|
+
const checks = [
|
|
61
|
+
await checkSignatures(receipts, { jwksJson }),
|
|
62
|
+
checkEngineCurrent(receipts, engineHashes, { floorOverride }),
|
|
63
|
+
checkGenuineEngine(receipts, engineHashes, { allowlistOverride }),
|
|
64
|
+
checkClientSideTokenisation(receipts),
|
|
65
|
+
// ⛔ SAK 198 — reports `not-run` as its own status, never `unknown`.
|
|
66
|
+
checkSafetyClassifier(receipts),
|
|
67
|
+
];
|
|
68
|
+
|
|
69
|
+
const failed = checks.filter((c) => c.status === STATUS.FAIL);
|
|
70
|
+
const unknown = checks.filter((c) => c.status === STATUS.UNKNOWN);
|
|
71
|
+
const passed = checks.filter((c) => c.status === STATUS.PASS);
|
|
72
|
+
// ⛔ SAK 198 — `not-run` is KNOWLEDGE, so it is counted separately and
|
|
73
|
+
// never folded into `unknown`. A receipt honestly stating that no
|
|
74
|
+
// classifier ran does not make a run inconclusive, and must not be
|
|
75
|
+
// reported as if we could not tell.
|
|
76
|
+
const notRun = checks.filter((c) => c.status === STATUS.NOT_RUN);
|
|
77
|
+
|
|
78
|
+
// CONFORMANT only if nothing FAILED and at least the signature + tokenisation
|
|
79
|
+
// checks passed (an all-unknown run is inconclusive, never "conformant").
|
|
80
|
+
const sigOk = checks.find((c) => c.id === 'receipt-signatures')?.status === STATUS.PASS;
|
|
81
|
+
const tokOk = checks.find((c) => c.id === 'client-side-tokenisation')?.status === STATUS.PASS;
|
|
82
|
+
const conformant = failed.length === 0 && sigOk && tokOk;
|
|
83
|
+
|
|
84
|
+
return {
|
|
85
|
+
conformant,
|
|
86
|
+
verdict: conformant ? 'CONFORMANT' : failed.length > 0 ? 'NON-CONFORMANT' : 'INCONCLUSIVE',
|
|
87
|
+
counts: {
|
|
88
|
+
pass: passed.length,
|
|
89
|
+
fail: failed.length,
|
|
90
|
+
unknown: unknown.length,
|
|
91
|
+
notRun: notRun.length,
|
|
92
|
+
},
|
|
93
|
+
checks,
|
|
94
|
+
limitations: [...HONEST_LIMITATIONS],
|
|
95
|
+
// Never a "100% safe" claim — surfaced verbatim so callers cannot drop it.
|
|
96
|
+
disclaimer:
|
|
97
|
+
'SELF-ATTESTED conformance (you ran this on your own receipts — not a third-party audit). A CONFORMANT result proves the supplied receipts are cryptographically valid & tamper-evident, the declared engine hash is current and on the published allowlist (a declared hash, not proof of which engine ran), and the receipts contain a client-signed tokenisation claim for egress. It does NOT prove that the detector or claimed engine ran, does NOT prove 100% PII detection, does NOT anchor issuer identity unless the receipts are gateway-countersigned (--jwks), and proves nothing about server internals CloakAPI cannot see.',
|
|
98
|
+
// Whether every included receipt is gateway-anchored (countersigned + JWKS-verified) vs self-signed.
|
|
99
|
+
selfAttested: !(jwksJson && isCountersignedResult(receipts)),
|
|
100
|
+
generatedAt: new Date().toISOString(),
|
|
101
|
+
};
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* @typedef {object} ConformanceCheck
|
|
106
|
+
* @property {string} id
|
|
107
|
+
* @property {string} title
|
|
108
|
+
* @property {'pass'|'fail'|'unknown'|'not-run'} status
|
|
109
|
+
* @property {string} detail
|
|
110
|
+
*/
|
|
111
|
+
/**
|
|
112
|
+
* @typedef {object} ConformanceReport
|
|
113
|
+
* @property {boolean} conformant
|
|
114
|
+
* @property {'CONFORMANT'|'NON-CONFORMANT'|'INCONCLUSIVE'} verdict
|
|
115
|
+
* @property {{pass:number,fail:number,unknown:number,notRun:number}} counts
|
|
116
|
+
* @property {ConformanceCheck[]} checks
|
|
117
|
+
* @property {string[]} limitations
|
|
118
|
+
* @property {string} disclaimer
|
|
119
|
+
* @property {string} generatedAt
|
|
120
|
+
*/
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Type declarations for @cloakapi/verify-widget.
|
|
3
|
+
* The runtime is a single dependency-free ES module (cloakapi-verify.js).
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
export interface VerdictCheck {
|
|
7
|
+
label: string;
|
|
8
|
+
status: 'ok' | 'fail' | 'skip';
|
|
9
|
+
detail: string;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
export interface Verdict {
|
|
13
|
+
ok: boolean;
|
|
14
|
+
status: 'verified' | 'failed';
|
|
15
|
+
tier: string;
|
|
16
|
+
tierLabel: string;
|
|
17
|
+
headline: string;
|
|
18
|
+
detail: string;
|
|
19
|
+
hidden: string[];
|
|
20
|
+
destination: string | null;
|
|
21
|
+
jti: string | null;
|
|
22
|
+
reasons: string[];
|
|
23
|
+
checks: VerdictCheck[];
|
|
24
|
+
verifyLink: string;
|
|
25
|
+
gatewayVerified?: boolean;
|
|
26
|
+
hashBound?: boolean;
|
|
27
|
+
witnessStatus?: GatewayWitnessStatus;
|
|
28
|
+
witnessVersion?: string | null;
|
|
29
|
+
witnessError?: string;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export type GatewayWitnessStatus =
|
|
33
|
+
| 'verified'
|
|
34
|
+
| 'unsupported-version'
|
|
35
|
+
| 'missing'
|
|
36
|
+
| 'invalid-format'
|
|
37
|
+
| 'unverified';
|
|
38
|
+
|
|
39
|
+
export interface CountersignedResult {
|
|
40
|
+
receipt: Record<string, unknown>;
|
|
41
|
+
countersignature?: Record<string, unknown>;
|
|
42
|
+
receipt_hash?: unknown;
|
|
43
|
+
tier?: string;
|
|
44
|
+
anchoring?: unknown;
|
|
45
|
+
[key: string]: unknown;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export function canonicaliseToString(value: unknown): string;
|
|
49
|
+
export function canonicalise(value: unknown): Uint8Array;
|
|
50
|
+
export function parseStrictJson(raw: string): unknown;
|
|
51
|
+
export function receiptHash(signed: unknown): Promise<string>;
|
|
52
|
+
|
|
53
|
+
export function isCountersignedResult(obj: unknown): obj is CountersignedResult;
|
|
54
|
+
export function verifyDeviceReceipt(env: unknown): Promise<{
|
|
55
|
+
ok: boolean;
|
|
56
|
+
reason: string;
|
|
57
|
+
unverifiedFields?: string[];
|
|
58
|
+
}>;
|
|
59
|
+
/** Missing receipt context is rejected at runtime and can never verify a witness. */
|
|
60
|
+
export function verifyGatewaySignature(
|
|
61
|
+
cs: Record<string, unknown>,
|
|
62
|
+
jwksJson: string,
|
|
63
|
+
): Promise<[false, string | null, string?]>;
|
|
64
|
+
export function verifyGatewaySignature(
|
|
65
|
+
cs: Record<string, unknown>,
|
|
66
|
+
jwksJson: string,
|
|
67
|
+
receiptContext: Record<string, unknown>,
|
|
68
|
+
): Promise<[boolean, string | null, string?]>;
|
|
69
|
+
/**
|
|
70
|
+
* A self-attested portal key id or a key matching the receipt's embedded
|
|
71
|
+
* client key is rejected with `countersignature key is a self-attested portal key, not a gateway witness`.
|
|
72
|
+
*/
|
|
73
|
+
export function verifyCountersigned(
|
|
74
|
+
result: CountersignedResult,
|
|
75
|
+
jwksJson: string | null,
|
|
76
|
+
): Promise<{
|
|
77
|
+
deviceVerified: boolean;
|
|
78
|
+
gatewayVerified: boolean;
|
|
79
|
+
hashBound: boolean;
|
|
80
|
+
/** Validity of the inner device receipt schema only. */
|
|
81
|
+
schemaValid: boolean;
|
|
82
|
+
witnessStatus: GatewayWitnessStatus;
|
|
83
|
+
witnessVersion: string | null;
|
|
84
|
+
witnessError?: string;
|
|
85
|
+
tier: string;
|
|
86
|
+
gatewayKid: string | null;
|
|
87
|
+
error?: string;
|
|
88
|
+
unverifiedFields?: string[];
|
|
89
|
+
}>;
|
|
90
|
+
/** Verify raw JSON while rejecting duplicate keys and lossy values before object parsing. */
|
|
91
|
+
export function verifyCountersignedJson(
|
|
92
|
+
raw: string | Uint8Array,
|
|
93
|
+
jwksJson: string | null,
|
|
94
|
+
): ReturnType<typeof verifyCountersigned>;
|
|
95
|
+
/** Verify raw JSON text/UTF-8 bytes without first discarding ambiguous values. */
|
|
96
|
+
export function verifyReceiptJson(
|
|
97
|
+
raw: string | Uint8Array,
|
|
98
|
+
opts?: { jwksJson?: string | null; verifyLink?: string },
|
|
99
|
+
): Promise<Verdict>;
|
|
100
|
+
export function verifyChain(
|
|
101
|
+
receipts: unknown[],
|
|
102
|
+
): Promise<{ ok: boolean; index?: number; reason?: string }>;
|
|
103
|
+
export function verifyReceipt(
|
|
104
|
+
input: unknown,
|
|
105
|
+
opts?: { jwksJson?: string | null; verifyLink?: string },
|
|
106
|
+
): Promise<Verdict>;
|
|
107
|
+
|
|
108
|
+
export function fetchReceiptByJti(jti: string): Promise<unknown>;
|
|
109
|
+
export function fetchJwks(): Promise<string | null>;
|
|
110
|
+
|
|
111
|
+
declare global {
|
|
112
|
+
interface HTMLElementTagNameMap {
|
|
113
|
+
'cloakapi-verify': HTMLElement & {
|
|
114
|
+
receipt: unknown;
|
|
115
|
+
receipts: unknown;
|
|
116
|
+
receiptJson: string | Uint8Array;
|
|
117
|
+
setReceipts(value: unknown): void;
|
|
118
|
+
setReceiptJson(raw: string | Uint8Array): void;
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
}
|