@telorun/kernel 0.42.0 → 0.44.0

package/src/transports/oci/docker-credentials.ts

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import * as path from "node:path";
+
+import { hostEnv } from "../../host-env.js";
+
+export interface DockerCredential {
+  username: string;
+  password: string;
+}
+
+interface DockerConfig {
+  auths?: Record<string, { auth?: string; username?: string; password?: string }>;
+  credHelpers?: Record<string, string>;
+  credsStore?: string;
+}
+
+/** Path to `config.json`, honouring `DOCKER_CONFIG`. */
+function dockerConfigPath(): string {
+  const override = hostEnv().DOCKER_CONFIG;
+  const dir = override && override.trim() ? override.trim() : path.join(homedir(), ".docker");
+  return path.join(dir, "config.json");
+}
+
+async function readDockerConfig(): Promise<DockerConfig | null> {
+  try {
+    return JSON.parse(await readFile(dockerConfigPath(), "utf-8")) as DockerConfig;
+  } catch {
+    return null; // no config, unreadable, or malformed → anonymous
+  }
+}
+
+/** Run `docker-credential-<helper> get` with `host` on stdin, per the Docker
+ *  credential-helper protocol, returning `{Username, Secret}` or null. */
+function runCredentialHelper(helper: string, host: string): Promise<DockerCredential | null> {
+  return new Promise((resolve) => {
+    const proc = spawn(`docker-credential-${helper}`, ["get"], {
+      stdio: ["pipe", "pipe", "ignore"],
+    });
+    let out = "";
+    proc.stdout.on("data", (c) => (out += c));
+    proc.on("error", () => resolve(null)); // helper binary not installed
+    proc.on("close", (code) => {
+      if (code !== 0) return resolve(null);
+      try {
+        const parsed = JSON.parse(out) as { Username?: string; Secret?: string };
+        if (parsed.Username && parsed.Secret) {
+          resolve({ username: parsed.Username, password: parsed.Secret });
+        } else {
+          resolve(null);
+        }
+      } catch {
+        resolve(null);
+      }
+    });
+    proc.stdin.end(host);
+  });
+}
+
+/** Resolve credentials for `host` from the ambient Docker credential chain:
+ *  a per-registry credential helper, the global credential store, then the
+ *  inline `auths` entry (base64 `user:password` or explicit fields). Returns
+ *  null for anonymous access — the caller falls back to an anonymous token. */
+export async function resolveDockerCredential(host: string): Promise<DockerCredential | null> {
+  const config = await readDockerConfig();
+  if (!config) return null;
+
+  const helper = config.credHelpers?.[host];
+  if (helper) return runCredentialHelper(helper, host);
+  if (config.credsStore) return runCredentialHelper(config.credsStore, host);
+
+  const entry = config.auths?.[host];
+  if (entry?.auth) {
+    const decoded = Buffer.from(entry.auth, "base64").toString("utf-8");
+    const colon = decoded.indexOf(":");
+    if (colon > 0) {
+      return { username: decoded.slice(0, colon), password: decoded.slice(colon + 1) };
+    }
+  }
+  if (entry?.username && entry?.password) {
+    return { username: entry.username, password: entry.password };
+  }
+  return null;
+}

package/src/transports/oci/oci-client.ts

