@mearl/preset 0.0.0-stage → 3.0.0-beta.1

package/dist/bundle.js

@@ -0,0 +1,219 @@
+import { satisfies, valid, validRange } from 'semver';
+import { clonePresetDefaults } from './manifest.js';
+export const MAX_BUNDLE_BYTES = 16 * 1024 * 1024;
+export const MAX_BUNDLE_MANIFEST_BYTES = 64 * 1024;
+export const MAX_BROWSER_STORAGE_BYTES = 64 * 1024 * 1024;
+export const MAX_PAGE_RUNTIME_BYTES = 2 * 1024 * 1024;
+export const MAX_REQUEST_UI_BYTES = 64 * 1024;
+export class BundleError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.name = 'BundleError';
+    }
+}
+function invalid(message) {
+    throw new BundleError('BUNDLE_INVALID', message);
+}
+function fields(value, names) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) ||
+        Object.keys(value).some(key => !names.includes(key)))
+        invalid('Unexpected manifest structure');
+}
+function path(value) {
+    if (!/^[a-zA-Z0-9_][a-zA-Z0-9_./-]{0,255}$/.test(value) ||
+        value.split('/').some(segment => !segment || segment === '.' || segment === '..')) {
+        invalid('Resource paths must stay inside the bundle directory');
+    }
+}
+export function bundleSourceUrl(source) {
+    try {
+        const url = new URL(source);
+        if (!['https:', 'http:', 'file:'].includes(url.protocol) || url.username || url.password)
+            invalid('Invalid bundle source');
+        url.hash = '';
+        return url.href;
+    }
+    catch {
+        invalid('Expected an absolute HTTP(S)/file bundle source without credentials');
+    }
+}
+export function validateBundleManifest(value, mearlApiVersion) {
+    let json;
+    try {
+        json = clonePresetDefaults(value);
+    }
+    catch {
+        invalid('Expected a JSON manifest');
+    }
+    fields(json, ['schemaVersion', 'id', 'version', 'requires', 'resources', 'contributions']);
+    if (json.schemaVersion !== 1 || typeof json.id !== 'string' || !/^[a-z][a-z0-9-]{0,79}$/.test(json.id))
+        invalid('Invalid bundle identity');
+    if (typeof json.version !== 'string' || valid(json.version) !== json.version)
+        invalid('Expected an exact bundle version');
+    if (valid(mearlApiVersion) !== mearlApiVersion)
+        invalid('Expected an exact host API version');
+    if (json.requires !== undefined) {
+        fields(json.requires, ['mearlApi']);
+        const requirement = json.requires.mearlApi;
+        if (typeof requirement !== 'string' || !requirement.trim() || validRange(requirement) === null)
+            invalid('Invalid host API requirement');
+        if (!satisfies(mearlApiVersion, requirement))
+            throw new BundleError('BUNDLE_INCOMPATIBLE', `Requires host API ${requirement}`);
+    }
+    if (!json.resources || typeof json.resources !== 'object' || Array.isArray(json.resources))
+        invalid('Expected a resource map');
+    const resources = Object.entries(json.resources);
+    if (!resources.length || resources.length > 64)
+        invalid('A bundle requires 1–64 resources');
+    let total = 0;
+    for (const [name, resource] of resources) {
+        path(name);
+        fields(resource, ['sha256', 'byteLength']);
+        if (typeof resource.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(resource.sha256) ||
+            typeof resource.byteLength !== 'number' || !Number.isSafeInteger(resource.byteLength) || resource.byteLength < 0)
+            invalid('Invalid resource metadata');
+        total += resource.byteLength;
+        if (total > MAX_BUNDLE_BYTES)
+            throw new BundleError('BUNDLE_QUOTA', 'Bundle resources exceed 16 MiB');
+    }
+    if (json.contributions !== undefined) {
+        fields(json.contributions, ['appProfiles', 'pageRuntimes', 'nodeRuntimes', 'browserRuntimes', 'requestUi', 'browserViews']);
+        if (json.contributions.requestUi !== undefined && (typeof json.contributions.requestUi !== 'string' || !Object.hasOwn(json.resources, json.contributions.requestUi)))
+            invalid('Request UI must reference a declared resource');
+        if (typeof json.contributions.requestUi === 'string' && json.resources[json.contributions.requestUi].byteLength > MAX_REQUEST_UI_BYTES)
+            throw new BundleError('BUNDLE_QUOTA', 'Request UI exceeds 64 KiB');
+        if (json.contributions.browserViews !== undefined) {
+            fields(json.contributions.browserViews, ['requestImport', 'requestCases', 'captureLauncher', 'captureController']);
+            for (const resource of Object.values(json.contributions.browserViews)) {
+                if (typeof resource !== 'string' || !Object.hasOwn(json.resources, resource))
+                    invalid('Browser views must reference declared resources');
+                if (json.resources[resource].byteLength > MAX_REQUEST_UI_BYTES)
+                    throw new BundleError('BUNDLE_QUOTA', 'Browser view definition exceeds 64 KiB');
+            }
+        }
+        const profiles = json.contributions.appProfiles;
+        if (!Array.isArray(profiles) || profiles.some(name => typeof name !== 'string' || !Object.hasOwn(json.resources, name)) ||
+            new Set(profiles).size !== profiles.length)
+            invalid('App profiles must reference distinct declared resources');
+        const runtimes = json.contributions.pageRuntimes;
+        if (runtimes !== undefined) {
+            if (!runtimes || typeof runtimes !== 'object' || Array.isArray(runtimes) || Object.entries(runtimes).some(([id, name]) => !/^[a-z][a-z0-9-]{0,79}$/.test(id) || typeof name !== 'string' || !Object.hasOwn(json.resources, name)))
+                invalid('Page runtimes must reference declared resources');
+            for (const name of Object.values(runtimes)) {
+                const resource = json.resources[name];
+                if (resource.byteLength > MAX_PAGE_RUNTIME_BYTES)
+                    throw new BundleError('BUNDLE_QUOTA', 'Page runtime exceeds 2 MiB');
+            }
+        }
+        for (const kind of ['nodeRuntimes', 'browserRuntimes']) {
+            const runtimes = json.contributions[kind];
+            const label = kind === 'nodeRuntimes' ? 'Node' : 'Browser';
+            if (runtimes === undefined)
+                continue;
+            if (!runtimes || typeof runtimes !== 'object' || Array.isArray(runtimes) || Object.keys(runtimes).length > 16)
+                invalid(`Invalid ${label} runtime declarations`);
+            for (const [host, declaration] of Object.entries(runtimes)) {
+                if (!/^[a-z][a-z0-9-]{0,79}$/.test(host))
+                    invalid(`Invalid ${label} runtime host`);
+                fields(declaration, ['entry', 'bindings']);
+                if (typeof declaration.entry !== 'string' || !Object.hasOwn(json.resources, declaration.entry) || !declaration.entry.endsWith('.cjs'))
+                    invalid(`${label} runtime entry must reference a declared CommonJS resource`);
+                if (!declaration.bindings || typeof declaration.bindings !== 'object' || Array.isArray(declaration.bindings) || Object.keys(declaration.bindings).length > 256 || Object.entries(declaration.bindings).some(([hook, handler]) => !/^[a-z][a-zA-Z0-9_.-]{0,127}$/.test(hook) || typeof handler !== 'string' || !/^[a-z][a-zA-Z0-9_.-]{0,127}$/.test(handler)))
+                    invalid(`Invalid ${label} runtime bindings`);
+            }
+        }
+    }
+    if (new TextEncoder().encode(JSON.stringify(json)).byteLength > MAX_BUNDLE_MANIFEST_BYTES)
+        throw new BundleError('BUNDLE_QUOTA', 'Manifest exceeds 64 KiB');
+    return json;
+}
+export async function bundleDigest(bytes) {
+    const digest = await crypto.subtle.digest('SHA-256', Uint8Array.from(bytes).buffer);
+    return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('');
+}
+async function manifestRevision(source, manifest) {
+    return bundleDigest(new TextEncoder().encode(JSON.stringify({ source, manifest })));
+}
+export function readBundleJson(bundle, name) {
+    if (!Object.hasOwn(bundle.resources, name))
+        invalid('Bundle resource is unavailable');
+    try {
+        return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bundle.resources[name]));
+    }
+    catch {
+        invalid('Expected a UTF-8 JSON resource');
+    }
+}
+export function readBundleText(bundle, name) {
+    if (!Object.hasOwn(bundle.resources, name))
+        invalid('Bundle resource is unavailable');
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bundle.resources[name]);
+    }
+    catch {
+        invalid('Expected a UTF-8 text resource');
+    }
+}
+export async function prepareBundle(source, options) {
+    options.signal?.throwIfAborted();
+    source = bundleSourceUrl(source);
+    if (options.version !== undefined && (!options.version.trim() || validRange(options.version) === null))
+        invalid('Invalid requested bundle version');
+    const bytes = Uint8Array.from(await options.load(source, { maxBytes: MAX_BUNDLE_MANIFEST_BYTES, signal: options.signal }));
+    options.signal?.throwIfAborted();
+    if (bytes.byteLength > MAX_BUNDLE_MANIFEST_BYTES)
+        throw new BundleError('BUNDLE_QUOTA', 'Manifest exceeds 64 KiB');
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        invalid('Expected a UTF-8 JSON manifest');
+    }
+    const manifest = validateBundleManifest(value, options.mearlApiVersion);
+    if (manifest.id !== options.expectedId)
+        invalid('Bundle identity does not match the requested package');
+    if (options.version && !satisfies(manifest.version, options.version))
+        throw new BundleError('BUNDLE_INCOMPATIBLE', 'Bundle version does not satisfy the requested range');
+    const resources = {};
+    for (const [name, expected] of Object.entries(manifest.resources)) {
+        options.signal?.throwIfAborted();
+        const resource = Uint8Array.from(await options.load(new URL(name, source).href, { maxBytes: expected.byteLength, signal: options.signal }));
+        options.signal?.throwIfAborted();
+        if (resource.byteLength !== expected.byteLength || await bundleDigest(resource) !== expected.sha256) {
+            throw new BundleError('BUNDLE_INTEGRITY', `Resource integrity check failed: ${name}`);
+        }
+        resources[name] = resource;
+    }
+    options.signal?.throwIfAborted();
+    return { source, manifest, revision: await manifestRevision(source, manifest), resources };
+}
+/** Revalidates persisted snapshots without network access and returns independent resource buffers. */
+export async function verifyBundle(bundle, mearlApiVersion) {
+    const source = bundleSourceUrl(bundle.source);
+    const manifest = validateBundleManifest(bundle.manifest, mearlApiVersion);
+    const revision = bundle.revision;
+    if (!bundle.resources || typeof bundle.resources !== 'object' ||
+        Object.keys(bundle.resources).length !== Object.keys(manifest.resources).length)
+        invalid('Stored resource set does not match the manifest');
+    const resources = {};
+    for (const [name, expected] of Object.entries(manifest.resources)) {
+        const original = bundle.resources[name];
+        if (!(original instanceof Uint8Array))
+            throw new BundleError('BUNDLE_INTEGRITY', 'Stored resource is not a byte buffer');
+        const bytes = Uint8Array.from(original);
+        if (bytes.byteLength !== expected.byteLength) {
+            throw new BundleError('BUNDLE_INTEGRITY', `Stored resource integrity check failed: ${name}`);
+        }
+        resources[name] = bytes;
+    }
+    if (await manifestRevision(source, manifest) !== revision)
+        throw new BundleError('BUNDLE_INTEGRITY', 'Stored manifest revision does not match');
+    for (const [name, expected] of Object.entries(manifest.resources)) {
+        if (await bundleDigest(resources[name]) !== expected.sha256)
+            throw new BundleError('BUNDLE_INTEGRITY', `Stored resource integrity check failed: ${name}`);
+    }
+    return { source, manifest, revision, resources };
+}

