threadwire 0.1.11 → 0.1.12

package/src/threadwire-binding.js

@@ -0,0 +1,192 @@
+// @ts-nocheck
+
+import {createHash} from "node:crypto"
+import {isAbsolute, normalize, relative} from "node:path"
+
+const UUID = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/u
+const VOLUME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u
+const REVISION = /^[0-9a-f]{40}$/u
+const DIGEST = /^sha256:[0-9a-f]{64}$/u
+const CONTAINER_ID = /^[0-9a-f]{64}$/u
+const POSITIVE_ID = /^[1-9]\d{0,9}$/u
+const MAX_ID = 2_147_483_647
+const MAX_MANIFEST_BYTES = 1_048_576
+const MAX_CONTEXT_ENTRIES = 4_096
+const MAX_CONTEXT_BYTES = 67_108_864
+
+/**
+ * Parse the closed Threadwire binding transport schema. This function is the
+ * single authority for a binding: callers must not re-parse loose fields.
+ * @param {unknown} value
+ */
+export function parseThreadwireBinding(value) {
+  if (!record(value) || !exactKeys(value, ["version", "taskId", "source", "context", "runtime", "leaseContainerId"])
+    || value.version !== 1 || !canonicalUuid(value.taskId) || !CONTAINER_ID.test(value.leaseContainerId)) failBinding()
+  const source = parseSource(value.source)
+  const context = parseContext(value.context)
+  const runtime = parseRuntime(value.runtime)
+  if (source.volume === context.volume || runtime.workdir !== "/workspace" && !within("/workspace", runtime.workdir)) failBinding()
+  return {
+    version: 1,
+    taskId: value.taskId,
+    source,
+    context,
+    runtime,
+    leaseContainerId: value.leaseContainerId
+  }
+}
+
+/**
+ * Parse the trusted launcher transport without retaining or reporting its raw
+ * text. A binding is control metadata, but still never belongs in a provider
+ * or worker environment.
+ * @param {unknown} value
+ */
+export function parseTrustedThreadwireBinding(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 32_768) failBinding()
+  try { return parseThreadwireBinding(JSON.parse(value)) } catch { failBinding() }
+}
+
+/** @param {ReturnType<typeof parseThreadwireBinding>} binding */
+export function canonicalThreadwireBinding(binding) {
+  const parsed = parseThreadwireBinding(binding)
+  return JSON.stringify({
+    version: parsed.version,
+    taskId: parsed.taskId,
+    source: {
+      volume: parsed.source.volume, target: parsed.source.target,
+      readOnly: parsed.source.readOnly, revision: parsed.source.revision
+    },
+    context: {
+      volume: parsed.context.volume, target: parsed.context.target,
+      readOnly: parsed.context.readOnly,
+      digests: {manifest: parsed.context.digests.manifest, content: parsed.context.digests.content},
+      imageId: parsed.context.imageId
+    },
+    runtime: {uid: parsed.runtime.uid, gid: parsed.runtime.gid, workdir: parsed.runtime.workdir},
+    leaseContainerId: parsed.leaseContainerId
+  })
+}
+
+/** @param {ReturnType<typeof parseThreadwireBinding>} binding */
+export function threadwireBindingDigest(binding) {
+  return `sha256:${createHash("sha256").update(canonicalThreadwireBinding(binding)).digest("hex")}`
+}
+
+/**
+ * A stable identity for state adoption. It intentionally excludes only the
+ * mutable source commit and recreatable lease identifier.
+ * @param {ReturnType<typeof parseThreadwireBinding>} binding
+ */
+export function resumeTaskIdentity(binding) {
+  const parsed = parseThreadwireBinding(binding)
+  return JSON.stringify({
+    version: parsed.version,
+    taskId: parsed.taskId,
+    source: {volume: parsed.source.volume, target: parsed.source.target, readOnly: parsed.source.readOnly},
+    context: {
+      volume: parsed.context.volume, target: parsed.context.target,
+      digests: {manifest: parsed.context.digests.manifest, content: parsed.context.digests.content},
+      imageId: parsed.context.imageId
+    },
+    runtime: parsed.runtime
+  })
+}
+
+/** @param {Buffer | string} bytes */
+export function parseContextManifest(bytes) {
+  const buffer = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes)
+  if (buffer.length === 0 || buffer.length > MAX_MANIFEST_BYTES) failManifest()
+  let value
+  try { value = JSON.parse(buffer.toString("utf8")) } catch { failManifest() }
+  if (!record(value) || !exactKeys(value, ["version", "taskId", "imageId", "content", "entries"])
+    || value.version !== 1 || !canonicalUuid(value.taskId) || !DIGEST.test(value.imageId) || !DIGEST.test(value.content)
+    || !Array.isArray(value.entries) || value.entries.length > MAX_CONTEXT_ENTRIES) failManifest()
+  let previous
+  let total = 0
+  const entries = value.entries.map((entry) => {
+    if (!record(entry) || !exactKeys(entry, ["path", "type", "mode", "bytes", "sha256"])
+      || !contextPath(entry.path) || entry.type !== "file" || !Number.isSafeInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o777 || (entry.mode & 0o222) !== 0
+      || !Number.isSafeInteger(entry.bytes) || entry.bytes < 0 || entry.bytes > MAX_CONTEXT_BYTES || !DIGEST.test(entry.sha256)) failManifest()
+    if (previous !== undefined && Buffer.compare(Buffer.from(previous), Buffer.from(entry.path)) >= 0) failManifest()
+    previous = entry.path
+    total += entry.bytes
+    if (total > MAX_CONTEXT_BYTES) failManifest()
+    return {path: entry.path, type: "file", mode: entry.mode, bytes: entry.bytes, sha256: entry.sha256}
+  })
+  return {version: 1, taskId: value.taskId, imageId: value.imageId, content: value.content, entries}
+}
+
+/** @param {ReturnType<typeof parseContextManifest>} manifest */
+export function canonicalContextInventory(manifest) {
+  const parsed = parseContextManifest(Buffer.from(JSON.stringify(manifest)))
+  return JSON.stringify(parsed.entries.map((entry) => ({
+    path: entry.path, type: entry.type, mode: entry.mode, bytes: entry.bytes, sha256: entry.sha256
+  })))
+}
+
+/** @param {ReturnType<typeof parseContextManifest>} manifest */
+export function contextInventoryDigest(manifest) {
+  return `sha256:${createHash("sha256").update(canonicalContextInventory(manifest)).digest("hex")}`
+}
+
+/**
+ * Bind a parsed manifest to the exact task and immutable image of the active
+ * binding before any inventory is accepted.
+ * @param {ReturnType<typeof parseContextManifest>} manifest
+ * @param {unknown} taskId
+ * @param {unknown} imageId
+ */
+export function assertContextManifestIdentity(manifest, taskId, imageId) {
+  if (!canonicalUuid(taskId) || typeof imageId !== "string" || !DIGEST.test(imageId)
+    || manifest.taskId !== taskId || manifest.imageId !== imageId) failManifest()
+}
+
+/** @param {unknown} value */
+function parseSource(value) {
+  // readOnly selects the exact admitted mount mode: false is a writable
+  // implementation source, true an explicitly read-only review source.
+  if (!record(value) || !exactKeys(value, ["volume", "target", "readOnly", "revision"])
+    || !VOLUME.test(value.volume) || value.target !== "/workspace" || typeof value.readOnly !== "boolean" || !REVISION.test(value.revision)) failBinding()
+  return {volume: value.volume, target: value.target, readOnly: value.readOnly, revision: value.revision}
+}
+
+/** @param {unknown} value */
+function parseContext(value) {
+  if (!record(value) || !exactKeys(value, ["volume", "target", "readOnly", "digests", "imageId"])
+    || !VOLUME.test(value.volume) || value.target !== "/context" || value.readOnly !== true || !DIGEST.test(value.imageId)
+    || !record(value.digests) || !exactKeys(value.digests, ["manifest", "content"])
+    || !DIGEST.test(value.digests.manifest) || !DIGEST.test(value.digests.content)) failBinding()
+  return {
+    volume: value.volume, target: value.target, readOnly: value.readOnly,
+    digests: {manifest: value.digests.manifest, content: value.digests.content}, imageId: value.imageId
+  }
+}
+
+/** @param {unknown} value */
+function parseRuntime(value) {
+  if (!record(value) || !exactKeys(value, ["uid", "gid", "workdir"])
+    || !safeContainerId(value.uid) || !safeContainerId(value.gid) || typeof value.workdir !== "string"
+    || !isAbsolute(value.workdir) || normalize(value.workdir) !== value.workdir) failBinding()
+  return {uid: value.uid, gid: value.gid, workdir: value.workdir}
+}
+
+/** @param {unknown} value */
+function safeContainerId(value) { return typeof value === "number" && Number.isSafeInteger(value) && POSITIVE_ID.test(String(value)) && value <= MAX_ID }
+/** @param {unknown} value */
+function canonicalUuid(value) { return typeof value === "string" && UUID.test(value) }
+/** @param {string} root @param {string} path */
+function within(root, path) { const path_ = relative(root, path); return path_ === "" || (!path_.startsWith("..") && !isAbsolute(path_)) }
+/** @param {unknown} value */
+function contextPath(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 1024 && !value.startsWith("/")
+    && !value.includes("\\") && value.split("/").every((part) => part !== "" && part !== "." && part !== "..")
+}
+/** @param {unknown} value @param {string[]} keys */
+function exactKeys(value, keys) { return record(value) && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key)) }
+/** @param {unknown} value */
+function record(value) { return typeof value === "object" && value !== null && !Array.isArray(value) }
+/** Fail without reflecting untrusted binding input. */
+function failBinding() { throw new Error("Threadwire binding is invalid") }
+/** Fail without reflecting untrusted manifest input. */
+function failManifest() { throw new Error("Threadwire context manifest is invalid") }

