@zxyycom/vibe-check 0.0.1

package/src/package-checks/json-schema-validation/options-validation.ts

@@ -0,0 +1,256 @@
+import {
+  hasExactPlainRecordKeys,
+  snapshotClosedArray,
+  snapshotClosedRecord
+} from "../../data-boundary/closed-values.ts";
+import { validProjectFileSelection } from "../project-files/configuration.ts";
+import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
+
+function exactRecord(
+  value: unknown,
+  keys: readonly string[]
+): Readonly<Record<string, unknown>> | undefined {
+  const record = snapshotClosedRecord(value);
+  return record !== undefined && hasExactPlainRecordKeys(record, keys) ? record : undefined;
+}
+
+function positiveSafeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+export function validJsonSchemaValidationOptions(
+  candidateOptions: unknown
+): candidateOptions is ResolvedJsonSchemaValidationOptions {
+  const options = exactRecord(candidateOptions, [
+    "files",
+    "maximumBytes",
+    "schemaIdentity",
+    "referenceResolution",
+    "schemas",
+    "bindings"
+  ]);
+  if (
+    options === undefined ||
+    !validProjectFileSelection(options.files) ||
+    !positiveSafeInteger(options.maximumBytes) ||
+    !validJsonSchemaIdentity(options.schemaIdentity) ||
+    !validJsonSchemaReferenceResolution(options.referenceResolution)
+  ) {
+    return false;
+  }
+
+  const schemas = snapshotClosedArray(options.schemas);
+  const bindings = snapshotClosedArray(options.bindings);
+  const declaredSchemaIds = schemas === undefined ? undefined : validatedSchemaRegistryIds(schemas);
+  return (
+    bindings !== undefined &&
+    declaredSchemaIds !== undefined &&
+    validJsonSchemaBindings(bindings, declaredSchemaIds)
+  );
+}
+
+function validJsonSchemaIdentity(candidateIdentity: unknown): boolean {
+  const identity = exactRecord(candidateIdentity, ["mode"]);
+  return (
+    identity !== undefined &&
+    (identity.mode === "require-match" ||
+      identity.mode === "configuration-authoritative" ||
+      identity.mode === "document-authoritative")
+  );
+}
+
+function validJsonSchemaReferenceResolution(candidateResolution: unknown): boolean {
+  const referenceResolution = snapshotClosedRecord(candidateResolution);
+  if (referenceResolution === undefined || typeof referenceResolution.mode !== "string") {
+    return false;
+  }
+  if (referenceResolution.mode === "offline") {
+    return exactRecord(referenceResolution, ["mode"]) !== undefined;
+  }
+  if (referenceResolution.mode !== "allowlisted") return false;
+
+  const allowlisted = exactRecord(referenceResolution, ["mode", "sources"]);
+  const sources = allowlisted === undefined ? undefined : snapshotClosedArray(allowlisted.sources);
+  return sources !== undefined && sources.length > 0 && validJsonSchemaReferenceSources(sources);
+}
+
+function validJsonSchemaReferenceSources(sources: readonly unknown[]): boolean {
+  const sourceIds = new Set<string>();
+  const sourceLocations = new Set<string>();
+  let bundledCatalogCount = 0;
+  for (const sourceCandidate of sources) {
+    const source = validatedReferenceSource(sourceCandidate);
+    if (source === undefined) return false;
+    if (source.kind === "bundled") {
+      bundledCatalogCount += 1;
+      if (bundledCatalogCount > 1) return false;
+      continue;
+    }
+    if (sourceIds.has(source.id) || sourceLocations.has(source.location)) return false;
+    sourceIds.add(source.id);
+    sourceLocations.add(source.location);
+  }
+  return true;
+}
+
+function validatedReferenceSource(sourceCandidate: unknown) {
+  const source = snapshotClosedRecord(sourceCandidate);
+  if (source === undefined || typeof source.kind !== "string") return undefined;
+  if (source.kind === "bundled")
+    return validBundledSource(source) ? { kind: "bundled" as const } : undefined;
+  if (source.kind !== "https") return undefined;
+  const httpsSource = validatedHttpsSource(source);
+  return httpsSource === undefined ? undefined : { kind: "https" as const, ...httpsSource };
+}
+
+function validBundledSource(source: Readonly<Record<string, unknown>>): boolean {
+  return exactRecord(source, ["kind", "catalog"])?.catalog === "json-schema-2020-12";
+}
+
+function validatedHttpsSource(source: Readonly<Record<string, unknown>>) {
+  const httpsSource = exactRecord(source, ["kind", "id", "origin", "pathPrefix"]);
+  if (
+    httpsSource === undefined ||
+    !safeAbsoluteIdentifier(httpsSource.id) ||
+    !safeHttpsOrigin(httpsSource.origin) ||
+    !safePathPrefix(httpsSource.pathPrefix)
+  )
+    return undefined;
+  return { id: httpsSource.id, location: `${httpsSource.origin}\n${httpsSource.pathPrefix}` };
+}
+
+/** Returns declared IDs only after the whole schema registry satisfies its closed authoring invariant. */
+function validatedSchemaRegistryIds(schemas: readonly unknown[]): ReadonlySet<string> | undefined {
+  const declaredSchemaIds = new Set<string>();
+  const schemaPaths = new Set<string>();
+  for (const schemaCandidate of schemas) {
+    const schemaRecord = exactRecord(schemaCandidate, ["id", "path"]);
+    if (
+      schemaRecord === undefined ||
+      !safeAbsoluteIdentifier(schemaRecord.id) ||
+      !normalizedProjectJsonPath(schemaRecord.path) ||
+      declaredSchemaIds.has(schemaRecord.id) ||
+      schemaPaths.has(schemaRecord.path)
+    ) {
+      return undefined;
+    }
+    declaredSchemaIds.add(schemaRecord.id);
+    schemaPaths.add(schemaRecord.path);
+  }
+  return declaredSchemaIds;
+}
+
+function validJsonSchemaBindings(
+  bindings: readonly unknown[],
+  declaredSchemaIds: ReadonlySet<string>
+): boolean {
+  const bindingIds = new Set<string>();
+  const bindingTargets = new Set<string>();
+  for (const bindingCandidate of bindings) {
+    const bindingRecord = exactRecord(bindingCandidate, ["id", "instancePath", "schemaId"]);
+    if (
+      bindingRecord === undefined ||
+      !safeBindingId(bindingRecord.id) ||
+      !normalizedProjectJsonPath(bindingRecord.instancePath) ||
+      typeof bindingRecord.schemaId !== "string" ||
+      !declaredSchemaIds.has(bindingRecord.schemaId) ||
+      bindingIds.has(bindingRecord.id)
+    ) {
+      return false;
+    }
+    const bindingTarget = `${bindingRecord.instancePath}\n${bindingRecord.schemaId}`;
+    if (bindingTargets.has(bindingTarget)) return false;
+    bindingIds.add(bindingRecord.id);
+    bindingTargets.add(bindingTarget);
+  }
+  return true;
+}
+
+function safeAbsoluteIdentifier(identifier: unknown): identifier is string {
+  if (!boundedNonEmptyString(identifier, 256)) return false;
+  try {
+    const url = new URL(identifier);
+    return safeIdentifierUrl(url, identifier);
+  } catch {
+    return false;
+  }
+}
+
+function safeIdentifierUrl(url: URL, identifier: string): boolean {
+  return (
+    (url.protocol === "https:" || url.protocol === "urn:") &&
+    url.username.length === 0 &&
+    url.password.length === 0 &&
+    url.search.length === 0 &&
+    url.hash.length === 0 &&
+    url.href === identifier
+  );
+}
+
+function safeHttpsOrigin(origin: unknown): origin is string {
+  if (!boundedNonEmptyString(origin, 200)) return false;
+  try {
+    const url = new URL(origin);
+    return safeHttpsOriginUrl(url, origin);
+  } catch {
+    return false;
+  }
+}
+
+function safeHttpsOriginUrl(url: URL, origin: string): boolean {
+  return (
+    url.protocol === "https:" &&
+    url.hostname.length > 0 &&
+    url.username.length === 0 &&
+    url.password.length === 0 &&
+    url.search.length === 0 &&
+    url.hash.length === 0 &&
+    url.pathname === "/" &&
+    url.origin === origin
+  );
+}
+
+function safePathPrefix(pathPrefix: unknown): pathPrefix is string {
+  if (!validPathPrefixSyntax(pathPrefix)) return false;
+  const segments = pathPrefix.split("/");
+  return segments.every(
+    (segment, index) => index === 0 || segment === "" || (segment !== "." && segment !== "..")
+  );
+}
+
+function validPathPrefixSyntax(pathPrefix: unknown): pathPrefix is string {
+  return (
+    boundedNonEmptyString(pathPrefix, 256) &&
+    pathPrefix.startsWith("/") &&
+    (pathPrefix === "/" || pathPrefix.endsWith("/")) &&
+    !pathPrefix.includes("\\") &&
+    !pathPrefix.includes("?") &&
+    !pathPrefix.includes("#") &&
+    !pathPrefix.includes("//")
+  );
+}
+
+function boundedNonEmptyString(value: unknown, maximumLength: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= maximumLength;
+}
+
+function normalizedProjectJsonPath(projectPath: unknown): projectPath is string {
+  if (
+    typeof projectPath !== "string" ||
+    projectPath.length === 0 ||
+    projectPath.length > 512 ||
+    !projectPath.endsWith(".json") ||
+    projectPath.startsWith("/") ||
+    projectPath.includes("\\") ||
+    projectPath.includes("\u0000")
+  ) {
+    return false;
+  }
+  return projectPath
+    .split("/")
+    .every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
+
+function safeBindingId(bindingId: unknown): bindingId is string {
+  return typeof bindingId === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u.test(bindingId);
+}

package/src/package-checks/json-schema-validation/options.ts

@@ -0,0 +1,66 @@
+import type {
+  ProjectFileSelection,
+  ProjectFileSelectionOptions
+} from "../project-files/configuration.ts";
+
+export type JsonSchemaIdentityMode =
+  | "require-match"
+  | "configuration-authoritative"
+  | "document-authoritative";
+
+export interface JsonSchemaIdentity {
+  readonly mode: JsonSchemaIdentityMode;
+}
+
+export type JsonSchemaReferenceSource =
+  | Readonly<{ readonly kind: "bundled"; readonly catalog: "json-schema-2020-12" }>
+  | Readonly<{
+      readonly kind: "https";
+      readonly id: string;
+      readonly origin: string;
+      readonly pathPrefix: string;
+    }>;
+
+export type JsonSchemaReferenceResolution =
+  | Readonly<{ readonly mode: "offline" }>
+  | Readonly<{
+      readonly mode: "allowlisted";
+      readonly sources: readonly JsonSchemaReferenceSource[];
+    }>;
+
+export interface RegisteredJsonSchema {
+  readonly id: string;
+  readonly path: string;
+}
+
+export interface JsonSchemaInstanceBinding {
+  readonly id: string;
+  readonly instancePath: string;
+  readonly schemaId: string;
+}
+
+/** `jsonSchemaValidation(options?)` 接受的可省略 authoring policy。 */
+export interface JsonSchemaValidationOptions {
+  /** schema/instance declarations 必须属于的 repository-file selection。 */
+  readonly files?: ProjectFileSelectionOptions;
+  /** 每个 local schema/instance document 允许的最大 raw byte 数；省略时为 1 MiB。 */
+  readonly maximumBytes?: number;
+  /** 整个 Check 共用的 schema root identity 规则；不得按 schema 混用。 */
+  readonly schemaIdentity?: JsonSchemaIdentity;
+  /** 默认离线；额外 schema source 必须显式 allowlist。 */
+  readonly referenceResolution?: JsonSchemaReferenceResolution;
+  /** 显式注册的 schema resources；ID 是 binding 和 public fact 使用的安全 authoring identity。 */
+  readonly schemas?: readonly RegisteredJsonSchema[];
+  /** 明确把一个由本 Check file selection 批准的 instance path 绑定到已声明 schema。 */
+  readonly bindings?: readonly JsonSchemaInstanceBinding[];
+}
+
+/** `json-schema-validation` execution 消费的完整、冻结 options。 */
+export interface ResolvedJsonSchemaValidationOptions {
+  readonly files: ProjectFileSelection;
+  readonly maximumBytes: number;
+  readonly schemaIdentity: JsonSchemaIdentity;
+  readonly referenceResolution: JsonSchemaReferenceResolution;
+  readonly schemas: readonly RegisteredJsonSchema[];
+  readonly bindings: readonly JsonSchemaInstanceBinding[];
+}

package/src/package-checks/json-schema-validation/reference-resolver.ts

@@ -0,0 +1,165 @@
+import type { AnySchemaObject } from "ajv";
+
+import type { ResolvedJsonSchemaValidationOptions } from "./options.ts";
+import type { SchemaCompileReason } from "./schema-engine.ts";
+import { inspectSchemaPolicy, isJsonObject } from "./schema-policy.ts";
+import { inspectStrictJsonBytes } from "../json-document/strict-document.ts";
+import { normalizeRemoteReference, readBoundedResponse } from "./remote-response.ts";
+
+interface ControlledResolverInput {
+  readonly referenceResolution: ResolvedJsonSchemaValidationOptions["referenceResolution"];
+  readonly signal: AbortSignal;
+}
+
+const MAX_REMOTE_RESPONSE_BYTES = 1_048_576;
+const REMOTE_TIMEOUT_MS = 5_000;
+
+export class ControlledReferenceResolver {
+  readonly #cache = new Map<string, Promise<AnySchemaObject>>();
+  #loadQueue: Promise<void> = Promise.resolve();
+  readonly #allowedHttpsSources: readonly Readonly<{
+    readonly origin: string;
+    readonly pathPrefix: string;
+  }>[];
+  readonly #resolverInput: ControlledResolverInput;
+
+  constructor(input: ControlledResolverInput) {
+    this.#resolverInput = input;
+    this.#allowedHttpsSources =
+      input.referenceResolution.mode === "allowlisted"
+        ? Object.freeze(
+            input.referenceResolution.sources.flatMap((source) =>
+              source.kind === "https"
+                ? [Object.freeze({ origin: source.origin, pathPrefix: source.pathPrefix })]
+                : []
+            )
+          )
+        : Object.freeze([]);
+  }
+
+  load(referenceUri: string): Promise<AnySchemaObject> {
+    let normalizedReferenceUri: string;
+    try {
+      normalizedReferenceUri = normalizeRemoteReference(referenceUri);
+    } catch {
+      return Promise.reject(new ReferenceResolutionFailure("unapproved-reference"));
+    }
+    const cached = this.#cache.get(normalizedReferenceUri);
+    if (cached !== undefined) return cached;
+    const loading = this.queueLoad(normalizedReferenceUri);
+    this.#cache.set(normalizedReferenceUri, loading);
+    return loading;
+  }
+
+  private queueLoad(referenceUri: string): Promise<AnySchemaObject> {
+    const loading = this.#loadQueue.then(
+      () => this.loadUncached(referenceUri),
+      () => this.loadUncached(referenceUri)
+    );
+    this.#loadQueue = loading.then(
+      () => undefined,
+      () => undefined
+    );
+    return loading;
+  }
+
+  private async loadUncached(referenceUri: string): Promise<AnySchemaObject> {
+    if (!this.isAllowedReference(referenceUri))
+      throw new ReferenceResolutionFailure("unapproved-reference");
+    if (this.#resolverInput.signal.aborted) throw new ReferenceTransportFailure();
+    const controller = new AbortController();
+    const abortForCaller = (): void => controller.abort();
+    this.#resolverInput.signal.addEventListener("abort", abortForCaller, { once: true });
+    const timeout = setTimeout(() => controller.abort(), REMOTE_TIMEOUT_MS);
+    try {
+      return await this.loadWithController(referenceUri, controller);
+    } catch (error) {
+      if (
+        error instanceof ReferenceResolutionFailure ||
+        error instanceof ReferenceTransportFailure
+      ) {
+        throw error;
+      }
+      throw new ReferenceTransportFailure();
+    } finally {
+      clearTimeout(timeout);
+      this.#resolverInput.signal.removeEventListener("abort", abortForCaller);
+    }
+  }
+
+  private async loadWithController(
+    referenceUri: string,
+    controller: AbortController
+  ): Promise<AnySchemaObject> {
+    const response = await fetchSchemaResponse(referenceUri, controller.signal);
+    assertAllowedResponse(response);
+    if (this.#resolverInput.signal.aborted) throw new ReferenceTransportFailure();
+    const bytes = await readBoundedResponse(
+      response,
+      MAX_REMOTE_RESPONSE_BYTES,
+      this.#resolverInput.signal
+    );
+    return schemaFromRemoteBytes(bytes, referenceUri);
+  }
+
+  private isAllowedReference(referenceUri: string): boolean {
+    let url: URL;
+    try {
+      url = new URL(referenceUri);
+    } catch {
+      return false;
+    }
+    return this.#allowedHttpsSources.some(
+      (source) =>
+        url.origin === source.origin &&
+        (source.pathPrefix === "/" || url.pathname.startsWith(source.pathPrefix))
+    );
+  }
+}
+
+async function fetchSchemaResponse(referenceUri: string, signal: AbortSignal): Promise<Response> {
+  if (typeof globalThis.fetch !== "function") throw new ReferenceTransportFailure();
+  return globalThis.fetch(referenceUri, {
+    credentials: "omit",
+    method: "GET",
+    redirect: "manual",
+    signal
+  });
+}
+
+function assertAllowedResponse(response: Response): void {
+  if (response.redirected || (response.status >= 300 && response.status < 400)) {
+    throw new ReferenceResolutionFailure("unapproved-reference");
+  }
+  if (response.ok) return;
+  if (response.status >= 500) throw new ReferenceTransportFailure();
+  throw new ReferenceResolutionFailure("unapproved-reference");
+}
+
+function schemaFromRemoteBytes(
+  bytes: Uint8Array | "too-large",
+  referenceUri: string
+): AnySchemaObject {
+  if (bytes === "too-large") throw new ReferenceResolutionFailure("remote-document-invalid");
+  const document = inspectStrictJsonBytes(bytes);
+  if (document.kind !== "valid" || !isJsonObject(document.jsonValue)) {
+    throw new ReferenceResolutionFailure("remote-document-invalid");
+  }
+  if (document.jsonValue.$id !== referenceUri) {
+    throw new ReferenceResolutionFailure("remote-schema-id-mismatch");
+  }
+  const referenceReason = inspectSchemaPolicy(document.jsonValue);
+  if (referenceReason !== undefined) throw new ReferenceResolutionFailure(referenceReason);
+  return document.jsonValue;
+}
+
+export class ReferenceResolutionFailure extends Error {
+  readonly reason: SchemaCompileReason;
+
+  constructor(reason: SchemaCompileReason) {
+    super(reason);
+    this.reason = reason;
+  }
+}
+
+export class ReferenceTransportFailure extends Error {}

