@coderifts/sdk 3.13.2 → 3.13.3

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 (33) hide show
  1. package/dist/cjs/authorize.d.ts +134 -0
  2. package/dist/cjs/authorize.d.ts.map +1 -0
  3. package/dist/cjs/authorize.js +118 -0
  4. package/dist/cjs/authorize.js.map +1 -0
  5. package/dist/cjs/index.d.ts +2 -0
  6. package/dist/cjs/index.d.ts.map +1 -1
  7. package/dist/cjs/index.js +10 -1
  8. package/dist/cjs/index.js.map +1 -1
  9. package/dist/cjs/vendor/receipt-verifier/VENDOR.sha256 +24 -0
  10. package/dist/cjs/vendor/receipt-verifier/arity.js +53 -0
  11. package/dist/cjs/vendor/receipt-verifier/evidence-root.js +188 -0
  12. package/dist/cjs/vendor/receipt-verifier/verified-execution-binding.js +316 -0
  13. package/dist/cjs/vendor/receipt-verifier/verify-evidence.js +410 -0
  14. package/dist/cjs/vendor/receipt-verifier/verify-grant.js +564 -0
  15. package/dist/cjs/vendor/receipt-verifier/verify-prove-transcript.js +72 -0
  16. package/dist/cjs/vendor/receipt-verifier/verify.js +454 -0
  17. package/dist/esm/authorize.d.ts +134 -0
  18. package/dist/esm/authorize.d.ts.map +1 -0
  19. package/dist/esm/authorize.js +114 -0
  20. package/dist/esm/authorize.js.map +1 -0
  21. package/dist/esm/index.d.ts +2 -0
  22. package/dist/esm/index.d.ts.map +1 -1
  23. package/dist/esm/index.js +7 -0
  24. package/dist/esm/index.js.map +1 -1
  25. package/dist/esm/vendor/receipt-verifier/VENDOR.sha256 +24 -0
  26. package/dist/esm/vendor/receipt-verifier/arity.js +53 -0
  27. package/dist/esm/vendor/receipt-verifier/evidence-root.js +188 -0
  28. package/dist/esm/vendor/receipt-verifier/verified-execution-binding.js +316 -0
  29. package/dist/esm/vendor/receipt-verifier/verify-evidence.js +410 -0
  30. package/dist/esm/vendor/receipt-verifier/verify-grant.js +564 -0
  31. package/dist/esm/vendor/receipt-verifier/verify-prove-transcript.js +72 -0
  32. package/dist/esm/vendor/receipt-verifier/verify.js +454 -0
  33. package/package.json +4 -3
