@bjoernrochel/sevro 0.1.0-rc.2 → 0.1.0-rc.21

package/src/identity.ts

@@ -40,90 +40,137 @@ export interface IdentityDimensions {
   passThreshold: number;
 }
 
+function surrogateKind(code: number): "high" | "low" | null {
+  if (code >= 0xd800 && code <= 0xdbff) return "high";
+  return code >= 0xdc00 && code <= 0xdfff ? "low" : null;
+}
+
 function assertUnicode(value: string): void {
   for (let index = 0; index < value.length; index++) {
-    const code = value.charCodeAt(index);
-    if (code >= 0xd800 && code <= 0xdbff) {
-      const next = value.charCodeAt(++index);
-      if (!(next >= 0xdc00 && next <= 0xdfff))
+    const kind = surrogateKind(value.charCodeAt(index));
+    if (kind === "high") {
+      if (surrogateKind(value.charCodeAt(++index)) !== "low")
         throw new Error("JSON string contains an unpaired surrogate");
-    } else if (code >= 0xdc00 && code <= 0xdfff) {
+    } else if (kind === "low") {
       throw new Error("JSON string contains an unpaired surrogate");
     }
   }
 }
 
-/** RFC 8785 JSON canonicalization for ordinary JSON values. */
-export function canonicalJson(value: unknown): string {
-  const visiting = new WeakSet<object>();
-  function write(item: unknown): string {
+class CanonicalJsonWriter {
+  private readonly visiting = new WeakSet();
+
+  write(item: unknown): string {
     if (item === null) return "null";
-    if (typeof item === "string") {
-      assertUnicode(item);
-      return JSON.stringify(item);
+    switch (typeof item) {
+      case "string":
+        assertUnicode(item);
+        return JSON.stringify(item);
+      case "number":
+        return this.number(item);
+      case "boolean":
+        return item ? "true" : "false";
+      case "object":
+        return this.object(item);
+      default:
+        throw new Error("value is not JSON data");
     }
-    if (typeof item === "number") {
-      if (!Number.isFinite(item)) throw new Error("JSON number must be finite");
-      return JSON.stringify(item);
-    }
-    if (typeof item === "boolean") return item ? "true" : "false";
-    if (typeof item !== "object") throw new Error("value is not JSON data");
-    if (visiting.has(item)) throw new Error("JSON value contains a cycle");
-    visiting.add(item);
+  }
+
+  private number(item: number): string {
+    if (!Number.isFinite(item)) throw new Error("JSON number must be finite");
+    return JSON.stringify(item);
+  }
+
+  private object(item: object): string {
+    if (this.visiting.has(item)) throw new Error("JSON value contains a cycle");
+    this.visiting.add(item);
     try {
-      if (Array.isArray(item)) return `[${item.map(write).join(",")}]`;
-      const prototype = Object.getPrototypeOf(item);
-      if (prototype !== Object.prototype && prototype !== null)
-        throw new Error("value is not a plain JSON object");
-      if (Object.getOwnPropertySymbols(item).length)
-        throw new Error("JSON object has symbol keys");
-      const record = item as Record<string, unknown>;
-      const entries = Object.keys(record)
+      if (Array.isArray(item))
+        return `[${item.map((value: unknown) => this.write(value)).join(",")}]`;
+      this.assertPlainObject(item);
+      const entries = Object.keys(item)
         .sort()
-        .map((key) => {
-          assertUnicode(key);
-          const descriptor = Object.getOwnPropertyDescriptor(record, key);
-          if (!descriptor || !Object.hasOwn(descriptor, "value"))
-            throw new Error("JSON object has an accessor property");
-          return `${JSON.stringify(key)}:${write(descriptor.value)}`;
-        });
+        .map((key) => this.property(item, key));
       return `{${entries.join(",")}}`;
     } finally {
-      visiting.delete(item);
+      this.visiting.delete(item);
     }
   }
-  return write(value);
+
+  private assertPlainObject(item: object): void {
+    const prototype: unknown = Object.getPrototypeOf(item);
+    if (prototype !== Object.prototype && prototype !== null)
+      throw new Error("value is not a plain JSON object");
+    if (Object.getOwnPropertySymbols(item).length)
+      throw new Error("JSON object has symbol keys");
+  }
+
+  private property(item: object, key: string): string {
+    assertUnicode(key);
+    const descriptor = Object.getOwnPropertyDescriptor(item, key);
+    if (!descriptor || !Object.hasOwn(descriptor, "value"))
+      throw new Error("JSON object has an accessor property");
+    const value: unknown = descriptor.value;
+    return `${JSON.stringify(key)}:${this.write(value)}`;
+  }
+}
+
+/** RFC 8785 JSON canonicalization for ordinary JSON values. */
+export function canonicalJson(value: unknown): string {
+  return new CanonicalJsonWriter().write(value);
+}
+
+/** Hash exact bytes, or a string's UTF-8 bytes, without JSON canonicalization. */
+export function sha256(content: string | Uint8Array): string {
+  return createHash("sha256").update(content).digest("hex");
 }
 
 export function hashJson(value: unknown): string {
-  return createHash("sha256")
-    .update(canonicalJson(value), "utf8")
-    .digest("hex");
+  return sha256(canonicalJson(value));
 }
 
 function validatedDimensions(value: unknown): IdentityDimensions {
   if (!value || typeof value !== "object" || Array.isArray(value))
     throw new Error("identity dimensions must be a JSON object");
   const record = value as Record<string, unknown>;
+  validateDimensionKeys(record);
+  validateDigestDimensions(record);
+  validateExtensionDimension(record);
+  validateTrialDimensions(record);
+  return record as unknown as IdentityDimensions;
+}
+
+function validateDimensionKeys(record: Record<string, unknown>): void {
   for (const key of DIMENSION_KEYS)
     if (!Object.hasOwn(record, key))
       throw new Error(`missing identity dimension: ${key}`);
   const unexpected = Object.keys(record).filter(
     (key) => !DIMENSION_KEYS.includes(key as (typeof DIMENSION_KEYS)[number]),
   );
-  if (unexpected.length)
-    throw new Error(`unexpected identity dimension: ${unexpected[0]}`);
+  const firstUnexpected = unexpected[0];
+  if (firstUnexpected !== undefined)
+    throw new Error(`unexpected identity dimension: ${firstUnexpected}`);
+}
+
+function validateDigestDimensions(record: Record<string, unknown>): void {
   for (const key of DIMENSION_KEYS.filter((name) => name.endsWith("Digest"))) {
     if (key === "extensionDigest" && record[key] === null) continue;
-    if (typeof record[key] !== "string" || !DIGEST.test(record[key]))
+    if (!validDigest(record[key]))
       throw new Error(`invalid identity dimension: ${key}`);
   }
+}
+
+function validateExtensionDimension(record: Record<string, unknown>): void {
   if (
     (record.extensionDigest === null) !== (record.extensionProtocol === null) ||
     (record.extensionProtocol !== null &&
       record.extensionProtocol !== "sevro.extension.v1")
   )
     throw new Error("extension identity requires its matching protocol");
+}
+
+function validateTrialDimensions(record: Record<string, unknown>): void {
   if (record.condition !== "passive" && record.condition !== "enforced")
     throw new Error("invalid identity condition");
   if (
@@ -131,14 +178,17 @@ function validatedDimensions(value: unknown): IdentityDimensions {
     (record.trialCount as number) < 1
   )
     throw new Error("invalid identity trial count");
+  validatePassThreshold(record.passThreshold);
+}
+
+function validatePassThreshold(value: unknown): void {
   if (
-    typeof record.passThreshold !== "number" ||
-    !Number.isFinite(record.passThreshold) ||
-    record.passThreshold <= 0 ||
-    record.passThreshold > 1
+    typeof value !== "number" ||
+    !Number.isFinite(value) ||
+    value <= 0 ||
+    value > 1
   )
     throw new Error("invalid identity pass threshold");
-  return record as unknown as IdentityDimensions;
 }
 
 /** Digest the exact comparison dimensions with a versioned domain prefix. */
@@ -154,3 +204,7 @@ export function createEvaluationIdentity(dimensions: unknown): {
     .digest("hex");
   return { algorithm: ALGORITHM, digest, dimensions: checked };
 }
+
+function validDigest(value: unknown): value is string {
+  return typeof value === "string" && DIGEST.test(value);
+}

package/src/instrumentation.ts

@@ -1,3 +1,4 @@
+import { isRecord, isUnknownArray } from "./value-guards";
 import { canonicalJson } from "./identity";
 
 export interface InstrumentationRequest {
@@ -19,52 +20,88 @@ export class InstrumentationEvidenceError extends Error {
 
 const ID = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/;
 
-function validRequest(value: InstrumentationRequest): boolean {
+function validInstrumentationId(value: unknown): value is string {
+  return typeof value === "string" && ID.test(value);
+}
+
+function validRequest(value: unknown): value is InstrumentationRequest {
   return (
-    Boolean(value && ID.test(value.id)) &&
-    Boolean(
-      value.configuration &&
-      typeof value.configuration === "object" &&
-      !Array.isArray(value.configuration),
-    )
+    isRecord(value) &&
+    validInstrumentationId(value.id) &&
+    isRecord(value.configuration)
   );
 }
 
-/** Validate an extension's request before the candidate host starts. */
-export function prepareInstrumentation(
-  requested: InstrumentationRequest[],
+function validateSupportedInstrumentation(
   supported: InstrumentationCapability[],
-  negotiated: string[],
-  condition: "passive" | "enforced",
-): InstrumentationRequest[] {
-  const supportedIds = new Set(supported.map((item) => item.id));
+): void {
+  const ids = new Set(supported.map((item) => item.id));
   if (
     supported.some(
       (item) =>
         !ID.test(item.id) || typeof item.executionChanging !== "boolean",
     ) ||
-    supportedIds.size !== supported.length
+    ids.size !== supported.length
   )
     throw new Error("host instrumentation capabilities are invalid");
-  const requestedIds = new Set(requested.map((item) => item.id));
+}
+
+function validateRequestedInstrumentation(
+  requested: InstrumentationRequest[],
+): void {
+  const ids = new Set(requested.map((item) => item.id));
   if (
     requested.some((item) => !validRequest(item)) ||
-    requestedIds.size !== requested.length
+    ids.size !== requested.length
   )
     throw new Error("requested instrumentation is invalid or duplicated");
-  for (const item of requested) {
-    const capability = supported.find((entry) => entry.id === item.id);
-    if (!capability || !negotiated.includes(item.id))
-      throw new Error(
-        "extension preparation requested unsupported instrumentation",
-      );
-    if (condition === "passive" && capability.executionChanging)
-      throw new Error(
-        "passive condition cannot apply execution-changing instrumentation",
-      );
-  }
-  canonicalJson(requested);
-  return requested;
+}
+
+function requestedCapability(
+  item: InstrumentationRequest,
+  supported: InstrumentationCapability[],
+  negotiated: string[],
+): InstrumentationCapability {
+  const capability = supported.find((entry) => entry.id === item.id);
+  if (!capability || !negotiated.includes(item.id))
+    throw new Error(
+      "extension preparation requested unsupported instrumentation",
+    );
+  return capability;
+}
+
+function validateInstrumentationCondition(
+  capability: InstrumentationCapability,
+  condition: "passive" | "enforced",
+): void {
+  if (condition === "passive" && capability.executionChanging)
+    throw new Error(
+      "passive condition cannot apply execution-changing instrumentation",
+    );
+}
+
+/** Validate an extension's request before the candidate host starts. */
+export function prepareInstrumentation(
+  requested: InstrumentationRequest[],
+  supported: InstrumentationCapability[],
+  negotiated: string[],
+  condition: "passive" | "enforced",
+): InstrumentationRequest[] {
+  validateSupportedInstrumentation(supported);
+  validateRequestedInstrumentation(requested);
+  for (const item of requested)
+    validateInstrumentationCondition(
+      requestedCapability(item, supported, negotiated),
+      condition,
+    );
+  return snapshotInstrumentation(requested);
+}
+
+/** Own the canonical JSON parameters independently of adapter state. */
+export function snapshotInstrumentation(
+  requested: InstrumentationRequest[],
+): InstrumentationRequest[] {
+  return JSON.parse(canonicalJson(requested)) as InstrumentationRequest[];
 }
 
 /** A host must report exactly the instrumentation it applied. */
@@ -75,32 +112,56 @@ export function verifyAppliedInstrumentation(
   actualCondition: "passive" | "enforced" | "unknown" | undefined,
 ): InstrumentationRequest[] {
   const actual = applied ?? [];
+  validateAppliedRequests(actual, requested);
+  validateActualCondition(actualCondition);
   if (
-    !Array.isArray(actual) ||
-    actual.some((item) => !validRequest(item)) ||
-    new Set(actual.map((item) => item.id)).size !== actual.length ||
-    canonicalJson(actual) !== canonicalJson(requested)
+    mismatchedCondition(actualCondition, requestedCondition) ||
+    (requested.length > 0 && actualCondition !== requestedCondition)
   )
     throw new InstrumentationEvidenceError(
-      "host applied instrumentation does not match the request",
+      "host did not confirm the requested condition",
     );
+  return snapshotInstrumentation(actual);
+}
+
+function requestArray(value: unknown): value is InstrumentationRequest[] {
+  return isUnknownArray(value) && value.every(validRequest);
+}
+
+function validateAppliedRequests(
+  actual: unknown,
+  requested: InstrumentationRequest[],
+): asserts actual is InstrumentationRequest[] {
   if (
-    actualCondition !== undefined &&
-    actualCondition !== "unknown" &&
-    actualCondition !== "passive" &&
-    actualCondition !== "enforced"
+    !requestArray(actual) ||
+    new Set(actual.map((item) => item.id)).size !== actual.length ||
+    canonicalJson(actual) !== canonicalJson(requested)
   )
     throw new InstrumentationEvidenceError(
-      "host condition evidence is invalid",
+      "host applied instrumentation does not match the request",
     );
-  if (
-    (actualCondition !== undefined &&
-      actualCondition !== "unknown" &&
-      actualCondition !== requestedCondition) ||
-    (requested.length > 0 && actualCondition !== requestedCondition)
-  )
+}
+
+function validActualCondition(value: unknown): boolean {
+  return (
+    value === undefined ||
+    value === "unknown" ||
+    value === "passive" ||
+    value === "enforced"
+  );
+}
+
+function validateActualCondition(value: unknown): void {
+  if (!validActualCondition(value))
     throw new InstrumentationEvidenceError(
-      "host did not confirm the requested condition",
+      "host condition evidence is invalid",
     );
-  return actual;
+}
+
+function mismatchedCondition(
+  actual: string | undefined,
+  requested: string,
+): boolean {
+  if (actual === undefined || actual === "unknown") return false;
+  return actual !== requested;
 }

package/src/native-transcript-state.ts

@@ -0,0 +1,131 @@
+import { lstat, mkdir, mkdtemp, realpath } from "node:fs/promises";
+import type { Stats } from "node:fs";
+import { realpathSync } from "node:fs";
+import { tmpdir, userInfo } from "node:os";
+import { basename, dirname, join, sep } from "node:path";
+
+/** A permanent deny boundary also covers roles allocated after command launch. */
+export async function nativeStateParent(): Promise<string> {
+  const root = nativeStatePath();
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const info = await lstat(root);
+  requirePrivateNamespace(info);
+  return realpath(root);
+}
+
+/** Canonical base also binds declaration symlinks before any private tree is read. */
+export function nativeStatePath(): string {
+  return join(realpathSync(nativeStateBase()), "sevro-native-private");
+}
+
+export function nativeStateProtectedRoots(): string[] {
+  return [nativeStatePath(), join(nativeStateBase(), "sevro-native-private")];
+}
+
+function nativeStateBase(): string {
+  return process.platform === "linux" ? "/var/tmp" : tmpdir();
+}
+
+function requirePrivateNamespace(info: Stats): void {
+  if (
+    !info.isDirectory() ||
+    info.uid !== userInfo().uid ||
+    (info.mode & 0o077) !== 0
+  )
+    throw new Error(
+      "native state namespace must be an owned private directory",
+    );
+}
+
+export async function allocateNativeState(
+  prefix: string,
+  runtimeWorkspace?: string,
+): Promise<string> {
+  await requireExternalNativeNamespace(runtimeWorkspace);
+  return realpath(await mkdtemp(join(await nativeStateParent(), prefix)));
+}
+
+/** Workspace writes must never reach existing or future native peer state. */
+async function requireExternalNativeNamespace(
+  workspace?: string,
+): Promise<void> {
+  if (workspace === undefined) return;
+  const fixtureRoot = join(await realpath(workspace), sep);
+  const namespaceRoot = join(nativeStatePath(), sep);
+  if (
+    fixtureRoot.startsWith(namespaceRoot) ||
+    namespaceRoot.startsWith(fixtureRoot)
+  )
+    throw new Error("native runtime namespace overlaps the fixture workspace");
+}
+
+export async function requireNativeTranscriptView(
+  root: string | undefined,
+): Promise<void> {
+  if (root === undefined) return;
+  const parent = await nativeStateParent();
+  if (
+    dirname(root) !== parent ||
+    !basename(root).startsWith("view-") ||
+    (await realpath(root)) !== root
+  )
+    throw new Error(
+      "native transcript view must be runner-owned and canonical",
+    );
+  requirePrivateNamespace(await lstat(root));
+}
+
+export async function requireNativeTranscriptViews(
+  roots: string[] | undefined,
+): Promise<void> {
+  for (const root of roots ?? []) await requireNativeTranscriptView(root);
+}
+
+/** Curated hook copies are a separate runner-owned exception, never policy roots. */
+export async function requireNativeHookRoots(
+  roots: string[] | undefined,
+  privateRoot: string,
+): Promise<void> {
+  for (const root of roots ?? [])
+    await requireNativeHookRoot(root, privateRoot);
+}
+
+async function requireNativeHookRoot(
+  root: string,
+  privateRoot: string,
+): Promise<void> {
+  const parent = await nativeStateParent();
+  const state = dirname(dirname(root));
+  if (!nativeHookLayout(root, state, parent) || (await realpath(root)) !== root)
+    throw new Error("native hook read root must be a canonical curated mount");
+  await requireNativeHookOwner(state, privateRoot);
+  const info = await lstat(root);
+  if (!info.isDirectory() || info.uid !== userInfo().uid)
+    throw new Error("native hook read root must be owned");
+}
+
+async function requireNativeHookOwner(
+  state: string,
+  privateRoot: string,
+): Promise<void> {
+  if (
+    dirname(privateRoot) !== state ||
+    (await realpath(privateRoot)) !== privateRoot
+  )
+    throw new Error("native hook read root must belong to the current request");
+  requirePrivateNamespace(await lstat(state));
+  requirePrivateNamespace(await lstat(privateRoot));
+}
+
+function nativeHookLayout(
+  root: string,
+  state: string,
+  parent: string,
+): boolean {
+  return (
+    dirname(state) === parent &&
+    /^(?:claude|codex)-/.test(basename(state)) &&
+    basename(dirname(root)) === "runtime-plugins" &&
+    /^plugin-[0-9]+$/.test(basename(root))
+  );
+}

package/src/native-transcript-view.ts

@@ -0,0 +1,90 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { allocateNativeState } from "./native-transcript-state";
+import { fixtureParts } from "./fixtures/preparation";
+import { isRecord, isUnknownArray } from "./value-guards";
+import { sha256 } from "./identity";
+
+const MAX_NATIVE_BYTES = 5 * 1024 * 1024;
+type NativeFormat =
+  "sevro.native-transcripts.v1" | "sevro.native-transcripts.v2";
+
+export async function materializeNativeTranscriptView(
+  bytes: Uint8Array,
+): Promise<string> {
+  const value: unknown = JSON.parse(Buffer.from(bytes).toString("utf8"));
+  const bundle = nativeBundle(value);
+  const root = await allocateNativeState("view-");
+  await writeFile(join(root, "index.json"), bytes, { flag: "wx", mode: 0o600 });
+  const filesRoot = join(root, bundle.host);
+  let remainingBytes = MAX_NATIVE_BYTES;
+  for (const item of bundle.files)
+    remainingBytes -= await materializeNativeFile(
+      filesRoot,
+      item,
+      bundle.format,
+      remainingBytes,
+    );
+  return root;
+}
+
+function nativeBundle(value: unknown) {
+  if (!isRecord(value) || !nativeFormat(value.format))
+    throw new Error("invalid native transcript bundle");
+  if (!nativeHost(value.host))
+    throw new Error("invalid native transcript host");
+  if (!isUnknownArray(value.files))
+    throw new Error("invalid native transcript files");
+  return { host: value.host, files: value.files, format: value.format };
+}
+
+function nativeFormat(value: unknown): value is NativeFormat {
+  return (
+    value === "sevro.native-transcripts.v1" ||
+    value === "sevro.native-transcripts.v2"
+  );
+}
+
+function nativeHost(value: unknown): value is "codex" | "claude" {
+  return value === "codex" || value === "claude";
+}
+
+async function materializeNativeFile(
+  root: string,
+  value: unknown,
+  format: NativeFormat,
+  remainingBytes: number,
+): Promise<number> {
+  if (!isRecord(value) || typeof value.path !== "string")
+    throw new Error("invalid native transcript file");
+  const path = join(root, ...fixtureParts(value.path));
+  const bytes = nativeFileBytes(value, format, remainingBytes);
+  if (bytes.length > remainingBytes)
+    throw new Error("native transcript byte limit exceeded");
+  if (sha256(bytes) !== value.sha256)
+    throw new Error("native transcript hash mismatch");
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await writeFile(path, bytes, { flag: "wx", mode: 0o600 });
+  return bytes.length;
+}
+
+function nativeFileBytes(
+  value: Record<string, unknown>,
+  format: NativeFormat,
+  remainingBytes: number,
+): Buffer {
+  const encoded =
+    format === "sevro.native-transcripts.v1"
+      ? value.bytesBase64
+      : value.gzipBase64;
+  if (typeof encoded !== "string")
+    throw new Error("invalid native transcript file");
+  const bytes = Buffer.from(encoded, "base64");
+  if (format === "sevro.native-transcripts.v1") return bytes;
+  try {
+    return gunzipSync(bytes, { maxOutputLength: Math.max(1, remainingBytes) });
+  } catch (cause) {
+    throw new Error("invalid native transcript gzip", { cause });
+  }
+}