@telorun/kernel 0.44.1 → 0.46.0

package/src/controller-loaders/npm-loader.ts

@@ -44,22 +44,39 @@ const PEER_INSTALL_FLAGS: ReadonlyArray<string> =
       : [];
 
 /**
- * Maximum age before a held lock is considered abandoned. `npm install` on a
- * cold cache for a tree with one or two controllers is comfortably under a
- * minute on modern hardware; tuning higher would let zombie locks persist.
+ * A held lock is refreshed (its mtime bumped) every {@link LOCK_HEARTBEAT_MS}
+ * by the holder. Staleness is judged purely by mtime age — a lock older than
+ * this means the holder stopped heartbeating (crashed, was killed, or its
+ * container vanished), so it is safe to reclaim. This deliberately does NOT
+ * probe the recorded PID for liveness: PID identity is meaningless across
+ * container restarts and PID namespaces (deterministic PID reuse makes an
+ * unrelated process look like the dead holder on the same hostname), which is
+ * exactly what deadlocked container boots. The `{pid, host}` in the lock body
+ * is diagnostics for humans, never a reclaim signal. Must be comfortably
+ * larger than the heartbeat interval so a briefly-descheduled holder (GC
+ * pause, busy event loop) is not reclaimed out from under itself.
  */
-const LOCK_STALE_MS = 60_000;
+const LOCK_STALE_MS = 30_000;
+
+/** How often the holder refreshes the lock mtime while `fn` runs. Well under
+ *  {@link LOCK_STALE_MS} so several heartbeats are missed before a live holder
+ *  is ever judged stale. */
+const LOCK_HEARTBEAT_MS = 5_000;
 
 /**
  * Total wall-clock cap for waiting on the install lock — enough for a slow
- * first install on a peer process to finish, short enough that a deadlocked
- * CI job fails loudly rather than hanging for hours. The retry interval
- * trades wakeup latency vs. wasted polls; 500ms is well below the lock
- * holder's typical hold time.
+ * first install on a peer process to finish, short enough that a genuinely
+ * deadlocked CI job fails loudly rather than hanging for hours. The retry
+ * interval trades wakeup latency vs. wasted polls; 500ms is well below the
+ * lock holder's typical hold time.
  */
 const LOCK_WAIT_MAX_MS = 5 * 60_000;
 const LOCK_RETRY_MS = 500;
 
