@kya-os/cli 2.0.0 → 2.0.2

package/node_modules/@kya-os/contracts/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;
+    headSha: string;
+    prNumber: number;
+}, {
+    repo: string;
+    headSha: string;
+    prNumber: number;
+}>;
+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;
+    detail?: string | undefined;
+    line?: number | undefined;
+}, {
+    summary: string;
+    severity: "blocking" | "major" | "minor" | "nit";
+    path?: string | undefined;
+    detail?: string | undefined;
+    line?: number | 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;
+        headSha: string;
+        prNumber: number;
+    }, {
+        repo: string;
+        headSha: string;
+        prNumber: number;
+    }>;
+    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;
+        detail?: string | undefined;
+        line?: number | undefined;
+    }, {
+        summary: string;
+        severity: "blocking" | "major" | "minor" | "nit";
+        path?: string | undefined;
+        detail?: string | undefined;
+        line?: number | 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, {
+        alg: "Ed25519" | "ES256";
+        signature: string;
+        kid?: string | undefined;
+    }, {
+        alg: "Ed25519" | "ES256";
+        signature: string;
+        kid?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    subject: {
+        repo: string;
+        headSha: string;
+        prNumber: number;
+    };
+    proof: {
+        alg: "Ed25519" | "ES256";
+        signature: string;
+        kid?: string | undefined;
+    };
+    taskId: string;
+    verdict: "approve" | "request-changes" | "comment";
+    findings: {
+        summary: string;
+        severity: "blocking" | "major" | "minor" | "nit";
+        path?: string | undefined;
+        detail?: string | undefined;
+        line?: number | undefined;
+    }[];
+    findingsDigest: string;
+}, {
+    subject: {
+        repo: string;
+        headSha: string;
+        prNumber: number;
+    };
+    proof: {
+        alg: "Ed25519" | "ES256";
+        signature: string;
+        kid?: string | undefined;
+    };
+    taskId: string;
+    verdict: "approve" | "request-changes" | "comment";
+    findings: {
+        summary: string;
+        severity: "blocking" | "major" | "minor" | "nit";
+        path?: string | undefined;
+        detail?: string | undefined;
+        line?: number | 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;
+        headSha: string;
+        prNumber: number;
+    };
+    proof: {
+        alg: "Ed25519" | "ES256";
+        signature: string;
+        kid?: string | undefined;
+    };
+    taskId: string;
+    verdict: "approve" | "request-changes" | "comment";
+    findings: {
+        summary: string;
+        severity: "blocking" | "major" | "minor" | "nit";
+        path?: string | undefined;
+        detail?: string | undefined;
+        line?: number | undefined;
+    }[];
+    findingsDigest: string;
+}, {
+    subject: {
+        repo: string;
+        headSha: string;
+        prNumber: number;
+    };
+    proof: {
+        alg: "Ed25519" | "ES256";
+        signature: string;
+        kid?: string | undefined;
+    };
+    taskId: string;
+    verdict: "approve" | "request-changes" | "comment";
+    findings: {
+        summary: string;
+        severity: "blocking" | "major" | "minor" | "nit";
+        path?: string | undefined;
+        detail?: string | undefined;
+        line?: number | undefined;
+    }[];
+    findingsDigest: string;
+}>;

package/node_modules/@kya-os/contracts/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/node_modules/@kya-os/contracts/dist/review/verify.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Fix Attestation & Review Verdict Verification
+ *
+ * Raw Ed25519 verify for `FixAttestation` (see `fix-attestation.ts`) and
+ * `ReviewVerdictBody` (see `schemas.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 a verify function itself is actually needed.
+ *
+ * `verifyReviewVerdictProof` closed the gap this file's doc comment used to
+ * describe (P9's review-verdict counterpart "has not landed in this
+ * package" — see review-loop P13, which carries it as an unblocking
+ * dependency for its `kya-os agent` CLI commands). Its sibling in
+ * `@kya-os/compute`, `packages/compute/src/didcomm/review.ts`'s
+ * `verifyReviewVerdictSignature`, verifies the same detached signature but
+ * over a JWK-keyed `AgentDIDConfig` and deliberately leaves the
+ * `findingsDigest`-matches-`findings` cross-check to its caller (the hub);
+ * this function takes a raw public key instead (the shape every other
+ * verify function in this file uses, and the shape `dco`'s local key
+ * material is already in) and performs that cross-check itself, since it is
+ * the one verify function a CLI/future caller reaches for end to end rather
+ * than a hub with its own separate recompute step.
+ *
+ * @package @kya-os/contracts/review/verify
+ */
+import { type FixAttestation } from './fix-attestation.js';
+import type { ReviewVerdictBody } from './schemas.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;
+/**
+ * Verify a review verdict's detached Ed25519 signature AND that
+ * `body.findingsDigest` actually matches `body.findings`.
+ *
+ * That second check is the one deliberate difference from
+ * `@kya-os/compute`'s `verifyReviewVerdictSignature`, which documents the
+ * digest-matches-findings cross-check as the CALLER's responsibility (the
+ * hub recomputes and compares separately). This function recomputes
+ * `computeFindingsDigest(body.findings)` itself and refuses a mismatch
+ * before ever checking the signature, so a caller that only calls this one
+ * function still gets the full guarantee: a tampered `findings` array with
+ * a stale digest left in place is rejected here even though the signature
+ * byte-string it verifies (`repo, prNumber, headSha, verdict,
+ * findingsDigest`) never actually contains the findings themselves — see
+ * `getVerdictCanonicalSigningString`'s doc comment in `canonicalize.ts`.
+ *
+ * `publicKeyRaw` is the raw 32-byte Ed25519 public key (e.g. `ssh-key.ts`'s
+ * `deriveEd25519PublicKey` output, or the `x` field of a resolved
+ * `did:web` document's Ed25519 `publicKeyJwk`, base64url-decoded).
+ *
+ * Fail-closed: any malformed input, digest mismatch, key-import failure, or
+ * signature mismatch returns `false` rather than throwing — never admit on
+ * an unverifiable proof.
+ */
+export declare function verifyReviewVerdictProof(body: ReviewVerdictBody, publicKeyRaw: Buffer | Uint8Array): boolean;

package/node_modules/@kya-os/contracts/dist/review/verify.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Fix Attestation & Review Verdict Verification
+ *
+ * Raw Ed25519 verify for `FixAttestation` (see `fix-attestation.ts`) and
+ * `ReviewVerdictBody` (see `schemas.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 a verify function itself is actually needed.
+ *
+ * `verifyReviewVerdictProof` closed the gap this file's doc comment used to
+ * describe (P9's review-verdict counterpart "has not landed in this
+ * package" — see review-loop P13, which carries it as an unblocking
+ * dependency for its `kya-os agent` CLI commands). Its sibling in
+ * `@kya-os/compute`, `packages/compute/src/didcomm/review.ts`'s
+ * `verifyReviewVerdictSignature`, verifies the same detached signature but
+ * over a JWK-keyed `AgentDIDConfig` and deliberately leaves the
+ * `findingsDigest`-matches-`findings` cross-check to its caller (the hub);
+ * this function takes a raw public key instead (the shape every other
+ * verify function in this file uses, and the shape `dco`'s local key
+ * material is already in) and performs that cross-check itself, since it is
+ * the one verify function a CLI/future caller reaches for end to end rather
+ * than a hub with its own separate recompute step.
+ *
+ * @package @kya-os/contracts/review/verify
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyFixAttestationProof = verifyFixAttestationProof;
+exports.verifyReviewVerdictProof = verifyReviewVerdictProof;
+const node_crypto_1 = require("node:crypto");
+const canonicalize_js_1 = require("./canonicalize.js");
+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
+    }
+}
+/**
+ * Verify a review verdict's detached Ed25519 signature AND that
+ * `body.findingsDigest` actually matches `body.findings`.
+ *
+ * That second check is the one deliberate difference from
+ * `@kya-os/compute`'s `verifyReviewVerdictSignature`, which documents the
+ * digest-matches-findings cross-check as the CALLER's responsibility (the
+ * hub recomputes and compares separately). This function recomputes
+ * `computeFindingsDigest(body.findings)` itself and refuses a mismatch
+ * before ever checking the signature, so a caller that only calls this one
+ * function still gets the full guarantee: a tampered `findings` array with
+ * a stale digest left in place is rejected here even though the signature
+ * byte-string it verifies (`repo, prNumber, headSha, verdict,
+ * findingsDigest`) never actually contains the findings themselves — see
+ * `getVerdictCanonicalSigningString`'s doc comment in `canonicalize.ts`.
+ *
+ * `publicKeyRaw` is the raw 32-byte Ed25519 public key (e.g. `ssh-key.ts`'s
+ * `deriveEd25519PublicKey` output, or the `x` field of a resolved
+ * `did:web` document's Ed25519 `publicKeyJwk`, base64url-decoded).
+ *
+ * Fail-closed: any malformed input, digest mismatch, key-import failure, or
+ * signature mismatch returns `false` rather than throwing — never admit on
+ * an unverifiable proof.
+ */
+function verifyReviewVerdictProof(body, publicKeyRaw) {
+    try {
+        const expectedDigest = (0, canonicalize_js_1.computeFindingsDigest)(body.findings);
+        if (expectedDigest !== body.findingsDigest) {
+            return false;
+        }
+        const signingString = (0, canonicalize_js_1.getVerdictCanonicalSigningString)(body.subject, body.verdict, body.findingsDigest);
+        const publicKey = (0, node_crypto_1.createPublicKey)({
+            key: Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(publicKeyRaw)]),
+            format: 'der',
+            type: 'spki',
+        });
+        return (0, node_crypto_1.verify)(null, Buffer.from(signingString, 'utf8'), publicKey, Buffer.from(body.proof.signature, 'base64url'));
+    }
+    catch {
+        return false; // fail-closed — never admit on an unverifiable proof
+    }
+}