@coderifts/sdk 3.13.3 → 3.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/README.md +49 -0
  2. package/dist/cjs/authorize.d.ts +46 -4
  3. package/dist/cjs/authorize.d.ts.map +1 -1
  4. package/dist/cjs/authorize.js +22 -1
  5. package/dist/cjs/authorize.js.map +1 -1
  6. package/dist/cjs/client.d.ts +31 -3
  7. package/dist/cjs/client.d.ts.map +1 -1
  8. package/dist/cjs/client.js +35 -5
  9. package/dist/cjs/client.js.map +1 -1
  10. package/dist/cjs/index.d.ts +2 -0
  11. package/dist/cjs/index.d.ts.map +1 -1
  12. package/dist/cjs/index.js +13 -1
  13. package/dist/cjs/index.js.map +1 -1
  14. package/dist/cjs/vendor/package.json +1 -0
  15. package/dist/cjs/vendor/receipt-verifier/VENDOR.sha256 +20 -3
  16. package/dist/cjs/vendor/receipt-verifier/verified-execution-binding.js +202 -11
  17. package/dist/cjs/vendor/receipt-verifier/verify-grant.js +34 -1
  18. package/dist/cjs/vendor/receipt-verifier/verify.d.ts +31 -0
  19. package/dist/cjs/verify-receipt-local.d.ts +69 -0
  20. package/dist/cjs/verify-receipt-local.d.ts.map +1 -0
  21. package/dist/cjs/verify-receipt-local.js +103 -0
  22. package/dist/cjs/verify-receipt-local.js.map +1 -0
  23. package/dist/esm/authorize.d.ts +46 -4
  24. package/dist/esm/authorize.d.ts.map +1 -1
  25. package/dist/esm/authorize.js +22 -1
  26. package/dist/esm/authorize.js.map +1 -1
  27. package/dist/esm/client.d.ts +31 -3
  28. package/dist/esm/client.d.ts.map +1 -1
  29. package/dist/esm/client.js +35 -5
  30. package/dist/esm/client.js.map +1 -1
  31. package/dist/esm/index.d.ts +2 -0
  32. package/dist/esm/index.d.ts.map +1 -1
  33. package/dist/esm/index.js +11 -0
  34. package/dist/esm/index.js.map +1 -1
  35. package/dist/esm/vendor/package.json +1 -0
  36. package/dist/esm/vendor/receipt-verifier/VENDOR.sha256 +20 -3
  37. package/dist/esm/vendor/receipt-verifier/verified-execution-binding.js +202 -11
  38. package/dist/esm/vendor/receipt-verifier/verify-grant.js +34 -1
  39. package/dist/esm/vendor/receipt-verifier/verify.d.ts +31 -0
  40. package/dist/esm/verify-receipt-local.d.ts +69 -0
  41. package/dist/esm/verify-receipt-local.d.ts.map +1 -0
  42. package/dist/esm/verify-receipt-local.js +97 -0
  43. package/dist/esm/verify-receipt-local.js.map +1 -0
  44. package/package.json +1 -1
@@ -58,6 +58,35 @@ const V2_REQUIRED_STRINGS = Object.freeze([
58
58
  'operation', 'target_uri', 'expected_state_token', 'after_payload_hash',
59
59
  'nonce_hash', 'policy_hash', 'audience_hash', 'not_before', 'expires_at',
60
60
  ]);
