@kya-os/cli 2.0.0 → 2.0.2

package/node_modules/@kya-os/contracts/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/node_modules/@kya-os/contracts/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, {
+        alg: "Ed25519" | "ES256";
+        signature: string;
+        kid?: string | undefined;
+    }, {
+        alg: "Ed25519" | "ES256";
+        signature: string;
+        kid?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    agentDid: string;
+    subject: {
+        repo: string;
+        prNumber: number;
+        fixedHeadSha: string;
+    };
+    proof: {
+        alg: "Ed25519" | "ES256";
+        signature: string;
+        kid?: string | undefined;
+    };
+    respondsToHeadSha: string;
+    taskId?: string | undefined;
+}, {
+    agentDid: string;
+    subject: {
+        repo: string;
+        prNumber: number;
+        fixedHeadSha: string;
+    };
+    proof: {
+        alg: "Ed25519" | "ES256";
+        signature: string;
+        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/node_modules/@kya-os/contracts/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');
+}

package/node_modules/@kya-os/contracts/dist/review/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Review Module Exports
+ *
+ * Types, Zod schemas, and canonicalization for PR review verdicts.
+ */
+export * from './schemas.js';
+export * from './canonicalize.js';
+export * from './registry.js';
+export * from './fix-attestation.js';

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

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Review Module Exports
+ *
+ * Types, Zod schemas, and canonicalization for PR review verdicts.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./schemas.js"), exports);
+__exportStar(require("./canonicalize.js"), exports);
+__exportStar(require("./registry.js"), exports);
+__exportStar(require("./fix-attestation.js"), exports);