@citeark/agent 0.3.20

package/src/autodl/tools.mjs

@@ -0,0 +1,129 @@
+import { AutoDlProClient } from "./client.mjs";
+import { CiteArkError } from "../util.mjs";
+
+export const AUTODL_TOOL_DEFINITIONS = Object.freeze([
+  tool("autodl_instances_list", "列出 CiteArk 后端可管理的 AutoDL Pro 实例", {
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+  }),
+  tool("autodl_instance_status", "查询一个 AutoDL Pro 实例的状态", instanceSchema()),
+  tool("autodl_instance_start", "启动一个已停止的 AutoDL Pro 实例", instanceSchema()),
+  tool("autodl_instance_stop", "关闭一个 AutoDL Pro 实例并保留系统盘", instanceSchema()),
+  tool("autodl_instance_release", "永久释放一个已关闭的 AutoDL Pro 实例", {
+    type: "object",
+    properties: {
+      instanceUuid: instanceUuidSchema(),
+      confirmInstanceUuid: instanceUuidSchema(),
+    },
+    required: ["instanceUuid", "confirmInstanceUuid"],
+    additionalProperties: false,
+  }),
+]);
+
+export function createAutoDlToolExecutor({
+  token,
+  apiBaseUrl,
+  client = new AutoDlProClient({ token, baseUrl: apiBaseUrl }),
+  audit = async () => {},
+} = {}) {
+  return async function executeAutoDlTool(name, input = {}) {
+    const instanceUuid = input?.instanceUuid;
+    if (name === "autodl_instances_list") {
+      const response = await client.listInstances();
+      return {
+        instances: (response?.list ?? []).map(publicInstance),
+      };
+    }
+    assertInstanceUuid(instanceUuid);
+    if (name === "autodl_instance_status") {
+      return { instanceUuid, status: await client.getStatus(instanceUuid) };
+    }
+    if (name === "autodl_instance_start") {
+      const previousStatus = normalizedStatus(await client.getStatus(instanceUuid));
+      if (previousStatus !== "running") {
+        await client.powerOn(instanceUuid, { startCommand: "sleep infinity" });
+      }
+      await auditEvent(audit, name, instanceUuid, previousStatus, "power-on-requested");
+      return { instanceUuid, previousStatus, action: "power-on-requested" };
+    }
+    if (name === "autodl_instance_stop") {
+      const previousStatus = normalizedStatus(await client.getStatus(instanceUuid));
+      if (!stopped(previousStatus)) await client.powerOff(instanceUuid);
+      await auditEvent(audit, name, instanceUuid, previousStatus, "power-off-requested");
+      return { instanceUuid, previousStatus, action: "power-off-requested" };
+    }
+    if (name === "autodl_instance_release") {
+      if (input.confirmInstanceUuid !== instanceUuid) {
+        throw new CiteArkError("释放 AutoDL 实例需要完整 UUID 二次确认");
+      }
+      const previousStatus = normalizedStatus(await client.getStatus(instanceUuid));
+      if (!stopped(previousStatus)) {
+        await client.powerOff(instanceUuid);
+        await client.waitForStatus(instanceUuid, ["stopped", "shutdown", "shutoff"]);
+      }
+      await client.release(instanceUuid);
+      await auditEvent(audit, name, instanceUuid, previousStatus, "released");
+      return { instanceUuid, previousStatus, action: "released" };
+    }
+    throw new CiteArkError(`未知 AutoDL 工具：${name}`);
+  };
+}
+
+function tool(name, description, parameters) {
+  return { type: "function", name, description, parameters, strict: true };
+}
+
+function instanceSchema() {
+  return {
+    type: "object",
+    properties: { instanceUuid: instanceUuidSchema() },
+    required: ["instanceUuid"],
+    additionalProperties: false,
+  };
+}
+
+function instanceUuidSchema() {
+  return {
+    type: "string",
+    pattern: "^pro-[a-zA-Z0-9]+$",
+    description: "AutoDL Pro 实例 UUID",
+  };
+}
+
+function assertInstanceUuid(value) {
+  if (typeof value !== "string" || !/^pro-[a-zA-Z0-9]+$/.test(value)) {
+    throw new CiteArkError("AutoDL 实例 UUID 无效");
+  }
+}
+
+function normalizedStatus(value) {
+  return String(value ?? "unknown").trim().toLowerCase();
+}
+
+function stopped(status) {
+  return new Set(["stopped", "shutdown", "shutoff"]).has(status);
+}
+
+function publicInstance(instance) {
+  return {
+    instanceUuid: instance?.uuid ?? null,
+    name: instance?.name ?? null,
+    status: instance?.status ?? null,
+    region: instance?.region_name ?? instance?.region_sign ?? null,
+    gpuSpecUuid: instance?.gpu_spec_uuid ?? null,
+    gpuCount: instance?.req_gpu_amount ?? null,
+  };
+}
+
+async function auditEvent(audit, toolName, instanceUuid, previousStatus, action) {
+  await audit({
+    schemaVersion: "0.1",
+    type: "autodl.lifecycle-tool",
+    toolName,
+    instanceUuid,
+    previousStatus,
+    action,
+    recordedAt: new Date().toISOString(),
+  });
+}