package/src/package-checks/json-schema-validation/remote-response.ts

@@ -0,0 +1,84 @@
+export async function readBoundedResponse(
+  response: Response,
+  maximumBytes: number,
+  signal: AbortSignal
+): Promise<Uint8Array | "too-large"> {
+  if (declaredResponseIsTooLarge(response, maximumBytes)) return "too-large";
+  const reader = response.body?.getReader();
+  if (reader === undefined) return new Uint8Array();
+
+  const chunks = await readResponseChunks(reader, maximumBytes, signal);
+  return chunks === "too-large" ? chunks : assembleResponseBytes(chunks);
+}
+
+function declaredResponseIsTooLarge(response: Response, maximumBytes: number): boolean {
+  const length = response.headers.get("content-length");
+  return length !== null && /^\d+$/u.test(length) && Number(length) > maximumBytes;
+}
+
+async function readResponseChunks(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  maximumBytes: number,
+  signal: AbortSignal
+): Promise<readonly Uint8Array[] | "too-large"> {
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      if (signal.aborted) throw transportFailure();
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      total += chunk.value.byteLength;
+      if (total > maximumBytes) {
+        await cancelRejectedReader(reader);
+        return "too-large";
+      }
+      chunks.push(chunk.value);
+    }
+    return chunks;
+  } catch {
+    throw transportFailure();
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function cancelRejectedReader(
+  reader: ReadableStreamDefaultReader<Uint8Array>
+): Promise<void> {
+  try {
+    await reader.cancel();
+  } catch {
+    // The bounded response has already been rejected; cancellation detail is not a transport fact.
+  }
+}
+
+function assembleResponseBytes(chunks: readonly Uint8Array[]): Uint8Array {
+  const responseBytes = new Uint8Array(
+    chunks.reduce((total, chunk) => total + chunk.byteLength, 0)
+  );
+  let offset = 0;
+  for (const chunk of chunks) {
+    responseBytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return responseBytes;
+}
+
+function transportFailure(): Error {
+  return new Error("remote response transport failed");
+}
+
+export function normalizeRemoteReference(referenceUri: string): string {
+  const url = new URL(referenceUri);
+  if (
+    url.protocol !== "https:" ||
+    url.username.length > 0 ||
+    url.password.length > 0 ||
+    url.search.length > 0 ||
+    url.hash.length > 0
+  ) {
+    throw new TypeError("unapproved remote reference");
+  }
+  return url.href;
+}