@lloyal-labs/rig 2.1.0 → 3.0.1

package/dist/bundle.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Signed-tarball App distribution — verify primitives.
+ *
+ * Apps are distributed as signed npm tarballs through the canonical
+ * channel at {@link CHANNEL_CATALOG_URL}. The `harness.dev install` CLI
+ * uses the primitives here ({@link verifyBundle}, {@link resolveAppEntry})
+ * to fetch + signature-verify a tarball against
+ * {@link CHANNEL_TRUST_ROOTS}, then shells out to `npm install <URL>` so
+ * the app lands in the harness's `node_modules` like any other npm
+ * dependency. The harness boots and imports each app with a plain static
+ * `import`; the framework provides no runtime "load app by name" verb.
+ *
+ * This module exposes the verify primitives only — the file-system and
+ * `npm install` shell-out live in the CLI package
+ * (`@lloyal-labs/harness-cli`) so this entry remains platform-agnostic
+ * (no `node:*` imports) and works in any JS runtime, including React
+ * Native harnesses that might consume `@lloyal-labs/rig` for non-install
+ * code paths.
+ *
+ * **Channel-canonical resolution.** {@link resolveAppEntry} fetches the
+ * catalog from {@link CHANNEL_CATALOG_URL}, verifies its Ed25519
+ * signature against {@link CHANNEL_TRUST_ROOTS}, and resolves a name +
+ * semver range to a {@link CatalogVersion} descriptor (manifestUrl +
+ * tarballUrl + sizeBytes). The caller never supplies a URL or a trust
+ * map — to use a different channel, fork `@lloyal-labs/rig` and edit
+ * the constants in `protocol.ts`.
+ *
+ * **Verification is the entire trust boundary.** `verifyBundle` runs
+ * before `harness.dev install` invokes `npm install <tarball-URL>`, so
+ * a tampered tarball never reaches `npm install`. Once installed, the
+ * lockfile's sha512 `integrity` field carries that trust forward for
+ * subsequent `npm ci` reproduction (immutable tarball URL → same bytes
+ * forever → same sha512 → same Ed25519 chain).
+ *
+ * @packageDocumentation
+ * @category Protocol
+ */
+import type { Operation } from 'effection';
+/**
+ * Manifest describing a signed tarball, served at the `manifestUrl`
+ * listed in a catalog entry. The manifest is the publisher-of-record
+ * payload that ties (tarball bytes ↔ Ed25519 signature ↔ npm-compatible
+ * sha512 integrity ↔ identifying metadata) together.
+ */
+export interface AppBundleManifest {
+    /** App identifier (matches `App.manifest.name`). */
+    name: string;
+    /** Semver of this release. */
+    version: string;
+    /**
+     * Filename of the tarball relative to the channel's bundle directory
+     * (e.g., `web-1.2.0.tgz`). The canonical record of what was signed —
+     * `signature` is over the bytes of this artifact.
+     */
+    entry: string;
+    /** Base64-encoded Ed25519 signature over the tarball bytes. */
+    signature: string;
+    /**
+     * npm-compatible Subresource Integrity hash over the tarball bytes
+     * (e.g., `sha512-<base64>`). `npm install` verifies this on extract
+     * as defense-in-depth; the Ed25519 `signature` above is the
+     * authoritative trust boundary, but the SRI hash carries trust
+     * forward into the consumer's `package-lock.json` so subsequent
+     * `npm ci` reproduces the install without re-verifying the
+     * signature.
+     */
+    integrity: string;
+    /**
+     * Identifier of the publisher's signing key. Looked up in
+     * {@link CHANNEL_TRUST_ROOTS} to obtain the verifying key.
+     */
+    publisherKeyId: string;
+    /** Tarball size in bytes (sanity check vs. download). */
+    sizeBytes: number;
+    /**
+     * peerDependencies of the app (e.g., `{"@lloyal-labs/rig":
+     * "^3.0.0"}`). Informational; npm enforces these on install.
+     */
+    peerDependencies?: Record<string, string>;
+}
+/**
+ * One version's entry in the catalog (under an app's `versions` array).
+ */
+export interface CatalogVersion {
+    /** Semver of this release. */
+    version: string;
+    /** URL the manifest JSON is served from. */
+    manifestUrl: string;
+    /**
+     * URL the signed tarball (`.tgz`) is served from. This URL is
+     * immutable per version: republishing forces a new semver. The
+     * `harness.dev install` CLI passes this URL straight to
+     * `npm install`, and it lands verbatim in the consumer's
+     * `package.json` and `package-lock.json` so CI can reproduce the
+     * install with plain `npm ci` against no Lloyal tooling.
+     */
+    tarballUrl: string;
+    /** App-protocol version this artifact targets (e.g., `'3.0'`). */
+    appProtocolVersion: string;
+    /** Tarball size in bytes (sanity check vs. download). */
+    sizeBytes: number;
+    /**
+     * npm package name as declared in the tarball's `package.json` (e.g.,
+     * `@lloyal-labs/web-app`). The catalog `name` is the scoped Lloyal
+     * identifier (`lloyal/web`); `importName` is what consumers actually
+     * `import { … } from '<importName>'` once npm has installed the tarball.
+     * Validated server-side at submission time against the tarball's
+     * embedded `package.json`.
+     */
+    importName: string;
+}
+/**
+ * One app's entry in the catalog.
+ */
+export interface CatalogEntry {
+    /** App identifier (matches `manifest.name`). */
+    name: string;
+    /** Published versions, unordered. */
+    versions: readonly CatalogVersion[];
+}
+/**
+ * The full signed catalog served at {@link CHANNEL_CATALOG_URL}.
+ *
+ * The signature is over a canonical-JSON encoding of
+ * `{ signedAt, entries, publisherKeyId }` (sorted keys, no whitespace).
+ */
+export interface SignedCatalog {
+    /** ISO-8601 timestamp of when the catalog was signed. */
+    signedAt: string;
+    /** All apps published to the channel. */
+    entries: readonly CatalogEntry[];
+    /**
+     * Identifier of the platform key that signed this catalog. Looked up
+     * in {@link CHANNEL_TRUST_ROOTS}.
+     */
+    publisherKeyId: string;
+    /** Base64-encoded Ed25519 signature. */
+    signature: string;
+}
+/**
+ * Raised when a tarball, manifest, or catalog fails signature, size,
+ * or trust-roots verification. Distinct from network errors raised by
+ * `cancellableFetch`.
+ */
+export declare class BundleVerificationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when {@link resolveAppEntry} cannot resolve the requested
+ * `(name, semver)` tuple against the catalog. Distinct from
+ * {@link BundleVerificationError}: the catalog was reached and verified,
+ * the name is just not listed (or no version matched the semver range).
+ */
+export declare class AppNotFoundError extends Error {
+    constructor(message: string);
+}
+/**
+ * Test-only: override {@link CHANNEL_TRUST_ROOTS} with a map containing
+ * exactly the (keyId, publicKey) pair given. Subsequent
+ * {@link resolveAppEntry} calls (and the internal catalog-verification
+ * path) use this override instead of the framework-vendored constant.
+ * Only active when `process.env.NODE_ENV === 'test'`.
+ *
+ * @internal
+ */
+export declare function setTestTrustRoot(keyId: string, key: Uint8Array): void;
+/**
+ * Test-only: override {@link CHANNEL_CATALOG_URL} with the given URL.
+ * Useful for pointing the resolver at a `file://` or `http://localhost:N`
+ * fixture during unit tests. Only active when
+ * `process.env.NODE_ENV === 'test'`.
+ *
+ * @internal
+ */
+export declare function setTestCatalogUrl(url: string): void;
+/**
+ * Test-only: clear both overrides. Call from `afterEach` to keep test
+ * isolation clean.
+ *
+ * @internal
+ */
+export declare function clearTestOverrides(): void;
+/**
+ * Test-only: drop the per-process catalog cache. Use in `afterEach` to
+ * guarantee a fresh catalog fetch per test.
+ *
+ * @internal
+ */
+export declare function clearCatalogCache(): void;
+/**
+ * Verify an Ed25519 signature over `bytes` using `publicKey` (32-byte
+ * raw key). Returns `true` if the signature is authentic; `false`
+ * otherwise. `crypto.subtle.verify` is async so the function returns a
+ * `Promise<boolean>`; callers `yield* call(() => verifyBundle(...))` to
+ * bridge.
+ */
+export declare function verifyBundle(bytes: Uint8Array, signatureBase64: string, publicKey: Uint8Array): Promise<boolean>;
+/**
+ * Resolve a name + optional semver range against the verified catalog.
+ * Returns the highest-matching version's catalog entry, or throws
+ * {@link AppNotFoundError} if the name is absent or no version matches.
+ *
+ * Consumers (notably the `harness.dev install` CLI) then fetch the
+ * returned `manifestUrl` + `tarballUrl`, run {@link verifyBundle}
+ * against the manifest's signature over the tarball bytes, and shell
+ * out to `npm install <tarballUrl>` to install the verified package.
+ */
+export declare function resolveAppEntry(name: string, opts?: {
+    semver?: string;
+}): Operation<CatalogVersion>;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAK3C;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;OAQG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAcD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,CAErE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAqCD;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAID;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,OAAO,CAAC,CAuBlB;AA2GD;;;;;;;;;GASG;AACH,wBAAiB,eAAe,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,SAAS,CAAC,cAAc,CAAC,CA2B3B"}

