@kya-os/contracts 1.10.0 → 1.12.1

package/dist/proof.d.ts

@@ -39,6 +39,8 @@ export declare const ProofMetaSchema: z.ZodObject<{
     scopeId: z.ZodOptional<z.ZodString>;
     delegationRef: z.ZodOptional<z.ZodString>;
     clientDid: z.ZodOptional<z.ZodString>;
+    toolName: z.ZodOptional<z.ZodString>;
+    submissionOutcome: z.ZodOptional<z.ZodEnum<["success", "failure", "denied"]>>;
 }, "strip", z.ZodTypeAny, {
     did: string;
     kid: string;
@@ -52,6 +54,8 @@ export declare const ProofMetaSchema: z.ZodObject<{
     delegationRef?: string | undefined;
     outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
     scopeId?: string | undefined;
+    toolName?: string | undefined;
+    submissionOutcome?: "success" | "denied" | "failure" | undefined;
 }, {
     did: string;
     kid: string;
@@ -65,6 +69,8 @@ export declare const ProofMetaSchema: z.ZodObject<{
     delegationRef?: string | undefined;
     outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
     scopeId?: string | undefined;
+    toolName?: string | undefined;
+    submissionOutcome?: "success" | "denied" | "failure" | undefined;
 }>;
 export declare const DetachedProofSchema: z.ZodObject<{
     jws: z.ZodString;
@@ -81,6 +87,8 @@ export declare const DetachedProofSchema: z.ZodObject<{
         scopeId: z.ZodOptional<z.ZodString>;
         delegationRef: z.ZodOptional<z.ZodString>;
         clientDid: z.ZodOptional<z.ZodString>;
+        toolName: z.ZodOptional<z.ZodString>;
+        submissionOutcome: z.ZodOptional<z.ZodEnum<["success", "failure", "denied"]>>;
     }, "strip", z.ZodTypeAny, {
         did: string;
         kid: string;
@@ -94,6 +102,8 @@ export declare const DetachedProofSchema: z.ZodObject<{
         delegationRef?: string | undefined;
         outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
         scopeId?: string | undefined;
+        toolName?: string | undefined;
+        submissionOutcome?: "success" | "denied" | "failure" | undefined;
     }, {
         did: string;
         kid: string;
@@ -107,6 +117,8 @@ export declare const DetachedProofSchema: z.ZodObject<{
         delegationRef?: string | undefined;
         outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
         scopeId?: string | undefined;
+        toolName?: string | undefined;
+        submissionOutcome?: "success" | "denied" | "failure" | undefined;
     }>;
 }, "strip", z.ZodTypeAny, {
     jws: string;
@@ -123,6 +135,8 @@ export declare const DetachedProofSchema: z.ZodObject<{
         delegationRef?: string | undefined;
         outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
         scopeId?: string | undefined;
+        toolName?: string | undefined;
+        submissionOutcome?: "success" | "denied" | "failure" | undefined;
     };
 }, {
     jws: string;
@@ -139,6 +153,8 @@ export declare const DetachedProofSchema: z.ZodObject<{
         delegationRef?: string | undefined;
         outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
         scopeId?: string | undefined;
+        toolName?: string | undefined;
+        submissionOutcome?: "success" | "denied" | "failure" | undefined;
     };
 }>;
 export declare const CanonicalHashesSchema: z.ZodObject<{
@@ -280,6 +296,8 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             scopeId: z.ZodOptional<z.ZodString>;
             delegationRef: z.ZodOptional<z.ZodString>;
             clientDid: z.ZodOptional<z.ZodString>;
+            toolName: z.ZodOptional<z.ZodString>;
+            submissionOutcome: z.ZodOptional<z.ZodEnum<["success", "failure", "denied"]>>;
         }, "strip", z.ZodTypeAny, {
             did: string;
             kid: string;
@@ -293,6 +311,8 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             delegationRef?: string | undefined;
             outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
             scopeId?: string | undefined;
+            toolName?: string | undefined;
+            submissionOutcome?: "success" | "denied" | "failure" | undefined;
         }, {
             did: string;
             kid: string;
@@ -306,6 +326,8 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             delegationRef?: string | undefined;
             outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
             scopeId?: string | undefined;
+            toolName?: string | undefined;
+            submissionOutcome?: "success" | "denied" | "failure" | undefined;
         }>;
     }, "strip", z.ZodTypeAny, {
         jws: string;
@@ -322,6 +344,8 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             delegationRef?: string | undefined;
             outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
             scopeId?: string | undefined;
+            toolName?: string | undefined;
+            submissionOutcome?: "success" | "denied" | "failure" | undefined;
         };
     }, {
         jws: string;
@@ -338,6 +362,8 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             delegationRef?: string | undefined;
             outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
             scopeId?: string | undefined;
+            toolName?: string | undefined;
+            submissionOutcome?: "success" | "denied" | "failure" | undefined;
         };
     }>, "many">;
     context: z.ZodOptional<z.ZodObject<{
@@ -397,6 +423,8 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             delegationRef?: string | undefined;
             outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
             scopeId?: string | undefined;
+            toolName?: string | undefined;
+            submissionOutcome?: "success" | "denied" | "failure" | undefined;
         };
     }[];
     delegation_id?: string | null | undefined;
