@2kw/ai 7.3.0-dev.5 → 7.3.0-dev.9

package/dist/relay-protocol/frames.d.ts

@@ -0,0 +1,75 @@
+import type { KeyObject } from "node:crypto";
+import type { HeaderPair } from "./wire.js";
+export type FrameType = "accepted" | "head" | "data" | "end" | "error";
+export type UnsignedFrame = {
+    seq: number;
+    type: "accepted";
+} | {
+    seq: number;
+    type: "head";
+    status: number;
+    headers: HeaderPair[];
+} | {
+    seq: number;
+    type: "data";
+    bytes: string;
+} | {
+    seq: number;
+    type: "end";
+} | {
+    seq: number;
+    type: "error";
+    code: string;
+    message: string;
+};
+export type Frame = UnsignedFrame & {
+    sig: string;
+};
+type Without<T, K extends keyof never> = T extends unknown ? Omit<T, K> : never;
+export type FrameFields = Without<UnsignedFrame, "seq">;
+export declare class FrameError extends Error {
+    readonly code = "response_invalid";
+    constructor(message: string);
+}
+/** UTF-16 code units, so `String.length` says the same thing on both sides of the wire. */
+export declare const MAX_FRAME_MESSAGE_LENGTH = 1024;
+export declare function isErrorFrameCode(code: string): boolean;
+export declare function isErrorFrameMessage(message: string): boolean;
+/**
+ * Makes a message built from untrusted text signable: control characters become spaces and the
+ * result is truncated. Every caller that interpolates something the hub or an upstream chose —
+ * a `srv` claim, a method, an upstream error string — runs it through this, because
+ * `FrameSigner.next` refuses the frame otherwise and the relay would answer nothing at all.
+ */
+export declare function sanitizeFrameMessage(message: string): string;
+/** Contract C7. */
+export declare function fieldsDigest(frame: UnsignedFrame): string;
+export declare function frameSigningInput(requestId: string, frame: UnsignedFrame, prev: string): string;
+export declare class FrameSigner {
+    private readonly key;
+    private readonly requestId;
+    private prev;
+    private seq;
+    constructor(key: KeyObject, requestId: string, jti: string);
+    get nextSeq(): number;
+    /**
+     * A `head`'s headers are signed as given: pass `filterHeaders(pairs, isReturnedResponseHeader)`
+     * output. An `error`'s code and message must already satisfy the injectivity rule — build the
+     * message with `sanitizeFrameMessage` when any part of it came from outside the relay — because
+     * the relay must never put a signature on a frame a hub could restate.
+     */
+    next(fields: FrameFields): Frame;
+}
+export declare function isFrameShape(raw: unknown): raw is Frame;
+export declare class FrameChainVerifier {
+    private readonly publicKey;
+    private readonly requestId;
+    private expectedSeq;
+    private prev;
+    private last;
+    private done;
+    constructor(publicKey: KeyObject, requestId: string, jti: string);
+    verify(raw: unknown): Frame;
+}
+export {};
+//# sourceMappingURL=frames.d.ts.map

package/dist/relay-protocol/frames.js