@@ -0,0 +1,237 @@
+import { createHash } from "node:crypto";
+
+import { resolveDockerCredential } from "./docker-credentials.js";
+
+export const TELO_LAYER_MEDIA_TYPE = "application/vnd.telo.module.v1+tar";
+export const OCI_MANIFEST_MEDIA_TYPE = "application/vnd.oci.image.manifest.v1+json";
+export const OCI_EMPTY_CONFIG_MEDIA_TYPE = "application/vnd.oci.empty.v1+json";
+
+/** The standard OCI empty descriptor — config `{}` (2 bytes). */
+const EMPTY_CONFIG = Buffer.from("{}", "utf-8");
+const EMPTY_CONFIG_DIGEST = "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a";
+
+const MANIFEST_ACCEPT = [
+  OCI_MANIFEST_MEDIA_TYPE,
+  "application/vnd.oci.image.index.v1+json",
+  "application/vnd.docker.distribution.manifest.v2+json",
+  "application/vnd.docker.distribution.manifest.list.v2+json",
+].join(", ");
+
+export interface OciDescriptor {
+  mediaType: string;
+  digest: string;
+  size: number;
+  data?: string;
+  artifactType?: string;
+}
+
+export interface OciManifest {
+  schemaVersion: number;
+  mediaType?: string;
+  artifactType?: string;
+  config: OciDescriptor;
+  layers: OciDescriptor[];
+}
+
+function sha256Hex(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/** Parse a `WWW-Authenticate: Bearer realm="...",service="...",scope="..."` header. */
+function parseBearerChallenge(header: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  const params = header.replace(/^Bearer\s+/i, "");
+  for (const m of params.matchAll(/([a-z]+)="([^"]*)"/gi)) {
+    out[m[1].toLowerCase()] = m[2];
+  }
+  return out;
+}
+
+/**
+ * A minimal OCI distribution (registry v2) client — exactly the surface Telo
+ * needs: pull manifest / pull blob / push blob / push manifest / list tags,
+ * with the `WWW-Authenticate` bearer-token handshake and the ambient Docker
+ * credential chain. Hand-rolled rather than depending on a stale/Deno-only
+ * client (see plan Decisions). One instance per `(host, repo)`; tokens are
+ * cached per scope for the instance's lifetime.
+ */
+export class OciClient {
+  private readonly tokenByScope = new Map<string, string>();
+
+  constructor(
+    private readonly host: string,
+    private readonly repo: string,
+  ) {}
+
+  private base(): string {
+    return `https://${this.host}/v2/${this.repo}`;
+  }
+
+  private pullScope(): string {
+    return `repository:${this.repo}:pull`;
+  }
+
+  private pushScope(): string {
+    return `repository:${this.repo}:pull,push`;
+  }
+
+  /** Fetch with the bearer-token dance: try (cached token if any), and on 401
+   *  resolve a token from the `WWW-Authenticate` challenge and retry once. */
+  private async authedFetch(
+    url: string,
+    init: RequestInit,
+    scope: string,
+  ): Promise<Response> {
+    const withToken = (token?: string): RequestInit => {
+      const headers = new Headers(init.headers);
+      if (token) headers.set("authorization", `Bearer ${token}`);
+      return { ...init, headers };
+    };
+
+    const cached = this.tokenByScope.get(scope);
+    let res = await fetch(url, withToken(cached));
+    if (res.status !== 401) return res;
+
+    const challenge = res.headers.get("www-authenticate");
+    if (!challenge) return res;
+    const token = await this.fetchToken(challenge, scope);
+    if (!token) return res;
+    this.tokenByScope.set(scope, token);
+    // Drain the 401 body so the connection can be reused.
+    await res.text().catch(() => {});
+    return fetch(url, withToken(token));
+  }
+
+  /** Exchange a bearer challenge for a token, authenticating to the token
+   *  service with Docker credentials when available (else anonymous). */
+  private async fetchToken(challenge: string, scope: string): Promise<string | null> {
+    const params = parseBearerChallenge(challenge);
+    if (!params.realm) return null;
+    const tokenUrl = new URL(params.realm);
+    if (params.service) tokenUrl.searchParams.set("service", params.service);
+    tokenUrl.searchParams.set("scope", params.scope || scope);
+
+    const headers = new Headers();
+    const cred = await resolveDockerCredential(this.host);
+    if (cred) {
+      const basic = Buffer.from(`${cred.username}:${cred.password}`).toString("base64");
+      headers.set("authorization", `Basic ${basic}`);
+    }
+    const res = await fetch(tokenUrl.href, { headers });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { token?: string; access_token?: string };
+    return body.token ?? body.access_token ?? null;
+  }
+
+  async pullManifest(reference: string): Promise<OciManifest> {
+    const res = await this.authedFetch(
+      `${this.base()}/manifests/${reference}`,
+      { headers: { accept: MANIFEST_ACCEPT } },
+      this.pullScope(),
+    );
+    if (!res.ok) {
+      throw new Error(
+        `OCI pull manifest ${this.repo}:${reference} on ${this.host} failed: ${res.status} ${res.statusText}`,
+      );
+    }
+    return (await res.json()) as OciManifest;
+  }
+
+  async pullBlob(digest: string): Promise<Buffer> {
+    const res = await this.authedFetch(`${this.base()}/blobs/${digest}`, {}, this.pullScope());
+    if (!res.ok) {
+      throw new Error(
+        `OCI pull blob ${digest} from ${this.repo} on ${this.host} failed: ${res.status} ${res.statusText}`,
+      );
+    }
+    return Buffer.from(await res.arrayBuffer());
+  }
+
+  async listTags(): Promise<string[]> {
+    const res = await this.authedFetch(`${this.base()}/tags/list`, {}, this.pullScope());
+    if (res.status === 404) return [];
+    if (!res.ok) {
+      throw new Error(
+        `OCI list tags for ${this.repo} on ${this.host} failed: ${res.status} ${res.statusText}`,
+      );
+    }
+    const body = (await res.json()) as { tags?: string[] | null };
+    return Array.isArray(body.tags) ? body.tags : [];
+  }
+
+  /** Upload `bytes` as a blob (skipped when already present), returning its
+   *  `sha256:<hex>` digest. Two-step upload: obtain a session, then PUT with
+   *  the digest. */
+  async pushBlob(bytes: Uint8Array): Promise<string> {
+    const digest = `sha256:${sha256Hex(bytes)}`;
+
+    const head = await this.authedFetch(
+      `${this.base()}/blobs/${digest}`,
+      { method: "HEAD" },
+      this.pushScope(),
+    );
+    if (head.ok) return digest; // already present
+    await head.text().catch(() => {});
+
+    const start = await this.authedFetch(
+      `${this.base()}/blobs/uploads/`,
+      { method: "POST" },
+      this.pushScope(),
+    );
+    if (start.status !== 202) {
+      throw new Error(
+        `OCI blob upload start for ${this.repo} on ${this.host} failed: ${start.status} ${start.statusText}`,
+      );
+    }
+    const location = start.headers.get("location");
+    await start.text().catch(() => {});
+    if (!location) {
+      throw new Error(`OCI blob upload for ${this.repo} returned no Location header`);
+    }
+    const uploadUrl = new URL(location, `https://${this.host}`);
+    uploadUrl.searchParams.set("digest", digest);
+
+    const put = await this.authedFetch(
+      uploadUrl.href,
+      {
+        method: "PUT",
+        headers: { "content-type": "application/octet-stream" },
+        body: bytes,
+      },
+      this.pushScope(),
+    );
+    if (put.status !== 201) {
+      const detail = await put.text().catch(() => "");
+      throw new Error(
+        `OCI blob PUT for ${this.repo} on ${this.host} failed: ${put.status} ${put.statusText} ${detail}`,
+      );
+    }
+    return digest;
+  }
+
+  async pushManifest(reference: string, manifest: OciManifest): Promise<void> {
+    const body = Buffer.from(JSON.stringify(manifest), "utf-8");
+    const res = await this.authedFetch(
+      `${this.base()}/manifests/${reference}`,
+      { method: "PUT", headers: { "content-type": OCI_MANIFEST_MEDIA_TYPE }, body },
+      this.pushScope(),
+    );
+    if (res.status !== 201) {
+      const detail = await res.text().catch(() => "");
+      throw new Error(
+        `OCI push manifest ${this.repo}:${reference} on ${this.host} failed: ${res.status} ${res.statusText} ${detail}`,
+      );
+    }
+  }
+
+  /** Push the standard empty config blob and return its descriptor. */
+  async pushEmptyConfig(): Promise<OciDescriptor> {
+    await this.pushBlob(EMPTY_CONFIG);
+    return {
+      mediaType: OCI_EMPTY_CONFIG_MEDIA_TYPE,
+      digest: EMPTY_CONFIG_DIGEST,
+      size: EMPTY_CONFIG.length,
+      data: EMPTY_CONFIG.toString("base64"),
+    };
+  }
+}

