@kya-os/cli 1.7.0 → 1.8.3

package/dist/utils/dco/verify.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Verifies that a pull request's attribution byline names an agent identity
+ * that actually resolves.
+ *
+ * `dco setup` only ever *instructs* the harness to write the byline —
+ * the PR body is composed by a model at PR time and can be edited by anyone
+ * with write access to the branch. So an `Agent DID:` line is a claim, not
+ * evidence, until the DID document behind it is fetched and checked. Every
+ * failure mode below exists because some way of "resolving" a DID would
+ * otherwise let an unverified claim read as verified.
+ */
+export type VerifyFailure = "no-did" | "unsupported-method" | "unresolvable" | "did-mismatch" | "blocked-host";
+export interface AttributionVerification {
+    ok: boolean;
+    /** The DID claimed by the PR body, when exactly one valid claim is present. */
+    did?: string;
+    /** Where the DID document was fetched from. */
+    documentUrl?: string;
+    /** The agent's registry page, taken from the document's service entry. */
+    agentUrl?: string;
+    reason?: VerifyFailure;
+    detail?: string;
+}
+export type FetchLike = (url: string, init?: {
+    signal?: AbortSignal;
+    redirect?: RequestInit["redirect"];
+}) => Promise<Response>;
+/**
+ * Resolve a hostname to every address it answers to. Injectable for the same
+ * reason `FetchLike` is: production wants the real resolver, tests want a
+ * fixed answer instead of a live DNS lookup.
+ */
+export type LookupLike = (hostname: string) => Promise<string[]>;
+/**
+ * Exported (review-loop P9 commit 3) so `review verify`'s did:web
+ * resolution (`../review/did-web-key.ts`) can pass the real resolver
+ * through to {@link checkDocumentHostIsSafe} without redefining it — same
+ * reasoning as that export.
+ */
+export declare const defaultLookup: LookupLike;
+/**
+ * The document host is chosen by the DID, which comes from a PR body we do
+ * not control. Without a deadline a hostile or merely unreachable host hangs
+ * the command for as long as it cares to hold the socket open — tolerable
+ * when a human can interrupt it, not when this runs unattended in CI.
+ */
+export declare const RESOLVE_TIMEOUT_MS = 10000;
+/**
+ * Pull the claimed DID out of a PR body.
+ *
+ * Returns null when the body claims two *different* DIDs. Taking the first
+ * match would mean an appended line could never change the verdict, but it
+ * would also mean a forged line prepended above the real one silently wins.
+ * Ambiguous attribution is a failure, not a tie to be broken.
+ */
+export declare function extractAgentDid(prBody: string): string | null;
+/**
+ * Whether a piece of text already carries an `Agent DID:` attribution line
+ * that `extractAgentDid` would pick up. Uses the exact same line pattern and
+ * backtick/whitespace handling, so a caller (notably `dco dispatch`, which
+ * appends its own authoritative line) can reject a description that would
+ * otherwise put a second, conflicting DID into the PR body. Matches the
+ * managed CLAUDE.md block's backticked, mid-line form, not just a line-start
+ * one.
+ */
+export declare function hasAgentDidClaim(text: string): boolean;
+/**
+ * Map a `did:web` to the HTTPS URL its document must be served from, per the
+ * did:web method spec: the identifier's colon-separated segments *are* the
+ * path, and a bare domain resolves under `/.well-known/`.
+ *
+ * Segments are validated AFTER percent-decoding. `DID_PATTERN` permits `%`,
+ * so a crafted `%2F` would otherwise smuggle a path separator through and
+ * point resolution at an attacker-chosen URL on the same host.
+ */
+export declare function didWebToHttpsUrl(did: string): string | null;
+/**
+ * Cheap, synchronous first line of defense against the exact literals an
+ * attacker would put directly in a did:web host: `localhost`, or an IPv4
+ * literal in a private, loopback, link-local, or otherwise reserved range.
+ *
+ * Takes the hostname `new URL()` produces, not the raw did:web segment.
+ * `URL` canonicalizes decimal/hex/octal IPv4 shorthand (`2130706433` and
+ * `0x7f000001` both become `127.0.0.1`) before `fetch` ever sees it, so
+ * checking the pre-parse segment would miss exactly the encodings an
+ * attacker would reach for to slip past a naive dotted-quad check. The
+ * trailing dot is stripped first for the same reason: `new URL()` preserves
+ * a root-zone dot (`"localhost."` stays `"localhost."`), and DNS treats it
+ * as identical to `"localhost"` — an unstripped compare would let that
+ * single character walk straight past an exact-match or `endsWith` check.
+ *
+ * This is a fast-path, not the actual guarantee: it only catches literals,
+ * so it cannot see a normal-looking hostname whose A/AAAA record happens to
+ * point at an internal address. `hostResolvesToBlockedAddress` below is
+ * what actually closes that gap, by checking where the name resolves to
+ * rather than how it's spelled.
+ */
+export declare function isBlockedResolutionHost(hostname: string): boolean;
+/**
+ * The actual guarantee `isBlockedResolutionHost` can't provide on its own:
+ * resolve the hostname and check every address it answers to, not just
+ * whether the hostname string itself looks like one of the blocked
+ * literals. A domain an attacker controls can point an A/AAAA record at
+ * 169.254.169.254 (or loopback, or an RFC1918 address) just as easily as a
+ * did:web host can spell the address out directly — DNS is the attacker's
+ * to shape here just as much as the PR body text is, since the DID names
+ * whatever host they choose.
+ *
+ * Deliberately does not catch a lookup failure: that is "no evidence
+ * either way", the same as a failed fetch, and the caller already has a
+ * reason for that (`unresolvable`) that this must not collide with —
+ * mislabeling a plain NXDOMAIN as "blocked-host" would tell the CLI's user
+ * they hit a private address when they actually just mistyped a domain.
+ */
+export declare function hostResolvesToBlockedAddress(hostname: string, lookupImpl?: LookupLike): Promise<boolean>;
+export type HostSafetyCheck = {
+    safe: true;
+} | {
+    safe: false;
+    reason: "unresolvable" | "blocked-host";
+    detail: string;
+};
+/**
+ * Everything that has to be true about `documentUrl`'s host before it is
+ * worth spending a request on: it must parse, it must not be one of the
+ * literals `isBlockedResolutionHost` recognizes, and it must not resolve to
+ * one either. Pulled out on its own so `verifyPrAttribution` reads as one
+ * linear pipeline instead of three nested guard clauses doing the same kind
+ * of check.
+ *
+ * Exported (review-loop P9 commit 3): `review verify`'s did:web resolution
+ * fetches a DIFFERENT document (an agent's DID document, not a PR-body
+ * claim) from an equally untrusted, wire-supplied host, and needs the exact
+ * same SSRF defense before spending a request on it. Reusing this function
+ * keeps that defense in ONE place rather than re-deriving the blocked-range
+ * checks a second time.
+ */
+export declare function checkDocumentHostIsSafe(documentUrl: string, lookupImpl: LookupLike): Promise<HostSafetyCheck>;
+/**
+ * Resolve the DID claimed by a PR body and confirm the document describes
+ * that same DID.
+ */
+export declare function verifyPrAttribution(prBody: string, fetchImpl?: FetchLike, lookupImpl?: LookupLike): Promise<AttributionVerification>;
+export type KeyResolutionFailure = Exclude<VerifyFailure, "no-did"> | "no-ed25519-key";
+export interface AgentPublicKeyResolution {
+    ok: boolean;
+    did: string;
+    /** Raw 32-byte Ed25519 public key, present only when `ok`. */
+    publicKeyRaw?: Buffer;
+    documentUrl?: string;
+    reason?: KeyResolutionFailure;
+    detail?: string;
+}
+/**
+ * Resolve an agent DID to its raw 32-byte Ed25519 public key, for verifying
+ * a signature it produced (a review verdict's or fix attestation's
+ * `proof`). This is `kya-os agent verify`'s "key resolution v1": scoped to
+ * `did:web` only, since every reviewer/maker DID in this feature is
+ * `did:web:knowthat.ai:agents:<slug>` — a `did:key` or other method fails
+ * closed with `unsupported-method` rather than half-supporting it (state
+ * that scope in the command's `--help`, per this feature's design doc).
+ *
+ * The DID here is read off a PR review or comment — the same
+ * untrusted-input shape `verifyPrAttribution` already handles — so it goes
+ * through the identical SSRF-hardened resolution path
+ * (`resolveDidWebDocument`) before this function ever looks at the document
+ * for a key.
+ */
+export declare function resolveAgentEd25519PublicKey(did: string, fetchImpl?: FetchLike, lookupImpl?: LookupLike): Promise<AgentPublicKeyResolution>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/utils/dco/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/utils/dco/verify.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,oBAAoB,GACpB,cAAc,GACd,cAAc,GACd,cAAc,CAAC;AAEnB,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAA;CAAE,KAChE,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAEjE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,UAG3B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAWzC;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAqC3D;AA0ED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIjE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,4BAA4B,CAChD,QAAQ,EAAE,MAAM,EAChB,UAAU,GAAE,UAA0B,GACrC,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GACd;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,eAAe,CAAC,CA0C1B;AA8HD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,SAA2C,EACtD,UAAU,GAAE,UAA0B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CAqBlC;AA4GD,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,gBAAgB,CAAC;AAEvF,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,4BAA4B,CAChD,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,SAA2C,EACtD,UAAU,GAAE,UAA0B,GACrC,OAAO,CAAC,wBAAwB,CAAC,CAwBnC"}