@kubohiroya/turbowarp-extension-loader 0.4.0 → 0.5.1

package/dist/project-authoring.js

@@ -1,4 +1,4 @@
-import { LoaderError, validateManifest } from './index.js';
+import { isRemoteSource, LoaderError, validateManifest } from './index.js';
 import { createProjectIO } from './project-codec.js';
 import { readPreparedProject } from './project-data.js';
 import { collectVerifiedCodes } from './verified-code.js';
@@ -35,19 +35,19 @@ export async function prepareExtensionAddition(input, request, ports, { zip: Zip
         if (value !== undefined && (!Number.isSafeInteger(value) || value < 1))
             fail('INVALID_OPTIONS', `Invalid ${key}`);
     }
-    const source = plainObject(request.source) && request.source.type === 'embedded' && request.source.path === undefined ?
+    const source = plainObject(request.source) && request.source.type === 'embedded-file' && request.source.path === undefined ?
         { ...request.source, path: `extensions/${request.id}.js` } : request.source;
     // Reuse the runtime schema before any bytes are read or network requests begin.
     const draft = validateManifest({ schemaVersion: 1, extensions: [{ id: request.id, source,
                 execution: request.execution === undefined ? 'unsandboxed' : request.execution,
                 sha256: '0'.repeat(64) }] }, loaderOptions).extensions[0];
-    if (draft.source.type === 'remote' && request.bytes !== undefined)
+    if (isRemoteSource(draft.source) && request.bytes !== undefined)
         fail('INVALID_ADDITION', 'Remote sources must be fetched from their URL', draft.id);
     if (request.bytes instanceof Uint8Array && (request.bytes.byteLength < 1 || request.bytes.byteLength > limits.maxBytes)) {
         fail('INVALID_BYTES', 'Extension file is empty or exceeds the byte limit', draft.id);
     }
     const suppliedBytes = request.bytes instanceof Uint8Array ? new Uint8Array(request.bytes) : request.bytes;
-    if (draft.source.type === 'embedded' && !(suppliedBytes instanceof Uint8Array) && !(suppliedBytes instanceof Blob)) {
+    if (draft.source.type === 'embedded-file' && !(suppliedBytes instanceof Uint8Array) && !(suppliedBytes instanceof Blob)) {
         fail('INVALID_BYTES', 'Embedded additions require a JavaScript file', draft.id);
     }
     if (suppliedBytes instanceof Blob && (suppliedBytes.size < 1 || suppliedBytes.size > limits.maxBytes)) {
@@ -94,15 +94,18 @@ export async function prepareExtensionAddition(input, request, ports, { zip: Zip
         if (project.extensionURLs !== undefined && !plainObject(project.extensionURLs))
             fail('INVALID_PROJECT', 'Project extensionURLs must be an object');
         const previous = prepared.manifest?.extensions || [];
+        // Carried through every rebuild below: an address that changed when an extension was
+        // added would not be an address.
+        const carried = prepared.manifest?.uri === undefined ? {} : { uri: prepared.manifest.uri };
         if (previous.some(spec => spec.id === draft.id) || (project.extensions || []).includes(draft.id) ||
             Object.hasOwn(project.extensionURLs || {}, draft.id))
             fail('DUPLICATE_EXTENSION', 'This extension ID already belongs to the project', draft.id);
-        validateManifest({ schemaVersion: 1, extensions: [...previous, draft] }, loaderOptions);
-        if (draft.source.type === 'embedded' && Object.hasOwn(files, draft.source.path)) {
+        validateManifest({ schemaVersion: 1, ...carried, extensions: [...previous, draft] }, loaderOptions);
+        if (draft.source.type === 'embedded-file' && Object.hasOwn(files, draft.source.path)) {
             fail('SOURCE_PATH_COLLISION', 'The embedded path already exists in this project', draft.id);
         }
         let bytes;
-        if (draft.source.type === 'embedded') {
+        if (!isRemoteSource(draft.source)) {
             bytes = suppliedBytes instanceof Blob ? new Uint8Array(await wait(() => suppliedBytes.arrayBuffer())) : suppliedBytes;
         }
         else {
@@ -128,12 +131,12 @@ export async function prepareExtensionAddition(input, request, ports, { zip: Zip
         }
         const verified = new Uint8Array(bytes);
         const sha256 = await wait(() => digest(verified));
-        const manifest = validateManifest({ schemaVersion: 1, extensions: [...previous, { ...draft, sha256 }] }, loaderOptions);
+        const manifest = validateManifest({ schemaVersion: 1, ...carried, extensions: [...previous, { ...draft, sha256 }] }, loaderOptions);
         const spec = manifest.extensions.find(item => item.id === draft.id);
         project.turboWarpPlus = manifest;
         project.extensions = [...(project.extensions || []), spec.id];
         files['project.json'] = encoder.encode(JSON.stringify(project));
-        if (spec.source.type === 'embedded')
+        if (spec.source.type === 'embedded-file')
             files[spec.source.path] = verified;
         const archive = new Zip();
         for (const [path, content] of Object.entries(files))
@@ -143,7 +146,7 @@ export async function prepareExtensionAddition(input, request, ports, { zip: Zip
         io.activate(candidate.context);
         // Only the newly fetched URL is snapshotted. Other pinned sources keep the host's fetch policy.
         const pinned = spec.source;
-        const fetcher = pinned.type === 'remote' ? {
+        const fetcher = isRemoteSource(pinned) ? {
             fetch(url, options) {
                 if (url === pinned.url)
                     return Promise.resolve({ bytes: new Uint8Array(verified), finalURL: url, redirects: [] });
@@ -159,3 +162,62 @@ export async function prepareExtensionAddition(input, request, ports, { zip: Zip
         externalSignal?.removeEventListener('abort', abort);
     }
 }
+const UUIDV7 = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+/** Where an unchosen address is put, relative to whatever origin assigns it. */
+export const PROJECT_URI_PREFIX = 'turbowarp-plus-projects';
+/**
+ * A fresh identifier for one project: a UUID version 7.
+ *
+ * Version 7 and not 4 because the first 48 bits are the millisecond clock, so the identifier
+ * itself sorts by when the project was first saved. That costs nothing over a random UUID and
+ * leaves the ordering available to anything that wants it.
+ * @returns {string} The UUID, in the canonical lowercase form.
+ */
+export function createProjectUUID() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    const time = Date.now();
+    for (let index = 0; index < 6; index++)
+        bytes[index] = (time / 2 ** (8 * (5 - index))) & 0xff;
+    bytes[6] = 0x70 | (bytes[6] & 0x0f);
+    bytes[8] = 0x80 | (bytes[8] & 0x3f);
+    const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/**
+ * The address a project is given when its author has not chosen one.
+ *
+ * Every project needs an address from its first save, because that address is what identifies it:
+ * the browser's caches and the opener's recorded decisions are filed under it. Nothing is served
+ * there until the author actually publishes, and that is fine — the point is that the name does
+ * not have to change if they ever do.
+ *
+ * So this address is deliberately opaque. A readable one would be derived from the title and
+ * would change when the title changed, filing one work under a second name. Readability belongs
+ * to the deliberate act of publishing, where the author names the address themselves; a list that
+ * has to be read by a person shows the project's title beside this.
+ *
+ * The two directory levels divide the projects so that no single directory grows without bound,
+ * and they are taken from the **end** of the UUID. A version 7 UUID begins with the top of a
+ * millisecond clock, which barely moves, so sharding on its first characters would put every
+ * project ever created in one directory. The last characters are the random half.
+ * @param {string} origin Where the editor that assigns this is served from; it claims no other host.
+ * @param {string} uuid A version 7 UUID, from createProjectUUID.
+ * @returns {string} The absolute HTTPS address.
+ */
+export function defaultProjectURI(origin, uuid) {
+    if (!UUIDV7.test(uuid))
+        fail('INVALID_PROJECT_URI', 'A version 7 UUID is required');
+    let base;
+    try {
+        base = new URL(origin);
+    }
+    catch {
+        fail('INVALID_PROJECT_URI', 'An absolute origin is required');
+    }
+    if (base.protocol !== 'https:' || base.username || base.password) {
+        fail('INVALID_PROJECT_URI', 'A project origin must be HTTPS without credentials');
+    }
+    const tail = uuid.replaceAll('-', '').slice(-4);
+    const path = `${base.pathname.replace(/\/*$/, '')}/${PROJECT_URI_PREFIX}/${tail.slice(0, 2)}/${tail}/${uuid}.sb3`;
+    return new URL(path, base.origin).href;
+}

package/dist/project-catalog.d.ts

@@ -1,16 +1,19 @@
-import { type ExecutionMode, type LoaderOptions, type LoaderPorts, type Manifest } from './index.js';
+import { type ExecutionMode, type ExtensionSource, type LoaderOptions, type LoaderPorts, type Manifest } from './index.js';
 import { type ArchiveLimits, type ZipConstructor } from './project-codec.js';
 export interface CatalogExtensionRequest {
     id: string;
     url: string;
     /**
-     * Where the project keeps it: carrying the bytes, or only a reference.
+     * Which of the four forms the project keeps it in, as the author decided.
      *
-     * Either way the manifest records where the bytes came from, so a project that carries them
-     * can still recover if its retained copy is lost. There is deliberately no third value:
-     * where bytes are cached in the browser is the opener's decision, passed to `load()`.
+     * The same four names the manifest and the SB3 save format use, so this is the author's
+     * decision written once. Either reference form records the address; either embedded form
+     * records it too, beside the bytes, which is what keeps a path back to a reference open.
+     *
+     * Whether the person opening the project actually keeps a copy of a `remote-cacheable`
+     * extension is theirs to decline, through `declineCaching` on `load()`.
      */
-    distribution: 'embedded' | 'remote';
+    distribution: ExtensionSource['type'];
     execution: ExecutionMode;
     dependencies?: string[];
     version?: string;

package/dist/project-catalog.js

@@ -1,9 +1,17 @@
-import { LoaderError, validateManifest } from './index.js';
-import { createProjectIO } from './project-codec.js';
+import { isRemoteSource, LoaderError, validateManifest } from './index.js';
+import { createProjectIO, DATA_CARRIER_PREFIX } from './project-codec.js';
 import { readPreparedProject } from './project-data.js';
 import { collectVerifiedCodes } from './verified-code.js';
 import { DEFAULT_LOADER_LIMITS, DEFAULT_TOTAL_BYTES } from './limits.js';
 const encoder = new TextEncoder();
+// A standard TurboWarp host looks for a URL in the project document and knows nothing of this
+// manifest, so for that carrier the bytes have to be the address itself.
+const dataCarrier = (bytes) => {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return `${DATA_CARRIER_PREFIX}${btoa(binary)}`;
+};
 const digest = async (bytes) => Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)), value => value.toString(16).padStart(2, '0')).join('');
 function fail(code, message, id) { throw new LoaderError(code, message, id); }
 export async function readProjectAuthoringState(input, { zip, signal, archiveOptions } = {}) {
@@ -63,13 +71,16 @@ export async function prepareCatalogExtensionChanges(input, requests, ports, { z
     try {
         const seen = new Set();
         const choices = requests.map(request => {
-            if (!request || !['remote', 'embedded'].includes(request.distribution) || seen.has(request.id)) {
+            if (!request || !['remote-non-cacheable', 'remote-cacheable', 'embedded-file', 'embedded-data']
+                .includes(request.distribution) || seen.has(request.id)) {
                 fail('INVALID_ADDITION', 'Invalid or duplicate catalog selection', request?.id);
             }
             seen.add(request.id);
             const execution = request.execution;
             const spec = validateManifest({ schemaVersion: 1, extensions: [{ id: request.id,
-                        source: { type: 'remote', url: request.url }, execution, sha256: '0'.repeat(64),
+                        // Validated as a reference whatever the request asks for: this is only here to
+                        // put the URL and the execution mode through the schema before anything is read.
+                        source: { type: 'remote-cacheable', url: request.url }, execution, sha256: '0'.repeat(64),
                         ...(request.version ? { version: request.version } : {}) }] }, loaderOptions).extensions[0];
             if (request.dependencies !== undefined && (!Array.isArray(request.dependencies) ||
                 request.dependencies.some(id => typeof id !== 'string')))
@@ -116,24 +127,29 @@ export async function prepareCatalogExtensionChanges(input, requests, ports, { z
         }
         // Copies the replaced entries kept; released below unless a final entry still names them.
         const replacedPaths = new Set();
+        // Bytes for a data carrier, kept until the project document is written.
+        const carriers = new Map();
         for (const choice of choices) {
             const replaced = prepared.manifest?.extensions.find(spec => spec.id === choice.id)?.source;
-            if (replaced && replaced.type !== 'remote')
+            if (replaced?.type === 'embedded-file')
                 replacedPaths.add(replaced.path);
             const old = previous.get(choice.id);
-            // Every catalog request was validated as a Remote source above.
-            const bytes = old ? encoder.encode(old.code) : await fetchBytes(choice.source.url);
+            // Validated as a reference above, so it has an address to fetch and to record.
+            if (!isRemoteSource(choice.source))
+                fail('INVALID_ADDITION', 'A catalog request is a reference', choice.id);
+            const origin = choice.source.url;
+            const bytes = old ? encoder.encode(old.code) : await fetchBytes(origin);
             const sha256 = await wait(() => digest(bytes));
             if (old && old.sha256 !== sha256)
                 fail('CONVERSION_INTEGRITY', 'Source conversion changed bytes', choice.id);
             const retainedPath = `extensions/${choice.id}-${sha256}.js`;
-            // A catalog extension was fetched from an address, so embedding keeps that address
-            // beside the copy rather than discarding what is already known. Bytes nobody fetched —
-            // a costume, a sound, an extension written here — have no address to record, which is
-            // why a url is optional on an embedded source.
-            const source = choice.distribution === 'embedded' ?
-                { type: 'embedded', path: retainedPath, url: choice.source.url } :
-                choice.source;
+            // A catalog extension was fetched from an address, so either embedded form keeps that
+            // address beside the bytes rather than discarding what is already known. Bytes nobody
+            // fetched — a costume, a sound, an extension written here — have no address to record,
+            // which is why a url is optional on an embedded source.
+            const source = choice.distribution === 'embedded-file' ? { type: 'embedded-file', path: retainedPath, url: origin } :
+                choice.distribution === 'embedded-data' ? { type: 'embedded-data', url: origin } :
+                    { type: choice.distribution, url: origin };
             // A recorded URL is a promise about what it serves, so it must still serve exactly
             // the pinned bytes — whether it is the only place they live or sits beside a copy.
             if (source.url !== undefined) {
@@ -142,29 +158,40 @@ export async function prepareCatalogExtensionChanges(input, requests, ports, { z
                     fail('DIGEST_MISMATCH', 'Remote source does not serve the currently pinned bytes', choice.id);
                 }
             }
-            // An embedded choice retains a copy in the project.
-            if (source.type !== 'remote') {
+            // Only the file carrier has an archive entry; the data carrier is written below,
+            // into the project document, because that is where a standard host looks for it.
+            if (source.type === 'embedded-file') {
                 if (Object.hasOwn(files, source.path) && await wait(() => digest(files[source.path])) !== sha256) {
                     fail('SOURCE_PATH_COLLISION', 'The embedded path belongs to different content', choice.id);
                 }
                 files[source.path] = new Uint8Array(bytes);
             }
+            if (source.type === 'embedded-data')
+                carriers.set(choice.id, new Uint8Array(bytes));
             extensions.set(choice.id, { id: choice.id, source, execution: choice.execution, sha256,
                 ...((old?.version || choice.version) ? { version: old?.version || choice.version } : {}),
                 ...(old?.publisher ? { publisher: old.publisher } : {}),
                 capabilities: old?.capabilities || [], dependencies: choice.dependencies });
         }
-        const manifest = validateManifest({ schemaVersion: 1, extensions: [...extensions.values()] }, loaderOptions);
+        // The project's own address survives a change to its extensions. Rebuilding the manifest
+        // without it would file the same work under a new name the next time it was saved, which
+        // is the one thing an address is for.
+        const manifest = validateManifest({ schemaVersion: 1, ...(prepared.manifest?.uri === undefined ?
+                {} : { uri: prepared.manifest.uri }), extensions: [...extensions.values()] }, loaderOptions);
         for (const spec of manifest.extensions)
-            if (spec.source.type !== 'remote')
+            if (spec.source.type === 'embedded-file')
                 replacedPaths.delete(spec.source.path);
         for (const path of replacedPaths)
             delete files[path];
         project.turboWarpPlus = manifest;
         project.extensions = [...new Set([...(project.extensions || []), ...manifest.extensions.map(spec => spec.id)])];
         const urls = { ...(project.extensionURLs || {}) };
-        for (const spec of manifest.extensions)
-            delete urls[spec.id];
+        for (const spec of manifest.extensions) {
+            if (spec.source.type === 'embedded-data')
+                urls[spec.id] = dataCarrier(carriers.get(spec.id));
+            else
+                delete urls[spec.id];
+        }
         project.extensionURLs = urls;
         files['project.json'] = encoder.encode(JSON.stringify(project));
         const archive = new Zip();

package/dist/project-codec.d.ts

@@ -45,11 +45,17 @@ export interface ProjectIO {
             signal?: AbortSignal;
             maxBytes?: number;
         }): Promise<Uint8Array>;
+        readData(id: string, options?: {
+            signal?: AbortSignal;
+            maxBytes?: number;
+        }): Promise<Uint8Array>;
     };
     restoreJSON<T extends string | Record<string, unknown>>(json: T, context: ProjectContext | null): T;
     restoreFiles(files: Record<string, Uint8Array>, context: ProjectContext | null): Record<string, Uint8Array>;
     restoreArchive<T extends ZipArchive>(archive: T, context: ProjectContext | null): T;
 }
+/** The one carrier spelling this family writes, and the only one a standard host is given. */
+export declare const DATA_CARRIER_PREFIX = "data:text/javascript;base64,";
 /** Validate the central directory before JSZip normalizes paths or inflates data. */
 export declare function inspectZip(bytes: Uint8Array, options?: ArchiveLimits): Map<string, ZipEntryMetadata>;
 /** ZIP implementation is injected; all manifest/archive policy remains in the core. */

package/dist/project-codec.js

@@ -4,6 +4,8 @@ const DEFAULTS = Object.freeze({ maxArchiveBytes: DEFAULT_TOTAL_BYTES, maxTotalB
     maxEntryBytes: DEFAULT_ENTRY_BYTES, maxProjectBytes: DEFAULT_PROJECT_JSON_BYTES, maxEntries: 4096, maxRatio: 1000 });
 const decoder = new TextDecoder('utf-8', { fatal: true });
 const encoder = new TextEncoder();
+/** The one carrier spelling this family writes, and the only one a standard host is given. */
+export const DATA_CARRIER_PREFIX = 'data:text/javascript;base64,';
 function fail(message) { throw new LoaderError('INVALID_ARCHIVE', message); }
 const cancelled = (signal) => { if (signal?.aborted)
     throw new LoaderError('CANCELLED', 'Project preparation cancelled'); };
@@ -255,7 +257,7 @@ export function createProjectIO({ zip: Zip, ...options } = {}) {
             if (data.extensionURLs !== undefined && (!data.extensionURLs || typeof data.extensionURLs !== 'object' || Array.isArray(data.extensionURLs)))
                 throw new LoaderError('INVALID_PROJECT', 'Project extensionURLs must be an object');
             for (const spec of manifest.extensions)
-                if (spec.source.type !== 'remote' && !files.has(spec.source.path))
+                if (spec.source.type === 'embedded-file' && !files.has(spec.source.path))
                     fail('Missing embedded extension entry');
             const context = Object.freeze({});
             contexts.set(context, { manifest, project: data, files });
@@ -289,6 +291,32 @@ export function createProjectIO({ zip: Zip, ...options } = {}) {
                 if (!bytes || bytes.length > (maxBytes ?? limits.maxEntryBytes))
                     fail('Missing or oversized embedded content');
                 return new Uint8Array(bytes);
+            },
+            // The data carrier lives in the project document, under the extension's own ID,
+            // because that is the one place a standard TurboWarp host looks. Decoding is not
+            // evaluating: what comes back is bytes, verified against the digest like any other.
+            async readData(id, { signal, maxBytes } = {}) {
+                cancelled(signal);
+                const carrier = get(active)?.project.extensionURLs?.[id];
+                if (typeof carrier !== 'string' || !carrier.startsWith(DATA_CARRIER_PREFIX))
+                    fail('Missing embedded data carrier');
+                const encoded = carrier.slice(DATA_CARRIER_PREFIX.length);
+                // Reject before allocating: base64 holds 3 bytes for every 4 characters.
+                if (encoded.length / 4 * 3 > (maxBytes ?? limits.maxEntryBytes) + 2)
+                    fail('Missing or oversized embedded content');
+                let binary;
+                try {
+                    binary = atob(encoded);
+                }
+                catch {
+                    fail('Embedded data carrier is not base64');
+                }
+                const bytes = new Uint8Array(binary.length);
+                for (let index = 0; index < binary.length; index++)
+                    bytes[index] = binary.charCodeAt(index);
+                if (bytes.length > (maxBytes ?? limits.maxEntryBytes))
+                    fail('Missing or oversized embedded content');
+                return bytes;
             }
         }),
         restoreJSON,

package/dist/session-trust.js

@@ -1,4 +1,4 @@
-import { LoaderError } from './index.js';
+import { isRemoteSource, LoaderError } from './index.js';
 export function createSessionTrustProvider({ requestApproval, maxApprovals = 128, hostPolicy } = {}) {
     if (typeof requestApproval !== 'function' || !Number.isSafeInteger(maxApprovals) || maxApprovals < 1) {
         throw new TypeError('A host approval prompt and bounded approval capacity are required');
@@ -25,7 +25,7 @@ export function createSessionTrustProvider({ requestApproval, maxApprovals = 128
             // An existing URL-only host policy cannot authorize an archive path.
             // Recheck before cached consent so later host restrictions take precedence.
             if (policy.canLoad || policy.mode) {
-                if (code.source.type !== 'remote')
+                if (!isRemoteSource(code.source))
                     return Object.freeze({ allowed: false });
                 if (policy.canLoad) {
                     const allowed = await policy.canLoad(code.source.url, { signal });

package/indexeddb-cache.js

@@ -1 +1 @@
-export {createIndexedDBContentCache} from './dist/indexeddb-cache.js';
+export {createIndexedDBContentCache, SHARED_BUCKET} from './dist/indexeddb-cache.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-extension-loader",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Host-independent verified TurboWarp Plus extension loading core",
   "keywords": [
     "turbowarp",
@@ -94,6 +94,7 @@
   "devDependencies": {
     "@turbowarp/jszip": "3.12.0",
     "@types/node": "26.6.6",
+    "fake-indexeddb": "6.2.7",
     "typescript": "6.0.3"
   },
   "publishConfig": {