@kya-os/contracts 1.10.1 → 1.12.1

package/dist/review/schemas.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Review Verdict Schemas
+ *
+ * Types and Zod schemas for PR review verdicts posted by reviewer agents
+ * over DIDComm (see `packages/compute/src/didcomm/`). A verdict binds an
+ * approve/request-changes/comment decision to a single commit
+ * (`subject.headSha`): a push changes head, so every prior verdict's
+ * subject stops matching and stale approvals become uncountable rather than
+ * needing dismissal logic. That is a deliberate, load-bearing tradeoff, not
+ * an oversight — see the module doc on `canonicalize.ts` for the signing
+ * scheme this schema's `findingsDigest` and `proof` fields depend on.
+ *
+ * Pure Zod schemas only. Crypto-dependent canonicalization lives in
+ * `canonicalize.ts` so this module stays portable across every runtime that
+ * consumes `@kya-os/contracts` (see that file's doc comment for why).
+ *
+ * @package @kya-os/contracts/review
+ */
+import { z } from 'zod';
+/**
+ * Review Subject Schema
+ *
+ * Binds a verdict to a single commit on a single PR.
+ */
+export declare const ReviewSubjectSchema: z.ZodObject<{
+    /** "owner/repo", e.g. "modelcontextprotocol-identity/xmcp-i" */
+    repo: z.ZodString;
+    /** GitHub PR number */
+    prNumber: z.ZodNumber;
+    /** Full 40-character SHA, lowercase */
+    headSha: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    repo: string;
+    prNumber: number;
+    headSha: string;
+}, {
+    repo: string;
+    prNumber: number;
+    headSha: string;
+}>;
+export type ReviewSubject = z.infer<typeof ReviewSubjectSchema>;
+/**
+ * Review Verdict Schema
+ */
+export declare const ReviewVerdictSchema: z.ZodEnum<["approve", "request-changes", "comment"]>;
+export type ReviewVerdict = z.infer<typeof ReviewVerdictSchema>;
+/**
+ * Review Finding Severity Schema
+ */
+export declare const ReviewFindingSeveritySchema: z.ZodEnum<["blocking", "major", "minor", "nit"]>;
+export type ReviewFindingSeverity = z.infer<typeof ReviewFindingSeveritySchema>;
+/**
+ * Review Finding Schema
+ */
+export declare const ReviewFindingSchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
+    line: z.ZodOptional<z.ZodNumber>;
+    severity: z.ZodEnum<["blocking", "major", "minor", "nit"]>;
+    summary: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    summary: string;
+    severity: "blocking" | "major" | "minor" | "nit";
+    path?: string | undefined;
+    line?: number | undefined;
+    detail?: string | undefined;
+}, {
+    summary: string;
+    severity: "blocking" | "major" | "minor" | "nit";
+    path?: string | undefined;
+    line?: number | undefined;
+    detail?: string | undefined;
+}>;
+export type ReviewFinding = z.infer<typeof ReviewFindingSchema>;
+/**
+ * Review Verdict Body Schema
+ *
+ * Full verdict payload a reviewer agent posts over DIDComm.
+ *
+ * `findingsDigest` and `proof` are NOT derived by this schema — Zod
+ * validates shape, not that the digest actually matches `findings` or that
+ * the signature actually verifies. Producers must compute `findingsDigest`
+ * with `computeFindingsDigest` (in `canonicalize.ts`) and sign
+ * `getVerdictCanonicalSigningString(subject, verdict, findingsDigest)`;
+ * verifiers must recompute both and compare rather than trusting the wire
+ * value. Do not hand-roll either at a call site.
+ */
+export declare const ReviewVerdictBodySchema: z.ZodObject<{
+    taskId: z.ZodString;
+    subject: z.ZodObject<{
+        /** "owner/repo", e.g. "modelcontextprotocol-identity/xmcp-i" */
+        repo: z.ZodString;
+        /** GitHub PR number */
+        prNumber: z.ZodNumber;
+        /** Full 40-character SHA, lowercase */
+        headSha: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        repo: string;
+        prNumber: number;
+        headSha: string;
+    }, {
+        repo: string;
+        prNumber: number;
+        headSha: string;
+    }>;
+    verdict: z.ZodEnum<["approve", "request-changes", "comment"]>;
+    /**
+     * Capped at 500: `computeFindingsDigest` (canonicalize.ts) does O(n) work
+     * per entry, and this is the array size a DIDComm-delivered payload from
+     * a reviewer agent controls. No real review produces more findings than
+     * this; a payload that does is malformed, not thorough.
+     */
+    findings: z.ZodArray<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        line: z.ZodOptional<z.ZodNumber>;
+        severity: z.ZodEnum<["blocking", "major", "minor", "nit"]>;
+        summary: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        summary: string;
+        severity: "blocking" | "major" | "minor" | "nit";
+        path?: string | undefined;
+        line?: number | undefined;
+        detail?: string | undefined;
+    }, {
+        summary: string;
+        severity: "blocking" | "major" | "minor" | "nit";
+        path?: string | undefined;
+        line?: number | undefined;
+        detail?: string | undefined;
+    }>, "many">;
+    /**
+     * base64url SHA-256 over canonicalized `findings`; see canonicalize.ts.
+     * Fixed at 43 chars — the exact length of an unpadded base64url SHA-256
+     * digest — matching the exact-length convention every other hash field
+     * in this package uses (e.g. `registry.ts`'s `contentHash`, `proof.ts`'s
+     * `requestHash`/`responseHash`).
+     */
+    findingsDigest: z.ZodString;
+    /** Detached JWS over subject + verdict + findingsDigest; see canonicalize.ts */
+    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, {
+    subject: {
+        repo: string;
+        prNumber: number;
+        headSha: string;
+    };
+    proof: {
+        signature: string;
+        alg: "Ed25519" | "ES256";
+        kid?: string | undefined;
+    };
+    taskId: string;
+    verdict: "approve" | "request-changes" | "comment";
+    findings: {
+        summary: string;
+        severity: "blocking" | "major" | "minor" | "nit";
+        path?: string | undefined;
+        line?: number | undefined;
+        detail?: string | undefined;
+    }[];
+    findingsDigest: string;
+}, {
+    subject: {
+        repo: string;
+        prNumber: number;
+        headSha: string;
+    };
+    proof: {
+        signature: string;
+        alg: "Ed25519" | "ES256";
+        kid?: string | undefined;
+    };
+    taskId: string;
+    verdict: "approve" | "request-changes" | "comment";
+    findings: {
+        summary: string;
+        severity: "blocking" | "major" | "minor" | "nit";
+        path?: string | undefined;
+        line?: number | undefined;
+        detail?: string | undefined;
+    }[];
+    findingsDigest: string;
+}>;
+export type ReviewVerdictBody = z.infer<typeof ReviewVerdictBodySchema>;
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate a review verdict body
+ *
+ * @param body - The body to validate
+ * @returns Validation result
+ */
+export declare function validateReviewVerdictBody(body: unknown): z.SafeParseReturnType<{
+    subject: {
+        repo: string;
+        prNumber: number;
+        headSha: string;
+    };
+    proof: {
+        signature: string;
+        alg: "Ed25519" | "ES256";
+        kid?: string | undefined;
+    };
+    taskId: string;
+    verdict: "approve" | "request-changes" | "comment";
+    findings: {
+        summary: string;
+        severity: "blocking" | "major" | "minor" | "nit";
+        path?: string | undefined;
+        line?: number | undefined;
+        detail?: string | undefined;
+    }[];
+    findingsDigest: string;
+}, {
+    subject: {
+        repo: string;
+        prNumber: number;
+        headSha: string;
+    };
+    proof: {
+        signature: string;
+        alg: "Ed25519" | "ES256";
+        kid?: string | undefined;
+    };
+    taskId: string;
+    verdict: "approve" | "request-changes" | "comment";
+    findings: {
+        summary: string;
+        severity: "blocking" | "major" | "minor" | "nit";
+        path?: string | undefined;
+        line?: number | undefined;
+        detail?: string | undefined;
+    }[];
+    findingsDigest: string;
+}>;

