@telorun/kernel 0.46.0 → 0.48.0

package/src/transports/registry-transport.ts

@@ -168,20 +168,26 @@ 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.
+  /** 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. `null` when this transport does not own the ref's shape. */
+  private manifestUrl(ref: string): string | null {
     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)) {
+      return base.includes(".yaml") ? base : `${base}/${DEFAULT_MANIFEST_FILENAME}`;
+    }
+    if (isRegistryRef(ref)) {
       const { modulePath, version } = parseModuleRef(ref);
-      fetchUrl = `${this.registryUrl.replace(/\/+$/, "")}/${modulePath}/${version}/${DEFAULT_MANIFEST_FILENAME}`;
-    } else {
-      return null;
+      return `${this.registryUrl.replace(/\/+$/, "")}/${modulePath}/${version}/${DEFAULT_MANIFEST_FILENAME}`;
     }
+    return null;
+  }
+
+  async digest(ref: string): Promise<string | null> {
+    // The digest is Telo's canonical hash over the `telo.yaml` bytes — the same
+    // value `manifestHash` returns, but absent-is-null rather than a throw.
+    const fetchUrl = this.manifestUrl(ref);
+    if (!fetchUrl) return null;
     await assertPublicEgress(fetchUrl);
     const res = await fetch(fetchUrl);
     if (res.status === 404) return null;
@@ -192,6 +198,22 @@ export class RegistryTransport implements Transport {
     return `sha256-${await sha256Base64Url(bytes)}`;
   }
 
+  /** Hashes the **raw response bytes**, which is exactly what `verifiedFetch`
+   *  checks an inline `#sha256-…` pin against on the read path. */
+  async manifestHash(ref: string): Promise<string> {
+    const fetchUrl = this.manifestUrl(ref);
+    if (!fetchUrl) {
+      throw new Error(`cannot hash non-remote import '${ref}'`);
+    }
+    await assertPublicEgress(fetchUrl);
+    const res = await fetch(fetchUrl);
+    if (!res.ok) {
+      throw new Error(`fetch ${fetchUrl}: ${res.status} ${res.statusText}`);
+    }
+    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);

package/src/transports/transport.ts

@@ -99,6 +99,26 @@ export interface Transport {
    *  digest per version and re-checks it on every track. */
   digest(ref: string): Promise<string | null>;
 
+  /** Telo's inline integrity hash (`sha256-<base64url>`) for the `telo.yaml`
+   *  `ref` resolves to — the value written as a `#sha256-…` pin by `telo
+   *  publish` and re-pinned by `telo upgrade`. Throws when the ref does not
+   *  resolve; callers decide whether that is fatal (`--frozen`) or best-effort.
+   *
+   *  This is on the interface, not computed by the caller, because *what gets
+   *  hashed* is transport-specific and must match exactly what that transport's
+   *  own `source.read()` verifies — otherwise a pin written at publish fails
+   *  verification at import. HTTP/registry hash the raw response bytes;
+   *  OCI hashes the UTF-8 encoding of the `telo.yaml` extracted from the tar
+   *  layer. A caller cannot know which, so a caller-side scheme branch silently
+   *  degrades the moment a transport is added — which is exactly how `oci://`
+   *  refs came to be published unpinned.
+   *
+   *  Distinct from `digest()`: that is an opaque transport-native content id for
+   *  change detection, never written into a manifest or compared across
+   *  transports. This is the portable, cross-transport hash Telo itself
+   *  verifies. */
+  manifestHash(ref: string): Promise<string>;
+
   /** 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`. */