package/src/cap/redaction.mjs

@@ -0,0 +1,38 @@
+import { lstat, readFile } from "node:fs/promises";
+
+import { CiteArkError, isRecord } from "../util.mjs";
+
+const SENSITIVE_KEY = /(api[_-]?key|auth[_-]?token|access[_-]?token|secret|password|credential)/i;
+const SECRET_PATTERNS = [
+  /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+  /\b(?:api[_-]?key|auth[_-]?token|access[_-]?token|password)\s*[:=]\s*["']?[^\s"']{12,}/gi,
+  /\bAuthorization\s*:\s*Bearer\s+[^\s]+/gi,
+];
+
+export function redactSensitive(value, key = "") {
+  if (SENSITIVE_KEY.test(key)) return "[REDACTED]";
+  if (typeof value === "string") return redactString(value);
+  if (Array.isArray(value)) return value.map((item) => redactSensitive(item));
+  if (isRecord(value)) {
+    return Object.fromEntries(Object.entries(value).map(([childKey, child]) => [childKey, redactSensitive(child, childKey)]));
+  }
+  return value;
+}
+
+export function redactString(input) {
+  return SECRET_PATTERNS.reduce((value, pattern) => value.replace(pattern, "[REDACTED]"), input);
+}
+
+export async function assertEvidenceHasNoLikelySecret(target, label) {
+  const stat = await lstat(target);
+  if (!stat.isFile() || stat.size > 10 * 1024 * 1024) return;
+  const buffer = await readFile(target);
+  if (buffer.includes(0)) return;
+  const text = buffer.toString("utf8");
+  if (SECRET_PATTERNS.some((pattern) => {
+    pattern.lastIndex = 0;
+    return pattern.test(text);
+  })) {
+    throw new CiteArkError(`证据疑似包含凭证，CAP 已拒绝发布：${label}`);
+  }
+}

package/src/cap/v2/archive.mjs

@@ -0,0 +1,152 @@
+import { link, lstat, mkdtemp, readdir, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { captureProcess } from "../../process.mjs";
+import { CiteArkError, pathExists, sha256File, sha256Value } from "../../util.mjs";
+import {
+  CAP_ARCHIVE_MEDIA_TYPE,
+  CAP_MANIFEST,
+  safeCapPath,
+} from "./core.mjs";
+import { verifyCapDirectory } from "./verify.mjs";
+
+export class CapArchiveConflictError extends CiteArkError {
+  constructor(message) {
+    super(message);
+    this.failureCategory = "archive";
+    this.failureCode = "target.archive_conflict";
+    this.retryable = false;
+    this.retryStrategy = "none";
+  }
+}
+
+export async function packCap({ directory, outputPath, reuseExisting = false }) {
+  const source = path.resolve(directory);
+  const destination = path.resolve(outputPath);
+  if (path.extname(destination).toLowerCase() !== ".cap") {
+    throw new CiteArkError("CAP 2.0 bundles must use the .cap suffix");
+  }
+  if (destination.startsWith(`${source}${path.sep}`)) {
+    throw new CiteArkError("CAP bundle cannot be written inside its source directory");
+  }
+  const verification = await verifyCapDirectory(source);
+  if (!verification.valid) {
+    throw Object.assign(new CiteArkError(`CAP 2.0 verification failed before packing:\n- ${verification.issues.join("\n- ")}`), {
+      failureCategory: "archive", failureCode: "target.archive_source_invalid", retryable: false, retryStrategy: "none",
+    });
+  }
+  const contentDigest = await capDirectoryContentDigest(source);
+  const existing = async () => {
+    if (!reuseExisting) throw new CapArchiveConflictError(`CAP output already exists: ${destination}`);
+    const stat = await lstat(destination);
+    const retained = stat.isFile() ? await verifyCapArchive(destination) : null;
+    if (!retained?.valid || retained.artifactDigest !== verification.artifactDigest || retained.archive.contentDigest !== contentDigest) {
+      throw new CapArchiveConflictError(`Existing CAP does not match the verified artifact: ${destination}`);
+    }
+    return { ...retained.archive, artifactDigest: retained.artifactDigest };
+  };
+  if (await pathExists(destination)) return existing();
+  // Publish only a complete file, with exclusive creation. A process failure
+  // before the stage checkpoint may leave a valid archive, which a resume can
+  // verify and reuse without rewriting its signed bytes.
+  const temporary = await mkdtemp(path.join(path.dirname(destination), ".cap-building-"));
+  try {
+    const candidate = path.join(temporary, "artifact.cap");
+    const result = await captureProcess(
+      "tar", ["-czf", candidate, "--exclude=.DS_Store", "--exclude=._*", "."],
+      { cwd: source, env: { ...process.env, COPYFILE_DISABLE: "1" } },
+    );
+    if (result.code !== 0) throw new CiteArkError(`Cannot create CAP bundle:\n${result.stderr.trim()}`);
+    try { await link(candidate, destination); }
+    catch (error) { if (error.code === "EEXIST") return await existing(); throw error; }
+    const stat = await lstat(destination);
+    return {
+      protocolVersion: verification.protocolVersion, format: "tar+gzip", mediaType: CAP_ARCHIVE_MEDIA_TYPE,
+      path: destination, size: stat.size, contentDigest, sha256: await sha256File(destination), artifactDigest: verification.artifactDigest,
+    };
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}
+
+export async function verifyCapArchive(archivePath, options = {}) {
+  const source = path.resolve(archivePath);
+  const issues = [];
+  if (path.extname(source).toLowerCase() !== ".cap") issues.push("CAP 2.0 bundle suffix must be .cap");
+  const temporary = await mkdtemp(path.join(os.tmpdir(), "citeark-cap-v2-"));
+  try {
+    const listing = await captureProcess("tar", ["-tzf", source]);
+    if (listing.code !== 0) return { valid: false, issues: ["File is not a valid tar+gzip CAP bundle"] };
+    const verbose = await captureProcess("tar", ["-tvzf", source]);
+    if (verbose.code !== 0 || verbose.stdout.split(/\r?\n/).filter(Boolean).some((line) => !new Set(["-", "d"]).has(line[0]))) {
+      return { valid: false, issues: ["CAP bundle contains links or non-regular entry types"] };
+    }
+    const paths = new Set();
+    for (const entry of listing.stdout.split(/\r?\n/).filter(Boolean)) {
+      const normalized = normalizeArchiveEntry(entry);
+      if (!normalized) continue;
+      if (!safeCapPath(normalized) || paths.has(normalized)) issues.push(`Unsafe or duplicate archive path: ${entry}`);
+      paths.add(normalized);
+    }
+    if (!paths.has(CAP_MANIFEST)) issues.push(`CAP 2.0 bundle is missing ${CAP_MANIFEST}`);
+    if (issues.length) return { valid: false, issues };
+    const extraction = await captureProcess("tar", ["-xzf", source, "-C", temporary]);
+    if (extraction.code !== 0) return { valid: false, issues: ["Cannot safely extract CAP bundle"] };
+    if (!(await onlyRegularFilesAndDirectories(temporary))) {
+      return { valid: false, issues: ["CAP bundle contains links or non-regular entry types"] };
+    }
+    const verification = await verifyCapDirectory(temporary, options);
+    const stat = await lstat(source);
+    return {
+      ...verification,
+      valid: verification.valid && issues.length === 0,
+      issues: [...issues, ...verification.issues],
+      archive: {
+        protocolVersion: verification.protocolVersion,
+        format: "tar+gzip",
+        mediaType: CAP_ARCHIVE_MEDIA_TYPE,
+        path: source,
+        size: stat.size,
+        sha256: await sha256File(source),
+        contentDigest: await capDirectoryContentDigest(temporary),
+      },
+    };
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}
+
+function normalizeArchiveEntry(value) {
+  return value.replace(/^\.\//, "").replace(/\/$/, "");
+}
+
+async function onlyRegularFilesAndDirectories(root) {
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const target = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      if (!(await onlyRegularFilesAndDirectories(target))) return false;
+    } else if (!entry.isFile()) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Binds all archived bytes, including signatures and derived attachments;
+ * the manifest Artifact Digest alone does not bind a processing-job signature.
+ */
+export async function capDirectoryContentDigest(directory) {
+  const entries = [];
+  async function scan(current, prefix = "") {
+    for (const entry of await readdir(current, { withFileTypes: true })) {
+      if (entry.name === ".DS_Store" || entry.name.startsWith("._")) continue;
+      const relative = prefix + entry.name;
+      const filename = path.join(current, entry.name);
+      if (entry.isDirectory()) await scan(filename, `${relative}/`);
+      else if (entry.isFile()) entries.push([relative, await sha256File(filename)]);
+      else throw new CapArchiveConflictError(`CAP contains a non-regular entry: ${relative}`);
+    }
+  }
+  await scan(directory);
+  entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return `sha256:${sha256Value(entries)}`;
+}

package/src/cap/v2/attestation.mjs

@@ -0,0 +1,204 @@
+import {
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign,
+  verify,
+} from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  assertSha256Digest,
+  canonicalJsonBytes,
+  parseCanonicalJson,
+  sha256Bytes,
+} from "./canonical-json.mjs";
+
+export const CAP_ATTESTATION_MEDIA_TYPE = "application/vnd.citeark.cap.attestation.v2+json";
+export const CAP_PREDICATE_TYPE = "https://citeark.com/cap/attestations/artifact/v2";
+export const IN_TOTO_STATEMENT_V1 = "https://in-toto.io/Statement/v1";
+export const IN_TOTO_PAYLOAD_TYPE = "application/vnd.in-toto+json";
+
+export async function capPublicKeyDigestFromPrivateKeyFile(signingKeyPath) {
+  const privateKey = createPrivateKey(await readFile(signingKeyPath, "utf8"));
+  return capPublicKeyIdentity(privateKey).publicKeyDigest;
+}
+
+export async function signCapArtifact({
+  artifactDigest,
+  actor,
+  role = "artifactAssembler",
+  createdAt = new Date().toISOString(),
+  signingKeyPath,
+  processingBinding,
+  trust = signingKeyPath ? "configured-key" : "local-ephemeral",
+}) {
+  assertSha256Digest(artifactDigest, "artifactDigest");
+  const privateKey = signingKeyPath
+    ? createPrivateKey(await readFile(signingKeyPath, "utf8"))
+    : generateKeyPairSync("ed25519").privateKey;
+  const { publicKeyPem, publicKeyDigest } = capPublicKeyIdentity(privateKey);
+  const statement = createCapStatement({
+    artifactDigest,
+    actor,
+    role,
+    createdAt,
+    processingBinding,
+  });
+  const payload = canonicalJsonBytes(statement);
+  const signature = sign(null, dssePreAuthenticationEncoding(IN_TOTO_PAYLOAD_TYPE, payload), privateKey);
+  return {
+    mediaType: CAP_ATTESTATION_MEDIA_TYPE,
+    envelope: {
+      payloadType: IN_TOTO_PAYLOAD_TYPE,
+      payload: payload.toString("base64"),
+      signatures: [{
+        keyid: publicKeyDigest,
+        sig: signature.toString("base64"),
+      }],
+    },
+    verificationMaterial: {
+      kind: "public-key",
+      keyId: publicKeyDigest,
+      publicKeyPem,
+      trust,
+    },
+  };
+}
+
+function capPublicKeyIdentity(privateKey) {
+  const publicKey = createPublicKey(privateKey);
+  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" }).toString();
+  return {
+    publicKeyPem,
+    publicKeyDigest: sha256Bytes(Buffer.from(publicKeyPem, "utf8")),
+  };
+}
+
+export function createCapStatement({
+  artifactDigest,
+  actor,
+  role,
+  createdAt,
+  processingBinding,
+}) {
+  const digest = assertSha256Digest(artifactDigest, "artifactDigest");
+  return {
+    _type: IN_TOTO_STATEMENT_V1,
+    subject: [{
+      name: "CiteArk CAP Artifact",
+      digest: { sha256: digest.slice(7) },
+    }],
+    predicateType: CAP_PREDICATE_TYPE,
+    predicate: {
+      artifactDigest: digest,
+      attestationRole: role,
+      actor,
+      createdAt,
+      ...(processingBinding ? { processingBinding } : {}),
+    },
+  };
+}
+
+export async function attachCapAttestation({ directory, attestation }) {
+  const bytes = canonicalJsonBytes(attestation);
+  const digest = sha256Bytes(bytes);
+  const targetDirectory = path.join(directory, "attestations");
+  const target = path.join(targetDirectory, `${digest.slice(7)}.dsse.json`);
+  await mkdir(targetDirectory, { recursive: true });
+  await writeFile(target, bytes);
+  return { path: `attestations/${digest.slice(7)}.dsse.json`, digest, size: bytes.byteLength };
+}
+
+export function verifyCapAttestation(bundle, {
+  artifactDigest,
+  trustedKeyDigests = [],
+} = {}) {
+  const issues = [];
+  const warnings = [];
+  if (!bundle || bundle.mediaType !== CAP_ATTESTATION_MEDIA_TYPE) {
+    return { recognized: false, signatureValid: false, subjectValid: false, trusted: false, issues, warnings };
+  }
+  const envelope = bundle.envelope;
+  const material = bundle.verificationMaterial;
+  if (envelope?.payloadType !== IN_TOTO_PAYLOAD_TYPE || typeof envelope.payload !== "string") {
+    issues.push("DSSE envelope has an invalid payload type or payload");
+    return result();
+  }
+  const signatures = Array.isArray(envelope.signatures) ? envelope.signatures : [];
+  if (signatures.length === 0) issues.push("DSSE envelope contains no signatures");
+  if (material?.kind !== "public-key" || typeof material.publicKeyPem !== "string") {
+    issues.push("Reference verifier requires embedded public-key verification material");
+    return result();
+  }
+  const publicKeyDigest = sha256Bytes(Buffer.from(material.publicKeyPem, "utf8"));
+  if (material.keyId !== publicKeyDigest) issues.push("Attestation public key id does not match its bytes");
+  let statement;
+  let payload;
+  try {
+    payload = Buffer.from(envelope.payload, "base64");
+    statement = parseCanonicalJson(payload, "in-toto Statement");
+  } catch (error) {
+    issues.push(error instanceof Error ? error.message : String(error));
+    return result();
+  }
+  const matchingSignatures = signatures.filter((item) => item?.keyid === publicKeyDigest && typeof item.sig === "string");
+  let signatureValid = false;
+  try {
+    const publicKey = createPublicKey(material.publicKeyPem);
+    signatureValid = matchingSignatures.some((item) => verify(
+      null,
+      dssePreAuthenticationEncoding(envelope.payloadType, payload),
+      publicKey,
+      Buffer.from(item.sig, "base64"),
+    ));
+  } catch (error) {
+    issues.push(`Attestation public key or signature is invalid: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!signatureValid) issues.push("No DSSE signature is valid for the embedded public key");
+
+  const expected = artifactDigest ? assertSha256Digest(artifactDigest, "artifactDigest") : null;
+  const subjectDigest = statement?.subject?.find((item) => item?.name === "CiteArk CAP Artifact")?.digest?.sha256;
+  const predicateDigest = statement?.predicate?.artifactDigest;
+  const subjectValid = statement?._type === IN_TOTO_STATEMENT_V1
+    && statement?.predicateType === CAP_PREDICATE_TYPE
+    && (!expected || subjectDigest === expected.slice(7))
+    && (!expected || predicateDigest === expected);
+  if (!subjectValid) issues.push("in-toto Statement does not bind the expected CAP Artifact digest");
+  const trusted = trustedKeyDigests.includes(publicKeyDigest);
+  if (!trusted) warnings.push(`Signature key is not trusted by the active policy: ${publicKeyDigest}`);
+  return {
+    recognized: true,
+    signatureValid,
+    subjectValid,
+    trusted,
+    publicKeyDigest,
+    statement,
+    trustLabel: material.trust ?? null,
+    issues,
+    warnings,
+  };
+
+  function result() {
+    return {
+      recognized: true,
+      signatureValid: false,
+      subjectValid: false,
+      trusted: false,
+      issues,
+      warnings,
+    };
+  }
+}
+
+export function dssePreAuthenticationEncoding(payloadType, payload) {
+  const typeBytes = Buffer.from(payloadType, "utf8");
+  const body = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+  return Buffer.concat([
+    Buffer.from(`DSSEv1 ${typeBytes.byteLength} `, "utf8"),
+    typeBytes,
+    Buffer.from(` ${body.byteLength} `, "utf8"),
+    body,
+  ]);
+}

package/src/cap/v2/canonical-json.mjs

@@ -0,0 +1,114 @@
+import { createHash } from "node:crypto";
+
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+export function canonicalJson(value) {
+  assertIJson(value);
+  return JSON.stringify(sortValue(value));
+}
+
+export function canonicalJsonBytes(value) {
+  return Buffer.from(canonicalJson(value), "utf8");
+}
+
+export function parseCanonicalJson(bytes, label = "JSON document") {
+  const source = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(source);
+  } catch (error) {
+    throw new Error(`${label} is not valid UTF-8`, { cause: error });
+  }
+
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${label} is not valid JSON`, { cause: error });
+  }
+  const canonical = canonicalJson(value);
+  if (text !== canonical) {
+    throw new Error(`${label} is not encoded as RFC 8785 canonical JSON`);
+  }
+  return value;
+}
+
+export function sha256Bytes(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+export function sha256CanonicalJson(value) {
+  return sha256Bytes(canonicalJsonBytes(value));
+}
+
+export function assertSha256Digest(value, label = "digest") {
+  if (!DIGEST_PATTERN.test(value)) {
+    throw new Error(`${label} must be a lowercase sha256 digest`);
+  }
+  return value;
+}
+
+export function assertIJson(value, pointer = "$", ancestors = new Set()) {
+  if (value === null || typeof value === "boolean") return;
+  if (typeof value === "string") {
+    assertUnicodeScalarString(value, pointer);
+    return;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`${pointer} must be a finite JSON number`);
+    return;
+  }
+  if (typeof value !== "object") {
+    throw new Error(`${pointer} contains a value that is not representable in JSON`);
+  }
+  if (ancestors.has(value)) throw new Error(`${pointer} contains a cyclic reference`);
+  ancestors.add(value);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertIJson(item, `${pointer}/${index}`, ancestors));
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Error(`${pointer} must be a plain JSON object`);
+    }
+    for (const [key, item] of Object.entries(value)) {
+      assertUnicodeScalarString(key, `${pointer} object key`);
+      assertIJson(item, `${pointer}/${escapePointer(key)}`, ancestors);
+    }
+  }
+  ancestors.delete(value);
+}
+
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort(compareUtf16)
+      .map((key) => [key, sortValue(value[key])]),
+  );
+}
+
+function compareUtf16(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function assertUnicodeScalarString(value, pointer) {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) {
+        throw new Error(`${pointer} contains an unpaired high surrogate`);
+      }
+      index += 1;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      throw new Error(`${pointer} contains an unpaired low surrogate`);
+    }
+  }
+}
+
+function escapePointer(value) {
+  return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}