61
+ /**
62
+ * RESERVED, AND INERT. Optional v2 fields a grant MAY carry and this verifier reads as NOTHING.
63
+ *
64
+ * ── WHY THEY EXIST BEFORE THE GATE THAT USES THEM ───────────────────────────────────────────
65
+ *
66
+ * The admitted key set is closed: an unknown field is `MALFORMED/unknown_field`, which is the
67
+ * right default and also means a future field cannot be introduced without every deployed
68
+ * verifier refusing the grants that carry it. Reserving the two names now is what keeps that
69
+ * introduction from being a breaking change later.
70
+ *
71
+ * ── WHAT THEY DO NOT DO, WHICH IS THE POINT ─────────────────────────────────────────────────
72
+ *
73
+ * NOTHING. A grant carrying `call_hash` is graded EXACTLY as one without it. There is no check,
74
+ * no comparison, and no `intended` field they bind to.
75
+ *
76
+ * A VERIFIER THAT READS THEIR PRESENCE AS AUTHORIZATION IS WRONG. `call_hash` present does not
77
+ * mean a tool call was bound; `executor_image_digest` present does not mean an executor image was
78
+ * pinned. Nothing signs a promise that the value is true, nothing compares it to anything, and an
79
+ * attacker who can mint a grant can put any value in them. Presence is not proof — it is a slot.
80
+ *
81
+ * They are unsigned-by-default only in the sense that no separate signature covers them: the v2
82
+ * signing input is the canonical JSON of the WHOLE body, so a grant that carries them signs
83
+ * different bytes than one that does not, and neither can be edited into the other. That binds
84
+ * the VALUE to the issuer; it says nothing about whether the value means anything.
85
+ *
86
+ * When a gate for them lands it will be a NEW check with its own negative fixtures, and this
87
+ * comment is what a reader should be shown if anyone claims otherwise before then.
88
+ */
89
+ const V2_RESERVED_INERT = Object.freeze(['call_hash', 'executor_image_digest']);
61
90
  const TARGET_SCHEMES = Object.freeze(['fs', 'git', 'api', 'db', 'registry', 'deploy']);
62
91
  const DEFAULT_FETCH_URL = 'https://app.coderifts.com/api/v1/attestation/public-key';
63
92
 
