@telorun/kernel 0.44.1 → 0.45.0

package/src/transports/egress-guard.ts

@@ -0,0 +1,103 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+import { hostEnv } from "../host-env.js";
+
+/** Egress policy for transport fetches, from `TELO_EGRESS`:
+ *  - unset / `open` — no restriction (the default; a developer machine).
+ *  - `public-only` — refuse any host that is, or resolves to, a private,
+ *    loopback, link-local, or carrier-grade-NAT address.
+ *
+ *  Built for deployments whose transports fetch attacker-suppliable refs — the
+ *  discovery hub's tracker is the first: a registered `oci://10.0.0.5/…` or
+ *  `https://169.254.169.254/…` ref must not become a request into the hub's
+ *  own network. A guardrail, not isolation: it checks the name a fetch starts
+ *  at, so redirect hops are not re-checked, and the check-then-fetch gap is
+ *  open to DNS rebinding (a hostile resolver can answer public for the check
+ *  and private for the fetch — the classic bypass for this guard shape).
+ *  Network-level egress policy on the deployment is the actual boundary;
+ *  this guard is defense-in-depth, not a substitute. */
+export class EgressDeniedError extends Error {
+  constructor(host: string, address: string) {
+    super(
+      `Egress to '${host}' denied: it resolves to the non-public address ${address} ` +
+        `(TELO_EGRESS=public-only). Refusing to fetch from private, loopback, ` +
+        `link-local, or CGNAT ranges.`,
+    );
+    this.name = "EgressDeniedError";
+  }
+}
+
+function isPrivateIpv4(address: string): boolean {
+  const octets = address.split(".").map(Number);
+  if (octets.length !== 4 || octets.some((o) => Number.isNaN(o))) return true; // malformed → deny
+  const [a, b] = octets;
+  return (
+    a === 0 || // "this network"
+    a === 10 ||
+    a === 127 || // loopback
+    (a === 100 && b >= 64 && b <= 127) || // CGNAT 100.64/10
+    (a === 169 && b === 254) || // link-local (incl. cloud metadata)
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168)
+  );
+}
+
+function isPrivateIpv6(address: string): boolean {
+  const lower = address.toLowerCase();
+  // IPv4-mapped (::ffff:a.b.c.d) — judge the embedded IPv4.
+  const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (mapped) return isPrivateIpv4(mapped[1]);
+  return (
+    lower === "::" ||
+    lower === "::1" || // loopback
+    lower.startsWith("fc") || // unique-local fc00::/7
+    lower.startsWith("fd") ||
+    lower.startsWith("fe8") || // link-local fe80::/10
+    lower.startsWith("fe9") ||
+    lower.startsWith("fea") ||
+    lower.startsWith("feb")
+  );
+}
+
+/** True when `address` (an IP literal) is not publicly routable. */
+export function isPrivateAddress(address: string): boolean {
+  const family = isIP(address);
+  if (family === 4) return isPrivateIpv4(address);
+  if (family === 6) return isPrivateIpv6(address);
+  return true; // not an IP literal → caller passed garbage; deny
+}
+
+function policyActive(): boolean {
+  // Read through `hostEnv()` like every kernel TELO_* read: `boot()` replaces
+  // `process.env` with the guardrail proxy that hides manifest-declared keys,
+  // so a manifest binding `env: TELO_EGRESS` must not be able to silently
+  // switch this security control off.
+  return (hostEnv().TELO_EGRESS ?? "").toLowerCase() === "public-only";
+}
+
+/** Assert `hostOrUrl` (a `host[:port]` or a full URL) may be fetched under the
+ *  active egress policy. No-op unless `TELO_EGRESS=public-only`. An IP-literal
+ *  host is judged directly; a hostname is resolved and every returned address
+ *  must be public. Throws {@link EgressDeniedError}; DNS failure surfaces as
+ *  the underlying error (never a silent pass). */
+export async function assertPublicEgress(hostOrUrl: string): Promise<void> {
+  if (!policyActive()) return;
+  let hostname = hostOrUrl;
+  if (hostOrUrl.includes("://")) {
+    hostname = new URL(hostOrUrl).hostname;
+  } else {
+    // Bare host[:port] — URL parsing handles IPv6 brackets and ports.
+    hostname = new URL(`https://${hostOrUrl}`).hostname;
+  }
+  // URL wraps IPv6 literals in brackets; strip for isIP/lookup.
+  const bare = hostname.replace(/^\[|\]$/g, "");
+  if (isIP(bare)) {
+    if (isPrivateAddress(bare)) throw new EgressDeniedError(bare, bare);
+    return;
+  }
+  const addresses = await lookup(bare, { all: true, verbatim: true });
+  for (const { address } of addresses) {
+    if (isPrivateAddress(address)) throw new EgressDeniedError(bare, address);
+  }
+}

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

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 
+import { assertPublicEgress } from "../egress-guard.js";
 import { resolveDockerCredential } from "./docker-credentials.js";
 
 export const TELO_LAYER_MEDIA_TYPE = "application/vnd.telo.module.v1+tar";