package/dist/review/schemas.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Review Verdict Schemas
+ *
+ * Types and Zod schemas for PR review verdicts posted by reviewer agents
+ * over DIDComm (see `packages/compute/src/didcomm/`). A verdict binds an
+ * approve/request-changes/comment decision to a single commit
+ * (`subject.headSha`): a push changes head, so every prior verdict's
+ * subject stops matching and stale approvals become uncountable rather than
+ * needing dismissal logic. That is a deliberate, load-bearing tradeoff, not
+ * an oversight — see the module doc on `canonicalize.ts` for the signing
+ * scheme this schema's `findingsDigest` and `proof` fields depend on.
+ *
+ * Pure Zod schemas only. Crypto-dependent canonicalization lives in
+ * `canonicalize.ts` so this module stays portable across every runtime that
+ * consumes `@kya-os/contracts` (see that file's doc comment for why).
+ *
+ * @package @kya-os/contracts/review
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReviewVerdictBodySchema = exports.ReviewFindingSchema = exports.ReviewFindingSeveritySchema = exports.ReviewVerdictSchema = exports.ReviewSubjectSchema = void 0;
+exports.validateReviewVerdictBody = validateReviewVerdictBody;
+const zod_1 = require("zod");
+const signing_spec_js_1 = require("../proof/signing-spec.js");
+/**
+ * Review Subject Schema
+ *
+ * Binds a verdict to a single commit on a single PR.
+ */
+exports.ReviewSubjectSchema = zod_1.z.object({
+    /** "owner/repo", e.g. "modelcontextprotocol-identity/xmcp-i" */
+    repo: zod_1.z.string().min(1),
+    /** GitHub PR number */
+    prNumber: zod_1.z.number().int().positive(),
+    /** Full 40-character SHA, lowercase */
+    headSha: zod_1.z.string().regex(/^[0-9a-f]{40}$/),
+});
+/**
+ * Review Verdict Schema
+ */
+exports.ReviewVerdictSchema = zod_1.z.enum(['approve', 'request-changes', 'comment']);
+/**
+ * Review Finding Severity Schema
+ */
+exports.ReviewFindingSeveritySchema = zod_1.z.enum(['blocking', 'major', 'minor', 'nit']);
+/**
+ * Review Finding Schema
+ */
+exports.ReviewFindingSchema = zod_1.z.object({
+    path: zod_1.z.string().min(1).optional(),
+    line: zod_1.z.number().int().positive().optional(),
+    severity: exports.ReviewFindingSeveritySchema,
+    summary: zod_1.z.string().min(1),
+    detail: zod_1.z.string().min(1).optional(),
+});
+/**
+ * Review Verdict Body Schema
+ *
+ * Full verdict payload a reviewer agent posts over DIDComm.
+ *
+ * `findingsDigest` and `proof` are NOT derived by this schema — Zod
+ * validates shape, not that the digest actually matches `findings` or that
+ * the signature actually verifies. Producers must compute `findingsDigest`
+ * with `computeFindingsDigest` (in `canonicalize.ts`) and sign
+ * `getVerdictCanonicalSigningString(subject, verdict, findingsDigest)`;
+ * verifiers must recompute both and compare rather than trusting the wire
+ * value. Do not hand-roll either at a call site.
+ */
+exports.ReviewVerdictBodySchema = zod_1.z.object({
+    taskId: zod_1.z.string().min(1),
+    subject: exports.ReviewSubjectSchema,
+    verdict: exports.ReviewVerdictSchema,
+    /**
+     * Capped at 500: `computeFindingsDigest` (canonicalize.ts) does O(n) work
+     * per entry, and this is the array size a DIDComm-delivered payload from
+     * a reviewer agent controls. No real review produces more findings than
+     * this; a payload that does is malformed, not thorough.
+     */
+    findings: zod_1.z.array(exports.ReviewFindingSchema).max(500),
+    /**
+     * base64url SHA-256 over canonicalized `findings`; see canonicalize.ts.
+     * Fixed at 43 chars — the exact length of an unpadded base64url SHA-256
+     * digest — matching the exact-length convention every other hash field
+     * in this package uses (e.g. `registry.ts`'s `contentHash`, `proof.ts`'s
+     * `requestHash`/`responseHash`).
+     */
+    findingsDigest: zod_1.z.string().regex(/^[A-Za-z0-9_-]{43}$/),
+    /** Detached JWS over subject + verdict + findingsDigest; see canonicalize.ts */
+    proof: signing_spec_js_1.DetachedJwsSchema,
+});
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate a review verdict body
+ *
+ * @param body - The body to validate
+ * @returns Validation result
+ */
+function validateReviewVerdictBody(body) {
+    return exports.ReviewVerdictBodySchema.safeParse(body);
+}

package/dist/review/verify.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Fix Attestation Verification
+ *
+ * Raw Ed25519 verify for `FixAttestation` (see `fix-attestation.ts`), kept
+ * in its own subpath (`@kya-os/contracts/review/verify`) rather than the
+ * `./review` barrel: this file's `node:crypto` import would otherwise be
+ * pulled into every edge/browser consumer of the review subpath just to
+ * reach the pure schemas and canonicalization it doesn't need. Import this
+ * module directly wherever the verify function itself is actually needed.
+ *
+ * (P9's review-verdict counterpart, `verifyReviewVerdictProof`, has not
+ * landed in this package as of this commit — see
+ * `packages/compute/src/didcomm/review.ts`'s `verifyReviewVerdictSignature`
+ * for the same Ed25519-verify pattern applied to `ReviewVerdictBody`. When
+ * it lands here, the two belong as siblings in this file's own subpath.)
+ *
+ * @package @kya-os/contracts/review/verify
+ */
+import { type FixAttestation } from './fix-attestation.js';
+/**
+ * Verify a fix attestation's detached Ed25519 signature: that
+ * `attestation.proof.signature` was produced by the private half of
+ * `publicKeyRaw` (raw 32-byte Ed25519 public key, e.g. `ssh-key.ts`'s
+ * `deriveEd25519PublicKey` output) over
+ * `getFixAttestationSigningString(attestation.subject, attestation.respondsToHeadSha)`.
+ *
+ * This does NOT check that `attestation.subject.fixedHeadSha` is actually
+ * the current head of the PR, or that `respondsToHeadSha` is actually the
+ * headSha a real review verdict requested changes on — it verifies one
+ * fact (possession + integrity of the signed tuple), not the whole review
+ * loop's state. Callers cross-check those against live PR/verdict data.
+ *
+ * Fail-closed: any malformed input, key-import failure, or signature
+ * mismatch returns `false` rather than throwing — never admit on an
+ * unverifiable proof.
+ */
+export declare function verifyFixAttestationProof(attestation: FixAttestation, publicKeyRaw: Buffer): boolean;

package/dist/review/verify.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Fix Attestation Verification
+ *
+ * Raw Ed25519 verify for `FixAttestation` (see `fix-attestation.ts`), kept
+ * in its own subpath (`@kya-os/contracts/review/verify`) rather than the
+ * `./review` barrel: this file's `node:crypto` import would otherwise be
+ * pulled into every edge/browser consumer of the review subpath just to
+ * reach the pure schemas and canonicalization it doesn't need. Import this
+ * module directly wherever the verify function itself is actually needed.
+ *
+ * (P9's review-verdict counterpart, `verifyReviewVerdictProof`, has not
+ * landed in this package as of this commit — see
+ * `packages/compute/src/didcomm/review.ts`'s `verifyReviewVerdictSignature`
+ * for the same Ed25519-verify pattern applied to `ReviewVerdictBody`. When
+ * it lands here, the two belong as siblings in this file's own subpath.)
+ *
+ * @package @kya-os/contracts/review/verify
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyFixAttestationProof = verifyFixAttestationProof;
+const node_crypto_1 = require("node:crypto");
+const fix_attestation_js_1 = require("./fix-attestation.js");
+// DER prefix that turns a raw 32-byte Ed25519 public key into an SPKI key,
+// the same wrapping `@kya-os/mcp-i`'s `NodeCryptoProvider.verify` and
+// `utils/dco/ssh-key.ts`'s PKCS8 sibling prefix use for the private half.
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+/**
+ * Verify a fix attestation's detached Ed25519 signature: that
+ * `attestation.proof.signature` was produced by the private half of
+ * `publicKeyRaw` (raw 32-byte Ed25519 public key, e.g. `ssh-key.ts`'s
+ * `deriveEd25519PublicKey` output) over
+ * `getFixAttestationSigningString(attestation.subject, attestation.respondsToHeadSha)`.
+ *
+ * This does NOT check that `attestation.subject.fixedHeadSha` is actually
+ * the current head of the PR, or that `respondsToHeadSha` is actually the
+ * headSha a real review verdict requested changes on — it verifies one
+ * fact (possession + integrity of the signed tuple), not the whole review
+ * loop's state. Callers cross-check those against live PR/verdict data.
+ *
+ * Fail-closed: any malformed input, key-import failure, or signature
+ * mismatch returns `false` rather than throwing — never admit on an
+ * unverifiable proof.
+ */
+function verifyFixAttestationProof(attestation, publicKeyRaw) {
+    try {
+        const signingString = (0, fix_attestation_js_1.getFixAttestationSigningString)(attestation.subject, attestation.respondsToHeadSha);
+        const publicKey = (0, node_crypto_1.createPublicKey)({
+            key: Buffer.concat([ED25519_SPKI_PREFIX, publicKeyRaw]),
+            format: 'der',
+            type: 'spki',
+        });
+        return (0, node_crypto_1.verify)(null, Buffer.from(signingString, 'utf8'), publicKey, Buffer.from(attestation.proof.signature, 'base64url'));
+    }
+    catch {
+        return false; // fail-closed — never admit on an unverifiable proof
+    }
+}

package/dist/test.d.ts

@@ -173,6 +173,13 @@ export declare const LocalVerificationResultSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     valid: boolean;
     warnings: string[];
+    proof: {
+        valid: boolean;
+        structure: boolean;
+        timestamps: boolean;
+        hashes: boolean;
+        error?: string | undefined;
+    };
     session: {
         valid: boolean;
         expired: boolean;
@@ -183,6 +190,11 @@ export declare const LocalVerificationResultSchema: z.ZodObject<{
         algorithm: string;
         error?: string | undefined;
     };
+    errors: string[];
+    did?: string | undefined;
+    kid?: string | undefined;
+}, {
+    valid: boolean;
     proof: {
         valid: boolean;
         structure: boolean;
@@ -190,11 +202,6 @@ export declare const LocalVerificationResultSchema: z.ZodObject<{
         hashes: boolean;
         error?: string | undefined;
     };
-    errors: string[];
-    did?: string | undefined;
-    kid?: string | undefined;
-}, {
-    valid: boolean;
     session: {
         valid: boolean;
         expired: boolean;
@@ -205,13 +212,6 @@ export declare const LocalVerificationResultSchema: z.ZodObject<{
         algorithm: string;
         error?: string | undefined;
     };
-    proof: {
-        valid: boolean;
-        structure: boolean;
-        timestamps: boolean;
-        hashes: boolean;
-        error?: string | undefined;
-    };
     did?: string | undefined;
     kid?: string | undefined;
     warnings?: string[] | undefined;

package/dist/vault/schemas.d.ts

@@ -46,13 +46,13 @@ export declare const resolveSecretsRequestSchema: z.ZodObject<{
     assertion: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     userDid: string;
-    envVarNames: string[];
     toolName: string;
+    envVarNames: string[];
     assertion: string;
 }, {
     userDid: string;
-    envVarNames: string[];
     toolName: string;
+    envVarNames: string[];
     assertion: string;
 }>;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-os/contracts",
-  "version": "1.10.1",
+  "version": "1.12.1",
   "description": "Shared contracts, types, and schemas for MCP-I framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,6 +33,14 @@
       "types": "./dist/proof/index.d.ts",
       "default": "./dist/proof/index.js"
     },
+    "./review": {
+      "types": "./dist/review/index.d.ts",
+      "default": "./dist/review/index.js"
+    },
+    "./review/verify": {
+      "types": "./dist/review/verify.d.ts",
+      "default": "./dist/review/verify.js"
+    },
     "./tool-protection": {
       "types": "./dist/tool-protection/index.d.ts",
       "default": "./dist/tool-protection/index.js"