+/** After this long waiting on a lock, emit one stderr line so a slow wait is
+ *  visible instead of looking like a silent hang. */
+const LOCK_WAIT_NOTICE_MS = 2_000;
+
 /**
  * Tells the dispatcher (and any UI consumer downstream) which branch the
  * resolver actually took. `npm-install` is the only one that hits the network;
@@ -532,9 +549,17 @@ async function resolveKernelPackageRoot(name: string): Promise<string | null> {
 
 /**
  * Acquire a process-portable lock on `<root>/.lock` and execute fn while
- * holding it. Implementation: `fs.open(path, 'wx')` is atomic on POSIX and
- * Windows; concurrent processes serialize naturally. PID + start time live
- * inside the lock file so a crashed-holder lock can be detected and reclaimed.
+ * holding it. `fs.open(path, 'wx')` is atomic on POSIX and Windows, so
+ * concurrent processes serialize naturally.
+ *
+ * Liveness is a heartbeat: the holder bumps the lock's mtime every
+ * {@link LOCK_HEARTBEAT_MS} while `fn` runs, and a waiter reclaims a lock whose
+ * mtime is older than {@link LOCK_STALE_MS} (holder crashed/killed/vanished).
+ * mtime age is the *only* reclaim signal — the recorded `{pid, host}` is
+ * diagnostics, never probed for liveness, because PID identity is unreliable
+ * across container restarts and PID namespaces (the failure that deadlocked
+ * container boots). Reclaim is via atomic rename to a unique tombstone so two
+ * waiters that both see the lock stale can't both win.
  *
  * The lock guards the install-root manifest write, the package-manager
  * invocation, and any state-file writes. It does NOT serialize *reads* of
@@ -548,6 +573,7 @@ async function withInstallLock<T>(installRoot: string, fn: () => Promise<T>): Pr
   const lockBody = JSON.stringify({ pid: process.pid, host: os.hostname(), startedAt: Date.now() });
   let handle: import("fs/promises").FileHandle | null = null;
   const waitedSince = Date.now();
+  let noticed = false;
   while (true) {
     try {
       handle = await fs.open(lockPath, "wx");
@@ -555,31 +581,41 @@ async function withInstallLock<T>(installRoot: string, fn: () => Promise<T>): Pr
       break;
     } catch (err: any) {
       if (err?.code !== "EEXIST") throw err;
-      // Lock exists. Inspect its mtime + PID. If older than LOCK_STALE_MS and
-      // the holding PID isn't alive (or is on another host), reclaim.
-      if (await isLockStale(lockPath)) {
-        await fs.rm(lockPath, { force: true });
-        continue;
-      }
-      if (Date.now() - waitedSince > LOCK_WAIT_MAX_MS) {
+      // Lock exists. Reclaim it only if its heartbeat has gone silent.
+      if (await reclaimIfStale(lockPath)) continue;
+      const waited = Date.now() - waitedSince;
+      if (waited > LOCK_WAIT_MAX_MS) {
         throw new Error(
           `[telo] timed out waiting for install lock at ${lockPath} ` +
-            `(held >${LOCK_WAIT_MAX_MS / 60_000} min). ` +
+            `(held >${LOCK_WAIT_MAX_MS / 60_000} min with a live heartbeat). ` +
             `Inspect the lock file or remove it manually if no other Telo process is running.`,
         );
       }
+      if (!noticed && waited > LOCK_WAIT_NOTICE_MS) {
+        noticed = true;
+        process.stderr.write(`[telo] waiting for controller install lock at ${lockPath}…\n`);
+      }
       await sleep(LOCK_RETRY_MS);
     }
   }
 
+  // Keep the lock fresh while `fn` runs so a slow-but-live install is never
+  // reclaimed. `unref` so the heartbeat can't by itself keep the process alive.
+  const heartbeat = setInterval(() => {
+    const now = new Date();
+    fs.utimes(lockPath, now, now).catch(() => {});
+  }, LOCK_HEARTBEAT_MS);
+  heartbeat.unref?.();
+
   try {
     return await fn();
   } finally {
+    clearInterval(heartbeat);
     // The fd close races nothing important: if it fails, the FD is reaped on
     // process exit. The unlink is the dangerous one — a non-ENOENT failure
     // (permissions, read-only mount) means every subsequent kernel waits
     // LOCK_STALE_MS before reclaiming. Surface it so the cause is visible
-    // rather than hiding behind a silent five-minute hang.
+    // rather than hiding behind a silent hang.
     await handle!.close().catch(() => {});
     try {
       await fs.rm(lockPath, { force: true });
@@ -593,47 +629,36 @@ async function withInstallLock<T>(installRoot: string, fn: () => Promise<T>): Pr
   }
 }
 
-async function isLockStale(lockPath: string): Promise<boolean> {
+/**
+ * If the lock at `lockPath` is stale (mtime older than {@link LOCK_STALE_MS}, so
+ * its holder stopped heartbeating), atomically claim and remove it and return
+ * true; otherwise return false. The claim is a `rename` to a unique tombstone:
+ * `rename` is atomic and fails for all but one racer, so two processes that
+ * both observe the same stale lock cannot both reclaim it — the loser's rename
+ * throws ENOENT (the file is already gone) and it simply retries the open.
+ */
+async function reclaimIfStale(lockPath: string): Promise<boolean> {
   let stat: import("fs").Stats;
   try {
     stat = await fs.stat(lockPath);
   } catch (err: any) {
-    // Race: lock vanished while we inspected it. The next open() will succeed.
-    if (err?.code === "ENOENT") return false;
+    // Race: lock vanished while we inspected it. Retry the open immediately.
+    if (err?.code === "ENOENT") return true;
     throw err;
   }
-  const age = Date.now() - stat.mtimeMs;
-  if (age < LOCK_STALE_MS) return false;
+  if (Date.now() - stat.mtimeMs < LOCK_STALE_MS) return false;
 
-  let body: string;
+  // Stale — the holder's heartbeat is silent. Claim via atomic rename; only one
+  // racer wins, the rest get ENOENT and fall back to retrying the open.
+  const tombstone = `${lockPath}.stale.${process.pid}.${stat.mtimeMs}`;
   try {
-    body = await fs.readFile(lockPath, "utf8");
+    await fs.rename(lockPath, tombstone);
   } catch (err: any) {
-    if (err?.code === "ENOENT") return false;
+    if (err?.code === "ENOENT") return true; // another waiter reclaimed it first
     throw err;
   }
-  // A zero-byte or unparseable lock file is interpreted as stale: a previous
-  // holder crashed mid-write (empty body) or got partially flushed (truncated
-  // JSON). Treating either as held would deadlock; throwing here would block
-  // every controller load behind a broken file the operator may not even
-  // notice exists.
-  if (!body) return true;
-  let parsed: { pid?: number; host?: string };
-  try {
-    parsed = JSON.parse(body);
-  } catch {
-    return true;
-  }
-  if (!parsed?.pid) return true;
-  if (parsed.host && parsed.host !== os.hostname()) return false; // different host: assume held
-  try {
-    // signal 0 throws if the PID isn't alive (or is owned by a different user)
-    process.kill(parsed.pid, 0);
-    return false;
-  } catch (err: any) {
-    // ESRCH = no such process. EPERM = exists but we can't signal it; treat as alive.
-    return err?.code === "ESRCH";
-  }
+  await fs.rm(tombstone, { force: true });
+  return true;
 }
 
 async function runPackageManager(cwd: string, args: string[]): Promise<void> {
@@ -1043,6 +1068,10 @@ export const __testing__ = {
   resolveExportTargetValue,
   tryResolveFile,
   computeInstallRoot,
+  withInstallLock,
+  reclaimIfStale,
+  LOCK_STALE_MS,
+  LOCK_HEARTBEAT_MS,
   EXPORTS_MAX_DEPTH,
   DEFAULT_RESOLVER_CONDITIONS,
   REALM_COLLAPSE_NAMES,

package/src/controllers/resource-definition/resource-definition-controller.ts

@@ -8,6 +8,7 @@ import type {
 import { RuntimeError } from "@telorun/sdk";
 import {
   controllerBearingAncestor,
+  effectiveAuthorSchema,
   hasOwnControllerOrTemplate,
   inheritedCapability,
   type DefResolver,
@@ -56,6 +57,28 @@ class ResourceDefinition implements ResourceInstance {
       return definingCtx.getDefinition?.(canonical) ?? definingCtx.getDefinition?.(kind);
     };
 
+    // Stamp the inheritance-resolved author schema, mirroring the capability
+    // stamping below: without `base:`, an `extends` child is authored against
+    // merge(parent, own), so a field the parent declares is legal on the child.
+    // Every consumer validating a resource against `definition.schema` must see
+    // that merged view — otherwise the analyzer accepts an inherited field and
+    // the kernel rejects it at create(). Shares `effectiveAuthorSchema` with the
+    // analyzer so `telo check` and the runtime cannot drift.
+    if (this.resource.extends) {
+      if (!resolveDef(this.resource.extends)) {
+        // Parent not loaded yet — defer rather than silently merging nothing,
+        // which would cache a schema missing every inherited field.
+        throw new RuntimeError(
+          "ERR_LOCAL_REF_PENDING",
+          `Telo.Definition '${this.resource.metadata.name}': 'extends' target '${this.resource.extends}' is not loaded yet.`,
+        );
+      }
+      this.resource.schema = effectiveAuthorSchema(
+        this.resource as ResourceDefinitionManifest,
+        resolveDef,
+      );
+    }
+
     // Inherited-controller delegation: a definition that `extends` a concrete
     // kind, declares no own `controllers:` / template body, inherits the parent
     // controller by delegation and maps its config via `base:`.

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`. */