sh3-core 0.6.0

package/dist/registry/installer.js

@@ -0,0 +1,168 @@
+/**
+ * Package installer -- coordinates storing, loading, and registering packages.
+ *
+ * This is the bridge between the store shard (which fetches and verifies
+ * bundles) and the framework (which registers shards/apps). The install API
+ * is host-only; shards and apps must not import from here.
+ *
+ * Flow:
+ *   1. `installPackage(bundle, meta)` -- load module from bytes, verify
+ *      declared type matches actual type, persist to IndexedDB, register
+ *      with framework.
+ *   2. `uninstallPackage(id)` -- deactivate if active, remove from storage.
+ *   3. `loadInstalledPackages()` -- called at boot, re-loads all installed
+ *      packages from IndexedDB and registers them.
+ */
+import { loadBundleModule } from './loader';
+import { savePackage, loadBundle, listInstalled, removePackage } from './storage';
+import { verifyIntegrity } from './integrity';
+import { registerShard, deactivateShard } from '../shards/activate.svelte';
+import { registerApp } from '../apps/registry.svelte';
+/**
+ * Install a package from raw bundle bytes and metadata.
+ *
+ * Loads the ESM module, verifies the declared type matches the actual module
+ * shape, persists to IndexedDB, and registers with the framework. If
+ * registration fails (e.g. duplicate id from a shard that was already
+ * glob-discovered), the package is still persisted but `hotLoaded` is false.
+ *
+ * @param bundle - Raw verified ESM bundle bytes.
+ * @param meta - Provenance metadata for the install record.
+ * @returns Result object indicating success/failure and hot-load status.
+ */
+export async function installPackage(bundle, meta) {
+    // 1. Verify bundle integrity before executing any code.
+    try {
+        await verifyIntegrity(bundle, meta.integrity);
+    }
+    catch (err) {
+        return {
+            success: false,
+            hotLoaded: false,
+            error: `Integrity check failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // 2. Load the module from verified bytes.
+    let loaded;
+    try {
+        loaded = await loadBundleModule(bundle);
+    }
+    catch (err) {
+        return {
+            success: false,
+            hotLoaded: false,
+            error: `Failed to load bundle: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // 3. Verify the bundle contains the declared type.
+    if (meta.type === 'shard' && loaded.shards.length === 0) {
+        return {
+            success: false,
+            hotLoaded: false,
+            error: `Package "${meta.id}" declared type "shard" but bundle contains no valid shard`,
+        };
+    }
+    if (meta.type === 'app' && loaded.apps.length === 0) {
+        return {
+            success: false,
+            hotLoaded: false,
+            error: `Package "${meta.id}" declared type "app" but bundle contains no valid app`,
+        };
+    }
+    // 4. Persist to IndexedDB.
+    const record = {
+        id: meta.id,
+        type: meta.type,
+        version: meta.version,
+        sourceRegistry: meta.sourceRegistry,
+        contractVersion: meta.contractVersion,
+        installedAt: new Date().toISOString(),
+    };
+    try {
+        await savePackage(meta.id, bundle, record);
+    }
+    catch (err) {
+        return {
+            success: false,
+            hotLoaded: false,
+            error: `Failed to persist package: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // 5. Register all shards and apps from the bundle.
+    let hotLoaded = true;
+    try {
+        for (const shard of loaded.shards)
+            registerShard(shard);
+        for (const app of loaded.apps)
+            registerApp(app);
+    }
+    catch (err) {
+        console.warn(`[sh3] Package "${meta.id}" installed but registration failed (will retry on next boot):`, err instanceof Error ? err.message : err);
+        hotLoaded = false;
+    }
+    return { success: true, package: record, hotLoaded };
+}
+/**
+ * Uninstall a package by id.
+ *
+ * If the package is a shard and currently active, deactivates it first.
+ * Removes both the bundle and metadata from IndexedDB.
+ *
+ * @param id - The package id to uninstall.
+ */
+export async function uninstallPackage(id) {
+    // Attempt deactivation (no-op if not active or not a shard).
+    try {
+        deactivateShard(id);
+    }
+    catch (_a) {
+        // Ignore -- may not be a shard, or may not be active.
+    }
+    await removePackage(id);
+}
+/**
+ * List all installed packages.
+ *
+ * Delegates directly to the storage layer. Returns metadata records only,
+ * not the bundle bytes.
+ */
+export async function listInstalledPackages() {
+    return listInstalled();
+}
+/**
+ * Load all installed packages from IndexedDB and register them.
+ *
+ * Called once at boot by `bootstrap()`, before any glob-discovered shards
+ * or the shell shard are registered. Individual package failures are logged
+ * as warnings but do not prevent the shell from booting.
+ */
+export async function loadInstalledPackages() {
+    let packages;
+    try {
+        packages = await listInstalled();
+    }
+    catch (err) {
+        console.warn('[sh3] Failed to read installed packages from storage:', err instanceof Error ? err.message : err);
+        return;
+    }
+    for (const pkg of packages) {
+        try {
+            const bytes = await loadBundle(pkg.id);
+            if (!bytes) {
+                console.warn(`[sh3] No bundle found for installed package "${pkg.id}", skipping`);
+                continue;
+            }
+            const loaded = await loadBundleModule(bytes);
+            for (const shard of loaded.shards)
+                registerShard(shard);
+            for (const app of loaded.apps)
+                registerApp(app);
+            if (loaded.shards.length === 0 && loaded.apps.length === 0) {
+                console.warn(`[sh3] Package "${pkg.id}" contains no valid shards or apps, skipping`);
+            }
+        }
+        catch (err) {
+            console.warn(`[sh3] Failed to load installed package "${pkg.id}":`, err instanceof Error ? err.message : err);
+        }
+    }
+}

package/dist/registry/integrity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * SRI integrity verification for downloaded bundles.
+ *
+ * Uses the Web Crypto API (available in browsers and Tauri WebView).
+ * Accepts "sha384-<base64>" format matching the W3C SRI spec.
+ * See: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
+ */
+/**
+ * Verify that `data` matches the expected SRI integrity string.
+ *
+ * Uses the Web Crypto API to compute the digest and compares it against the
+ * base64 hash in `integrity`. Throws with a descriptive message on any
+ * mismatch, invalid format, or unsupported algorithm.
+ *
+ * @param data - Raw bytes of the downloaded bundle.
+ * @param integrity - SRI hash string, e.g. `"sha384-abc123..."`.
+ * @returns Resolves on success; throws on mismatch or bad format.
+ * @throws If the format is invalid, the algorithm is unsupported, or the hash does not match.
+ */
+export declare function verifyIntegrity(data: ArrayBuffer, integrity: string): Promise<void>;
+/**
+ * Compute an SRI hash for the given data.
+ *
+ * Useful for publishing tools that need to generate the `integrity` field
+ * for a `registry.json` entry. Defaults to `sha384`, which is the recommended
+ * algorithm for the SH3 registry protocol.
+ *
+ * @param data - Raw bytes of the bundle to hash.
+ * @param algorithm - Hash algorithm to use. Defaults to `"sha384"`.
+ * @returns SRI string in the form `"<algorithm>-<base64hash>"`.
+ */
+export declare function computeIntegrity(data: ArrayBuffer, algorithm?: 'sha256' | 'sha384' | 'sha512'): Promise<string>;

package/dist/registry/integrity.js

@@ -0,0 +1,92 @@
+/**
+ * SRI integrity verification for downloaded bundles.
+ *
+ * Uses the Web Crypto API (available in browsers and Tauri WebView).
+ * Accepts "sha384-<base64>" format matching the W3C SRI spec.
+ * See: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
+ */
+const SUPPORTED_ALGORITHMS = ['sha256', 'sha384', 'sha512'];
+/**
+ * Parse an SRI integrity string into its algorithm and base64 hash components.
+ *
+ * @param integrity - SRI string in the form `"<algorithm>-<base64hash>"`.
+ * @returns Object with `algorithm` and `hash` fields.
+ * @throws If the format is invalid or the algorithm is not supported.
+ */
+function parseSri(integrity) {
+    const dashIndex = integrity.indexOf('-');
+    if (dashIndex === -1) {
+        throw new Error(`Invalid SRI format: ${integrity}`);
+    }
+    const algorithm = integrity.slice(0, dashIndex);
+    const hash = integrity.slice(dashIndex + 1);
+    if (!SUPPORTED_ALGORITHMS.includes(algorithm)) {
+        throw new Error(`Unsupported SRI algorithm: ${algorithm}. Supported: ${SUPPORTED_ALGORITHMS.join(', ')}`);
+    }
+    if (!hash) {
+        throw new Error(`Empty hash in SRI: ${integrity}`);
+    }
+    return { algorithm, hash };
+}
+/**
+ * Map an SRI algorithm name to its Web Crypto API equivalent.
+ *
+ * @param alg - SRI algorithm name (`"sha256"`, `"sha384"`, `"sha512"`).
+ * @returns Web Crypto algorithm name (e.g. `"SHA-384"`).
+ */
+function algorithmToWebCrypto(alg) {
+    return `SHA-${alg.slice(3)}`;
+}
+/**
+ * Encode an `ArrayBuffer` as a base64 string.
+ *
+ * @param buffer - Raw bytes to encode.
+ * @returns Base64 string representation of `buffer`.
+ */
+function bufferToBase64(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/**
+ * Verify that `data` matches the expected SRI integrity string.
+ *
+ * Uses the Web Crypto API to compute the digest and compares it against the
+ * base64 hash in `integrity`. Throws with a descriptive message on any
+ * mismatch, invalid format, or unsupported algorithm.
+ *
+ * @param data - Raw bytes of the downloaded bundle.
+ * @param integrity - SRI hash string, e.g. `"sha384-abc123..."`.
+ * @returns Resolves on success; throws on mismatch or bad format.
+ * @throws If the format is invalid, the algorithm is unsupported, or the hash does not match.
+ */
+export async function verifyIntegrity(data, integrity) {
+    const { algorithm, hash: expectedHash } = parseSri(integrity);
+    const webCryptoAlg = algorithmToWebCrypto(algorithm);
+    const digest = await crypto.subtle.digest(webCryptoAlg, data);
+    const actualHash = bufferToBase64(digest);
+    if (actualHash !== expectedHash) {
+        throw new Error(`Integrity check failed for ${algorithm}. ` +
+            `Expected: ${expectedHash}, got: ${actualHash}`);
+    }
+}
+/**
+ * Compute an SRI hash for the given data.
+ *
+ * Useful for publishing tools that need to generate the `integrity` field
+ * for a `registry.json` entry. Defaults to `sha384`, which is the recommended
+ * algorithm for the SH3 registry protocol.
+ *
+ * @param data - Raw bytes of the bundle to hash.
+ * @param algorithm - Hash algorithm to use. Defaults to `"sha384"`.
+ * @returns SRI string in the form `"<algorithm>-<base64hash>"`.
+ */
+export async function computeIntegrity(data, algorithm = 'sha384') {
+    const webCryptoAlg = algorithmToWebCrypto(algorithm);
+    const digest = await crypto.subtle.digest(webCryptoAlg, data);
+    const hash = bufferToBase64(digest);
+    return `${algorithm}-${hash}`;
+}

package/dist/registry/loader.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Runtime loader -- loads a pre-built ESM bundle from raw bytes via blob URL.
+ *
+ * The install API hands us an ArrayBuffer (the verified bundle), we wrap it
+ * in a blob URL, dynamic-import it, then immediately revoke the URL so the
+ * blob can be GC'd. The module's default export must carry a `manifest`
+ * field; we use duck-typing to distinguish shards from apps.
+ *
+ * Bare specifier rewriting: bundles are built with external dependencies
+ * (`sh3`, `svelte`, `svelte/internal/client`, etc.). Blob URLs can't
+ * resolve bare specifiers, so we expose each dependency's runtime exports
+ * at a stable blob URL (a "shim") and rewrite bare specifiers in the
+ * bundle source before loading.
+ */
+import type { Shard } from '../shards/types';
+import type { App } from '../apps/types';
+/**
+ * Result of loading a bundle — may contain a shard, an app, or both.
+ * Combo bundles (one shard + its companion app) are a supported pattern.
+ */
+export interface LoadedBundle {
+    shards: Shard[];
+    apps: App[];
+}
+/**
+ * Load a pre-built ESM bundle from raw bytes.
+ *
+ * Scans all module exports (default + named) for objects with a `manifest`
+ * property and classifies each as a shard or app. Combo bundles that export
+ * both a shard and its companion app are supported.
+ *
+ * @param bytes - Raw bundle bytes (the verified ESM file contents).
+ * @returns All shards and apps found in the module's exports.
+ * @throws If the blob URL cannot be created or the import fails.
+ */
+export declare function loadBundleModule(bytes: ArrayBuffer): Promise<LoadedBundle>;
+/**
+ * Type guard: returns true if the loaded module is a shard.
+ *
+ * A shard has an `activate` function and `manifest.views` array. An app
+ * has neither — it has `initialLayout` and `manifest.requiredShards`.
+ */
+export declare function isShard(mod: Shard | App): mod is Shard;
+/**
+ * Type guard: returns true if the loaded module is an app.
+ *
+ * An app has `initialLayout` and `manifest.requiredShards`. A shard has
+ * `activate` and `manifest.views` instead.
+ */
+export declare function isApp(mod: Shard | App): mod is App;

package/dist/registry/loader.js

@@ -0,0 +1,145 @@
+/**
+ * Runtime loader -- loads a pre-built ESM bundle from raw bytes via blob URL.
+ *
+ * The install API hands us an ArrayBuffer (the verified bundle), we wrap it
+ * in a blob URL, dynamic-import it, then immediately revoke the URL so the
+ * blob can be GC'd. The module's default export must carry a `manifest`
+ * field; we use duck-typing to distinguish shards from apps.
+ *
+ * Bare specifier rewriting: bundles are built with external dependencies
+ * (`sh3`, `svelte`, `svelte/internal/client`, etc.). Blob URLs can't
+ * resolve bare specifiers, so we expose each dependency's runtime exports
+ * at a stable blob URL (a "shim") and rewrite bare specifiers in the
+ * bundle source before loading.
+ */
+import * as api from '../api';
+import * as svelte from 'svelte';
+// @ts-expect-error — svelte/internal/client has no public type declarations
+import * as svelteInternalClient from 'svelte/internal/client';
+// ---- shim infrastructure ---------------------------------------------------
+/**
+ * Create a blob URL that re-exports every runtime key from a module
+ * previously stashed on globalThis. The shim is created once and never
+ * revoked — it must outlive every bundle that references it.
+ */
+// JS reserved words that can't appear in destructuring or as bare export names.
+const RESERVED = new Set([
+    'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
+    'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false',
+    'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'let',
+    'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try',
+    'typeof', 'var', 'void', 'while', 'with', 'yield',
+]);
+function createShimUrl(globalKey, mod) {
+    const names = Object.keys(mod);
+    const safe = names.filter(n => !RESERVED.has(n));
+    const reserved = names.filter(n => RESERVED.has(n));
+    const lines = [`const __m__ = globalThis.${globalKey};`];
+    // Safe names can use destructuring.
+    if (safe.length > 0) {
+        lines.push(`export const { ${safe.join(', ')} } = __m__;`);
+    }
+    // Reserved words need individual re-exports via a renamed binding.
+    for (const name of reserved) {
+        lines.push(`const __r_${name}__ = __m__['${name}']; export { __r_${name}__ as ${name} };`);
+    }
+    lines.push(`export default __m__.default;`);
+    return URL.createObjectURL(new Blob([lines.join('\n')], { type: 'application/javascript' }));
+}
+// Expose modules on globalThis so shims can read them.
+const g = globalThis;
+g.__sh3__ = api;
+g.__sh3_svelte__ = svelte;
+g.__sh3_svelte_internal_client__ = svelteInternalClient;
+// Build shim URLs once at module load time.
+const shimUrls = {
+    'sh3-core': createShimUrl('__sh3__', api),
+    'svelte': createShimUrl('__sh3_svelte__', svelte),
+    'svelte/internal/client': createShimUrl('__sh3_svelte_internal_client__', svelteInternalClient),
+};
+// `svelte/internal/disclose-version` is a side-effect-only import (no exports).
+// Create an empty shim so the import doesn't fail.
+shimUrls['svelte/internal/disclose-version'] = URL.createObjectURL(new Blob([''], { type: 'application/javascript' }));
+// `sh3/tokens.css` — design tokens are already loaded by the host shell.
+// Bundles that import this path get a no-op so the import doesn't fail.
+shimUrls['sh3-core/tokens.css'] = URL.createObjectURL(new Blob([''], { type: 'application/javascript' }));
+// ---- bare specifier rewriting ----------------------------------------------
+/**
+ * Match bare specifier imports/re-exports:
+ *   from 'svelte/internal/client'
+ *   from "sh3-core"
+ *   import "svelte/internal/disclose-version"
+ *
+ * Captures the quote char and the specifier. Only rewrites specifiers
+ * that have a shim URL registered above.
+ */
+const BARE_IMPORT_RE = /(?:from|import)\s*(['"])(sh3-core(?:\/[^'"]*)?|svelte(?:\/[^'"]*)?)\1/g;
+function rewriteBareImports(source) {
+    return source.replace(BARE_IMPORT_RE, (match, _quote, specifier) => {
+        const shim = shimUrls[specifier];
+        if (!shim)
+            return match; // unknown specifier — leave as-is
+        // Preserve the keyword (from vs import) from the original match.
+        const keyword = match.startsWith('from') ? 'from' : 'import';
+        return `${keyword} '${shim}'`;
+    });
+}
+/**
+ * Load a pre-built ESM bundle from raw bytes.
+ *
+ * Scans all module exports (default + named) for objects with a `manifest`
+ * property and classifies each as a shard or app. Combo bundles that export
+ * both a shard and its companion app are supported.
+ *
+ * @param bytes - Raw bundle bytes (the verified ESM file contents).
+ * @returns All shards and apps found in the module's exports.
+ * @throws If the blob URL cannot be created or the import fails.
+ */
+export async function loadBundleModule(bytes) {
+    const source = new TextDecoder().decode(bytes);
+    const rewritten = rewriteBareImports(source);
+    const blob = new Blob([rewritten], { type: 'application/javascript' });
+    const url = URL.createObjectURL(blob);
+    try {
+        const mod = await import(/* @vite-ignore */ url);
+        const result = { shards: [], apps: [] };
+        for (const value of Object.values(mod)) {
+            if (!value || typeof value !== 'object' || !('manifest' in value)) {
+                continue;
+            }
+            const candidate = value;
+            if (isShard(candidate))
+                result.shards.push(candidate);
+            else if (isApp(candidate))
+                result.apps.push(candidate);
+        }
+        if (result.shards.length === 0 && result.apps.length === 0) {
+            throw new Error('Bundle has no exports with a "manifest" property — expected at least one shard or app');
+        }
+        return result;
+    }
+    finally {
+        URL.revokeObjectURL(url);
+    }
+}
+/**
+ * Type guard: returns true if the loaded module is a shard.
+ *
+ * A shard has an `activate` function and `manifest.views` array. An app
+ * has neither — it has `initialLayout` and `manifest.requiredShards`.
+ */
+export function isShard(mod) {
+    return ('activate' in mod &&
+        typeof mod.activate === 'function' &&
+        Array.isArray(mod.manifest.views));
+}
+/**
+ * Type guard: returns true if the loaded module is an app.
+ *
+ * An app has `initialLayout` and `manifest.requiredShards`. A shard has
+ * `activate` and `manifest.views` instead.
+ */
+export function isApp(mod) {
+    return ('initialLayout' in mod &&
+        Array.isArray(mod.manifest.requiredShards));
+}

package/dist/registry/schema.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Runtime validation for registry index JSON.
+ *
+ * No external schema library — plain runtime checks. The registry index
+ * is fetched from untrusted URLs so all fields are validated before any
+ * typed access occurs. Validation errors carry a JSON-path string so the
+ * caller can surface actionable diagnostics in the store UI.
+ *
+ * Usage:
+ * ```ts
+ * const raw = await response.json();
+ * const index = validateRegistryIndex(raw); // throws RegistryValidationError on bad input
+ * ```
+ */
+import type { RegistryIndex } from './types.js';
+/**
+ * Thrown when a registry index document fails validation.
+ *
+ * The `path` property is a JSON-path string pointing to the field that
+ * caused the failure (e.g. `"$.packages[2].versions[0].integrity"`).
+ * Consumers may display this directly in diagnostic/error UI.
+ */
+export declare class RegistryValidationError extends Error {
+    /**
+     * JSON-path of the failing field (e.g. `"$.packages[0].type"`).
+     */
+    readonly path: string;
+    /**
+     * @param path - JSON-path string of the failing field.
+     * @param message - Human-readable description of why validation failed.
+     */
+    constructor(path: string, message: string);
+}
+/**
+ * Validate an unknown value as a `RegistryIndex`.
+ *
+ * Performs a full deep validation of all required fields and their types.
+ * Returns a correctly typed `RegistryIndex` on success.
+ * Throws `RegistryValidationError` on the first validation failure.
+ *
+ * Call this immediately after `response.json()` before touching any field.
+ *
+ * @param data - The raw parsed JSON value from a registry fetch.
+ * @returns A fully validated `RegistryIndex`.
+ * @throws `RegistryValidationError` if any field is missing or has the wrong type.
+ */
+export declare function validateRegistryIndex(data: unknown): RegistryIndex;