package/src/transports/oci/oci-ref.ts

@@ -0,0 +1,53 @@
+import { splitIntegrity } from "@telorun/analyzer";
+
+export const OCI_SCHEME = "oci://";
+
+/** A parsed `oci://host/repo@reference` module ref.
+ *
+ *  - `host` — the registry host (`ghcr.io`, `123.dkr.ecr.us-east-1.amazonaws.com`).
+ *  - `repo` — the repository path (`aws/telo-s3`), possibly multi-segment.
+ *  - `reference` — a tag (`1.2.0`) or a digest (`sha256:...`); the OCI address.
+ *  - `integrity` — Telo's inline `sha256-<base64url>` hash when the ref is pinned
+ *    (authoritative across transports; the OCI digest is only corroborating). */
+export interface ParsedOciRef {
+  host: string;
+  repo: string;
+  reference: string;
+  integrity?: string;
+}
+
+/** True when `ref` uses the `oci://` scheme (integrity fragment tolerated). */
+export function isOciRef(ref: string): boolean {
+  return splitIntegrity(ref).base.startsWith(OCI_SCHEME);
+}
+
+/** Parse `oci://host/repo@reference[#sha256-...]`. Throws on a malformed ref.
+ *  A `reference` may be a tag or a `sha256:` digest; when absent (`@` omitted)
+ *  it defaults to `latest`, matching OCI tooling. */
+export function parseOciRef(ref: string): ParsedOciRef {
+  const { base, integrity } = splitIntegrity(ref);
+  if (!base.startsWith(OCI_SCHEME)) {
+    throw new Error(`Invalid OCI reference '${ref}', expected oci://host/repo@reference`);
+  }
+  const rest = base.slice(OCI_SCHEME.length);
+  const slash = rest.indexOf("/");
+  if (slash <= 0) {
+    throw new Error(`Invalid OCI reference '${ref}', missing repository path after host`);
+  }
+  const host = rest.slice(0, slash);
+  let repoAndRef = rest.slice(slash + 1);
+
+  let reference = "latest";
+  const at = repoAndRef.lastIndexOf("@");
+  // A digest reference is `repo@sha256:...` — the `@` before `sha256:` is the
+  // separator, not part of the repo. A tag reference has no `@`.
+  if (at > 0) {
+    reference = repoAndRef.slice(at + 1);
+    repoAndRef = repoAndRef.slice(0, at);
+  }
+  const repo = repoAndRef;
+  if (!host || !repo || !reference) {
+    throw new Error(`Invalid OCI reference '${ref}', expected oci://host/repo@reference`);
+  }
+  return { host, repo, reference, integrity };
+}