@@ -37,6 +38,17 @@ function sha256Hex(bytes: Uint8Array): string {
   return createHash("sha256").update(bytes).digest("hex");
 }
 
+/** Resolve the `rel="next"` target of a `Link` header against the registry
+ *  origin, or `null` when there is no next page. */
+function nextPageUrl(linkHeader: string | null, origin: string): string | null {
+  if (!linkHeader) return null;
+  for (const part of linkHeader.split(",")) {
+    const m = part.match(/<([^>]+)>\s*;[^,]*rel="?next"?/i);
+    if (m) return new URL(m[1], origin).href;
+  }
+  return null;
+}
+
 /** Parse a `WWW-Authenticate: Bearer realm="...",service="...",scope="..."` header. */
 function parseBearerChallenge(header: string): Record<string, string> {
   const out: Record<string, string> = {};
@@ -82,6 +94,9 @@ export class OciClient {
     init: RequestInit,
     scope: string,
   ): Promise<Response> {
+    // Registry refs are attacker-suppliable once public registration exists —
+    // refuse non-public hosts under TELO_EGRESS=public-only (no-op otherwise).
+    await assertPublicEgress(url);
     const withToken = (token?: string): RequestInit => {
       const headers = new Headers(init.headers);
       if (token) headers.set("authorization", `Bearer ${token}`);
@@ -107,6 +122,10 @@ export class OciClient {
   private async fetchToken(challenge: string, scope: string): Promise<string | null> {
     const params = parseBearerChallenge(challenge);
     if (!params.realm) return null;
+    // The token realm comes from the registry's own WWW-Authenticate header —
+    // an attacker-controlled registry could point it anywhere, so it is
+    // egress-checked like any other host.
+    await assertPublicEgress(params.realm);
     const tokenUrl = new URL(params.realm);
     if (params.service) tokenUrl.searchParams.set("service", params.service);
     tokenUrl.searchParams.set("scope", params.scope || scope);
@@ -147,16 +166,58 @@ export class OciClient {
     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 [];
+  /** Content-identity digest of the manifest a reference resolves to, via a
+   *  HEAD request — no blob download. Falls back to hashing the manifest body
+   *  when the registry omits `Docker-Content-Digest`. `null` when the
+   *  reference does not exist. */
+  async headManifest(reference: string): Promise<string | null> {
+    const url = `${this.base()}/manifests/${reference}`;
+    const head = await this.authedFetch(
+      url,
+      { method: "HEAD", headers: { accept: MANIFEST_ACCEPT } },
+      this.pullScope(),
+    );
+    await head.text().catch(() => {});
+    if (head.status === 404) return null;
+    if (!head.ok) {
+      throw new Error(
+        `OCI head manifest ${this.repo}:${reference} on ${this.host} failed: ${head.status} ${head.statusText}`,
+      );
+    }
+    const digest = head.headers.get("docker-content-digest");
+    if (digest) return digest;
+
+    const res = await this.authedFetch(url, { headers: { accept: MANIFEST_ACCEPT } }, this.pullScope());
+    if (res.status === 404) return null;
     if (!res.ok) {
       throw new Error(
-        `OCI list tags for ${this.repo} on ${this.host} failed: ${res.status} ${res.statusText}`,
+        `OCI pull manifest ${this.repo}:${reference} on ${this.host} failed: ${res.status} ${res.statusText}`,
       );
     }
-    const body = (await res.json()) as { tags?: string[] | null };
-    return Array.isArray(body.tags) ? body.tags : [];
+    return `sha256:${sha256Hex(new Uint8Array(await res.arrayBuffer()))}`;
+  }
+
+  /** All tags, following the distribution spec's pagination (`Link: …;
+   *  rel="next"` with `last=` cursors) so a many-versioned repo enumerates
+   *  fully — registries cap a single page (Docker Hub at 100). */
+  async listTags(): Promise<string[]> {
+    const tags: string[] = [];
+    let url: string | null = `${this.base()}/tags/list?n=1000`;
+    const seen = new Set<string>();
+    while (url && !seen.has(url)) {
+      seen.add(url);
+      const res: Response = await this.authedFetch(url, {}, this.pullScope());
+      if (res.status === 404) return tags;
+      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 };
+      if (Array.isArray(body.tags)) tags.push(...body.tags);
+      url = nextPageUrl(res.headers.get("link"), `https://${this.host}`);
+    }
+    return tags;
   }
 
   /** Upload `bytes` as a blob (skipped when already present), returning its

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

@@ -1,53 +1,4 @@
-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 };
-}
+// The OCI ref grammar is pure string parsing shared with the browser-safe
+// manifest-cache key helper, so it lives in `@telorun/analyzer`; this shim
+// keeps the kernel-internal import sites stable.
+export { OCI_SCHEME, isOciRef, parseOciRef, type ParsedOciRef } from "@telorun/analyzer";

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

@@ -125,6 +125,11 @@ export class OciTransport implements Transport {
     return tags;
   }
 
+  async digest(ref: string): Promise<string | null> {
+    const { host, repo, reference } = parseOciRef(ref);
+    return new OciClient(host, repo).headManifest(reference);
+  }
+
   async fetchArtifact(ref: string): Promise<FetchedArtifact> {
     return pullVerified(ref);
   }

package/src/transports/registry-transport.ts

@@ -5,6 +5,7 @@ import {
   RegistrySource,
   isRegistryRef,
   parseModuleRef,
+  sha256Base64Url,
   splitIntegrity,
   type ManifestSource,
 } from "@telorun/analyzer";
@@ -13,6 +14,7 @@ import { createHash } from "crypto";
 import { computeFilesIntegrity, injectFilesIntegrity } from "../bundle/files-integrity.js";
 import { readOwnerManifest } from "../bundle/module-manifest.js";
 import { makeTarGz, readTarGz, toPayloadFiles } from "../bundle/tar.js";
+import { assertPublicEgress } from "./egress-guard.js";
 import type {
   FetchedArtifact,
   PublishBundle,
@@ -88,7 +90,12 @@ export class RegistryTransport implements Transport {
       this.httpSource.supports(ref) ? this.httpSource : this.registrySource;
     this.source = {
       supports: (url) => this.supports(url),
-      read: (url) => pick(url).read(url),
+      read: async (url) => {
+        // The browser-safe sources do the fetch; the Node-side egress policy
+        // is enforced here, on the host the read will actually hit.
+        await assertPublicEgress(this.httpSource.supports(url) ? url : this.registryUrl);
+        return pick(url).read(url);
+      },
       resolveRelative: (base, relative) => pick(base).resolveRelative(base, relative),
     };
   }
@@ -151,6 +158,7 @@ export class RegistryTransport implements Transport {
     if (!isRegistryRef(ref)) return null;
     const { modulePath } = parseModuleRef(ref);
     const url = `${this.registryUrl.replace(/\/+$/, "")}/${modulePath}`;
+    await assertPublicEgress(url);
     const res = await fetch(url, { headers: { accept: "application/json" } });
     if (res.status === 404) return null;
     if (!res.ok) {
@@ -160,6 +168,30 @@ export class RegistryTransport implements Transport {
     return Array.isArray(body.versions) ? body.versions : [];
   }
 
+  async digest(ref: string): Promise<string | null> {
+    // Mirrors the sources' fetch-URL derivation: a direct URL points at (or
+    // contains) the YAML file; a bare registry ref folds into the registry
+    // layout. The digest is Telo's canonical hash over the `telo.yaml` bytes.
+    const { base } = splitIntegrity(ref);
+    let fetchUrl: string;
+    if (base.startsWith("http://") || base.startsWith("https://")) {
+      fetchUrl = base.includes(".yaml") ? base : `${base}/${DEFAULT_MANIFEST_FILENAME}`;
+    } else if (isRegistryRef(ref)) {
+      const { modulePath, version } = parseModuleRef(ref);
+      fetchUrl = `${this.registryUrl.replace(/\/+$/, "")}/${modulePath}/${version}/${DEFAULT_MANIFEST_FILENAME}`;
+    } else {
+      return null;
+    }
+    await assertPublicEgress(fetchUrl);
+    const res = await fetch(fetchUrl);
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      throw new Error(`Registry returned ${res.status} ${res.statusText} for ${fetchUrl}`);
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    return `sha256-${await sha256Base64Url(bytes)}`;
+  }
+
   async fetchArtifact(ref: string): Promise<FetchedArtifact> {
     // `read` verifies the manifest bytes against the inline `#sha256-...` hash.
     const { text: manifest, source } = await this.source.read(ref);
@@ -168,6 +200,7 @@ export class RegistryTransport implements Transport {
 
     // The payload rides beside the manifest as `module.tar.gz`.
     const tarUrl = source.replace(/\/telo\.yaml$/, "/module.tar.gz");
+    await assertPublicEgress(tarUrl);
     const res = await fetch(tarUrl);
     if (!res.ok) {
       throw new Error(`could not fetch bundle ${tarUrl}: ${res.status} ${res.statusText}`);

package/src/transports/transport-registry.ts

@@ -47,6 +47,12 @@ export class TransportRegistry {
     return this.require(ref).fetchArtifact(ref);
   }
 
+  /** Cheap content-identity digest for `ref` via its owning transport; `null`
+   *  when the version does not exist. Throws when no transport owns the ref. */
+  digest(ref: string): Promise<string | null> {
+    return this.require(ref).digest(ref);
+  }
+
   /** Publish `bundle` to `destination` via the transport its scheme selects.
    *  Throws when no transport owns the destination. */
   publish(

package/src/transports/transport.ts

@@ -89,6 +89,16 @@ export interface Transport {
    *  the out-of-band bundle fetch that used to sit outside the source chain. */
   fetchArtifact(ref: string): Promise<FetchedArtifact>;
 
+  /** Cheap content-identity digest of what `ref` currently resolves to — no
+   *  payload download. Opaque and transport-specific (OCI: the image manifest's
+   *  `sha256:<hex>` content digest; HTTP: `sha256-<base64url>` over the
+   *  `telo.yaml` bytes), so compare for equality only, never across transports.
+   *  Returns `null` when the version does not exist. Version content
+   *  immutability is a convention no transport enforces — a tag can be
+   *  re-pushed to different bytes — so the discovery tracker records this
+   *  digest per version and re-checks it on every track. */
+  digest(ref: string): Promise<string | null>;
+
   /** Push `bundle` to `destination` (a base ref / repo whose scheme this
    *  transport owns), pinning the payload and writing the transport-native
    *  artifact shape. Throws on failure. Used by `telo publish`. */