@@ -0,0 +1,224 @@
+import { b64url, fromB64url, sha256b64url } from "./b64.js";
+import { HeaderError, canonicalHeaders, filterHeaders, isReturnedResponseHeader } from "./headers.js";
+import { signBytes, verifyBytes } from "./keys.js";
+export class FrameError extends Error {
+    code = "response_invalid";
+    constructor(message) {
+        super(message);
+        this.name = "FrameError";
+    }
+}
+/**
+ * An `error` frame's digest is `code + "\n" + message`, so without a rule on the two fields the
+ * pair is not injective: `("upstream_incomplete", "a\nb")` and `("upstream_incomplete\na", "b")`
+ * hash the same and share one signature, which lets the untrusted hub (spec D14) restate either
+ * as the other. This is the rule C6 already applies to header values, in the one place C7 left
+ * open. The code is additionally constrained to a wire-code spelling because it ends up as a
+ * metric label and as a `McpRelayErrorCode` on the Java side; the message is bounded so a frame
+ * cannot carry a payload in a field nothing reads as one. `fieldsDigest` is unchanged: the rule
+ * lives in the shape gate, on the signer's side and the verifier's alike.
+ */
+const ERROR_CODE_SHAPE = /^[a-z][a-z0-9_]{0,63}$/;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
+/** UTF-16 code units, so `String.length` says the same thing on both sides of the wire. */
+export const MAX_FRAME_MESSAGE_LENGTH = 1024;
+export function isErrorFrameCode(code) {
+    return ERROR_CODE_SHAPE.test(code);
+}
+export function isErrorFrameMessage(message) {
+    return message.length <= MAX_FRAME_MESSAGE_LENGTH && !CONTROL_CHARACTERS.test(message);
+}
+/**
+ * Makes a message built from untrusted text signable: control characters become spaces and the
+ * result is truncated. Every caller that interpolates something the hub or an upstream chose —
+ * a `srv` claim, a method, an upstream error string — runs it through this, because
+ * `FrameSigner.next` refuses the frame otherwise and the relay would answer nothing at all.
+ */
+export function sanitizeFrameMessage(message) {
+    return message.replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, MAX_FRAME_MESSAGE_LENGTH);
+}
+/** Contract C7. */
+export function fieldsDigest(frame) {
+    switch (frame.type) {
+        case "accepted":
+        case "end":
+            return sha256b64url(Buffer.alloc(0));
+        case "head":
+            return sha256b64url(`${frame.status}\n${canonicalHeaders(frame.headers, isReturnedResponseHeader)}`);
+        case "data":
+            return sha256b64url(fromB64url(frame.bytes));
+        case "error":
+            return sha256b64url(`${frame.code}\n${frame.message}`);
+    }
+}
+export function frameSigningInput(requestId, frame, prev) {
+    return `mcprelay-frame-v1\n${requestId}\n${frame.seq}\n${frame.type}\n${fieldsDigest(frame)}\n${prev}`;
+}
+export class FrameSigner {
+    key;
+    requestId;
+    prev;
+    seq = 0;
+    constructor(key, requestId, jti) {
+        this.key = key;
+        this.requestId = requestId;
+        this.prev = jti;
+    }
+    get nextSeq() {
+        return this.seq;
+    }
+    /**
+     * A `head`'s headers are signed as given: pass `filterHeaders(pairs, isReturnedResponseHeader)`
+     * output. An `error`'s code and message must already satisfy the injectivity rule — build the
+     * message with `sanitizeFrameMessage` when any part of it came from outside the relay — because
+     * the relay must never put a signature on a frame a hub could restate.
+     */
+    next(fields) {
+        const frame = { ...fields, seq: this.seq };
+        if (frame.type === "error") {
+            if (!isErrorFrameCode(frame.code)) {
+                throw new FrameError(`error frame code ${JSON.stringify(frame.code)} is not a wire code`);
+            }
+            if (!isErrorFrameMessage(frame.message)) {
+                throw new FrameError("error frame message carries a control character or exceeds 1024 characters");
+            }
+        }
+        const sig = b64url(signBytes(this.key, frameSigningInput(this.requestId, frame, this.prev)));
+        this.prev = sig;
+        this.seq += 1;
+        return { ...frame, sig };
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isHeaderPairs(value) {
+    return (Array.isArray(value) &&
+        value.every((pair) => Array.isArray(pair) && pair.length === 2 && typeof pair[0] === "string" && typeof pair[1] === "string"));
+}
+export function isFrameShape(raw) {
+    if (!isRecord(raw) || typeof raw.sig !== "string" || !Number.isInteger(raw.seq) || raw.seq < 0) {
+        return false;
+    }
+    switch (raw.type) {
+        case "accepted":
+        case "end":
+            return true;
+        case "head":
+            return Number.isInteger(raw.status) && isHeaderPairs(raw.headers);
+        case "data":
+            return typeof raw.bytes === "string";
+        case "error":
+            return (typeof raw.code === "string" &&
+                isErrorFrameCode(raw.code) &&
+                typeof raw.message === "string" &&
+                isErrorFrameMessage(raw.message));
+        default:
+            return false;
+    }
+}
+/**
+ * The signed fields of a frame and nothing else. `isFrameShape` tolerates extra properties — the
+ * hub is untrusted (spec D14) and may add any — and the digest covers only the enumerated ones,
+ * so a verified object must be rebuilt before it reaches a caller. Otherwise unsigned,
+ * attacker-chosen data rides inside an object the backend has just proved authentic. The header
+ * pairs are copied for the same reason: the arrays themselves are the hub's.
+ */
+function signedFieldsOnly(frame) {
+    switch (frame.type) {
+        case "accepted":
+            return { seq: frame.seq, type: "accepted", sig: frame.sig };
+        case "end":
+            return { seq: frame.seq, type: "end", sig: frame.sig };
+        case "head":
+            return {
+                seq: frame.seq,
+                type: "head",
+                status: frame.status,
+                headers: frame.headers.map(([name, value]) => [name, value]),
+                sig: frame.sig,
+            };
+        case "data":
+            return { seq: frame.seq, type: "data", bytes: frame.bytes, sig: frame.sig };
+        case "error":
+            return { seq: frame.seq, type: "error", code: frame.code, message: frame.message, sig: frame.sig };
+    }
+}
+/**
+ * A `head` carries the canonical returned headers of contract C6 as sorted pairs. The digest
+ * covers that canonical form, so a frame whose pairs are spelled differently would let the hub
+ * restate a signed head; a HeaderError (duplicate name, control character in a value) says the
+ * same thing — these pairs are not the canonical form — and is therefore a rejection here, not
+ * an exception out of the verifier.
+ */
+function isCanonicalHead(headers) {
+    try {
+        return JSON.stringify(filterHeaders(headers, isReturnedResponseHeader)) === JSON.stringify(headers);
+    }
+    catch (error) {
+        if (error instanceof HeaderError) {
+            return false;
+        }
+        throw error;
+    }
+}
+export class FrameChainVerifier {
+    publicKey;
+    requestId;
+    expectedSeq = 0;
+    prev;
+    last = null;
+    done = false;
+    constructor(publicKey, requestId, jti) {
+        this.publicKey = publicKey;
+        this.requestId = requestId;
+        this.prev = jti;
+    }
+    verify(raw) {
+        if (!isFrameShape(raw)) {
+            throw new FrameError("malformed frame");
+        }
+        if (raw.seq !== this.expectedSeq) {
+            throw new FrameError(`expected frame ${this.expectedSeq}, got ${raw.seq}`);
+        }
+        if (this.done) {
+            throw new FrameError("frame after a terminal frame");
+        }
+        const allowed = raw.seq === 0
+            ? raw.type === "accepted" || raw.type === "error"
+            : this.last === "accepted"
+                ? raw.type === "head" || raw.type === "error"
+                : raw.type === "data" || raw.type === "end" || raw.type === "error";
+        if (!allowed) {
+            throw new FrameError(`${raw.type} is not allowed at this point of the chain`);
+        }
+        if (raw.type === "head" && !isCanonicalHead(raw.headers)) {
+            throw new FrameError("head headers are not canonical");
+        }
+        let signature;
+        try {
+            signature = fromB64url(raw.sig);
+        }
+        catch {
+            throw new FrameError("malformed signature");
+        }
+        let signingInput;
+        try {
+            signingInput = frameSigningInput(this.requestId, raw, this.prev);
+        }
+        catch {
+            // A `data` payload that is not canonical base64url (contract C1) lands here: the hub is
+            // untrusted for integrity (spec D14), so its input is rejected, never thrown past us.
+            throw new FrameError("malformed frame fields");
+        }
+        if (!verifyBytes(this.publicKey, signingInput, signature)) {
+            throw new FrameError("frame signature does not verify");
+        }
+        this.prev = raw.sig;
+        this.expectedSeq += 1;
+        this.last = raw.type;
+        this.done = raw.type === "end" || raw.type === "error";
+        return signedFieldsOnly(raw);
+    }
+}
+//# sourceMappingURL=frames.js.map

package/dist/relay-protocol/headers.d.ts

@@ -0,0 +1,18 @@
+import type { HeaderPair } from "./wire.js";
+export type HeaderErrorCode = "duplicate_header" | "invalid_header";
+export declare class HeaderError extends Error {
+    readonly code: HeaderErrorCode;
+    constructor(code: HeaderErrorCode, message: string);
+}
+export declare function isForwardedRequestHeader(name: string): boolean;
+export declare function isReturnedResponseHeader(name: string): boolean;
+/**
+ * Contract C6: lower-case, keep allowed, refuse control characters and non-token names,
+ * trim, refuse duplicates, sort by name. A header that is not on the allowlist is ignored
+ * without being validated — it never reaches the digest.
+ */
+export declare function filterHeaders(pairs: Iterable<readonly [string, string]>, allowed: (name: string) => boolean): HeaderPair[];
+export declare function canonicalHeaders(pairs: Iterable<readonly [string, string]>, allowed: (name: string) => boolean): string;
+export declare function requestHeadersDigest(pairs: Iterable<readonly [string, string]>): string;
+export declare function bodyDigest(body: Uint8Array): string;
+//# sourceMappingURL=headers.d.ts.map

package/dist/relay-protocol/headers.js

@@ -0,0 +1,88 @@
+// GENERATED COPY of relay/src/protocol/headers.ts (#1377). Do not edit here: edit the relay's file,
+// then run `npm run sync:relay-protocol` in cli/. `npm run check:relay-protocol` fails on any drift.
+import { sha256b64url } from "./b64.js";
+const FORWARDED_REQUEST_HEADERS = new Set([
+    "accept",
+    "authorization",
+    "content-type",
+    "idempotency-key",
+    "last-event-id",
+    "mcp-method",
+    "mcp-name",
+    "mcp-protocol-version",
+    "mcp-session-id",
+    "traceparent",
+    "tracestate",
+]);
+const RETURNED_RESPONSE_HEADERS = new Set([
+    "cache-control",
+    "content-type",
+    "etag",
+    "location",
+    "mcp-protocol-version",
+    "mcp-session-id",
+    "retry-after",
+    "www-authenticate",
+]);
+export class HeaderError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "HeaderError";
+        this.code = code;
+    }
+}
+export function isForwardedRequestHeader(name) {
+    return FORWARDED_REQUEST_HEADERS.has(name) || name.startsWith("mcp-param-");
+}
+export function isReturnedResponseHeader(name) {
+    return RETURNED_RESPONSE_HEADERS.has(name);
+}
+const SURROUNDING_WHITESPACE = /^[ \t]+|[ \t]+$/g;
+/** RFC 7230 token, already lower-cased. Only the `mcp-param-` prefix can reach it unvetted. */
+const HEADER_NAME_TOKEN = /^[!#$%&'*+\-.^_`|~0-9a-z]+$/;
+/**
+ * Any code unit below 0x20 except TAB, plus DEL. The canonical form joins pairs with ":"
+ * and "\n", so a value carrying either separator would let two different header sets
+ * produce one digest — and the hub, untrusted for integrity (spec D14), is the party that
+ * would exploit that. Refusing the whole control range keeps the rule trivial to restate
+ * in Java.
+ */
+const FORBIDDEN_VALUE_CHARS = /[\u0000-\u0008\u000a-\u001f\u007f]/;
+/**
+ * Contract C6: lower-case, keep allowed, refuse control characters and non-token names,
+ * trim, refuse duplicates, sort by name. A header that is not on the allowlist is ignored
+ * without being validated — it never reaches the digest.
+ */
+export function filterHeaders(pairs, allowed) {
+    const kept = new Map();
+    for (const [rawName, rawValue] of pairs) {
+        const name = rawName.toLowerCase();
+        if (!allowed(name)) {
+            continue;
+        }
+        if (!HEADER_NAME_TOKEN.test(name)) {
+            throw new HeaderError("invalid_header", `header name ${JSON.stringify(name)} is not a token`);
+        }
+        if (FORBIDDEN_VALUE_CHARS.test(rawValue)) {
+            throw new HeaderError("invalid_header", `header ${name} carries a control character`);
+        }
+        if (kept.has(name)) {
+            throw new HeaderError("duplicate_header", `header ${name} appears more than once`);
+        }
+        kept.set(name, rawValue.replace(SURROUNDING_WHITESPACE, ""));
+    }
+    return [...kept.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+export function canonicalHeaders(pairs, allowed) {
+    return filterHeaders(pairs, allowed)
+        .map(([name, value]) => `${name}:${value}\n`)
+        .join("");
+}
+export function requestHeadersDigest(pairs) {
+    return sha256b64url(canonicalHeaders(pairs, isForwardedRequestHeader));
+}
+export function bodyDigest(body) {
+    return sha256b64url(body);
+}
+//# sourceMappingURL=headers.js.map

package/dist/relay-protocol/jws.d.ts

@@ -0,0 +1,28 @@
+import type { KeyObject } from "node:crypto";
+export declare class JwsError extends Error {
+    readonly code: "malformed" | "bad_alg" | "bad_typ" | "unknown_kid" | "bad_signature" | "bad_claims";
+    constructor(code: "malformed" | "bad_alg" | "bad_typ" | "unknown_kid" | "bad_signature" | "bad_claims", message: string);
+}
+export interface JwsHeader {
+    alg: "EdDSA";
+    typ: string;
+    kid: string;
+}
+export interface DecodedJws {
+    header: JwsHeader;
+    claims: Record<string, unknown>;
+    signingInput: string;
+    signature: Buffer;
+}
+/** Contract C3. */
+export declare function signJws(typ: string, kid: string, claims: Record<string, unknown>, key: KeyObject): string;
+export declare function decodeJws(token: string): DecodedJws;
+export declare function verifyJws(token: string, expectedTyp: string, keyFor: (kid: string) => KeyObject | undefined): DecodedJws;
+/** Contract C8. */
+export declare function enrolProofInput(token: string, kid: string, publicKey: string): string;
+export declare function signEnrolProof(key: KeyObject, token: string, kid: string, publicKey: string): string;
+/** Contract C5. */
+export declare function mintRelayJwt(key: KeyObject, kid: string, relayId: string, audience: string, nowSec: number): string;
+/** Checks the claims of an already signature-verified relay JWT; returns the relay id. */
+export declare function verifyRelayJwtClaims(claims: Record<string, unknown>, audience: string, nowSec: number): string;
+//# sourceMappingURL=jws.d.ts.map

package/dist/relay-protocol/jws.js

@@ -0,0 +1,113 @@
+import { b64url, fromB64url, randomHex } from "./b64.js";
+import { signBytes, verifyBytes } from "./keys.js";
+import { CLOCK_SKEW_SECONDS, MAX_JWT_LIFETIME_SECONDS, RELAY_TYP } from "./wire.js";
+export class JwsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "JwsError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function part(json) {
+    return b64url(Buffer.from(JSON.stringify(json), "utf8"));
+}
+/** Contract C3. */
+export function signJws(typ, kid, claims, key) {
+    const signingInput = `${part({ alg: "EdDSA", typ, kid })}.${part(claims)}`;
+    return `${signingInput}.${b64url(signBytes(key, signingInput))}`;
+}
+export function decodeJws(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+        throw new JwsError("malformed", "a compact JWS has three parts");
+    }
+    const [headerPart, payloadPart, signaturePart] = parts;
+    let header;
+    let claims;
+    let signature;
+    try {
+        header = JSON.parse(fromB64url(headerPart).toString("utf8"));
+        claims = JSON.parse(fromB64url(payloadPart).toString("utf8"));
+        signature = fromB64url(signaturePart);
+    }
+    catch {
+        throw new JwsError("malformed", "unparseable header, payload or signature");
+    }
+    if (!isRecord(header) || !isRecord(claims)) {
+        throw new JwsError("malformed", "header and payload must be JSON objects");
+    }
+    if (header.alg !== "EdDSA") {
+        throw new JwsError("bad_alg", "alg must be EdDSA");
+    }
+    if (typeof header.typ !== "string") {
+        throw new JwsError("malformed", "typ must be a string");
+    }
+    if (typeof header.kid !== "string" || header.kid.length < 1 || header.kid.length > 64) {
+        throw new JwsError("malformed", "kid must be a string of 1 to 64 characters");
+    }
+    if (signature.length !== 64) {
+        throw new JwsError("malformed", "an Ed25519 signature has 64 bytes");
+    }
+    return {
+        header: { alg: "EdDSA", typ: header.typ, kid: header.kid },
+        claims,
+        signingInput: `${headerPart}.${payloadPart}`,
+        signature,
+    };
+}
+export function verifyJws(token, expectedTyp, keyFor) {
+    const decoded = decodeJws(token);
+    if (decoded.header.typ !== expectedTyp) {
+        throw new JwsError("bad_typ", `typ must be ${expectedTyp}`);
+    }
+    const key = keyFor(decoded.header.kid);
+    if (key === undefined) {
+        throw new JwsError("unknown_kid", "no key for this kid");
+    }
+    if (!verifyBytes(key, decoded.signingInput, decoded.signature)) {
+        throw new JwsError("bad_signature", "signature does not verify");
+    }
+    return decoded;
+}
+/** Contract C8. */
+export function enrolProofInput(token, kid, publicKey) {
+    return `mcprelay-enrol-v1\n${token}\n${kid}\n${publicKey}`;
+}
+export function signEnrolProof(key, token, kid, publicKey) {
+    return b64url(signBytes(key, enrolProofInput(token, kid, publicKey)));
+}
+/** Contract C5. */
+export function mintRelayJwt(key, kid, relayId, audience, nowSec) {
+    return signJws(RELAY_TYP, kid, { iss: relayId, aud: audience, iat: nowSec, exp: nowSec + MAX_JWT_LIFETIME_SECONDS, jti: randomHex(16) }, key);
+}
+/** Checks the claims of an already signature-verified relay JWT; returns the relay id. */
+export function verifyRelayJwtClaims(claims, audience, nowSec) {
+    const { iss, aud, iat, exp } = claims;
+    if (typeof iss !== "string" || iss.length === 0) {
+        throw new JwsError("bad_claims", "relay JWT has no issuer");
+    }
+    if (aud !== audience) {
+        throw new JwsError("bad_claims", "relay JWT audience does not match");
+    }
+    if (typeof iat !== "number" || typeof exp !== "number" || !Number.isInteger(iat) || !Number.isInteger(exp)) {
+        throw new JwsError("bad_claims", "relay JWT times must be integers");
+    }
+    if (exp - iat > MAX_JWT_LIFETIME_SECONDS) {
+        throw new JwsError("bad_claims", "relay JWT lifetime exceeds 60 seconds");
+    }
+    if (exp < iat) {
+        throw new JwsError("bad_claims", "relay JWT expires before it was issued");
+    }
+    if (nowSec > exp + CLOCK_SKEW_SECONDS) {
+        throw new JwsError("bad_claims", "relay JWT expired");
+    }
+    if (iat > nowSec + CLOCK_SKEW_SECONDS) {
+        throw new JwsError("bad_claims", "relay JWT issued in the future");
+    }
+    return iss;
+}
+//# sourceMappingURL=jws.js.map

package/dist/relay-protocol/keys.d.ts

@@ -0,0 +1,26 @@
+import { type KeyObject } from "node:crypto";
+export interface Jwk {
+    kty: "OKP";
+    crv: "Ed25519";
+    x: string;
+    kid: string;
+    alg: "EdDSA";
+    use: "sig";
+}
+export declare function privateKeyFromSeed(seed: Uint8Array): KeyObject;
+export declare function privateKeyFromPem(pem: string): KeyObject;
+export declare function privateKeyToPem(key: KeyObject): string;
+export declare function generatePrivateKey(): KeyObject;
+export declare function rawPublicKey(key: KeyObject): Buffer;
+export declare function publicKeyFromRaw(raw: Uint8Array): KeyObject;
+export declare function publicKeyFromJwk(jwk: {
+    kty?: unknown;
+    crv?: unknown;
+    x?: unknown;
+}): KeyObject;
+/** Contract C2: first 16 characters of base64url(SHA-256(raw public key)). */
+export declare function kidOf(raw: Uint8Array): string;
+export declare function jwkOf(raw: Uint8Array): Jwk;
+export declare function signBytes(key: KeyObject, data: Uint8Array | string): Buffer;
+export declare function verifyBytes(key: KeyObject, data: Uint8Array | string, signature: Uint8Array): boolean;
+//# sourceMappingURL=keys.d.ts.map

package/dist/relay-protocol/keys.js

@@ -0,0 +1,80 @@
+// GENERATED COPY of relay/src/protocol/keys.ts (#1377). Do not edit here: edit the relay's file,
+// then run `npm run sync:relay-protocol` in cli/. `npm run check:relay-protocol` fails on any drift.
+import { createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify, } from "node:crypto";
+import { b64url, fromB64url, sha256b64url } from "./b64.js";
+// DER prefixes for Ed25519 keys (RFC 8410): PKCS#8 private key and SPKI public key.
+const PKCS8_ED25519_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+const SPKI_ED25519_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+export function privateKeyFromSeed(seed) {
+    if (seed.length !== 32) {
+        throw new Error("Ed25519 seed must be 32 bytes");
+    }
+    return createPrivateKey({
+        key: Buffer.concat([PKCS8_ED25519_PREFIX, Buffer.from(seed)]),
+        format: "der",
+        type: "pkcs8",
+    });
+}
+export function privateKeyFromPem(pem) {
+    const key = createPrivateKey(pem);
+    if (key.asymmetricKeyType !== "ed25519") {
+        throw new Error("not an Ed25519 private key");
+    }
+    return key;
+}
+export function privateKeyToPem(key) {
+    return key.export({ format: "pem", type: "pkcs8" }).toString();
+}
+export function generatePrivateKey() {
+    return generateKeyPairSync("ed25519").privateKey;
+}
+export function rawPublicKey(key) {
+    if (key.asymmetricKeyType !== "ed25519") {
+        throw new Error("not an Ed25519 key");
+    }
+    // createPublicKey derives the public key from a private one, but rejects a public KeyObject.
+    const publicKey = key.type === "public" ? key : createPublicKey(key);
+    const der = publicKey.export({ format: "der", type: "spki" });
+    return Buffer.from(der.subarray(der.length - 32));
+}
+export function publicKeyFromRaw(raw) {
+    if (raw.length !== 32) {
+        throw new Error("Ed25519 public key must be 32 bytes");
+    }
+    return createPublicKey({
+        key: Buffer.concat([SPKI_ED25519_PREFIX, Buffer.from(raw)]),
+        format: "der",
+        type: "spki",
+    });
+}
+export function publicKeyFromJwk(jwk) {
+    if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || typeof jwk.x !== "string") {
+        throw new Error("not an Ed25519 JWK");
+    }
+    return publicKeyFromRaw(fromB64url(jwk.x));
+}
+/** Contract C2: first 16 characters of base64url(SHA-256(raw public key)). */
+export function kidOf(raw) {
+    return sha256b64url(raw).slice(0, 16);
+}
+export function jwkOf(raw) {
+    return { kty: "OKP", crv: "Ed25519", x: b64url(raw), kid: kidOf(raw), alg: "EdDSA", use: "sig" };
+}
+function bytes(data) {
+    return typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
+}
+export function signBytes(key, data) {
+    return sign(null, bytes(data), key);
+}
+export function verifyBytes(key, data, signature) {
+    if (signature.length !== 64) {
+        return false;
+    }
+    try {
+        return verify(null, bytes(data), key, Buffer.from(signature));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=keys.js.map