package/src/transports/oci/oci-transport.ts

@@ -0,0 +1,192 @@
+import {
+  DEFAULT_MANIFEST_FILENAME,
+  IntegrityError,
+  verifyIntegrity,
+  type ManifestSource,
+} from "@telorun/analyzer";
+
+import { computeFilesIntegrity, injectFilesIntegrity } from "../../bundle/files-integrity.js";
+import { readOwnerManifest } from "../../bundle/module-manifest.js";
+import { makeTarGz, readTarGz, toPayloadFiles } from "../../bundle/tar.js";
+import type {
+  FetchedArtifact,
+  PublishBundle,
+  PublishOptions,
+  PublishResult,
+  SiblingIdentity,
+  Transport,
+} from "../transport.js";
+import {
+  OciClient,
+  OCI_MANIFEST_MEDIA_TYPE,
+  TELO_LAYER_MEDIA_TYPE,
+  type OciManifest,
+} from "./oci-client.js";
+import { OCI_SCHEME, isOciRef, parseOciRef } from "./oci-ref.js";
+
+/** Pull the module blob, returning its extracted entries and the `telo.yaml`
+ *  bytes, verified against the ref's inline hash and its own `filesIntegrity`. */
+async function pullVerified(ref: string): Promise<FetchedArtifact> {
+  const { host, repo, reference, integrity } = parseOciRef(ref);
+  const client = new OciClient(host, repo);
+  const manifest = await client.pullManifest(reference);
+  const layer =
+    manifest.layers.find((l) => l.mediaType === TELO_LAYER_MEDIA_TYPE) ?? manifest.layers[0];
+  if (!layer) {
+    throw new Error(`OCI artifact ${ref} has no layers`);
+  }
+  const tar = await client.pullBlob(layer.digest);
+  const entries = await readTarGz(tar);
+
+  const teloEntry = entries.find((e) => e.name === DEFAULT_MANIFEST_FILENAME);
+  if (!teloEntry) {
+    throw new Error(`OCI artifact ${ref} blob does not contain ${DEFAULT_MANIFEST_FILENAME}`);
+  }
+  const manifestText =
+    typeof teloEntry.content === "string" ? teloEntry.content : teloEntry.content.toString("utf-8");
+
+  // Telo's inline hash is authoritative; the OCI content digest only corroborates.
+  if (integrity) {
+    await verifyIntegrity(new TextEncoder().encode(manifestText), integrity, ref);
+  }
+
+  const files = toPayloadFiles(entries);
+
+  const { filesIntegrity } = readOwnerManifest(manifestText);
+  if (filesIntegrity) {
+    const actual = await computeFilesIntegrity(files);
+    if (actual !== filesIntegrity) {
+      throw new IntegrityError(
+        `Integrity check failed for ${ref}: filesIntegrity expected ${filesIntegrity}, ` +
+          `got ${actual}. The payload does not match the recorded hash.`,
+      );
+    }
+  }
+
+  return { manifest: manifestText, files };
+}
+
+/**
+ * OCI transport: `oci://host/repo@reference` modules on any OCI distribution
+ * registry (GHCR / ECR / Docker Hub / Harbor), over a hand-rolled minimal
+ * client. A module is a single artifact — one tar blob carrying `telo.yaml`
+ * and the `files:` payload — pushed under a standard OCI artifact manifest.
+ *
+ * Not browser-reachable (token handshake, Docker credentials, tar extraction),
+ * so its resolution `source` is Node-only; the editor resolves `oci://` imports
+ * through the discovery hub instead.
+ */
+export class OciTransport implements Transport {
+  readonly source: ManifestSource;
+
+  constructor() {
+    this.source = {
+      supports: (url) => this.supports(url),
+      read: async (url) => {
+        const { manifest } = await pullVerified(url);
+        const { host, repo, reference } = parseOciRef(url);
+        return { text: manifest, source: `${OCI_SCHEME}${host}/${repo}@${reference}` };
+      },
+      resolveRelative: (base, relative) => this.resolveRelative(base, relative),
+    };
+  }
+
+  supports(ref: string): boolean {
+    return isOciRef(ref);
+  }
+
+  cacheLocation(ref: string): string[] | null {
+    let parsed: ReturnType<typeof parseOciRef>;
+    try {
+      parsed = parseOciRef(ref);
+    } catch {
+      return null;
+    }
+    return ["__oci", parsed.host, ...parsed.repo.split("/"), parsed.reference];
+  }
+
+  /** Resolve a relative import against an `oci://` base, normalizing the repo to
+   *  a directory base so `../lib` under `oci://ghcr.io/aws/my-app` →
+   *  `oci://ghcr.io/aws/lib` (never `oci://ghcr.io/lib`). Non-relative refs pass
+   *  through. The reference/tag is dropped — the caller re-pins from the
+   *  sibling's own version. */
+  resolveRelative(base: string, relative: string): string {
+    if (!relative.startsWith(".") && !relative.startsWith("/")) return relative;
+    const { host, repo } = parseOciRef(base);
+    // Resolve the repo path with standard URL semantics against a directory base.
+    const resolved = new URL(relative, `https://${host}/${repo}/`);
+    const newRepo = resolved.pathname.replace(/^\/+/, "");
+    return `${OCI_SCHEME}${host}/${newRepo}`;
+  }
+
+  async listVersions(ref: string): Promise<string[] | null> {
+    const { host, repo } = parseOciRef(ref);
+    const tags = await new OciClient(host, repo).listTags();
+    return tags;
+  }
+
+  async fetchArtifact(ref: string): Promise<FetchedArtifact> {
+    return pullVerified(ref);
+  }
+
+  async publish(
+    destination: string,
+    bundle: PublishBundle,
+    _opts: PublishOptions = {},
+  ): Promise<PublishResult> {
+    const identity = readOwnerManifest(bundle.manifest);
+    if (!identity.version) {
+      throw new Error("OCI publish requires metadata.version (used as the tag).");
+    }
+
+    // Destination is a full repo (`oci://host/repo`) or host-only
+    // (`oci://host`), which defaults the repo to `<namespace>/<name>`.
+    const afterScheme = destination.replace(/^oci:\/\//, "").replace(/\/+$/, "");
+    const slash = afterScheme.indexOf("/");
+    const host = slash > 0 ? afterScheme.slice(0, slash) : afterScheme;
+    let repo = slash > 0 ? afterScheme.slice(slash + 1) : "";
+    if (!repo) {
+      if (!identity.namespace || !identity.name) {
+        throw new Error(
+          `OCI publish to host-only '${destination}' needs metadata.namespace and metadata.name to default the repo.`,
+        );
+      }
+      repo = `${identity.namespace}/${identity.name}`;
+    }
+    const tag = identity.version;
+
+    // Pin the payload, then pack telo.yaml + files into the single module blob.
+    let manifestText = bundle.manifest;
+    if (bundle.files.length > 0) {
+      manifestText = injectFilesIntegrity(manifestText, await computeFilesIntegrity(bundle.files));
+    }
+    const tar = await makeTarGz([
+      { name: DEFAULT_MANIFEST_FILENAME, content: manifestText },
+      ...bundle.files.map((f) => ({ name: f.name, content: Buffer.from(f.content) })),
+    ]);
+
+    const client = new OciClient(host, repo);
+    const layerDigest = await client.pushBlob(tar);
+    const config = await client.pushEmptyConfig();
+    const manifest: OciManifest = {
+      schemaVersion: 2,
+      mediaType: OCI_MANIFEST_MEDIA_TYPE,
+      artifactType: TELO_LAYER_MEDIA_TYPE,
+      config,
+      layers: [{ mediaType: TELO_LAYER_MEDIA_TYPE, digest: layerDigest, size: tar.length }],
+    };
+    await client.pushManifest(tag, manifest);
+
+    return { label: `${repo}@${tag}`, url: `${OCI_SCHEME}${host}/${repo}@${tag}` };
+  }
+
+  canonicalizeSiblingRef(
+    destination: string,
+    relativeSource: string,
+    sibling: SiblingIdentity,
+  ): string {
+    // The sibling's repo is the destination repo with the relative applied; the
+    // version is its own (identity is the ref, not metadata).
+    return `${this.resolveRelative(destination, relativeSource)}@${sibling.version}`;
+  }
+}