package/dist/bundle.js

@@ -0,0 +1,296 @@
+"use strict";
+/**
+ * Signed-tarball App distribution — verify primitives.
+ *
+ * Apps are distributed as signed npm tarballs through the canonical
+ * channel at {@link CHANNEL_CATALOG_URL}. The `harness.dev install` CLI
+ * uses the primitives here ({@link verifyBundle}, {@link resolveAppEntry})
+ * to fetch + signature-verify a tarball against
+ * {@link CHANNEL_TRUST_ROOTS}, then shells out to `npm install <URL>` so
+ * the app lands in the harness's `node_modules` like any other npm
+ * dependency. The harness boots and imports each app with a plain static
+ * `import`; the framework provides no runtime "load app by name" verb.
+ *
+ * This module exposes the verify primitives only — the file-system and
+ * `npm install` shell-out live in the CLI package
+ * (`@lloyal-labs/harness-cli`) so this entry remains platform-agnostic
+ * (no `node:*` imports) and works in any JS runtime, including React
+ * Native harnesses that might consume `@lloyal-labs/rig` for non-install
+ * code paths.
+ *
+ * **Channel-canonical resolution.** {@link resolveAppEntry} fetches the
+ * catalog from {@link CHANNEL_CATALOG_URL}, verifies its Ed25519
+ * signature against {@link CHANNEL_TRUST_ROOTS}, and resolves a name +
+ * semver range to a {@link CatalogVersion} descriptor (manifestUrl +
+ * tarballUrl + sizeBytes). The caller never supplies a URL or a trust
+ * map — to use a different channel, fork `@lloyal-labs/rig` and edit
+ * the constants in `protocol.ts`.
+ *
+ * **Verification is the entire trust boundary.** `verifyBundle` runs
+ * before `harness.dev install` invokes `npm install <tarball-URL>`, so
+ * a tampered tarball never reaches `npm install`. Once installed, the
+ * lockfile's sha512 `integrity` field carries that trust forward for
+ * subsequent `npm ci` reproduction (immutable tarball URL → same bytes
+ * forever → same sha512 → same Ed25519 chain).
+ *
+ * @packageDocumentation
+ * @category Protocol
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppNotFoundError = exports.BundleVerificationError = void 0;
+exports.setTestTrustRoot = setTestTrustRoot;
+exports.setTestCatalogUrl = setTestCatalogUrl;
+exports.clearTestOverrides = clearTestOverrides;
+exports.clearCatalogCache = clearCatalogCache;
+exports.verifyBundle = verifyBundle;
+exports.resolveAppEntry = resolveAppEntry;
+const effection_1 = require("effection");
+const semver_1 = require("semver");
+const cancellable_fetch_1 = require("./cancellable-fetch");
+const protocol_1 = require("./protocol");
+/**
+ * Raised when a tarball, manifest, or catalog fails signature, size,
+ * or trust-roots verification. Distinct from network errors raised by
+ * `cancellableFetch`.
+ */
+class BundleVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BundleVerificationError';
+    }
+}
+exports.BundleVerificationError = BundleVerificationError;
+/**
+ * Raised when {@link resolveAppEntry} cannot resolve the requested
+ * `(name, semver)` tuple against the catalog. Distinct from
+ * {@link BundleVerificationError}: the catalog was reached and verified,
+ * the name is just not listed (or no version matched the semver range).
+ */
+class AppNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AppNotFoundError';
+    }
+}
+exports.AppNotFoundError = AppNotFoundError;
+// ── Test-only injection (NODE_ENV=test) ─────────────────────────────
+//
+// bundle.test.ts overrides the framework-vendored CHANNEL_TRUST_ROOTS +
+// CHANNEL_CATALOG_URL via the helpers below so it can exercise the
+// verification flow against a fresh test keypair + a local HTTP / file://
+// catalog fixture. The overrides are inert outside NODE_ENV=test —
+// `getTrustRoots()` / `getCatalogUrl()` consult them only when the
+// environment names the test runner.
+let testTrustRoots;
+let testCatalogUrl;
+/**
+ * Test-only: override {@link CHANNEL_TRUST_ROOTS} with a map containing
+ * exactly the (keyId, publicKey) pair given. Subsequent
+ * {@link resolveAppEntry} calls (and the internal catalog-verification
+ * path) use this override instead of the framework-vendored constant.
+ * Only active when `process.env.NODE_ENV === 'test'`.
+ *
+ * @internal
+ */
+function setTestTrustRoot(keyId, key) {
+    testTrustRoots = new Map([[keyId, key]]);
+}
+/**
+ * Test-only: override {@link CHANNEL_CATALOG_URL} with the given URL.
+ * Useful for pointing the resolver at a `file://` or `http://localhost:N`
+ * fixture during unit tests. Only active when
+ * `process.env.NODE_ENV === 'test'`.
+ *
+ * @internal
+ */
+function setTestCatalogUrl(url) {
+    testCatalogUrl = url;
+}
+/**
+ * Test-only: clear both overrides. Call from `afterEach` to keep test
+ * isolation clean.
+ *
+ * @internal
+ */
+function clearTestOverrides() {
+    testTrustRoots = undefined;
+    testCatalogUrl = undefined;
+}
+function isTestEnv() {
+    return (typeof process !== 'undefined' &&
+        process.env != null &&
+        process.env.NODE_ENV === 'test');
+}
+function getTrustRoots() {
+    if (isTestEnv() && testTrustRoots)
+        return testTrustRoots;
+    return protocol_1.CHANNEL_TRUST_ROOTS;
+}
+function getCatalogUrl() {
+    if (isTestEnv() && testCatalogUrl)
+        return testCatalogUrl;
+    return protocol_1.CHANNEL_CATALOG_URL;
+}
+const catalogCache = new Map();
+/**
+ * Test-only: drop the per-process catalog cache. Use in `afterEach` to
+ * guarantee a fresh catalog fetch per test.
+ *
+ * @internal
+ */
+function clearCatalogCache() {
+    catalogCache.clear();
+}
+// ── Verification primitives ────────────────────────────────────────
+/**
+ * Verify an Ed25519 signature over `bytes` using `publicKey` (32-byte
+ * raw key). Returns `true` if the signature is authentic; `false`
+ * otherwise. `crypto.subtle.verify` is async so the function returns a
+ * `Promise<boolean>`; callers `yield* call(() => verifyBundle(...))` to
+ * bridge.
+ */
+async function verifyBundle(bytes, signatureBase64, publicKey) {
+    let signature;
+    try {
+        signature = base64ToBytes(signatureBase64);
+    }
+    catch {
+        return false;
+    }
+    if (publicKey.byteLength !== 32)
+        return false;
+    if (signature.byteLength !== 64)
+        return false;
+    const key = await crypto.subtle.importKey('raw', toArrayBuffer(publicKey), { name: 'Ed25519' }, false, ['verify']);
+    return crypto.subtle.verify({ name: 'Ed25519' }, key, toArrayBuffer(signature), toArrayBuffer(bytes));
+}
+/**
+ * Canonical-JSON encoding for signature payloads. Sorts object keys
+ * recursively and emits compact (no-whitespace) output. Arrays preserve
+ * insertion order. Numbers, booleans, null, and strings round-trip via
+ * `JSON.stringify`. Sufficient for `signedAt: ISO8601`, `publisherKeyId:
+ * string`, and the `entries` tree (all string / number primitives).
+ *
+ * Not a full RFC 8785 implementation — explicitly. The catalog schema
+ * is constrained to JSON types this helper handles correctly, and an
+ * RFC 8785 dep would be overkill for the surface area.
+ */
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(',')}]`;
+    }
+    const entries = Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    return `{${entries
+        .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`)
+        .join(',')}}`;
+}
+/**
+ * Compute the signed payload bytes for a catalog: canonical-JSON of
+ * `{ signedAt, entries, publisherKeyId }`, UTF-8 encoded. Used by both
+ * the verifier (here) and the signer (out-of-repo publish tooling).
+ */
+function catalogSignedBytes(signedAt, entries, publisherKeyId) {
+    const json = canonicalJson({ signedAt, entries, publisherKeyId });
+    return new TextEncoder().encode(json);
+}
+/**
+ * Fetch the catalog from {@link CHANNEL_CATALOG_URL}, verify its
+ * signature against {@link CHANNEL_TRUST_ROOTS}, and return the verified
+ * structure. Memoized per-process per effective URL.
+ */
+function* fetchAndVerifyCatalog() {
+    const url = getCatalogUrl();
+    const cached = catalogCache.get(url);
+    if (cached)
+        return cached.catalog;
+    const response = yield* (0, cancellable_fetch_1.cancellableFetch)(url);
+    if (!response.ok) {
+        throw new BundleVerificationError(`Catalog fetch from ${url} returned HTTP ${response.status} ${response.statusText}.`);
+    }
+    const text = yield* (0, effection_1.call)(() => response.text());
+    let catalog;
+    try {
+        catalog = JSON.parse(text);
+    }
+    catch (err) {
+        throw new BundleVerificationError(`Catalog at ${url} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof catalog.signedAt !== 'string' ||
+        !Array.isArray(catalog.entries) ||
+        typeof catalog.publisherKeyId !== 'string' ||
+        typeof catalog.signature !== 'string') {
+        throw new BundleVerificationError(`Catalog at ${url} is missing required fields (signedAt, entries, publisherKeyId, signature).`);
+    }
+    const trustKey = getTrustRoots().get(catalog.publisherKeyId);
+    if (!trustKey) {
+        throw new BundleVerificationError(`Catalog at ${url} is signed by publisherKeyId="${catalog.publisherKeyId}" ` +
+            `which is not in CHANNEL_TRUST_ROOTS. The framework refuses to trust ` +
+            `keys it does not vendor.`);
+    }
+    const signedBytes = catalogSignedBytes(catalog.signedAt, catalog.entries, catalog.publisherKeyId);
+    const ok = yield* (0, effection_1.call)(() => verifyBundle(signedBytes, catalog.signature, trustKey));
+    if (!ok) {
+        throw new BundleVerificationError(`Catalog at ${url} failed Ed25519 signature verification ` +
+            `(publisherKeyId="${catalog.publisherKeyId}"). The catalog was tampered with ` +
+            `or the publisher's signing key has changed without a corresponding rig update.`);
+    }
+    catalogCache.set(url, { catalog, bytes: signedBytes });
+    return catalog;
+}
+/**
+ * Resolve a name + optional semver range against the verified catalog.
+ * Returns the highest-matching version's catalog entry, or throws
+ * {@link AppNotFoundError} if the name is absent or no version matches.
+ *
+ * Consumers (notably the `harness.dev install` CLI) then fetch the
+ * returned `manifestUrl` + `tarballUrl`, run {@link verifyBundle}
+ * against the manifest's signature over the tarball bytes, and shell
+ * out to `npm install <tarballUrl>` to install the verified package.
+ */
+function* resolveAppEntry(name, opts = {}) {
+    const catalog = yield* fetchAndVerifyCatalog();
+    const entry = catalog.entries.find((e) => e.name === name);
+    if (!entry) {
+        throw new AppNotFoundError(`App "${name}" is not listed in the catalog at ${getCatalogUrl()}.`);
+    }
+    const range = opts.semver;
+    const matching = range
+        ? entry.versions.filter((v) => {
+            try {
+                return (0, semver_1.satisfies)(v.version, range);
+            }
+            catch {
+                return false;
+            }
+        })
+        : [...entry.versions];
+    if (matching.length === 0) {
+        const available = entry.versions.map((v) => v.version).join(', ') || '(none published)';
+        throw new AppNotFoundError(`App "${name}" has no version matching "${range ?? '*'}". ` +
+            `Published versions: ${available}.`);
+    }
+    matching.sort((a, b) => (0, semver_1.rcompare)(a.version, b.version));
+    return matching[0];
+}
+// ── Byte helpers ───────────────────────────────────────────────────
+function base64ToBytes(b64) {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/**
+ * Coerce a `Uint8Array` whose underlying buffer is `ArrayBufferLike`
+ * (could be SharedArrayBuffer-backed) into a fresh `ArrayBuffer` copy.
+ * WebCrypto's typed signature rejects `SharedArrayBuffer`-backed inputs.
+ */
+function toArrayBuffer(view) {
+    const buf = new ArrayBuffer(view.byteLength);
+    new Uint8Array(buf).set(view);
+    return buf;
+}
+//# sourceMappingURL=bundle.js.map

package/dist/bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.js","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"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"}

package/dist/cancellable-fetch.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `cancellableFetch(url, init, opts)` — Effection-native HTTP with
+ * scope-linked cancellation and a deadline timeout.
+ *
+ * Wraps the global `fetch` so:
+ *
+ * 1. **Outer-scope halt aborts the in-flight request.** The Effection
+ *    `useAbortSignal()` returns a signal linked to the current scope;
+ *    when the scope halts (because a containing operation throws,
+ *    `race` chose another leg, the harness is cancelled, etc.) the
+ *    signal aborts and the underlying socket closes. The fetch is
+ *    *genuinely* cancelled — not abandoned.
+ *
+ * 2. **Timeout aborts the in-flight request.** A second leg sleeps for
+ *    `opts.timeoutMs` and throws on completion. `race` halts whichever
+ *    leg loses, propagating the abort the same way an outer halt does.
+ *
+ * Three current/planned consumers route through this primitive:
+ *
+ * - `@lloyal-labs/web-app/src/tools/fetch-page.ts` (post-migration —
+ *   replaces raw `AbortController` + `setTimeout`, closes the latent
+ *   socket-leak bug where a halted pool kept fetch-page sockets open).
+ * - `@lloyal-labs/web-app/src/tools/keyless-search.ts` (post-migration
+ *   — replaces the private `fetchWithTimeout` from which this primitive
+ *   was lifted; zero behavior change, just consolidation).
+ * - `@lloyal-labs/rig/src/bundle.ts` (`resolveAppEntry`) — fetches the
+ *   signed catalog via `cancellableFetch` so a halted scope during
+ *   resolution tears down cleanly. Used by `harness.dev install` to
+ *   resolve names against the canonical channel.
+ *
+ * Third-party apps SHOULD use `cancellableFetch` for any HTTP they do
+ * under structured concurrency, rather than reinventing the
+ * `race + useAbortSignal` pattern.
+ *
+ * @packageDocumentation
+ * @category Contract
+ */
+import type { Operation } from 'effection';
+/**
+ * Options accepted by {@link cancellableFetch}.
+ */
+export interface CancellableFetchOptions {
+    /**
+     * Maximum time in milliseconds before the fetch is aborted with a
+     * {@link FetchTimeoutError}. Default: 30000 (30 seconds). Set to
+     * `Infinity` to disable the timeout (cancellation via outer scope
+     * still works).
+     */
+    timeoutMs?: number;
+    /**
+     * Inject a non-default `fetch` implementation for testing or for
+     * harnesses that proxy network access. Defaults to the global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Thrown when the timeout leg of `cancellableFetch` wins the race.
+ * Distinct from generic `Error` so consumers can catch only the
+ * timeout case (e.g., to retry with a longer timeout) without also
+ * catching network-layer errors thrown from the fetch leg.
+ */
+export declare class FetchTimeoutError extends Error {
+    constructor(url: string, timeoutMs: number);
+}
+/**
+ * Fetch a URL with Effection-scope-linked cancellation and a timeout.
+ *
+ * @param url - The URL to fetch.
+ * @param init - Standard `RequestInit` options. `init.signal` is *replaced*
+ *   by the Effection-scope-linked signal; callers cannot pass their own
+ *   AbortController. (If you want to compose with an external abort
+ *   source, do it at the outer-scope level — halting the outer scope
+ *   propagates here.)
+ * @param opts - Timeout + injection knobs.
+ * @returns The `Response` object — unread. Callers `yield* call(() => res.text())`
+ *   etc. as appropriate to their use case.
+ *
+ * @throws {FetchTimeoutError} If the timeout leg wins.
+ * @throws Network-layer errors thrown by the underlying `fetch` (e.g., DNS
+ *   resolution failure, TLS error, socket reset). When the abort signal
+ *   fires, `fetch` throws a `DOMException` with `name === 'AbortError'` —
+ *   distinguishable from real network errors by that name.
+ *
+ * **Body buffering.** The returned `Response`'s body is **fully buffered
+ * in memory** before the function returns; the caller may safely call
+ * `.text()` / `.json()` / `.arrayBuffer()` on it without further async
+ * coordination. This is load-bearing: the underlying `useAbortSignal()`
+ * aborts when the http leg's scope unwinds (after `race` resolves),
+ * which would otherwise cause the caller's body-read to throw
+ * `AbortError` mid-flight (the body is still bound to the request's
+ * signal in undici). Pre-consuming inside the http leg, before the
+ * signal aborts, sidesteps that interaction. Cost: streaming is not
+ * supported — all responses are fully resident before return. Acceptable
+ * for the consumers we have (catalog JSON, manifest JSON, signed
+ * bundles up to a few hundred KB).
+ */
+export declare function cancellableFetch(url: string, init?: RequestInit, opts?: CancellableFetchOptions): Operation<Response>;
+//# sourceMappingURL=cancellable-fetch.d.ts.map

package/dist/cancellable-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancellable-fetch.d.ts","sourceRoot":"","sources":["../src/cancellable-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAG3C;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAI3C;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAiB,gBAAgB,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,IAAI,CAAC,EAAE,uBAAuB,GAC7B,SAAS,CAAC,QAAQ,CAAC,CAwCrB"}