package/dist/bundleFetch.d.ts

@@ -0,0 +1,6 @@
+import { type BundleLoader } from './bundle.js';
+/** Source trust and browser host permission checks belong to the caller's fetch implementation. */
+export declare function createBundleFetchLoader(options?: {
+    fetch?: typeof fetch;
+    credentials?: RequestCredentials;
+}): BundleLoader;

package/dist/bundleFetch.js

@@ -0,0 +1,42 @@
+import { BundleError } from './bundle.js';
+/** Source trust and browser host permission checks belong to the caller's fetch implementation. */
+export function createBundleFetchLoader(options = {}) {
+    return async (source, { maxBytes, signal }) => {
+        const response = await (options.fetch ?? fetch)(source, {
+            credentials: options.credentials ?? 'omit', redirect: 'error', cache: 'no-store', signal,
+        });
+        if (!response.ok || response.redirected)
+            throw new BundleError('BUNDLE_INVALID', 'Bundle download failed or redirected');
+        if (!response.body)
+            return new Uint8Array();
+        const reader = response.body.getReader();
+        const chunks = [];
+        let total = 0;
+        try {
+            while (true) {
+                signal?.throwIfAborted();
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                total += value.byteLength;
+                if (total > maxBytes)
+                    throw new BundleError('BUNDLE_QUOTA', 'Download exceeds its declared size limit');
+                chunks.push(value.slice());
+            }
+        }
+        catch (error) {
+            await reader.cancel().catch(() => { });
+            throw error;
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const bytes = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return bytes;
+    };
+}

package/dist/bundleStore.d.ts

@@ -0,0 +1,70 @@
+import { type PreparedBundle } from './bundle.js';
+import { type BrowserPresetSnapshot } from './browserPreset.js';
+import type { JsonObject } from './types.js';
+export interface BrowserPresetInstallation {
+    revision: string;
+    browserRevision: string;
+    overrides: JsonObject;
+}
+export declare class BrowserBundleStore {
+    private readonly options;
+    private database?;
+    constructor(options: {
+        mearlApiVersion: string;
+        databaseName?: string;
+        indexedDB?: IDBFactory;
+    });
+    private open;
+    close(): Promise<void>;
+    private records;
+    get(id: string): Promise<PreparedBundle | undefined>;
+    private verified;
+    list(): Promise<{
+        bundles: PreparedBundle[];
+        errors: {
+            id: string;
+            error: string;
+        }[];
+        activation: {
+            snapshot: BrowserPresetSnapshot;
+            preset: import("./types.js").ResolvedPreset;
+        } | undefined;
+        activationError: string | undefined;
+        installation: BrowserPresetInstallation | undefined;
+        installationError: string | undefined;
+        installationToken: string | null;
+        activeRevision: string | null;
+        revisions: {
+            [k: string]: string;
+        };
+    }>;
+    activePreset(): Promise<{
+        snapshot: BrowserPresetSnapshot;
+        preset: import("./types.js").ResolvedPreset;
+    } | undefined>;
+    /** Verified browser modules remain addressable while a bound document retains them. */
+    browserRuntimeBytes(sha256: string): Promise<Uint8Array>;
+    /** Content-addressed code survives package updates so pinned documents can still navigate. */
+    pageRuntimeSource(sha256: string): Promise<string>;
+    pinPageRuntimes(patch: Record<string, string | null>): Promise<void>;
+    /** Hosts rebuild these references from their authoritative session state after restart. */
+    synchronizePageRuntimePins(pins: Record<string, string>): Promise<void>;
+    private updateRuntimePins;
+    /** Pins the verified selection while reading its package from the same IndexedDB snapshot. */
+    profileBinding(name: string): Promise<{
+        target: string;
+        bundle: PreparedBundle;
+    } | undefined>;
+    /** Packages and the exact preset graph become visible together, after host contribution checks. */
+    activatePreset(input: BrowserPresetSnapshot, replacements: Array<{
+        bundle: PreparedBundle;
+        expectedRevision: string | null;
+    }>, expectedRevision: string | null, association?: {
+        installation?: BrowserPresetInstallation;
+        expectedInstallationToken: string | null;
+    }, expectedBundleRevisions?: Record<string, string>): Promise<void>;
+    /** Verifies all resources before a compare-and-swap transaction replaces the active snapshot. */
+    install(bundle: PreparedBundle, expectedRevision: string | null, expectedBundleRevisions?: Record<string, string>): Promise<void>;
+    remove(id: string, expectedRevision: string): Promise<void>;
+    private change;
+}