kestrel.markets
Version:
A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.
189 lines (188 loc) • 10.3 kB
JavaScript
/**
* # protocol/attestation — the shared WIRE constants of the signed grade root (OSS-ADR-0046)
*
* The load-bearing, OPAQUE wire constants that the Ed25519-signed grade root and the receipt
* attestation label are built from. Extracted here as the ONE dependency-free home so the
* platform signer and the OSS CLI verifier import the SAME literals instead of each re-declaring
* them — a drift between two independently-declared copies is invisible until a cross-repo verify
* fails (exactly the `kestrel-markets-ha87` failure mode: a verifier that mishandled the `sha256:`
* display prefix falsely reported UNVERIFIED on every prod proof). One shared home makes any
* future drift a RED conformance run instead of a silent cross-repo break.
*
* FAIL-CLOSED CONTRACT: the OSS verifier never trusts a proof body's own `verified` flag — it
* rebuilds the signing input from THESE canonical constants (`${GRADE_SIGN_PREFIX}.<bare-hex-root>`)
* and re-checks the signature locally. These constants ARE that rebuild's vocabulary.
*
* DEPENDENCY-FREE (OSS-ADR-0046 §2): plain named `const`s, zero runtime deps, no engine/frame/lang
* — importable by the LIGHT `verify` path (node built-ins only) without dragging control-plane or
* runtime code into its import graph.
*
* VERSIONING NOTE (OSS-ADR-0046 addendum): these attestation constants are their OWN independent
* epochs and are deliberately NOT gated on `PROTOCOL_VERSION`. `JUDGE_VERSION` / `FILL_MODEL_VERSION`
* pin the judge attestation label and the honest-fill model version; a wire major.minor bump must not
* silently re-stamp a previously-signed grade (bead b83 froze the analogous catalog epoch for exactly
* this reason). Bump each here, explicitly, only when its own semantics change.
*
* COLLISION WARNING — do NOT merge with `src/catalog/session-catalog.ts`'s `JUDGE_VERSION`
* (`"kestrel-judge/1"`): that is the catalog/replay grade-engine EPOCH (frozen per bead b83), an
* unrelated constant that merely shares a name with the attestation label `"0.1"` here. Import both
* only under distinct local names.
*/
/**
* The grade signing-input prefix (`kgrade1`): the Ed25519 signature attests over
* `${GRADE_SIGN_PREFIX}.<bare-hex-root>`. An OPAQUE wire constant the OSS verifier and the platform
* signer must agree on byte-for-byte — it carries no grade schema and no attribution meaning.
*/
export const GRADE_SIGN_PREFIX = "kgrade1";
/**
* The judge identity STAMPED on every certified receipt (`${JUDGE_ID}@${JUDGE_VERSION}`) — names
* "the one open judge" a grade was minted under. The COMPUTED numbers are the OSS grader's
* (`grade()`); this is the platform ATTESTATION label the signature covers, not a metric owner.
*/
export const JUDGE_ID = "kestrel-open-judge";
/**
* The judge ATTESTATION label version (`"0.1"`) — its OWN epoch, NOT gated on `PROTOCOL_VERSION`
* (see the versioning note above). Distinct from the catalog `JUDGE_VERSION` (`"kestrel-judge/1"`,
* the replay grade-engine epoch) despite the shared name.
*/
export const JUDGE_VERSION = "0.1";
/**
* The honest-fill model version pin (`"honest-fill-v0"`) the signature covers — EVs computed under
* different fill-model versions refuse naive comparison. Its OWN epoch, NOT gated on
* `PROTOCOL_VERSION`.
*/
export const FILL_MODEL_VERSION = "honest-fill-v0";
/**
* The `sha256:` DISPLAY prefix the wire `root` carries (platform bead 7ea) so it equals the Grade
* artifact's `content_hash`. The Ed25519 signature covers the BARE lowercase-hex root
* (`${GRADE_SIGN_PREFIX}.<hex>`, never `${GRADE_SIGN_PREFIX}.sha256:<hex>`), so a verifier MUST strip
* this prefix before rebuilding the signed message — not doing so falsely reported UNVERIFIED on every
* genuine prod proof (bead `kestrel-markets-ha87`). An OPAQUE wire constant — not business logic.
*/
export const ROOT_HASH_PREFIX = "sha256:";
/**
* WHERE the published verify-set lives, relative to the API base — the anonymous discovery document
* carrying `grade_verify_keys`. Quoted in the UNVERIFIED/KEY_RETIRED diagnostic so a reader can
* independently re-adjudicate the signature against the SAME key material (beads
* `kestrel-markets-5bjn` / `fjq7` — the key was published but no proof said WHERE, so a cold verifier
* guessed and 404'd). The platform re-exports this as `GRADE_VERIFY_KEYS_PATH` — two names, ONE wire
* path; a drift is a cold-verifier 404.
*/
export const VERIFY_KEYS_PATH = "/.well-known/kestrel-markets";
/**
* The EXACT top-level field keys the Ed25519 signature commits to — the SHAPE the root is a hash of,
* versioned here as public dependency-free protocol (OSS-ADR-0051, superseding the platform-only
* `SIGNATURE_COVERED_GRADE_FIELDS` in `apps/api/src/grade/signer.ts`). ADDITIVE-OPTIONAL: an absent
* optional field (`pinnedProvenanceRef`, `pinnedAuthorProvenanceRef`, `counterfactual`) is dropped by
* the canonical form and reads UNKNOWN, so a prior-version grade that never carried it still recomputes
* byte-identically — additive fields never break prior-version recompute.
*
* VERSIONED WITH `PROTOCOL_VERSION`: this key SET + its membership is part of the wire contract. A
* BREAKING change to the set (a covered field removed, or a former-optional made required) is a
* coordinated `PROTOCOL_VERSION` bump that FAILS CLOSED on mismatch — never a silent divergence. (The
* key ORDER here is documentary only: `canonicalizeJson` sorts keys, so the signed bytes depend on the
* key SET and the values, never on this tuple's order.)
*/
export const SIGNATURE_COVERED_GRADE_FIELDS = Object.freeze([
"kind",
"result",
"evView",
"supportPartition",
"pinnedDataRef",
"pinnedProvenanceRef",
"pinnedAuthorProvenanceRef",
"pinnedFillModelVersion",
"judge",
"issuedAt",
"boundRoots",
"counterfactual",
"kid",
"epoch",
"replayable",
]);
/**
* Recursively rebuild a value with every object's keys sorted lexicographically; arrays keep their
* order (meaningful); every `undefined`/absent entry is dropped (a canonical value carries no
* `undefined`). Pure — no wall clock, no RNG. Self-contained inside the dependency-free protocol
* boundary (it may NOT import the runtime's `src/canonical`); a drift-guard test asserts it is
* byte-identical to that ONE canonical owner over the covered-field domain (mirroring how the platform
* proved byte-identity before deleting its local copy).
*/
function canonicalize(value) {
if (value === null)
return null;
if (Array.isArray(value))
return value.map(canonicalize);
if (typeof value === "object") {
const src = value;
const out = {};
for (const key of Object.keys(src).sort()) {
const v = src[key];
if (v === undefined)
continue; // absent, never `undefined`
out[key] = canonicalize(v);
}
return out;
}
return value;
}
/**
* Canonical JSON of a value: compact machine-JSON with lexicographically ordered keys and no trailing
* newline — the exact bytes the signed root is a hash of. Pure and total; the same value always yields
* byte-identical text (byte-identical to the runtime's `src/canonical/json.ts` `canonicalizeJson`, the
* ONE canonical owner — asserted by the drift-guard test).
*/
export function canonicalizeJson(value) {
return JSON.stringify(canonicalize(value));
}
/**
* Build the canonical covered-field payload the root hashes over: the {@link SIGNATURE_COVERED_GRADE_FIELDS}
* key set, with the three additive-optional keys dropped when absent (so a grade that never carried them
* recomputes byte-identically). Matches the platform signer's `signingPayload` exactly.
*/
function certifiedPayload(fields) {
return {
kind: fields.kind,
result: fields.result,
evView: fields.evView,
supportPartition: fields.supportPartition,
pinnedDataRef: fields.pinnedDataRef,
...(fields.pinnedProvenanceRef !== undefined ? { pinnedProvenanceRef: fields.pinnedProvenanceRef } : {}),
...(fields.pinnedAuthorProvenanceRef !== undefined ? { pinnedAuthorProvenanceRef: fields.pinnedAuthorProvenanceRef } : {}),
pinnedFillModelVersion: fields.pinnedFillModelVersion,
judge: fields.judge,
issuedAt: fields.issuedAt,
boundRoots: [...fields.boundRoots],
...(fields.counterfactual !== undefined ? { counterfactual: fields.counterfactual } : {}),
kid: fields.kid,
epoch: fields.epoch,
replayable: fields.replayable,
};
}
/** Lowercase hex SHA-256 of a UTF-8 string via WebCrypto — portable across node (`globalThis.crypto`),
* Bun, and Worker isolates, and byte-identical to the platform signer's `sha256Hex`. No import needed
* (WebCrypto is a global), keeping the protocol boundary dependency-free. */
async function sha256Hex(text) {
const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
const bytes = new Uint8Array(digest);
let hex = "";
for (const byte of bytes)
hex += byte.toString(16).padStart(2, "0");
return hex;
}
/**
* The signed grade ROOT derivation, as a PURE protocol function (OSS-ADR-0051): the BARE lowercase-hex
* `sha256` of the canonical covered-field payload — `sha256Hex(canonicalizeJson(certifiedPayload(fields)))`.
* This is the SHAPE the Ed25519 signature commits to (the signature attests `${GRADE_SIGN_PREFIX}.<root>`
* over this bare hex; the wire `root` additionally carries the `${ROOT_HASH_PREFIX}` display prefix).
*
* Pure & deterministic: no wall clock, no RNG, no private key. `issuedAt`/`kid`/`epoch` are INPUTS. The
* private signing key stays platform-side (OSS-ADR-0001/0009 open/closed seam) — only the DERIVATION is
* shared, never the key. An outsider can now rebuild the signed root, not merely the numbers under it.
*
* Async because WebCrypto's digest is async; deterministic all the same. Byte-identical to the platform
* signer's `sha256Hex(canonicalize(signingPayload(...)))`, so the eventual signer swap changes no signed byte.
*/
export async function certifiedRoot(fields) {
return sha256Hex(canonicalizeJson(certifiedPayload(fields)));
}