@@ -177,7 +206,9 @@ function verifyExecutionGrantV2(payload, sigB64, ctx, opts = {}) {
177
206
  if (!Number.isInteger(payload.max_attempts) || payload.max_attempts < 1) {
178
207
  return { valid: false, status: 'MALFORMED', reason: 'bad_max_attempts', payload };
179
208
  }
180
- const allowed = new Set([...V2_REQUIRED_STRINGS, 'max_attempts']);
209
+ // The reserved names are ADMITTED, never inspected. Everything below this line treats a payload
210
+ // carrying them identically to one that does not — verified by test, not by intent.
211
+ const allowed = new Set([...V2_REQUIRED_STRINGS, 'max_attempts', ...V2_RESERVED_INERT]);
181
212
  for (const k of Object.keys(payload)) {
182
213
  if (!allowed.has(k)) return { valid: false, status: 'MALFORMED', reason: 'unknown_field', payload };
183
214
  }
@@ -555,6 +586,8 @@ module.exports = {
555
586
  SIGNING_PREFIX_V2,
556
587
  SIGNED_FIELDS,
557
588
  V1_OPTIONAL_SIGNED_FIELDS,
589
+ V2_REQUIRED_STRINGS,
590
+ V2_RESERVED_INERT,
558
591
  CLOCK_SKEW_LEEWAY_MS,
559
592
  isIssuedInFuture,
560
593
  };
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Types for the vendored `verify.js`, written HERE rather than in the vendored file.
3
+ *
4
+ * The vendored bytes must stay byte-identical to receipt-verifier's — a pin that survives an edit
5
+ * is not a pin — so the declaration lives beside them instead of inside them.
6
+ *
7
+ * Only the two entry points this SDK uses are declared. Declaring the rest would invite callers to
8
+ * reach into the core through this package, and the core is vendored for internal use, not
9
+ * re-exported as an API this SDK then owns.
10
+ */
11
+ export interface CoreReceiptVerdict {
12
+ valid: boolean;
13
+ status: string;
14
+ reason?: string;
15
+ payload?: Record<string, unknown>;
16
+ }
17
+ /**
18
+ * The DEFAULT export — `module.exports` whole.
19
+ *
20
+ * Declared this way because node's cjs-module-lexer does not surface every name on this module to
21
+ * an ESM importer (measured: `verifyReceipt` yes, `keyringFromDocument` no). Named declarations
22
+ * here would type-check and then fail at load in the ESM build.
23
+ */
24
+ declare const core: {
25
+ verifyReceipt(
26
+ token: string,
27
+ opts: { ctx: { keyring: unknown; expectedKid: string | null }; now?: number },
28
+ ): CoreReceiptVerdict;
29
+ keyringFromDocument(doc: unknown): Map<string, unknown> | { byKid: Map<string, unknown> };
30
+ };
31
+ export default core;
@@ -0,0 +1,69 @@
1
+ /**
2
+ * LOCAL receipt verification — the proof, and the only thing on this surface that is one.
3
+ *
4
+ * ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
5
+ *
6
+ * MEASURED before it was written: this SDK's only `verifyReceipt` was
7
+ * `client.verifyReceipt()` — an HTTP POST to `/api/v1/verify-receipt`. It answers well and it is
8
+ * useful, and it is not an offline verification: the caller learns what CodeRifts says, over a
9
+ * network, about bytes CodeRifts was handed. A reader told "verify offline, without us" and given
10
+ * only that method has been told something the package could not do.
11
+ *
12
+ * This runs the SAME vendored core the public receipt-verifier and the conformance CLI run, in
13
+ * process, over bytes already in memory plus a keyring the CALLER supplies. No API key, no
14
+ * network, full Ed25519.
15
+ *
16
+ * ── WHAT IT IS NOT ──────────────────────────────────────────────────────────────────────────
17
+ *
18
+ * It is not authorization. A valid signature says a holder of the named key signed these bytes and
19
+ * that the receipt has not expired; it does not say the receipt permits the action you are about
20
+ * to take. `client.verifyReceipt(token, intended)` answers that second question, on the server,
21
+ * and `authorize()` answers the execution-binding one. Those are different questions and this
22
+ * module deliberately answers only the first.
23
+ *
24
+ * It also cannot see REVOCATION or the issuer's clock. A key compromised five minutes ago still
25
+ * verifies here, because nothing local can know. That is the whole reason
26
+ * `verifyReceiptViaServer` exists beside it — as a mirror, never as the proof.
27
+ */
28
+ import type { PinnedKeyring } from './authorize.js';
29
+ /** The verdict, in the vocabulary the receipt-verifier and the conformance CLI already use. */
30
+ export interface LocalReceiptVerdict {
31
+ /** True only when the signature verified against the pinned key and the receipt is current. */
32
+ valid: boolean;
33
+ /** VERIFIED_CURRENT · INVALID_SIGNATURE · MALFORMED · UNKNOWN_KEY · EXPIRED · … */
34
+ status: string;
35
+ /** Present on a refusal; the specific cause, not a class. */
36
+ reason?: string;
37
+ /** The decoded body, when the token decoded at all. Never evidence on its own. */
38
+ payload?: Record<string, unknown>;
39
+ /**
40
+ * Said on every result, so a caller cannot read this as more than it is.
41
+ *
42
+ * A verdict that travels without its ceiling gets quoted without it.
43
+ */
44
+ does_not_prove: string[];
45
+ }
46
+ export interface VerifyReceiptLocalOptions {
47
+ /**
48
+ * THE KEYS YOU PIN, and the reason this is required rather than fetched.
49
+ *
50
+ * A verifier that downloads the key it is about to trust has not verified anything an attacker
51
+ * on the path could not arrange. Fetching the keyring is a deployment decision — make it once,
52
+ * pin the result, and hand it in.
53
+ */
54
+ keyring: PinnedKeyring;
55
+ /** Refuse a token whose `kid` is not this one. Null (default) accepts any pinned kid. */
56
+ expectedKid?: string | null;
57
+ /** Clock injection. Absent = the host clock. */
58
+ now?: number;
59
+ }
60
+ /**
61
+ * Verify a chain receipt LOCALLY. No network, no API key, full Ed25519.
62
+ *
63
+ * @example
64
+ * import { verifyReceipt } from '@coderifts/sdk';
65
+ * const r = verifyReceipt(token, { keyring: pinnedKeys });
66
+ * if (!r.valid) throw new Error(`${r.status}: ${r.reason}`);
67
+ */
68
+ export declare function verifyReceipt(token: string, options: VerifyReceiptLocalOptions): LocalReceiptVerdict;
69
+ //# sourceMappingURL=verify-receipt-local.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"verify-receipt-local.d.ts","sourceRoot":"","sources":["../../src/verify-receipt-local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAkBpD,+FAA+F;AAC/F,MAAM,WAAW,mBAAmB;IAChC,+FAA+F;IAC/F,KAAK,EAAE,OAAO,CAAC;IACf,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;;OAIG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,yBAAyB;IACtC;;;;;;OAMG;IACH,OAAO,EAAE,aAAa,CAAC;IACvB,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAmCD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CACzB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,yBAAyB,GACnC,mBAAmB,CAarB"}
@@ -0,0 +1,97 @@
1
+ /**
2
+ * LOCAL receipt verification — the proof, and the only thing on this surface that is one.
3
+ *
4
+ * ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
5
+ *
6
+ * MEASURED before it was written: this SDK's only `verifyReceipt` was
7
+ * `client.verifyReceipt()` — an HTTP POST to `/api/v1/verify-receipt`. It answers well and it is
8
+ * useful, and it is not an offline verification: the caller learns what CodeRifts says, over a
9
+ * network, about bytes CodeRifts was handed. A reader told "verify offline, without us" and given
10
+ * only that method has been told something the package could not do.
11
+ *
12
+ * This runs the SAME vendored core the public receipt-verifier and the conformance CLI run, in
13
+ * process, over bytes already in memory plus a keyring the CALLER supplies. No API key, no
14
+ * network, full Ed25519.
15
+ *
16
+ * ── WHAT IT IS NOT ──────────────────────────────────────────────────────────────────────────
17
+ *
18
+ * It is not authorization. A valid signature says a holder of the named key signed these bytes and
19
+ * that the receipt has not expired; it does not say the receipt permits the action you are about
20
+ * to take. `client.verifyReceipt(token, intended)` answers that second question, on the server,
21
+ * and `authorize()` answers the execution-binding one. Those are different questions and this
22
+ * module deliberately answers only the first.
23
+ *
24
+ * It also cannot see REVOCATION or the issuer's clock. A key compromised five minutes ago still
25
+ * verifies here, because nothing local can know. That is the whole reason
26
+ * `verifyReceiptViaServer` exists beside it — as a mirror, never as the proof.
27
+ */
28
+ // ── A STATIC IMPORT, AND THAT IS THE POINT ──────────────────────────────────────────────────
29
+ //
30
+ // MEASURED on the built package: `authorize()` loads the same core with a bare `require(...)`, and
31
+ // `dist/esm/authorize.js` therefore throws `require is not defined` for every ESM consumer. The
32
+ // tests never saw it because they load the CJS source. A call-time `require` is invisible to the
33
+ // compiler in exactly the build where it cannot work.
34
+ //
35
+ // A static import is compiled to `require` for the CJS output and left as an import for the ESM
36
+ // one, so this module works in both — and the compiler, not a runtime, is what checks it.
37
+ //
38
+ // The DEFAULT import, not named ones. MEASURED on the built ESM package: node's cjs-module-lexer
39
+ // resolved `verifyReceipt` from the vendored CommonJS and NOT `keyringFromDocument`, so a named
40
+ // import compiled fine and threw at load time — "does not provide an export named". Taking
41
+ // `module.exports` whole and destructuring at runtime is interop that does not depend on a lexer
42
+ // guessing right about bytes this package is forbidden to edit.
43
+ import core from './vendor/receipt-verifier/verify.js';
44
+ const DOES_NOT_PROVE = Object.freeze([
45
+ 'that the receipt AUTHORIZES the action you are about to take — a valid signature is '
46
+ + 'authenticity, not authorization. Pass an intended context to the server verify, or use '
47
+ + 'authorize() for the execution binding',
48
+ 'that the signing key is still trusted — REVOCATION and the issuer\'s clock are not visible '
49
+ + 'to any local verifier, including this one. A key compromised a minute ago still verifies here',
50
+ 'that the bytes came from the run you think they did — this checks ONE token, and "these '
51
+ + 'tokens are one run" is a property of a set (see cr.evidence.root.v1)',
52
+ ]);
53
+ function toKeyringMap(keyring) {
54
+ if (!keyring || !Array.isArray(keyring.keys) || keyring.keys.length === 0) {
55
+ throw new TypeError('verifyReceipt: a keyring with at least one key is required — this '
56
+ + 'verifier does not fetch keys, because a verifier that downloads the key it is about '
57
+ + 'to trust has verified nothing an attacker on the path could not arrange');
58
+ }
59
+ // THE CORE'S OWN keyring parser, not a second one written here.
60
+ //
61
+ // `keyringFromDocument` is the function the receipt-verifier CLI and the conformance measure
62
+ // both use. Re-implementing the parse in this file would be a second idea of what a keyring
63
+ // is — the exact shape 1423 came from, where conformance had its own notion of checking and it
64
+ // was weaker than prove's.
65
+ const parsed = core.keyringFromDocument(keyring);
66
+ // The core returns either a Map or a `{ byKid }` wrapper depending on the document shape it
67
+ // was handed. Both are accepted here rather than the caller being told which to produce.
68
+ const m = (parsed && parsed.byKid)
69
+ || parsed;
70
+ if (!m || typeof m.get !== 'function' || m.size === 0) {
71
+ throw new TypeError('verifyReceipt: the keyring contained no usable {kid, public_key_pem}');
72
+ }
73
+ return m;
74
+ }
75
+ /**
76
+ * Verify a chain receipt LOCALLY. No network, no API key, full Ed25519.
77
+ *
78
+ * @example
79
+ * import { verifyReceipt } from '@coderifts/sdk';
80
+ * const r = verifyReceipt(token, { keyring: pinnedKeys });
81
+ * if (!r.valid) throw new Error(`${r.status}: ${r.reason}`);
82
+ */
83
+ export function verifyReceipt(token, options) {
84
+ const ring = toKeyringMap(options && options.keyring);
85
+ const r = core.verifyReceipt(token, {
86
+ ctx: { keyring: ring, expectedKid: options.expectedKid ?? null },
87
+ ...(Number.isFinite(options.now) ? { now: options.now } : {}),
88
+ });
89
+ return {
90
+ valid: r.valid === true,
91
+ status: r.status,
92
+ ...(r.reason ? { reason: r.reason } : {}),
93
+ ...(r.payload ? { payload: r.payload } : {}),
94
+ does_not_prove: [...DOES_NOT_PROVE],
95
+ };
96
+ }
97
+ //# sourceMappingURL=verify-receipt-local.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"verify-receipt-local.js","sourceRoot":"","sources":["../../src/verify-receipt-local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,+FAA+F;AAC/F,EAAE;AACF,mGAAmG;AACnG,gGAAgG;AAChG,iGAAiG;AACjG,sDAAsD;AACtD,EAAE;AACF,gGAAgG;AAChG,0FAA0F;AAC1F,EAAE;AACF,iGAAiG;AACjG,gGAAgG;AAChG,2FAA2F;AAC3F,iGAAiG;AACjG,gEAAgE;AAChE,OAAO,IAAI,MAAM,qCAAqC,CAAC;AAmCvD,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IACjC,sFAAsF;UACpF,yFAAyF;UACzF,uCAAuC;IACzC,6FAA6F;UAC3F,+FAA+F;IACjG,0FAA0F;UACxF,sEAAsE;CAC3E,CAAC,CAAC;AAEH,SAAS,YAAY,CAAC,OAAsB;IACxC,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,SAAS,CAAC,oEAAoE;cAClF,sFAAsF;cACtF,yEAAyE,CAAC,CAAC;IACrF,CAAC;IACD,gEAAgE;IAChE,EAAE;IACF,6FAA6F;IAC7F,4FAA4F;IAC5F,+FAA+F;IAC/F,2BAA2B;IAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACjD,4FAA4F;IAC5F,yFAAyF;IACzF,MAAM,CAAC,GAAG,CAAC,MAAM,IAAK,MAA2C,CAAC,KAAK,CAAC;WAChE,MAA+B,CAAC;IACxC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,GAAG,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,SAAS,CAAC,sEAAsE,CAAC,CAAC;IAChG,CAAC;IACD,OAAO,CAAC,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CACzB,KAAa,EACb,OAAkC;IAElC,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD,MAAM,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE;QAChC,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI,EAAE;QAChE,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChE,CAAC,CAAC;IACH,OAAO;QACH,KAAK,EAAE,CAAC,CAAC,KAAK,KAAK,IAAI;QACvB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,cAAc,EAAE,CAAC,GAAG,cAAc,CAAC;KACtC,CAAC;AACN,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@coderifts/sdk",
3
- "version": "3.13.3",
3
+ "version": "3.14.0",
4
4
  "description": "Agent Governance SDK \u2014 validate API changes before tool invocations. TypeScript client for the CodeRifts API.",
5
5
  "main": "./dist/cjs/index.js",
6
6
  "module": "./dist/esm/index.js",