@@ -0,0 +1,316 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * verifiedExecutionBinding — the ONE predicate that answers "authorized and committed".
5
+ *
6
+ * ── WHY ONE (1459) ──────────────────────────────────────────────────────────────────────────
7
+ *
8
+ * The same question was being answered in several places with different rules, and the answers
9
+ * disagreed. Measured on the public agent-guard 17.2.0, with a forged-signature grant and a REAL
10
+ * attestation from a trusted executor bound to that grant's jti and scope:
11
+ *
12
+ * ENFORCING_STRICT authorized_and_committed = false
13
+ * ENFORCING_ATOMIC authorized_and_committed = true
14
+ *
15
+ * Two profiles of one product, looking at one set of bytes, reaching opposite conclusions — because
16
+ * the Atomic formula was `receipt_verified && committed && class === 'executor_attested'` and never
17
+ * asked whether the GRANT was signed by anyone. A predicate that is recomputed is a predicate that
18
+ * drifts; this file exists so callers QUOTE the answer instead.
19
+ *
20
+ * ── FOUR AUTHORITIES, AND ONLY THEIR INTERSECTION ───────────────────────────────────────────
21
+ *
22
+ * Each is independently true or not, and each answers a different question. None of them implies
23
+ * another, which is exactly why the intersection — not any one of them — is the success condition:
24
+ *
25
+ * issuer_grant did CodeRifts authorize THIS change? (a signature under a pinned key)
26
+ * executor_attestation did the executor commit THAT grant? (a signature over the grant's ids)
27
+ * one_run_root are these bytes from ONE run? (cr.evidence.root.v1 digests)
28
+ * provider_witness did the provider record it? (a readback — UNSIGNED by nature)
29
+ *
30
+ * ── SHORTFALLS ARE NAMED, NOT FOLDED INTO `false` ───────────────────────────────────────────
31
+ *
32
+ * "Not authorized" and "authorized but the commit is unproven" are different facts with different
33
+ * remedies, and a boolean loses that. Every shortfall gets a state a human can act on, and the
34
+ * states are ORDERED by severity so the returned one is the most serious thing that is wrong.
35
+ *
36
+ * WHAT THIS DOES NOT DO. It reaches no network and holds no keys: every input is supplied by the
37
+ * caller, already-verified or verifiable, and the four authorities are recomputed here from those
38
+ * inputs rather than taken as claims. It also cannot see a lying executor — the root closes
39
+ * third-party splicing, not an executor misreporting its own run.
40
+ */
41
+
42
+ const crypto = require('node:crypto');
43
+
44
+ const { verifyExecutionGrant } = require('./verify-grant.js');
45
+ const { verifyEvidenceRootBinding } = require('./verify-evidence.js');
46
+
47
+ const BINDING_V = 'cr.verified-execution-binding.v1';
48
+
49
+ /**
50
+ * Ordered most-severe first. The returned `state` is the FIRST unmet one, so a caller that renders
51
+ * a single line renders the thing that most needs fixing.
52
+ */
53
+ const STATE = Object.freeze({
54
+ UNAUTHORIZED: 'UNAUTHORIZED',
55
+ COMMIT_UNPROVEN: 'COMMIT_UNPROVEN',
56
+ ONE_RUN_UNPROVEN: 'ONE_RUN_UNPROVEN',
57
+ RECORDED_UNWITNESSED: 'RECORDED_UNWITNESSED',
58
+ NOT_COMMITTED: 'NOT_COMMITTED',
59
+ AUTHORIZED_AND_COMMITTED: 'AUTHORIZED_AND_COMMITTED',
60
+ });
61
+
62
+ /** What each authority is allowed to be missing for, so a caller can choose its own strictness. */
63
+ const AUTHORITY = Object.freeze({
64
+ ISSUER_GRANT: 'issuer_grant',
65
+ EXECUTOR_ATTESTATION: 'executor_attestation',
66
+ ONE_RUN_ROOT: 'one_run_root',
67
+ PROVIDER_WITNESS: 'provider_witness',
68
+ });
69
+
70
+ const sha256pref = (v) =>
71
+ `sha256:${crypto.createHash('sha256').update(String(v), 'utf8').digest('hex')}`;
72
+
73
+ const b64json = (seg) => {
74
+ try { return JSON.parse(Buffer.from(seg, 'base64url').toString('utf8')); } catch (_) { return null; }
75
+ };
76
+
77
+ /** The four fields an attestation binds, read from its own signed preimage. */
78
+ function attestationClaims(token) {
79
+ if (typeof token !== 'string') return null;
80
+ const seg = token.split('|');
81
+ if (seg.length !== 4 || !seg[2]) return null;
82
+ const body = b64json(seg[2]);
83
+ return body && typeof body === 'object' ? body : null;
84
+ }
85
+
86
+ /** The grant's identity, in one vocabulary across v1 and v2. */
87
+ function grantClaims(token) {
88
+ if (typeof token !== 'string') return null;
89
+ const body = b64json(String(token).split('.')[0]);
90
+ if (!body || typeof body !== 'object') return null;
91
+ return {
92
+ v: body.v,
93
+ jti: body.grant_id || body.jti || null,
94
+ scope_hash: body.after_payload_hash || body.scope_hash || null,
95
+ receipt_hash: body.receipt_hash || body.receipt_digest || null,
96
+ operation: body.operation || null,
97
+ // The rest of what a grant SAYS, so the attestation can be checked against all of it rather
98
+ // than against the two fields that happened to be compared first.
99
+ target: body.target_uri || body.target_id || null,
100
+ tenant_id: body.tenant_id || null,
101
+ executor_id: body.executor_id || null,
102
+ adapter_id: body.adapter_id || null,
103
+ audience: body.audience_hash || body.audience || null,
104
+ policy_hash: body.policy_hash || null,
105
+ state_token: body.expected_state_token || body.state_nonce || null,
106
+ };
107
+ }
108
+
109
+ /**
110
+ * @param {object} o
111
+ * @param {{verified: boolean, token?: string}} o.receipt
112
+ * @param {{token: string, publicKey?, keyring?, intended?: object, now?: number}} o.grant
113
+ * THE EXACT BYTES THE ISSUER SIGNED. Not a grant read back out of a tool result: a caller
114
+ * that lets the executed tool hand back its own authorization has already lost.
115
+ * @param {{token: string, registry?: object, verify?: Function}} [o.attestation]
116
+ * @param {{artifact: object, executorKey}} [o.evidenceRoot]
117
+ * @param {{signed: boolean}} [o.providerReadback]
118
+ * @param {boolean} o.committed
119
+ * @param {string[]} [o.required] authorities this caller demands; default: grant + attestation.
120
+ */
121
+ function verifiedExecutionBinding(o = {}) {
122
+ const required = new Set(Array.isArray(o.required) && o.required.length
123
+ ? o.required
124
+ : [AUTHORITY.ISSUER_GRANT, AUTHORITY.EXECUTOR_ATTESTATION]);
125
+ const shortfalls = [];
126
+ const authorities = {};
127
+ const note = (name, ok, detail) => {
128
+ authorities[name] = { ok, required: required.has(name), detail };
129
+ if (!ok && required.has(name)) shortfalls.push(`${name}: ${detail}`);
130
+ return ok;
131
+ };
132
+
133
+ // ── 1. THE ISSUER GRANT ────────────────────────────────────────────────────────────────
134
+ const g = o.grant || {};
135
+ let grantOk = false;
136
+ let gClaims = null;
137
+ if (typeof g.token !== 'string' || g.token.length === 0) {
138
+ note(AUTHORITY.ISSUER_GRANT, false, 'no execution grant was supplied');
139
+ } else if (!g.publicKey && !g.keyring) {
140
+ // FAIL-CLOSED, and named as its own thing: "we had no key" is not "the signature was bad".
141
+ note(AUTHORITY.ISSUER_GRANT, false,
142
+ 'no pinned issuer keyring was supplied, so the grant could not be authenticated');
143
+ } else {
144
+ const r = verifyExecutionGrant(g.token, {
145
+ ctx: { publicKey: g.publicKey, keyring: g.keyring, expectedKid: g.expectedKid ?? null },
146
+ ...(g.intended ? { intended: g.intended } : {}),
147
+ ...(Number.isFinite(g.now) ? { now: g.now } : {}),
148
+ });
149
+ gClaims = grantClaims(g.token);
150
+ grantOk = note(AUTHORITY.ISSUER_GRANT, r.valid === true,
151
+ `${r.status}${r.reason ? `/${r.reason}` : ''}`);
152
+ }
153
+
154
+ // ── 2. THE EXECUTOR ATTESTATION ────────────────────────────────────────────────────────
155
+ const a = o.attestation || {};
156
+ let attOk = false;
157
+ if (typeof a.token !== 'string' || a.token.length === 0) {
158
+ note(AUTHORITY.EXECUTOR_ATTESTATION, false, 'no executor attestation was supplied');
159
+ } else if (typeof a.verify !== 'function') {
160
+ note(AUTHORITY.EXECUTOR_ATTESTATION, false,
161
+ 'no attestation verifier was supplied, so the commit could not be checked');
162
+ } else {
163
+ const r = a.verify(a.token, { registry: a.registry });
164
+ const sigOk = r && r.valid === true;
165
+ // BOUND TO THE VERIFIED GRANT'S OWN IDS — not to ids the caller passed alongside. This is the
166
+ // join that makes the two signatures one statement instead of two unrelated true things.
167
+ const c = attestationClaims(a.token);
168
+ // ── THE ATTESTATION MUST BIND THE SAME EXECUTION, NOT MERELY THE SAME NAMES (1464) ────
169
+ //
170
+ // REPRODUCED before this was written. A correctly-signed grant bound to receipt R1, and a
171
+ // correctly-signed attestation from a trusted executor bound to receipt R2, sharing a
172
+ // grant_jti and a scope_hash — R1 != R2 — read AUTHORIZED_AND_COMMITTED. Both signatures are
173
+ // real; the two documents describe DIFFERENT executions and the join could not tell.
174
+ //
175
+ // `jti` and `scope_hash` are the two fields an attacker controls most cheaply: they are copied
176
+ // FROM the grant into the attestation by whoever assembles the pair. Comparing only those is
177
+ // comparing a value with its own copy. What binds is the receipt each side was issued against,
178
+ // and — the strongest available — the sha256 of the exact grant token bytes.
179
+ const attReceipt = c ? String(c.receipt_digest || '') : '';
180
+ const grantReceipt = gClaims ? String(gClaims.receipt_hash || '') : '';
181
+ const mismatch = (() => {
182
+ if (!sigOk) return `attestation ${r ? r.status : 'unverifiable'}`;
183
+ if (!gClaims) return 'there is no verified grant for the attestation to bind';
184
+ if (String(c.grant_jti || '') !== String(gClaims.jti || '')) {
185
+ return 'the attestation binds a different grant id than the verified grant';
186
+ }
187
+ if (String(c.scope_hash || '') !== String(gClaims.scope_hash || '')) {
188
+ return 'the attestation binds a different scope than the verified grant';
189
+ }
190
+ // THE CROSS-RECEIPT CHECK. Empty on either side is a mismatch: an attestation that names no
191
+ // receipt cannot be shown to be about this authorization, and "unstated" must not read as
192
+ // "the same".
193
+ if (!attReceipt || !grantReceipt || attReceipt !== grantReceipt) {
194
+ return `the grant was issued against receipt ${grantReceipt || '(none)'} and the `
195
+ + `attestation commits receipt ${attReceipt || '(none)'} — two different executions`;
196
+ }
197
+ // ── WHAT cr.exec.attest.v1 CAN AND CANNOT BE ASKED ──────────────────────────────
198
+ //
199
+ // MEASURED, and it bounds this check rather than the check bounding the format: the
200
+ // attestation body is a CLOSED set — executor_kid, grant_jti, receipt_digest, scope_hash,
201
+ // committed_at, state_nonce, result_digest, meta. Any other key is refused
202
+ // ATTEST_MALFORMED / unknown_field by its own verifier.
203
+ //
204
+ // So target, operation, tenant, executor, adapter, audience and policy CANNOT be
205
+ // cross-checked here: the attestation never states them, and a comparison against a field
206
+ // that cannot exist is not a check — it is a line that always passes. They are named in
207
+ // `does_not_prove` instead, which is the honest place for a binding the format cannot carry.
208
+ //
209
+ // The same is true of the exact grant-token digest: there is no field for it. Binding the
210
+ // grant BYTES rather than its claims would be the tightest join available and it needs a
211
+ // format change (a `grant_token_digest` slot in cr.exec.attest.v2), not a check here.
212
+ //
213
+ // What the format DOES let us bind is the state nonce, and it is bound below.
214
+ if (gClaims.state_token != null && c.state_nonce != null
215
+ && String(gClaims.state_token) !== String(c.state_nonce)) {
216
+ return 'the grant and the attestation disagree about the state nonce';
217
+ }
218
+ return null;
219
+ })();
220
+ attOk = note(AUTHORITY.EXECUTOR_ATTESTATION, mismatch === null, mismatch || 'bound');
221
+ }
222
+
223
+ // ── 3. ONE RUN ─────────────────────────────────────────────────────────────────────────
224
+ const er = o.evidenceRoot || null;
225
+ if (!er || !er.artifact) {
226
+ note(AUTHORITY.ONE_RUN_ROOT, false,
227
+ 'no cr.evidence.root.v1 was supplied, so these bytes are not shown to be one run');
228
+ } else {
229
+ const r = verifyEvidenceRootBinding(er.artifact, { executorKey: er.executorKey, sidecars: er.sidecars });
230
+ note(AUTHORITY.ONE_RUN_ROOT, r.ok === true, r.ok ? 'bound' : (r.failures[0] || 'unbound'));
231
+ }
232
+
233
+ // ── 4. THE PROVIDER WITNESS ────────────────────────────────────────────────────────────
234
+ // A readback is an UNSIGNED document by nature. It is carried, not verified, and this authority
235
+ // is false unless a caller states it was witnessed some stronger way — never true by default.
236
+ // ── A CALLER BOOLEAN IS NOT EVIDENCE (1465) ────────────────────────────────────────────
237
+ //
238
+ // REPRODUCED before this was written:
239
+ //
240
+ // required: ['provider_witness'], receipt: {verified: true},
241
+ // providerReadback: {signed: true}, committed: true, NO grant, NO attestation, NO root
242
+ // → AUTHORIZED_AND_COMMITTED, shortfalls: []
243
+ //
244
+ // `signed: true` was a bare boolean the caller wrote, and this function aggregated it into a
245
+ // global success. Nothing was verified; a field named `signed` was believed because it was set.
246
+ //
247
+ // A witness now requires a VERIFIED witness envelope: bytes plus a verifier plus a trust anchor.
248
+ // No such format exists yet (phase D measured that the readback is unsigned by nature), so this
249
+ // authority cannot currently be satisfied at all — and saying that plainly is the honest answer.
250
+ // Asking for it yields RECORDED_UNWITNESSED, which is exactly what it means.
251
+ //
252
+ // NOT a breaking change for the five consumers: none of them requires `provider_witness` today
253
+ // (guard and contract-gate ask for issuer_grant + executor_attestation; prove and conformance for
254
+ // issuer_grant + one_run_root). It removes a way to LIE, not a way anyone works.
255
+ const pw = o.providerReadback || null;
256
+ const witnessVerified = !!(pw && pw.verified === true && pw.envelope && pw.verifier);
257
+ note(AUTHORITY.PROVIDER_WITNESS, witnessVerified,
258
+ pw
259
+ ? (pw.signed === true && !witnessVerified
260
+ ? 'the caller asserted `signed: true` and supplied no verifiable witness envelope — a '
261
+ + 'boolean is not evidence, and no signed-witness format exists yet'
262
+ : 'the provider readback is an unsigned document (carried, not verified)')
263
+ : 'no provider readback was supplied');
264
+
265
+ // ── THE INTERSECTION ───────────────────────────────────────────────────────────────────
266
+ const committed = o.committed === true;
267
+ // THE RECEIPT, and what this function can honestly say about it.
268
+ //
269
+ // `verified` is the CALLER's determination: this core is not given the receipt token or a
270
+ // keyring, so it cannot re-establish it. That is recorded rather than hidden — a reader of the
271
+ // result can see whether the receipt was verified HERE or asserted by whoever called.
272
+ //
273
+ // Left as-is deliberately: making a bare boolean insufficient would change the input shape of
274
+ // all five consumers at once, and that belongs with the closed-profile work (1465), not
275
+ // half-done in a round that would leave them broken. The gap is named, not narrowed in silence.
276
+ const receiptOk = !!(o.receipt && o.receipt.verified === true);
277
+ const receiptAsserted = receiptOk && !(o.receipt.token && (o.receipt.keyring || o.receipt.publicKey));
278
+ if (!receiptOk) shortfalls.unshift('receipt: the decision receipt did not verify');
279
+
280
+ let state = STATE.AUTHORIZED_AND_COMMITTED;
281
+ if (!receiptOk || (required.has(AUTHORITY.ISSUER_GRANT) && !grantOk)) state = STATE.UNAUTHORIZED;
282
+ else if (required.has(AUTHORITY.EXECUTOR_ATTESTATION) && !attOk) state = STATE.COMMIT_UNPROVEN;
283
+ else if (required.has(AUTHORITY.ONE_RUN_ROOT) && !authorities[AUTHORITY.ONE_RUN_ROOT].ok) {
284
+ state = STATE.ONE_RUN_UNPROVEN;
285
+ } else if (required.has(AUTHORITY.PROVIDER_WITNESS) && !authorities[AUTHORITY.PROVIDER_WITNESS].ok) {
286
+ state = STATE.RECORDED_UNWITNESSED;
287
+ } else if (!committed) state = STATE.NOT_COMMITTED;
288
+
289
+ return {
290
+ v: BINDING_V,
291
+ authorized_and_committed: state === STATE.AUTHORIZED_AND_COMMITTED,
292
+ state,
293
+ authorities,
294
+ shortfalls,
295
+ /** True when `receipt.verified` was taken on the caller's word rather than established here. */
296
+ receipt_caller_asserted: receiptAsserted,
297
+ // Said out loud so a caller cannot read success as more than it is.
298
+ does_not_prove: [
299
+ 'that the executor told the truth about its own run — the evidence root closes third-party '
300
+ + 'splicing, not an executor misreporting itself',
301
+ 'that a provider merged anything; `provider_witness` is an unsigned readback unless a caller '
302
+ + 'states otherwise',
303
+ 'that the grant and the attestation agree about target, operation, tenant, executor, adapter, '
304
+ + 'audience or policy — cr.exec.attest.v1 is a closed field set that states none of them, so '
305
+ + 'those are UNCHECKED here rather than checked and equal (1464)',
306
+ 'that the attestation commits the exact grant BYTES — the format carries no grant-token '
307
+ + 'digest, so the join is over the grant id, scope, receipt and state nonce',
308
+ ...(receiptAsserted
309
+ ? ['that the decision receipt verifies — `receipt.verified` was asserted by the caller and '
310
+ + 'not established here; this core is given no receipt token or keyring to check it with']
311
+ : []),
312
+ ],
313
+ };
314
+ }
315
+
316
+ module.exports = { verifiedExecutionBinding, STATE, AUTHORITY, BINDING_V, grantClaims, attestationClaims };