package/src/workspace-profile.js

@@ -6,6 +6,7 @@ import {dirname, join, resolve, sep} from "node:path"
 import {fileURLToPath} from "node:url"
 import {promisify} from "node:util"
 import {PROVIDERS} from "./providers/index.js"
+import {parseThreadwireBinding} from "./threadwire-binding.js"
 
 const execFile = promisify(nodeExecFile)
 const DEFAULT_PROFILES_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "threadwire.workspace-profiles.json")
@@ -14,9 +15,9 @@ const SOURCE_IDENTITY_PATTERN = /^[0-9a-f]{40}$|^[0-9a-f]{64}$/u
 const PROFILE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u
 
 /**
- * @typedef {{repositoryRoot: string, cwd: string, providers: ("codex" | "claude" | "kimi" | "opencode")[]}} WorkspaceProfile
- * @typedef {{version: 1, defaultProfile: string, profiles: Record<string, WorkspaceProfile>}} WorkspaceProfilesConfig
- * @typedef {{profile: string, repositoryRoot: string, cwd: string, revision: string, sourceIdentity: string}} ResolvedWorkspaceProfile
+ * @typedef {{repositoryRoot: string, cwd: string, providers: ("codex" | "claude" | "kimi" | "opencode")[], bindings?: {kimi: "threadwire-v1"}}} WorkspaceProfile
+ * @typedef {{version: 1 | 2, defaultProfile: string, profiles: Record<string, WorkspaceProfile>}} WorkspaceProfilesConfig
+ * @typedef {{profile: string, repositoryRoot: string, cwd: string, revision: string, sourceIdentity: string, binding?: unknown}} ResolvedWorkspaceProfile
  * @typedef {{repositoryRoot: string, revision: string, sourceIdentity: string}} GitProvenance
  * @typedef {{
  *   readProfiles?: () => Promise<unknown>,
@@ -27,7 +28,7 @@ const PROFILE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u
 
 /** @param {unknown} value @returns {WorkspaceProfilesConfig} */
 export function parseWorkspaceProfiles(value) {
-  if (!isRecord(value) || value.version !== 1 || typeof value.defaultProfile !== "string" || !isRecord(value.profiles)) {
+  if (!isRecord(value) || (value.version !== 1 && value.version !== 2) || typeof value.defaultProfile !== "string" || !isRecord(value.profiles)) {
     throw new Error("Workspace profile configuration is invalid")
   }
   assertExactKeys(value, ["version", "defaultProfile", "profiles"])
@@ -35,24 +36,31 @@ export function parseWorkspaceProfiles(value) {
   const profiles = {}
   for (const [name, profile] of Object.entries(value.profiles)) {
     if (!PROFILE_NAME_PATTERN.test(name) || !isRecord(profile)) throw new Error("Workspace profile configuration is invalid")
-    assertExactKeys(profile, ["repositoryRoot", "cwd", "providers"])
+    assertExactKeys(profile, value.version === 2 ? ["repositoryRoot", "cwd", "providers", "bindings"] : ["repositoryRoot", "cwd", "providers"])
     const repositoryRoot = absoluteNormalizedPath(profile.repositoryRoot)
     const cwd = absoluteAbsolutePath(profile.cwd)
     if (cwd !== resolve(cwd) || !pathWithin(repositoryRoot, resolve(cwd))) {
       throw new Error(`Workspace profile ${name} cwd must stay within its repository root`)
     }
     const providers = parseProviders(profile.providers)
-    profiles[name] = {repositoryRoot, cwd: resolve(cwd), providers}
+    let bindings
+    if (value.version === 2 && Object.hasOwn(profile, "bindings")) {
+      if (!isRecord(profile.bindings)) throw new Error("Workspace profile configuration is invalid")
+      assertExactKeys(profile.bindings, ["kimi"])
+      if (profile.bindings.kimi !== "threadwire-v1") throw new Error("Workspace profile configuration is invalid")
+      bindings = /** @type {{kimi: "threadwire-v1"}} */ ({kimi: "threadwire-v1"})
+    }
+    profiles[name] = {repositoryRoot, cwd: resolve(cwd), providers, ...(bindings === undefined ? {} : {bindings})}
   }
   if (!Object.hasOwn(profiles, value.defaultProfile)) {
     throw new Error("Workspace profile configuration is invalid")
   }
-  return {version: 1, defaultProfile: value.defaultProfile, profiles}
+  return {version: value.version, defaultProfile: value.defaultProfile, profiles}
 }
 
 /**
  * Resolve a reviewed workspace profile to a validated in-container workspace.
- * @param {{provider: "codex" | "claude" | "kimi" | "opencode", profile?: string}} selection
+ * @param {{provider: "codex" | "claude" | "kimi" | "opencode", profile?: string, binding?: unknown}} selection
  * @param {WorkspaceProfileOperations} [operations]
  * @returns {Promise<ResolvedWorkspaceProfile>}
  */
@@ -65,6 +73,21 @@ export async function resolveWorkspaceProfile(selection, operations = {}) {
   if (!profile.providers.includes(selection.provider)) {
     throw new WorkspaceProviderMismatchError(profileName, selection.provider)
   }
+  if (selection.provider === "kimi") {
+    if (config.version !== 2 || profile.bindings?.kimi !== "threadwire-v1" || selection.binding === undefined) {
+      throw new Error("Kimi requires Threadwire binding schema v1")
+    }
+    let binding
+    try { binding = parseThreadwireBinding(selection.binding) } catch { throw new Error("Kimi requires Threadwire binding schema v1") }
+    return {
+      profile: profileName,
+      repositoryRoot: binding.source.target,
+      cwd: binding.runtime.workdir,
+      revision: binding.source.revision,
+      sourceIdentity: binding.context.digests.content.slice("sha256:".length),
+      binding
+    }
+  }
   const directoryExists = operations.directoryExists ?? defaultDirectoryExists
   if (!await directoryExists(profile.repositoryRoot) || !await directoryExists(profile.cwd)) {
     throw new Error(`Workspace profile ${profileName} workspace is unavailable`)

package/threadwire.workspace-profiles.json

@@ -1,11 +1,12 @@
 {
-  "version": 1,
+  "version": 2,
   "defaultProfile": "container-runtime",
   "profiles": {
     "container-runtime": {
       "repositoryRoot": "/workspace/threadwire",
       "cwd": "/workspace/threadwire",
-      "providers": ["codex", "kimi"]
+      "providers": ["codex", "kimi"],
+      "bindings": {"kimi": "threadwire-v1"}
     }
   }
 }