@@ -427,6 +455,8 @@ export declare const ProofSubmissionRequestSchema: z.ZodObject<{
             delegationRef?: string | undefined;
             outcome?: "allowed" | "denied" | "step_up_required" | "needs_authorization" | undefined;
             scopeId?: string | undefined;
+            toolName?: string | undefined;
+            submissionOutcome?: "success" | "denied" | "failure" | undefined;
         };
     }[];
     delegation_id?: string | null | undefined;

package/dist/proof.js

@@ -52,6 +52,12 @@ exports.ProofMetaSchema = zod_1.z.object({
     scopeId: zod_1.z.string().optional(),
     delegationRef: zod_1.z.string().optional(),
     clientDid: zod_1.z.string().optional(), // Optional for backward compatibility
+    toolName: zod_1.z.string().min(1).optional(),
+    // KTA's "did the tool call itself succeed" concept -- distinct from
+    // `outcome` above (the ratified DIF policy-decision field). Only at JWS
+    // payload serialization time does this get mapped onto the literal wire
+    // key `outcome`; the two never share a validation enum here.
+    submissionOutcome: zod_1.z.enum(["success", "failure", "denied"]).optional(),
 });
 exports.DetachedProofSchema = zod_1.z.object({
     jws: zod_1.z.string().min(1), // Full compact JWS format (header.payload.signature)

package/dist/reputation/api.d.ts

@@ -2864,20 +2864,3 @@ export declare const REPUTATION_ENV_VARS: {
  * Default reputation threshold for trust decisions
  */
 export declare const DEFAULT_REPUTATION_THRESHOLD: 76;
-/**
- * Built-in API key for Know That AI Reputation Engine
- *
- * This key is maintained by @kya-os package maintainers.
- * Users do NOT need to configure this - registration with KTA is the gate.
- *
- * The key is used by ProofService to authenticate reputation updates.
- * Only agents with `identity.kta.registered === true` will send updates.
- *
- * SECURITY NOTE: This is a write-only key for submitting metrics.
- * It cannot be used to read reputation data without the agent's DID.
- */
-/**
- * Production API key for MCP-I framework
- * Provisioned by Know That AI team
- */
-export declare const BUILT_IN_REPUTATION_API_KEY: "Dn/qCC/0udWcGpdnt+IzA5GpWl9JF2g/avuBxlzB";

package/dist/reputation/api.js

@@ -14,7 +14,7 @@
  * Related Spec: MCP-I §5.2 (Reputation API)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BUILT_IN_REPUTATION_API_KEY = exports.DEFAULT_REPUTATION_THRESHOLD = exports.REPUTATION_ENV_VARS = exports.REPUTATION_API_LIMITS = exports.REPUTATION_API_PATHS = exports.REGISTRY_URL = exports.ReputationUpdateRequestSchema = exports.ShadowRegisterResponseSchema = exports.ShadowRegisterRequestSchema = exports.ReputationErrorResponseSchema = exports.ReputationErrorCodeSchema = exports.GetReputationResponseSchema = exports.GetReputationRequestSchema = exports.PredictScoreChangeResponseSchema = exports.PredictScoreChangeRequestSchema = exports.BatchCalculateResponseSchema = exports.BatchResultItemSchema = exports.BatchCalculateRequestSchema = exports.CalculateReputationResponseSchema = exports.CalculateReputationRequestSchema = void 0;
+exports.DEFAULT_REPUTATION_THRESHOLD = exports.REPUTATION_ENV_VARS = exports.REPUTATION_API_LIMITS = exports.REPUTATION_API_PATHS = exports.REGISTRY_URL = exports.ReputationUpdateRequestSchema = exports.ShadowRegisterResponseSchema = exports.ShadowRegisterRequestSchema = exports.ReputationErrorResponseSchema = exports.ReputationErrorCodeSchema = exports.GetReputationResponseSchema = exports.GetReputationRequestSchema = exports.PredictScoreChangeResponseSchema = exports.PredictScoreChangeRequestSchema = exports.BatchCalculateResponseSchema = exports.BatchResultItemSchema = exports.BatchCalculateRequestSchema = exports.CalculateReputationResponseSchema = exports.CalculateReputationRequestSchema = void 0;
 exports.validateCalculateRequest = validateCalculateRequest;
 exports.validateBatchCalculateRequest = validateBatchCalculateRequest;
 exports.validatePredictRequest = validatePredictRequest;
@@ -395,23 +395,3 @@ exports.REPUTATION_ENV_VARS = {
  * Default reputation threshold for trust decisions
  */
 exports.DEFAULT_REPUTATION_THRESHOLD = 76;
-// ============================================================================
-// BUILT-IN API KEY
-// ============================================================================
-/**
- * Built-in API key for Know That AI Reputation Engine
- *
- * This key is maintained by @kya-os package maintainers.
- * Users do NOT need to configure this - registration with KTA is the gate.
- *
- * The key is used by ProofService to authenticate reputation updates.
- * Only agents with `identity.kta.registered === true` will send updates.
- *
- * SECURITY NOTE: This is a write-only key for submitting metrics.
- * It cannot be used to read reputation data without the agent's DID.
- */
-/**
- * Production API key for MCP-I framework
- * Provisioned by Know That AI team
- */
-exports.BUILT_IN_REPUTATION_API_KEY = "Dn/qCC/0udWcGpdnt+IzA5GpWl9JF2g/avuBxlzB";

package/dist/review/canonicalize.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Review Verdict Canonicalization
+ *
+ * Canonical string construction and digest computation for review
+ * verdicts. Isolated from `schemas.ts` so the Zod schemas there stay free
+ * of Node.js dependencies — same split as `agent-deployment-utils.ts` vs
+ * `agent-deployment.ts` in this package — while every producer and
+ * verifier of a `ReviewVerdictBody` computes `findingsDigest` and the
+ * signing input from this one implementation. Two implementations that
+ * canonicalize differently produce signatures that verify on one side and
+ * fail on the other; that failure presents as a security incident, not a
+ * serialization bug, so do not re-derive this logic at a call site.
+ *
+ * **Node.js only** — uses `crypto.createHash`. This runs in the DIDComm
+ * reviewer/hub path (`packages/compute`), which is server-side. If an
+ * edge/browser producer or verifier is ever needed, port to
+ * `crypto.subtle.digest` and add a parity test asserting byte-identical
+ * output against this implementation (see `didToSlug`'s JSDoc in
+ * `agent-deployment-utils.ts` for the same caveat on the same tradeoff).
+ *
+ * ## Canonicalization scheme
+ *
+ * Every scalar field value is passed through `JSON.stringify`: strings are
+ * quoted and escaped (so a raw `\n`, `"`, or unicode control character in
+ * `summary`/`detail` can never appear literally in the output), and numbers
+ * print as plain digits. An **absent** optional field becomes the empty
+ * string `''`, which can never collide with a **present** field —
+ * `JSON.stringify` never returns `''` for a defined value (an empty string
+ * value stringifies to `'""'`, two characters). Because no token can ever
+ * contain a raw `\n` (JSON.stringify escapes it inside the string), joining
+ * tokens with `\n` is unambiguous: two different `findings` arrays can
+ * never produce the same token stream.
+ *
+ * Field order per finding: `path, line, severity, summary, detail`
+ * (`FINDING_FIELD_ORDER`), matching the order `ReviewFinding` is declared
+ * in `schemas.ts`.
+ *
+ * ### Worked example
+ *
+ * ```ts
+ * const findings: ReviewFinding[] = [
+ *   { path: 'src/foo.ts', line: 42, severity: 'major', summary: 'off by one' },
+ * ];
+ * // detail is absent -> its token is ''
+ * // tokens:  '"src/foo.ts"', '42', '"major"', '"off by one"', ''
+ * canonicalizeFindings(findings)
+ *   // => '"src/foo.ts"\n42\n"major"\n"off by one"\n'
+ * computeFindingsDigest(findings)
+ *   // => base64url(SHA-256('"src/foo.ts"\n42\n"major"\n"off by one"\n'))
+ * ```
+ *
+ * The verdict signing input follows the identical scheme over the fixed
+ * field order `[repo, prNumber, headSha, verdict, findingsDigest]`
+ * (`VERDICT_SIGNING_ORDER`) — see `getVerdictCanonicalSigningString`.
+ *
+ * @package @kya-os/contracts/review
+ */
+import type { ReviewFinding, ReviewSubject, ReviewVerdict } from './schemas.js';
+/**
+ * Field order for a single `ReviewFinding`. Changing this order changes
+ * every existing `findingsDigest`.
+ */
+export declare const FINDING_FIELD_ORDER: readonly ["path", "line", "severity", "summary", "detail"];
+/**
+ * Field order for the verdict signing input. Changing this order changes
+ * every existing signature.
+ */
+export declare const VERDICT_SIGNING_ORDER: readonly ["repo", "prNumber", "headSha", "verdict", "findingsDigest"];
+/**
+ * Build the canonical string for a `findings` array. Exported so callers
+ * that need to reason about the exact bytes being hashed (tests, audit
+ * tooling) do not have to re-derive it.
+ */
+export declare function canonicalizeFindings(findings: readonly ReviewFinding[]): string;
+/**
+ * Compute `findingsDigest`: base64url SHA-256 over the canonicalized
+ * `findings` array. This is the single implementation every producer and
+ * verifier of a `ReviewVerdictBody` must call.
+ */
+export declare function computeFindingsDigest(findings: readonly ReviewFinding[]): string;
+/**
+ * Build the canonical signing input for a review verdict's detached JWS:
+ * `subject.repo`, `subject.prNumber`, `subject.headSha`, `verdict`,
+ * `findingsDigest`, in that fixed order (`VERDICT_SIGNING_ORDER`). The
+ * `proof` in `ReviewVerdictBody` signs exactly this string.
+ */
+export declare function getVerdictCanonicalSigningString(subject: ReviewSubject, verdict: ReviewVerdict, findingsDigest: string): string;

package/dist/review/canonicalize.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Review Verdict Canonicalization
+ *
+ * Canonical string construction and digest computation for review
+ * verdicts. Isolated from `schemas.ts` so the Zod schemas there stay free
+ * of Node.js dependencies — same split as `agent-deployment-utils.ts` vs
+ * `agent-deployment.ts` in this package — while every producer and
+ * verifier of a `ReviewVerdictBody` computes `findingsDigest` and the
+ * signing input from this one implementation. Two implementations that
+ * canonicalize differently produce signatures that verify on one side and
+ * fail on the other; that failure presents as a security incident, not a
+ * serialization bug, so do not re-derive this logic at a call site.
+ *
+ * **Node.js only** — uses `crypto.createHash`. This runs in the DIDComm
+ * reviewer/hub path (`packages/compute`), which is server-side. If an
+ * edge/browser producer or verifier is ever needed, port to
+ * `crypto.subtle.digest` and add a parity test asserting byte-identical
+ * output against this implementation (see `didToSlug`'s JSDoc in
+ * `agent-deployment-utils.ts` for the same caveat on the same tradeoff).
+ *
+ * ## Canonicalization scheme
+ *
+ * Every scalar field value is passed through `JSON.stringify`: strings are
+ * quoted and escaped (so a raw `\n`, `"`, or unicode control character in
+ * `summary`/`detail` can never appear literally in the output), and numbers
+ * print as plain digits. An **absent** optional field becomes the empty
+ * string `''`, which can never collide with a **present** field —
+ * `JSON.stringify` never returns `''` for a defined value (an empty string
+ * value stringifies to `'""'`, two characters). Because no token can ever
+ * contain a raw `\n` (JSON.stringify escapes it inside the string), joining
+ * tokens with `\n` is unambiguous: two different `findings` arrays can
+ * never produce the same token stream.
+ *
+ * Field order per finding: `path, line, severity, summary, detail`
+ * (`FINDING_FIELD_ORDER`), matching the order `ReviewFinding` is declared
+ * in `schemas.ts`.
+ *
+ * ### Worked example
+ *
+ * ```ts
+ * const findings: ReviewFinding[] = [
+ *   { path: 'src/foo.ts', line: 42, severity: 'major', summary: 'off by one' },
+ * ];
+ * // detail is absent -> its token is ''
+ * // tokens:  '"src/foo.ts"', '42', '"major"', '"off by one"', ''
+ * canonicalizeFindings(findings)
+ *   // => '"src/foo.ts"\n42\n"major"\n"off by one"\n'
+ * computeFindingsDigest(findings)
+ *   // => base64url(SHA-256('"src/foo.ts"\n42\n"major"\n"off by one"\n'))
+ * ```
+ *
+ * The verdict signing input follows the identical scheme over the fixed
+ * field order `[repo, prNumber, headSha, verdict, findingsDigest]`
+ * (`VERDICT_SIGNING_ORDER`) — see `getVerdictCanonicalSigningString`.
+ *
+ * @package @kya-os/contracts/review
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERDICT_SIGNING_ORDER = exports.FINDING_FIELD_ORDER = void 0;
+exports.canonicalizeFindings = canonicalizeFindings;
+exports.computeFindingsDigest = computeFindingsDigest;
+exports.getVerdictCanonicalSigningString = getVerdictCanonicalSigningString;
+const crypto_1 = require("crypto");
+/**
+ * Field order for a single `ReviewFinding`. Changing this order changes
+ * every existing `findingsDigest`.
+ */
+exports.FINDING_FIELD_ORDER = ['path', 'line', 'severity', 'summary', 'detail'];
+/**
+ * Field order for the verdict signing input. Changing this order changes
+ * every existing signature.
+ */
+exports.VERDICT_SIGNING_ORDER = [
+    'repo',
+    'prNumber',
+    'headSha',
+    'verdict',
+    'findingsDigest',
+];
+/** A single canonicalization token: `''` for an absent field, else `JSON.stringify(value)`. */
+function canonicalToken(value) {
+    return value === undefined ? '' : JSON.stringify(value);
+}
+/**
+ * Build the canonical string for a `findings` array. Exported so callers
+ * that need to reason about the exact bytes being hashed (tests, audit
+ * tooling) do not have to re-derive it.
+ */
+function canonicalizeFindings(findings) {
+    const tokens = [];
+    for (const finding of findings) {
+        for (const field of exports.FINDING_FIELD_ORDER) {
+            tokens.push(canonicalToken(finding[field]));
+        }
+    }
+    return tokens.join('\n');
+}
+/**
+ * Compute `findingsDigest`: base64url SHA-256 over the canonicalized
+ * `findings` array. This is the single implementation every producer and
+ * verifier of a `ReviewVerdictBody` must call.
+ */
+function computeFindingsDigest(findings) {
+    return (0, crypto_1.createHash)('sha256').update(canonicalizeFindings(findings), 'utf8').digest('base64url');
+}
+/**
+ * Build the canonical signing input for a review verdict's detached JWS:
+ * `subject.repo`, `subject.prNumber`, `subject.headSha`, `verdict`,
+ * `findingsDigest`, in that fixed order (`VERDICT_SIGNING_ORDER`). The
+ * `proof` in `ReviewVerdictBody` signs exactly this string.
+ */
+function getVerdictCanonicalSigningString(subject, verdict, findingsDigest) {
+    const values = {
+        repo: subject.repo,
+        prNumber: subject.prNumber,
+        headSha: subject.headSha,
+        verdict,
+        findingsDigest,
+    };
+    return exports.VERDICT_SIGNING_ORDER.map((field) => canonicalToken(values[field])).join('\n');
+}

package/dist/review/fix-attestation.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Fix Attestation Schema
+ *
+ * A fix attestation is the answer to a `ReviewVerdictBody` that requested
+ * changes: a verdict says "I reviewed `respondsToHeadSha` and found these
+ * findings"; a fix attestation says "I pushed `subject.fixedHeadSha` on
+ * `subject.repo`#`subject.prNumber` in response to that review." Posted as a
+ * signed PR comment (see `dco fix` in `@kya-os/cli`) so the audit trail
+ * closes the loop without trusting an unsigned comment body.
+ *
+ * Pure Zod schemas plus canonicalization only, no `node:crypto` — this
+ * module (and this package's `./review` barrel, which re-exports it) stays
+ * importable from an edge/browser runtime. The Ed25519 verify counterpart,
+ * `verifyFixAttestationProof`, lives in the separate `./review/verify`
+ * subpath instead of here for exactly that reason: it needs `node:crypto`
+ * for raw Ed25519 verification, and a subpath barrel must not force that
+ * dependency on every consumer who only needs the schema/signing-string
+ * (see `verify.ts`'s own module doc).
+ *
+ * @package @kya-os/contracts/review
+ */
+import { z } from 'zod';
+export declare const FixAttestationSubjectSchema: z.ZodObject<{
+    /**
+     * "owner/repo", e.g. "modelcontextprotocol-identity/xmcp-i". Constrained
+     * to GitHub's actual owner/repo character set (alphanumeric, hyphen,
+     * underscore, period) rather than a bare non-empty string: this value
+     * gets interpolated into a PR-comment marker
+     * (`buildFixAttestationCommentBody` in `@kya-os/cli`'s `dco fix`), and a
+     * bare `.min(1)` would let a backtick or an HTML comment-closing `-->`
+     * through into that markdown.
+     */
+    repo: z.ZodString;
+    /** GitHub PR number */
+    prNumber: z.ZodNumber;
+    /** Full 40-character SHA, lowercase — the commit this attestation covers */
+    fixedHeadSha: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    repo: string;
+    prNumber: number;
+    fixedHeadSha: string;
+}, {
+    repo: string;
+    prNumber: number;
+    fixedHeadSha: string;
+}>;
+export type FixAttestationSubject = z.infer<typeof FixAttestationSubjectSchema>;
+export declare const FixAttestationSchema: z.ZodObject<{
+    subject: z.ZodObject<{
+        /**
+         * "owner/repo", e.g. "modelcontextprotocol-identity/xmcp-i". Constrained
+         * to GitHub's actual owner/repo character set (alphanumeric, hyphen,
+         * underscore, period) rather than a bare non-empty string: this value
+         * gets interpolated into a PR-comment marker
+         * (`buildFixAttestationCommentBody` in `@kya-os/cli`'s `dco fix`), and a
+         * bare `.min(1)` would let a backtick or an HTML comment-closing `-->`
+         * through into that markdown.
+         */
+        repo: z.ZodString;
+        /** GitHub PR number */
+        prNumber: z.ZodNumber;
+        /** Full 40-character SHA, lowercase — the commit this attestation covers */
+        fixedHeadSha: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        repo: string;
+        prNumber: number;
+        fixedHeadSha: string;
+    }, {
+        repo: string;
+        prNumber: number;
+        fixedHeadSha: string;
+    }>;
+    /** Full 40-character SHA, lowercase — the reviewed head that requested changes */
+    respondsToHeadSha: z.ZodString;
+    /** The DIDComm fix task this attestation was dispatched for, when applicable */
+    taskId: z.ZodOptional<z.ZodString>;
+    /** did:<method>:<method-specific-id>, e.g. did:web:knowthat.ai:agents:acme-bot */
+    agentDid: z.ZodString;
+    /** Detached JWS over `getFixAttestationSigningString(subject, respondsToHeadSha)` */
+    proof: z.ZodObject<{
+        alg: z.ZodEnum<["Ed25519", "ES256"]>;
+        kid: z.ZodOptional<z.ZodString>;
+        signature: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        signature: string;
+        alg: "Ed25519" | "ES256";
+        kid?: string | undefined;
+    }, {
+        signature: string;
+        alg: "Ed25519" | "ES256";
+        kid?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    agentDid: string;
+    subject: {
+        repo: string;
+        prNumber: number;
+        fixedHeadSha: string;
+    };
+    proof: {
+        signature: string;
+        alg: "Ed25519" | "ES256";
+        kid?: string | undefined;
+    };
+    respondsToHeadSha: string;
+    taskId?: string | undefined;
+}, {
+    agentDid: string;
+    subject: {
+        repo: string;
+        prNumber: number;
+        fixedHeadSha: string;
+    };
+    proof: {
+        signature: string;
+        alg: "Ed25519" | "ES256";
+        kid?: string | undefined;
+    };
+    respondsToHeadSha: string;
+    taskId?: string | undefined;
+}>;
+export type FixAttestation = z.infer<typeof FixAttestationSchema>;
+/**
+ * Field order for the fix-attestation signing input, fixed forever: changing
+ * it changes every existing signature. `"fix-attestation:v1"` is a version
+ * tag, not a subject field — bumping the scheme (e.g. adding a field) must
+ * bump this string too, so an old signature can never be replayed against a
+ * new canonicalization.
+ */
+export declare const FIX_ATTESTATION_SIGNING_ORDER: readonly ["version", "repo", "prNumber", "fixedHeadSha", "respondsToHeadSha"];
+/**
+ * Build the canonical signing string for a fix attestation's detached JWS:
+ * newline-joined `"fix-attestation:v1"`, `subject.repo`, `subject.prNumber`
+ * (decimal), `subject.fixedHeadSha`, `respondsToHeadSha`, in that fixed
+ * order (`FIX_ATTESTATION_SIGNING_ORDER`). Every field is required here (no
+ * optional-field ambiguity to resolve, unlike `getVerdictCanonicalSigningString`'s
+ * findings tokens), so each token is simply `JSON.stringify(value)`.
+ *
+ * ### Worked example
+ *
+ * ```ts
+ * const subject: FixAttestationSubject = {
+ *   repo: 'acme/demo',
+ *   prNumber: 42,
+ *   fixedHeadSha: 'a'.repeat(40),
+ * };
+ * getFixAttestationSigningString(subject, 'b'.repeat(40))
+ *   // => '"fix-attestation:v1"\n"acme/demo"\n42\n"aaaa...aaaa"\n"bbbb...bbbb"'
+ * ```
+ */
+export declare function getFixAttestationSigningString(subject: FixAttestationSubject, respondsToHeadSha: string): string;

package/dist/review/fix-attestation.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Fix Attestation Schema
+ *
+ * A fix attestation is the answer to a `ReviewVerdictBody` that requested
+ * changes: a verdict says "I reviewed `respondsToHeadSha` and found these
+ * findings"; a fix attestation says "I pushed `subject.fixedHeadSha` on
+ * `subject.repo`#`subject.prNumber` in response to that review." Posted as a
+ * signed PR comment (see `dco fix` in `@kya-os/cli`) so the audit trail
+ * closes the loop without trusting an unsigned comment body.
+ *
+ * Pure Zod schemas plus canonicalization only, no `node:crypto` — this
+ * module (and this package's `./review` barrel, which re-exports it) stays
+ * importable from an edge/browser runtime. The Ed25519 verify counterpart,
+ * `verifyFixAttestationProof`, lives in the separate `./review/verify`
+ * subpath instead of here for exactly that reason: it needs `node:crypto`
+ * for raw Ed25519 verification, and a subpath barrel must not force that
+ * dependency on every consumer who only needs the schema/signing-string
+ * (see `verify.ts`'s own module doc).
+ *
+ * @package @kya-os/contracts/review
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIX_ATTESTATION_SIGNING_ORDER = exports.FixAttestationSchema = exports.FixAttestationSubjectSchema = void 0;
+exports.getFixAttestationSigningString = getFixAttestationSigningString;
+const zod_1 = require("zod");
+const agent_deployment_js_1 = require("../agent-deployment.js");
+// Reached via the same relative path `schemas.ts` already uses, not a
+// self-package import of `@kya-os/contracts/proof`.
+const signing_spec_js_1 = require("../proof/signing-spec.js");
+exports.FixAttestationSubjectSchema = zod_1.z.object({
+    /**
+     * "owner/repo", e.g. "modelcontextprotocol-identity/xmcp-i". Constrained
+     * to GitHub's actual owner/repo character set (alphanumeric, hyphen,
+     * underscore, period) rather than a bare non-empty string: this value
+     * gets interpolated into a PR-comment marker
+     * (`buildFixAttestationCommentBody` in `@kya-os/cli`'s `dco fix`), and a
+     * bare `.min(1)` would let a backtick or an HTML comment-closing `-->`
+     * through into that markdown.
+     */
+    repo: zod_1.z.string().regex(/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?\/[A-Za-z0-9._-]+$/),
+    /** GitHub PR number */
+    prNumber: zod_1.z.number().int().positive(),
+    /** Full 40-character SHA, lowercase — the commit this attestation covers */
+    fixedHeadSha: zod_1.z.string().regex(/^[0-9a-f]{40}$/),
+});
+exports.FixAttestationSchema = zod_1.z.object({
+    subject: exports.FixAttestationSubjectSchema,
+    /** Full 40-character SHA, lowercase — the reviewed head that requested changes */
+    respondsToHeadSha: zod_1.z.string().regex(/^[0-9a-f]{40}$/),
+    /** The DIDComm fix task this attestation was dispatched for, when applicable */
+    taskId: zod_1.z.string().min(1).optional(),
+    /** did:<method>:<method-specific-id>, e.g. did:web:knowthat.ai:agents:acme-bot */
+    agentDid: agent_deployment_js_1.DidStringSchema,
+    /** Detached JWS over `getFixAttestationSigningString(subject, respondsToHeadSha)` */
+    proof: signing_spec_js_1.DetachedJwsSchema,
+});
+/**
+ * Field order for the fix-attestation signing input, fixed forever: changing
+ * it changes every existing signature. `"fix-attestation:v1"` is a version
+ * tag, not a subject field — bumping the scheme (e.g. adding a field) must
+ * bump this string too, so an old signature can never be replayed against a
+ * new canonicalization.
+ */
+exports.FIX_ATTESTATION_SIGNING_ORDER = [
+    'version',
+    'repo',
+    'prNumber',
+    'fixedHeadSha',
+    'respondsToHeadSha',
+];
+/** A single canonicalization token: `JSON.stringify(value)`, matching canonicalize.ts's scheme. */
+function canonicalToken(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Build the canonical signing string for a fix attestation's detached JWS:
+ * newline-joined `"fix-attestation:v1"`, `subject.repo`, `subject.prNumber`
+ * (decimal), `subject.fixedHeadSha`, `respondsToHeadSha`, in that fixed
+ * order (`FIX_ATTESTATION_SIGNING_ORDER`). Every field is required here (no
+ * optional-field ambiguity to resolve, unlike `getVerdictCanonicalSigningString`'s
+ * findings tokens), so each token is simply `JSON.stringify(value)`.
+ *
+ * ### Worked example
+ *
+ * ```ts
+ * const subject: FixAttestationSubject = {
+ *   repo: 'acme/demo',
+ *   prNumber: 42,
+ *   fixedHeadSha: 'a'.repeat(40),
+ * };
+ * getFixAttestationSigningString(subject, 'b'.repeat(40))
+ *   // => '"fix-attestation:v1"\n"acme/demo"\n42\n"aaaa...aaaa"\n"bbbb...bbbb"'
+ * ```
+ */
+function getFixAttestationSigningString(subject, respondsToHeadSha) {
+    const values = {
+        version: 'fix-attestation:v1',
+        repo: subject.repo,
+        prNumber: subject.prNumber,
+        fixedHeadSha: subject.fixedHeadSha,
+        respondsToHeadSha,
+    };
+    return exports.FIX_ATTESTATION_SIGNING_ORDER.map((field) => canonicalToken(values[field])).join('\n');
+}