@runuai/host 0.9.13 → 0.9.42

package/lib/release-manifest.ts

@@ -0,0 +1,708 @@
+import {
+  createHash,
+  createPublicKey,
+  KeyObject,
+  timingSafeEqual,
+  verify as verifySignature,
+} from "node:crypto";
+
+/**
+ * Signed host-runtime release manifests (ADR-099).
+ *
+ * The manifest is an untrusted network input. Keep this module deliberately
+ * independent of the downloader: callers must pin the public keys in their
+ * shipped code, verify the manifest bytes here, and verify the downloaded
+ * artifact before unpacking it.
+ *
+ * Bootstrap is intentionally different from self-update: a fresh POSIX-sh
+ * machine has no portable Ed25519 verifier. The cloud `/install` route uses
+ * this Node module, checks the manifest version against its deployed host
+ * version, and embeds all four authenticated artifact tuples in a no-store
+ * script. The shell selects with uname and checks size/sha256. Once bundled
+ * Node exists, the updater verifies the signed manifest here directly.
+ */
+
+export const RELEASE_MANIFEST_SCHEMA_VERSION = 1 as const;
+export const MAX_RELEASE_MANIFEST_BYTES = 64 * 1024;
+export const MAX_RELEASE_ARTIFACT_BYTES = 512 * 1024 * 1024;
+/**
+ * The source repository is private. Runtime artifacts belong in a dedicated,
+ * release-artifact-only public feed so a fresh machine can download them
+ * without a GitHub credential. The artifact still contains the same host
+ * sources/assets published to npm; the separate feed excludes private Git
+ * history and unrelated monorepo content. Provisioning it is intentionally
+ * separate from this code change.
+ */
+export const DEFAULT_RELEASE_DOWNLOAD_BASE =
+  "https://github.com/runuai/uai-host-releases/releases/download";
+
+export const RELEASE_PLATFORMS = Object.freeze([
+  "darwin-arm64",
+  "darwin-x64",
+  "linux-arm64",
+  "linux-x64",
+] as const);
+
+export type ReleasePlatform = (typeof RELEASE_PLATFORMS)[number];
+
+export interface ReleaseArtifact {
+  readonly url: string;
+  /** Exact byte length of the final compressed tarball. */
+  readonly size: number;
+  /** Lowercase sha256 of the final compressed tarball bytes. */
+  readonly sha256: string;
+}
+
+export type ReleaseArtifacts = Readonly<
+  Record<ReleasePlatform, ReleaseArtifact>
+>;
+
+export interface ReleaseManifestPayload {
+  readonly schemaVersion: typeof RELEASE_MANIFEST_SCHEMA_VERSION;
+  readonly keyId: string;
+  readonly version: string;
+  readonly files: ReleaseArtifacts;
+}
+
+export interface SignedReleaseManifest extends ReleaseManifestPayload {
+  /** Canonical RFC 4648 base64. Ed25519 signatures are exactly 64 bytes. */
+  readonly signature: string;
+}
+
+/**
+ * A caller-owned trust anchor. This list must be compiled into the installer
+ * or runtime; a key delivered beside the manifest is not trusted.
+ */
+export interface PinnedReleaseManifestKey {
+  readonly publicKey: string | Buffer | KeyObject;
+}
+
+export interface ReleaseManifestVerificationOptions {
+  /** Map keys are the pinned key ids; manifest-provided key material is ignored. */
+  readonly trustedKeys: ReadonlyMap<string, PinnedReleaseManifestKey>;
+  readonly releaseBaseUrl?: string;
+}
+
+export interface ReleaseArtifactIntegrity {
+  readonly size: number;
+  /** A lowercase hex digest or the raw 32-byte sha256 digest. */
+  readonly sha256: string | Uint8Array;
+}
+
+export type ReleaseManifestErrorCode =
+  | "manifest_too_large"
+  | "invalid_encoding"
+  | "invalid_json"
+  | "invalid_schema"
+  | "invalid_trust_store"
+  | "unknown_key"
+  | "invalid_signature"
+  | "artifact_too_large"
+  | "artifact_size_mismatch"
+  | "artifact_sha256_mismatch";
+
+export class ReleaseManifestError extends Error {
+  override readonly name = "ReleaseManifestError";
+
+  constructor(
+    readonly code: ReleaseManifestErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+const SIGNATURE_CONTEXT = "uai-host-release-manifest/v1\n";
+const KEY_ID_PATTERN = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
+const VERSION_PATTERN = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+const BASE64_ED25519_PATTERN = /^[A-Za-z0-9+/]{86}==$/;
+const MAX_JSON_DEPTH = 32;
+
+function fail(code: ReleaseManifestErrorCode, message: string): never {
+  throw new ReleaseManifestError(code, message);
+}
+
+export function releaseArtifactFilename(
+  version: string,
+  platform: ReleasePlatform,
+): string {
+  assertVersion(version);
+  if (!isReleasePlatform(platform)) {
+    fail("invalid_schema", `unsupported release platform: ${String(platform)}`);
+  }
+  return `uai-host-v${version}-${platform}.tar.gz`;
+}
+
+/** The only release asset URL accepted by the host installer/updater. */
+export function releaseArtifactUrl(
+  version: string,
+  platform: ReleasePlatform,
+  releaseBaseUrl = DEFAULT_RELEASE_DOWNLOAD_BASE,
+): string {
+  const filename = releaseArtifactFilename(version, platform);
+  const base = validateReleaseBaseUrl(releaseBaseUrl);
+  return `${base}/host-tarball-v${version}/${filename}`;
+}
+
+/**
+ * Produce the one canonical byte sequence covered by the signature.
+ * The context prefix prevents a valid signature from being reused by a
+ * different protocol that happens to serialize the same JSON.
+ */
+export function canonicalReleaseManifestBytes(
+  payload: ReleaseManifestPayload,
+  releaseBaseUrl = DEFAULT_RELEASE_DOWNLOAD_BASE,
+): Buffer {
+  const normalized = validatePayload(payload, releaseBaseUrl);
+  const json = JSON.stringify(normalized);
+  return Buffer.from(`${SIGNATURE_CONTEXT}${json}`, "utf8");
+}
+
+/**
+ * Parse and authenticate raw response bytes. No property of the returned
+ * object is exposed until strict schema and Ed25519 verification both pass.
+ */
+export function verifyReleaseManifest(
+  input: Uint8Array,
+  options: ReleaseManifestVerificationOptions,
+): SignedReleaseManifest {
+  const parsed = parseUntrustedJson(input);
+  const releaseBaseUrl = validateReleaseBaseUrl(
+    options.releaseBaseUrl ?? DEFAULT_RELEASE_DOWNLOAD_BASE,
+  );
+  const manifest = validateSignedManifest(parsed, releaseBaseUrl);
+  const key = resolvePinnedKey(manifest.keyId, options.trustedKeys);
+  const signature = decodeSignature(manifest.signature);
+  const signingBytes = canonicalReleaseManifestBytes(manifest, releaseBaseUrl);
+
+  let valid = false;
+  try {
+    valid = verifySignature(null, signingBytes, key, signature);
+  } catch {
+    fail("invalid_signature", "release manifest signature verification failed");
+  }
+  if (!valid) {
+    fail("invalid_signature", "release manifest signature verification failed");
+  }
+
+  return freezeManifest(manifest);
+}
+
+/** Select only a platform from the closed release platform set. */
+export function releaseArtifactForPlatform(
+  manifest: SignedReleaseManifest,
+  platform: string,
+): ReleaseArtifact {
+  if (!isReleasePlatform(platform)) {
+    fail("invalid_schema", `unsupported release platform: ${platform}`);
+  }
+  return manifest.files[platform];
+}
+
+/**
+ * Verify the exact bytes fetched for an artifact before any extraction.
+ * Size is checked before hashing so a declared artifact cannot silently gain
+ * trailing data.
+ */
+export function verifyReleaseArtifactBytes(
+  artifact: ReleaseArtifact,
+  bytes: Uint8Array,
+): void {
+  const expected = validateArtifactShape(artifact, "artifact");
+  if (bytes.byteLength > MAX_RELEASE_ARTIFACT_BYTES) {
+    fail(
+      "artifact_too_large",
+      `release artifact exceeds ${MAX_RELEASE_ARTIFACT_BYTES} bytes`,
+    );
+  }
+  if (bytes.byteLength !== expected.size) {
+    fail(
+      "artifact_size_mismatch",
+      `release artifact size mismatch: expected ${expected.size}, received ${bytes.byteLength}`,
+    );
+  }
+  const digest = createHash("sha256").update(bytes).digest();
+  verifyReleaseArtifactIntegrity(expected, {
+    size: bytes.byteLength,
+    sha256: digest,
+  });
+}
+
+/**
+ * Streaming-friendly final gate. A downloader can count bytes and update a
+ * sha256 hash as it writes to a temporary file, then call this without ever
+ * buffering the artifact in memory.
+ */
+export function verifyReleaseArtifactIntegrity(
+  artifact: ReleaseArtifact,
+  actual: ReleaseArtifactIntegrity,
+): void {
+  const expected = validateArtifactShape(artifact, "artifact");
+  if (
+    !Number.isSafeInteger(actual.size) ||
+    actual.size < 0 ||
+    actual.size > MAX_RELEASE_ARTIFACT_BYTES
+  ) {
+    fail(
+      "artifact_too_large",
+      `release artifact exceeds ${MAX_RELEASE_ARTIFACT_BYTES} bytes`,
+    );
+  }
+  if (actual.size !== expected.size) {
+    fail(
+      "artifact_size_mismatch",
+      `release artifact size mismatch: expected ${expected.size}, received ${actual.size}`,
+    );
+  }
+
+  const expectedDigest = Buffer.from(expected.sha256, "hex");
+  const actualDigest = decodeArtifactDigest(actual.sha256);
+  if (!timingSafeEqual(actualDigest, expectedDigest)) {
+    fail("artifact_sha256_mismatch", "release artifact sha256 mismatch");
+  }
+}
+
+export function isReleasePlatform(value: string): value is ReleasePlatform {
+  return (RELEASE_PLATFORMS as readonly string[]).includes(value);
+}
+
+function validateSignedManifest(
+  value: unknown,
+  releaseBaseUrl: string,
+): SignedReleaseManifest {
+  const object = strictObject(
+    value,
+    ["schemaVersion", "keyId", "version", "files", "signature"],
+    "manifest",
+  );
+  const payload = validatePayload(object, releaseBaseUrl);
+  const signature = object.signature;
+  if (
+    typeof signature !== "string" ||
+    !BASE64_ED25519_PATTERN.test(signature)
+  ) {
+    fail(
+      "invalid_schema",
+      "manifest.signature must be canonical base64 for a 64-byte Ed25519 signature",
+    );
+  }
+  return { ...payload, signature };
+}
+
+function validatePayload(
+  value: unknown,
+  releaseBaseUrl: string,
+): ReleaseManifestPayload {
+  const object = strictObject(
+    value,
+    ["schemaVersion", "keyId", "version", "files"],
+    "manifest payload",
+    // A signed envelope has one additional field. Its payload is still
+    // normalized from exactly the four authenticated fields below.
+    value !== null &&
+      typeof value === "object" &&
+      Object.prototype.hasOwnProperty.call(value, "signature")
+      ? ["signature"]
+      : [],
+  );
+
+  if (object.schemaVersion !== RELEASE_MANIFEST_SCHEMA_VERSION) {
+    fail(
+      "invalid_schema",
+      `manifest.schemaVersion must be ${RELEASE_MANIFEST_SCHEMA_VERSION}`,
+    );
+  }
+
+  const keyId = object.keyId;
+  if (typeof keyId !== "string" || !KEY_ID_PATTERN.test(keyId)) {
+    fail("invalid_schema", "manifest.keyId is invalid");
+  }
+
+  const version = object.version;
+  if (typeof version !== "string") {
+    fail("invalid_schema", "manifest.version must be a string");
+  }
+  assertVersion(version);
+
+  const files = strictObject(
+    object.files,
+    [...RELEASE_PLATFORMS],
+    "manifest.files",
+  );
+  const normalizedFiles = Object.create(null) as Record<
+    ReleasePlatform,
+    ReleaseArtifact
+  >;
+
+  for (const platform of RELEASE_PLATFORMS) {
+    const artifact = validateArtifactShape(
+      files[platform],
+      `manifest.files.${platform}`,
+    );
+    const expectedUrl = releaseArtifactUrl(version, platform, releaseBaseUrl);
+    if (artifact.url !== expectedUrl) {
+      fail(
+        "invalid_schema",
+        `manifest.files.${platform}.url must be ${expectedUrl}`,
+      );
+    }
+    normalizedFiles[platform] = artifact;
+  }
+
+  return {
+    schemaVersion: RELEASE_MANIFEST_SCHEMA_VERSION,
+    keyId,
+    version,
+    files: normalizedFiles,
+  };
+}
+
+function validateArtifactShape(value: unknown, path: string): ReleaseArtifact {
+  const object = strictObject(value, ["url", "size", "sha256"], path);
+  const { url, size, sha256 } = object;
+  if (typeof url !== "string") {
+    fail("invalid_schema", `${path}.url must be a string`);
+  }
+  if (
+    typeof size !== "number" ||
+    !Number.isSafeInteger(size) ||
+    size <= 0 ||
+    size > MAX_RELEASE_ARTIFACT_BYTES
+  ) {
+    fail(
+      "invalid_schema",
+      `${path}.size must be a positive safe integer no larger than ${MAX_RELEASE_ARTIFACT_BYTES}`,
+    );
+  }
+  if (typeof sha256 !== "string" || !SHA256_PATTERN.test(sha256)) {
+    fail("invalid_schema", `${path}.sha256 must be 64 lowercase hex digits`);
+  }
+  return { url, size, sha256 };
+}
+
+function assertVersion(version: string): void {
+  if (version.length > 64 || !VERSION_PATTERN.test(version)) {
+    fail(
+      "invalid_schema",
+      "release version must be a canonical stable semantic version",
+    );
+  }
+}
+
+function strictObject(
+  value: unknown,
+  expectedKeys: readonly string[],
+  path: string,
+  allowedAdditionalKeys: readonly string[] = [],
+): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    fail("invalid_schema", `${path} must be an object`);
+  }
+  const object = value as Record<string, unknown>;
+  const actualKeys = Object.keys(object);
+  const allowed = new Set([...expectedKeys, ...allowedAdditionalKeys]);
+  if (
+    actualKeys.length !== expectedKeys.length + allowedAdditionalKeys.length ||
+    actualKeys.some((key) => !allowed.has(key)) ||
+    expectedKeys.some((key) => !Object.prototype.hasOwnProperty.call(object, key)) ||
+    allowedAdditionalKeys.some(
+      (key) => !Object.prototype.hasOwnProperty.call(object, key),
+    )
+  ) {
+    fail(
+      "invalid_schema",
+      `${path} must contain exactly: ${[...expectedKeys, ...allowedAdditionalKeys].join(", ")}`,
+    );
+  }
+  return object;
+}
+
+function resolvePinnedKey(
+  keyId: string,
+  pinnedKeys: ReadonlyMap<string, PinnedReleaseManifestKey>,
+): KeyObject {
+  for (const pinnedKeyId of pinnedKeys.keys()) {
+    if (!KEY_ID_PATTERN.test(pinnedKeyId)) {
+      fail(
+        "invalid_trust_store",
+        "release manifest trust store contains an invalid key id",
+      );
+    }
+  }
+
+  const pinned = pinnedKeys.get(keyId);
+  if (!pinned) {
+    fail("unknown_key", `release manifest key is not trusted: ${keyId}`);
+  }
+
+  let key: KeyObject;
+  try {
+    if (pinned.publicKey instanceof KeyObject) {
+      key = pinned.publicKey;
+    } else {
+      const encoded = Buffer.isBuffer(pinned.publicKey)
+        ? pinned.publicKey.toString("utf8")
+        : pinned.publicKey;
+      if (!encoded.includes("-----BEGIN PUBLIC KEY-----")) {
+        fail("invalid_trust_store", `pinned release key is invalid: ${keyId}`);
+      }
+      key = createPublicKey(encoded);
+    }
+  } catch {
+    fail("invalid_trust_store", `pinned release key is invalid: ${keyId}`);
+  }
+  if (key.type !== "public" || key.asymmetricKeyType !== "ed25519") {
+    fail("invalid_trust_store", `pinned release key is not Ed25519: ${keyId}`);
+  }
+  return key;
+}
+
+function validateReleaseBaseUrl(value: string): string {
+  if (typeof value !== "string" || value.length > 2_048) {
+    fail("invalid_trust_store", "release download base URL is invalid");
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    fail("invalid_trust_store", "release download base URL is invalid");
+  }
+
+  const pathSegments = parsed.pathname.split("/").filter(Boolean);
+  if (
+    parsed.protocol !== "https:" ||
+    parsed.username !== "" ||
+    parsed.password !== "" ||
+    parsed.port !== "" ||
+    parsed.search !== "" ||
+    parsed.hash !== "" ||
+    parsed.hostname === "localhost" ||
+    parsed.hostname.endsWith(".localhost") ||
+    parsed.hostname.includes(":") ||
+    /^\d{1,3}(?:\.\d{1,3}){3}$/.test(parsed.hostname) ||
+    !parsed.hostname.includes(".") ||
+    parsed.pathname === "/" ||
+    parsed.pathname.endsWith("/") ||
+    parsed.pathname.includes("//") ||
+    pathSegments.some((segment) =>
+      segment === "." || segment === ".." || segment.includes("%")
+    ) ||
+    value !== `${parsed.origin}${parsed.pathname}`
+  ) {
+    fail(
+      "invalid_trust_store",
+      "release download base must be a canonical remote HTTPS URL",
+    );
+  }
+  return value;
+}
+
+function decodeArtifactDigest(value: string | Uint8Array): Buffer {
+  if (typeof value === "string") {
+    if (!SHA256_PATTERN.test(value)) {
+      fail("artifact_sha256_mismatch", "release artifact sha256 mismatch");
+    }
+    return Buffer.from(value, "hex");
+  }
+  if (value.byteLength !== 32) {
+    fail("artifact_sha256_mismatch", "release artifact sha256 mismatch");
+  }
+  return Buffer.from(value);
+}
+
+function decodeSignature(encoded: string): Buffer {
+  const decoded = Buffer.from(encoded, "base64");
+  if (
+    decoded.byteLength !== 64 ||
+    decoded.toString("base64") !== encoded
+  ) {
+    fail("invalid_schema", "manifest.signature is not canonical base64");
+  }
+  return decoded;
+}
+
+function freezeManifest(manifest: SignedReleaseManifest): SignedReleaseManifest {
+  const files = Object.create(null) as Record<
+    ReleasePlatform,
+    ReleaseArtifact
+  >;
+  for (const platform of RELEASE_PLATFORMS) {
+    files[platform] = Object.freeze({ ...manifest.files[platform] });
+  }
+  Object.freeze(files);
+  return Object.freeze({ ...manifest, files });
+}
+
+/**
+ * JSON.parse accepts duplicate object names and silently keeps the last one.
+ * A signed security document cannot permit that ambiguity, so use a small,
+ * bounded JSON parser that rejects duplicates before schema validation.
+ */
+function parseUntrustedJson(input: Uint8Array): unknown {
+  if (input.byteLength > MAX_RELEASE_MANIFEST_BYTES) {
+    fail(
+      "manifest_too_large",
+      `release manifest exceeds ${MAX_RELEASE_MANIFEST_BYTES} bytes`,
+    );
+  }
+
+  let source: string;
+  try {
+    source = new TextDecoder("utf-8", { fatal: true }).decode(input);
+  } catch {
+    fail("invalid_encoding", "release manifest is not valid UTF-8");
+  }
+
+  try {
+    return new DuplicateSafeJsonParser(source).parse();
+  } catch (error) {
+    if (error instanceof ReleaseManifestError) throw error;
+    fail("invalid_json", "release manifest is not valid JSON");
+  }
+}
+
+class DuplicateSafeJsonParser {
+  private index = 0;
+
+  constructor(private readonly source: string) {}
+
+  parse(): unknown {
+    this.skipWhitespace();
+    const value = this.parseValue(0);
+    this.skipWhitespace();
+    if (this.index !== this.source.length) this.invalid();
+    return value;
+  }
+
+  private parseValue(depth: number): unknown {
+    if (depth > MAX_JSON_DEPTH) this.invalid();
+    const char = this.source[this.index];
+    if (char === "{") return this.parseObject(depth + 1);
+    if (char === "[") return this.parseArray(depth + 1);
+    if (char === '"') return this.parseString();
+    if (char === "t") return this.parseLiteral("true", true);
+    if (char === "f") return this.parseLiteral("false", false);
+    if (char === "n") return this.parseLiteral("null", null);
+    if (char === "-" || (char !== undefined && /[0-9]/.test(char))) {
+      return this.parseNumber();
+    }
+    return this.invalid();
+  }
+
+  private parseObject(depth: number): Record<string, unknown> {
+    const result = Object.create(null) as Record<string, unknown>;
+    const keys = new Set<string>();
+    this.index += 1;
+    this.skipWhitespace();
+    if (this.consume("}")) return result;
+
+    while (true) {
+      if (this.source[this.index] !== '"') this.invalid();
+      const key = this.parseString();
+      if (keys.has(key)) {
+        fail("invalid_json", `release manifest contains duplicate key: ${key}`);
+      }
+      keys.add(key);
+      this.skipWhitespace();
+      if (!this.consume(":")) this.invalid();
+      this.skipWhitespace();
+      result[key] = this.parseValue(depth);
+      this.skipWhitespace();
+      if (this.consume("}")) return result;
+      if (!this.consume(",")) this.invalid();
+      this.skipWhitespace();
+    }
+  }
+
+  private parseArray(depth: number): unknown[] {
+    const result: unknown[] = [];
+    this.index += 1;
+    this.skipWhitespace();
+    if (this.consume("]")) return result;
+
+    while (true) {
+      result.push(this.parseValue(depth));
+      this.skipWhitespace();
+      if (this.consume("]")) return result;
+      if (!this.consume(",")) this.invalid();
+      this.skipWhitespace();
+    }
+  }
+
+  private parseString(): string {
+    const start = this.index;
+    this.index += 1;
+    while (this.index < this.source.length) {
+      const char = this.source[this.index];
+      if (char === '"') {
+        this.index += 1;
+        try {
+          return JSON.parse(this.source.slice(start, this.index)) as string;
+        } catch {
+          return this.invalid();
+        }
+      }
+      if (char === "\\") {
+        this.index += 1;
+        const escape = this.source[this.index];
+        if (escape === "u") {
+          const hex = this.source.slice(this.index + 1, this.index + 5);
+          if (!/^[a-fA-F0-9]{4}$/.test(hex)) return this.invalid();
+          this.index += 5;
+          continue;
+        }
+        if (escape === undefined || !'"\\/bfnrt'.includes(escape)) {
+          return this.invalid();
+        }
+        this.index += 1;
+        continue;
+      }
+      if (char === undefined || char.charCodeAt(0) < 0x20) {
+        return this.invalid();
+      }
+      this.index += 1;
+    }
+    return this.invalid();
+  }
+
+  private parseNumber(): number {
+    const rest = this.source.slice(this.index);
+    const match = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(rest);
+    if (!match) return this.invalid();
+    this.index += match[0].length;
+    const value = Number(match[0]);
+    if (!Number.isFinite(value)) return this.invalid();
+    return value;
+  }
+
+  private parseLiteral<T>(token: string, value: T): T {
+    if (this.source.slice(this.index, this.index + token.length) !== token) {
+      return this.invalid();
+    }
+    this.index += token.length;
+    return value;
+  }
+
+  private consume(char: string): boolean {
+    if (this.source[this.index] !== char) return false;
+    this.index += 1;
+    return true;
+  }
+
+  private skipWhitespace(): void {
+    while (
+      this.source[this.index] === " " ||
+      this.source[this.index] === "\t" ||
+      this.source[this.index] === "\n" ||
+      this.source[this.index] === "\r"
+    ) {
+      this.index += 1;
+    }
+  }
+
+  private invalid(): never {
+    fail("invalid_json", "release manifest is not valid JSON");
+  }
+}