@kubohiroya/turbowarp-extension-loader 0.3.1 → 0.5.0

package/dist/index.js

@@ -1,4 +1,6 @@
 import { DEFAULT_LOADER_LIMITS } from './limits.js';
+/** Whether the project holds a reference the loader has to fetch, rather than the bytes. */
+export const isRemoteSource = (source) => source.type === 'remote-non-cacheable' || source.type === 'remote-cacheable';
 const DEFAULTS = DEFAULT_LOADER_LIMITS;
 const RESERVED_IDS = new Set(['pen', 'music', 'videoSensing', 'text2speech', 'translate', 'microbit', 'ev3', 'boost', 'wedo2', 'gdxfor', 'makeymakey']);
 const ID = /^[a-zA-Z][a-zA-Z0-9]{0,63}$/;
@@ -30,18 +32,25 @@ const string = (value, label, max = 256) => {
         fail('INVALID_MANIFEST', `Invalid ${label}`);
     return value;
 };
-function remoteURL(value) {
+// One rule for every address this family records. The code says which address was wrong, since
+// a project's own URI is not one of its sources and should not be reported as one.
+function address(value, code, what) {
     let url;
+    // Reported under the caller's code throughout, including a value that is not a string at
+    // all, so one wrong address is one error a reader can place.
+    if (typeof value !== 'string' || value.length > 4096)
+        fail(code, `${what} must be an absolute HTTPS URL`);
     try {
         url = new URL(value);
     }
     catch {
-        fail('INVALID_SOURCE', 'Remote source must be an absolute HTTPS URL');
+        fail(code, `${what} must be an absolute HTTPS URL`);
     }
     if (url.protocol !== 'https:' || url.username || url.password || url.hash)
-        fail('INVALID_SOURCE', 'Remote source requires HTTPS without credentials or fragment');
+        fail(code, `${what} requires HTTPS without credentials or fragment`);
     return url.href;
 }
+const remoteURL = (value) => address(value, 'INVALID_SOURCE', 'Remote source');
 function embeddedPath(value) {
     const path = string(value, 'embedded path', 256);
     if (!/^extensions\/[a-zA-Z0-9][a-zA-Z0-9._/-]*\.js$/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..'))
@@ -51,26 +60,42 @@ function embeddedPath(value) {
 function sourceOf(source) {
     if (!object(source))
         fail('INVALID_SOURCE', 'Missing extension source');
-    if (source.type === 'remote') {
+    const origin = (value) => remoteURL(string(value, 'URL', 4096));
+    if (source.type === 'remote-non-cacheable' || source.type === 'remote-cacheable') {
         keys(source, ['type', 'url'], 'source');
-        return Object.freeze({ type: 'remote', url: remoteURL(string(source.url, 'URL', 4096)) });
+        return Object.freeze({ type: source.type, url: origin(source.url) });
     }
-    if (source.type === 'embedded') {
-        keys(source, ['type', 'path'], 'source');
-        return Object.freeze({ type: 'embedded', path: embeddedPath(source.path) });
+    if (source.type === 'embedded-file') {
+        keys(source, ['type', 'path', 'url'], 'source');
+        const path = embeddedPath(source.path);
+        if (source.url === undefined)
+            return Object.freeze({ type: 'embedded-file', path });
+        return Object.freeze({ type: 'embedded-file', path, url: origin(source.url) });
     }
-    if (source.type === 'cached') {
-        keys(source, ['type', 'url', 'path'], 'source');
-        // The same HTTPS and path policies as the two single-location forms it combines.
-        return Object.freeze({ type: 'cached', url: remoteURL(string(source.url, 'URL', 4096)), path: embeddedPath(source.path) });
+    if (source.type === 'embedded-data') {
+        keys(source, ['type', 'url'], 'source');
+        if (source.url === undefined)
+            return Object.freeze({ type: 'embedded-data' });
+        return Object.freeze({ type: 'embedded-data', url: origin(source.url) });
     }
+    // Name each retired spelling and what replaces it. A project written by an older version
+    // fails with something a reader can act on rather than "unsupported", and the reader has to
+    // make the choice the old name left implicit rather than have one picked for them.
+    if (source.type === 'remote')
+        fail('INVALID_SOURCE', 'A remote source is now remote-cacheable or remote-non-cacheable');
+    if (source.type === 'cached')
+        fail('INVALID_SOURCE', 'A cached source is now embedded-file with a url');
+    if (source.type === 'embedded')
+        fail('INVALID_SOURCE', 'An embedded source is now embedded-file or embedded-data');
     fail('INVALID_SOURCE', 'Unsupported source type');
 }
 /** Validate and snapshot untrusted data; execution is only a request. */
 export function validateManifest(input, options = {}) {
-    keys(input, ['schemaVersion', 'extensions'], 'manifest');
+    keys(input, ['schemaVersion', 'uri', 'extensions'], 'manifest');
     if (input.schemaVersion !== 1)
         fail('UNSUPPORTED_SCHEMA', 'Only schemaVersion 1 is supported');
+    // The same rule as every other address this family records, so there is one to learn.
+    const uri = input.uri === undefined ? undefined : address(input.uri, 'INVALID_PROJECT_URI', 'A project URI');
     const maxExtensions = options.maxExtensions ?? DEFAULTS.maxExtensions;
     if (!Array.isArray(input.extensions) || input.extensions.length > maxExtensions)
         fail('INVALID_MANIFEST', 'Invalid extension list');
@@ -117,7 +142,8 @@ export function validateManifest(input, options = {}) {
         ordered.push(spec);
     };
     extensions.forEach(visit);
-    return Object.freeze({ schemaVersion: 1, extensions: Object.freeze(ordered) });
+    return Object.freeze({ schemaVersion: 1, ...(uri === undefined ? {} : { uri }),
+        extensions: Object.freeze(ordered) });
 }
 export function discoverManifest(project, options) {
     if (!object(project))
@@ -320,10 +346,17 @@ export function createExtensionLoader(ports, options = {}) {
         ports.diagnostics?.(Object.freeze({ ...event }));
     }
     catch { /* Diagnostics must not alter authorization. */ } };
-    async function resolve(spec, signal, budget) {
+    async function resolve(spec, signal, budget, declineCaching) {
         let bytes;
         let cached = false;
-        if (ports.cache) {
+        // The manifest is frozen, so the narrowed source stays valid inside the port callbacks.
+        const source = spec.source;
+        // One form permits a copy, and only the person can come in under that. The author's
+        // `remote-non-cacheable` is a prohibition nothing here can undo, and embedded bytes
+        // already travel with the project, so a second copy would buy nothing. The decision
+        // holds in both directions: not read for this extension, and not written either.
+        const mayCache = source.type === 'remote-cacheable' && !declineCaching?.has(spec.id);
+        if (mayCache && ports.cache) {
             const entry = await guarded(() => ports.cache.get(spec.sha256, { signal }), signal);
             if (entry !== undefined && entry !== null) {
                 const candidate = snapshotBytes(entry, limits.maxBytes, spec.id);
@@ -334,26 +367,32 @@ export function createExtensionLoader(ports, options = {}) {
             }
         }
         if (!bytes) {
-            // The manifest is frozen, so the narrowed source stays valid inside the port callbacks.
-            const source = spec.source;
-            if (source.type !== 'remote') {
-                if (typeof ports.embeddedReader?.read !== 'function')
-                    fail('INVALID_PORT', 'Embedded reader is unavailable', spec.id);
-                // A cached source may have lost its retained copy; its URL remains the canonical one.
+            if (source.type === 'embedded-file' || source.type === 'embedded-data') {
+                const reader = source.type === 'embedded-file' ?
+                    () => ports.embeddedReader.read(source.path, { signal, maxBytes: limits.maxBytes }) :
+                    () => ports.embeddedReader.readData(spec.id, { signal, maxBytes: limits.maxBytes });
+                const available = source.type === 'embedded-file' ?
+                    typeof ports.embeddedReader?.read === 'function' :
+                    typeof ports.embeddedReader?.readData === 'function';
+                if (!available)
+                    fail('INVALID_PORT', `Reader for ${source.type} is unavailable`, spec.id);
                 try {
-                    bytes = snapshotBytes(await guarded(() => ports.embeddedReader.read(source.path, { signal, maxBytes: limits.maxBytes }), signal), limits.maxBytes, spec.id);
+                    bytes = snapshotBytes(await guarded(reader, signal), limits.maxBytes, spec.id);
                 }
                 catch (cause) {
-                    if (source.type === 'embedded' || signal.aborted)
+                    // Falling back is only possible where the project recorded where the bytes
+                    // came from; without that, a missing retained copy is the end of it.
+                    if (source.url === undefined || signal.aborted)
                         throw cause;
                     report({ type: 'retained-copy-unavailable', id: spec.id });
                 }
             }
-            if (!bytes && source.type !== 'embedded') {
+            const url = source.url;
+            if (!bytes && url !== undefined) {
                 if (typeof ports.fetcher?.fetch !== 'function')
                     fail('INVALID_PORT', 'Remote fetch port is unavailable', spec.id);
-                const response = await guarded(() => ports.fetcher.fetch(source.url, { signal, maxBytes: limits.maxBytes }), signal);
-                if (!response || !Array.isArray(response.redirects) || response.redirects.length || response.finalURL !== source.url)
+                const response = await guarded(() => ports.fetcher.fetch(url, { signal, maxBytes: limits.maxBytes }), signal);
+                if (!response || !Array.isArray(response.redirects) || response.redirects.length || response.finalURL !== url)
                     fail('REDIRECT_DENIED', 'Unproven or redirected remote source', spec.id);
                 bytes = snapshotBytes(response.bytes, limits.maxBytes, spec.id);
             }
@@ -373,13 +412,13 @@ export function createExtensionLoader(ports, options = {}) {
         catch (cause) {
             throw new LoaderError('INVALID_ENCODING', 'Extension must contain valid UTF-8', spec.id, cause);
         }
-        if (!cached && ports.cache)
+        if (!cached && mayCache && ports.cache)
             await guarded(() => ports.cache.put(spec.sha256, new Uint8Array(bytes), { signal }), signal);
         const result = Object.freeze({ ...spec, code, byteLength: bytes.byteLength, actualSHA256: actual, cached });
         report({ type: 'verified', id: spec.id, sha256: actual, cached });
         return result;
     }
-    async function load(input, { signal: externalSignal } = {}) {
+    async function load(input, { signal: externalSignal, declineCaching } = {}) {
         if (state !== 'idle')
             fail('BUSY', 'Unload the previous project before another load');
         const manifest = validateManifest(input, limits);
@@ -397,7 +436,7 @@ export function createExtensionLoader(ports, options = {}) {
         try {
             const budget = { bytes: 0 };
             for (const spec of manifest.extensions) {
-                const code = await resolve(spec, signal, budget);
+                const code = await resolve(spec, signal, budget, declineCaching);
                 const decision = await guarded(() => ports.trustProvider.authorize(code, { signal }), signal);
                 if (decision?.allowed !== true || decision.scope !== 'digest' || decision.sha256 !== code.sha256)
                     fail('TRUST_DENIED', 'Host did not approve this exact extension digest', spec.id);

package/dist/indexeddb-cache.d.ts

@@ -1,6 +1,44 @@
+/** Which projects an entry is kept for, so one project's share can be listed and released. */
+export interface CacheUsage {
+    /** The project URI an entry is filed under, or SHARED_BUCKET. */
+    readonly bucket: string;
+    readonly key: string;
+    readonly bytes: number;
+    readonly originalBytes: number;
+    readonly lastAccess: number;
+}
+export interface CacheBucket {
+    readonly bucket: string;
+    readonly entries: number;
+    readonly bytes: number;
+}
+/**
+ * The bucket for bytes that belong to no one project.
+ *
+ * A catalog extension is pinned to a version and shared by many projects, so filing it under
+ * whichever project happened to fetch it first would make that project look responsible for
+ * storage every other one reuses, and releasing that project would evict bytes the rest still
+ * want. It is not a URI, so no project can name it.
+ */
+export declare const SHARED_BUCKET = "shared";
 export interface IndexedDBContentCacheOptions {
     indexedDB?: IDBFactory;
     databaseName?: string;
+    /**
+     * The URI of the project being opened, which entries fetched for it are filed under.
+     *
+     * Without one, everything is filed as shared: a host that cannot say which project it is
+     * opening cannot have per-project accounting, and guessing a name would be worse than
+     * admitting there is none.
+     */
+    appURI?: string;
+    /**
+     * Digests that belong to no one project, read at the time of each write.
+     *
+     * The host knows which extensions came from the catalog; this module cannot. Passing a set
+     * the host keeps updating is enough, since it is consulted per write.
+     */
+    sharedDigests?: ReadonlySet<string>;
     /** Compressed bytes quota (default 32 MiB). */
     maxBytes?: number;
     /** Maximum decompressed JS size (default 16 MiB, the largest default extension). */
@@ -20,9 +58,29 @@ export type IndexedDBContentCache = Readonly<{
         entries: number;
         bytes: number;
     }>;
+    /** Every bucket that holds something, with what it accounts for. */
+    listBuckets(): Promise<CacheBucket[]>;
+    /** What one bucket holds. SHARED_BUCKET lists what belongs to no one project. */
+    listBucket(bucket: string): Promise<CacheUsage[]>;
+    /**
+     * Release one bucket, and with it any bytes nothing else still refers to.
+     *
+     * Bytes shared with another bucket stay: they are one copy, referred to twice, and the other
+     * project did not ask to lose them.
+     * @returns {Promise<{released: number; freed: number}>} Entries dropped and bytes reclaimed.
+     */
+    deleteBucket(bucket: string): Promise<{
+        released: number;
+        freed: number;
+    }>;
+    /** Release named digests from one bucket, with the same rule. */
+    deleteFromBucket(bucket: string, keys: readonly string[]): Promise<{
+        released: number;
+        freed: number;
+    }>;
     close(): Promise<void>;
 }>;
 /** Persistent, content-addressed cache. The Loader independently verifies SHA-256 on every hit.
  * Storage is untrusted: this adapter is not an authorization or integrity boundary.
  */
-export declare function createIndexedDBContentCache({ indexedDB, databaseName, maxBytes, maxDecompressedBytes, now }?: IndexedDBContentCacheOptions): IndexedDBContentCache;
+export declare function createIndexedDBContentCache({ indexedDB, databaseName, appURI, sharedDigests, maxBytes, maxDecompressedBytes, now }?: IndexedDBContentCacheOptions): IndexedDBContentCache;

package/dist/indexeddb-cache.js

@@ -1,9 +1,18 @@
 import { gzipBytes, gunzipBytes } from './cache-gzip.js';
 import { DEFAULT_ENTRY_BYTES } from './limits.js';
+/**
+ * The bucket for bytes that belong to no one project.
+ *
+ * A catalog extension is pinned to a version and shared by many projects, so filing it under
+ * whichever project happened to fetch it first would make that project look responsible for
+ * storage every other one reuses, and releasing that project would evict bytes the rest still
+ * want. It is not a URI, so no project can name it.
+ */
+export const SHARED_BUCKET = 'shared';
 /** Persistent, content-addressed cache. The Loader independently verifies SHA-256 on every hit.
  * Storage is untrusted: this adapter is not an authorization or integrity boundary.
  */
-export function createIndexedDBContentCache({ indexedDB = globalThis.indexedDB, databaseName = 'turbowarp-plus-extension-cache', maxBytes = 32 * 1024 * 1024, maxDecompressedBytes = DEFAULT_ENTRY_BYTES, now = Date.now } = {}) {
+export function createIndexedDBContentCache({ indexedDB = globalThis.indexedDB, databaseName = 'turbowarp-plus-extension-cache', appURI, sharedDigests, maxBytes = 32 * 1024 * 1024, maxDecompressedBytes = DEFAULT_ENTRY_BYTES, now = Date.now } = {}) {
     if (!indexedDB || typeof indexedDB.open !== 'function')
         throw new Error('IndexedDB unavailable');
     if (typeof databaseName !== 'string' || !databaseName || !Number.isSafeInteger(maxBytes) || maxBytes < 1 ||
@@ -14,11 +23,22 @@ export function createIndexedDBContentCache({ indexedDB = globalThis.indexedDB,
     function open() {
         if (!dbPromise) {
             dbPromise = new Promise((resolve, reject) => {
-                const request = indexedDB.open(databaseName, 1);
+                const request = indexedDB.open(databaseName, 2);
                 request.onupgradeneeded = () => {
                     const db = request.result;
                     if (!db.objectStoreNames.contains('content'))
                         db.createObjectStore('content', { keyPath: 'key' });
+                    if (!db.objectStoreNames.contains('usage')) {
+                        const usage = db.createObjectStore('usage', { keyPath: ['bucket', 'key'] });
+                        // Finding every claim on one digest is what decides whether releasing a
+                        // project may take its bytes with it.
+                        usage.createIndex('key', 'key');
+                        usage.createIndex('bucket', 'bucket');
+                        // Entries written before there were buckets have no owner, and inventing
+                        // one would make a project answer for storage it never asked for. This is
+                        // a cache: dropping it costs a fetch, which is cheaper than a wrong name.
+                        request.transaction.objectStore('content').clear();
+                    }
                 };
                 request.onsuccess = () => {
                     const db = request.result;
@@ -31,15 +51,15 @@ export function createIndexedDBContentCache({ indexedDB = globalThis.indexedDB,
         }
         return dbPromise;
     }
-    function transaction(db, mode, work) {
+    function transaction(db, mode, work, stores = 'content') {
         return new Promise((resolve, reject) => {
-            const tx = db.transaction('content', mode);
+            const tx = db.transaction(stores, mode);
             let value;
             tx.oncomplete = () => resolve(value);
             tx.onerror = () => reject(tx.error || new Error('IndexedDB transaction failed'));
             tx.onabort = () => reject(tx.error || new Error('IndexedDB transaction aborted'));
             try {
-                work(tx.objectStore('content'), result => { value = result; }, tx);
+                work(tx.objectStore(typeof stores === 'string' ? stores : stores[0]), result => { value = result; }, tx);
             }
             catch (error) {
                 try {
@@ -56,7 +76,14 @@ export function createIndexedDBContentCache({ indexedDB = globalThis.indexedDB,
         entry.bytes instanceof ArrayBuffer && Number.isSafeInteger(entry.originalBytes) &&
         entry.originalBytes >= 0 && entry.originalBytes <= maxDecompressedBytes &&
         entry.bytes.byteLength <= maxBytes;
-    function sweep(store, protectedKey = null) {
+    const dropClaims = (usage, key) => {
+        const claims = usage.index('key').getAllKeys(key);
+        claims.onsuccess = () => {
+            for (const claim of claims.result)
+                usage.delete(claim);
+        };
+    };
+    function sweep(store, usage, protectedKey = null) {
         const request = store.getAll();
         request.onsuccess = () => {
             let total = 0;
@@ -64,6 +91,7 @@ export function createIndexedDBContentCache({ indexedDB = globalThis.indexedDB,
             for (const record of request.result) {
                 if (!validRecord(record)) {
                     store.delete(record.key);
+                    dropClaims(usage, record.key);
                     continue;
                 }
                 total += record.bytes.byteLength;
@@ -76,10 +104,51 @@ export function createIndexedDBContentCache({ indexedDB = globalThis.indexedDB,
                 if (record.key === protectedKey)
                     continue;
                 store.delete(record.key);
+                dropClaims(usage, record.key);
                 total -= record.bytes.byteLength;
             }
         };
     }
+    async function release(bucket, keys) {
+        if (typeof bucket !== 'string' || !bucket)
+            throw new TypeError('A bucket name is required');
+        if (keys !== null && (!Array.isArray(keys) || keys.some(key => !keyValid(key)))) {
+            throw new TypeError('Cache keys must be SHA-256 digests');
+        }
+        const wanted = keys === null ? null : new Set(keys);
+        const db = await open();
+        return transaction(db, 'readwrite', (store, set, tx) => {
+            const usage = tx.objectStore('usage');
+            // The same object the transaction resolves with, filled in as the nested requests
+            // below run: every one of them completes before the transaction does.
+            const result = { released: 0, freed: 0 };
+            set(result);
+            const mine = usage.index('bucket').getAll(bucket);
+            mine.onsuccess = () => {
+                for (const claim of mine.result) {
+                    if (wanted !== null && !wanted.has(claim.key))
+                        continue;
+                    usage.delete([bucket, claim.key]);
+                    result.released++;
+                    // One copy, referred to more than once. Another project did not ask to lose
+                    // it, so the bytes only follow the last claim on them.
+                    const others = usage.index('key').getAll(claim.key);
+                    others.onsuccess = () => {
+                        if (others.result.some(other => other.bucket !== bucket))
+                            return;
+                        const record = store.get(claim.key);
+                        record.onsuccess = () => {
+                            const entry = record.result;
+                            if (!entry)
+                                return;
+                            result.freed += entry.bytes?.byteLength || 0;
+                            store.delete(claim.key);
+                        };
+                    };
+                }
+            };
+        }, ['content', 'usage']);
+    }
     return Object.freeze({
         async get(key, { signal } = {}) {
             if (!keyValid(key))
@@ -128,20 +197,28 @@ export function createIndexedDBContentCache({ indexedDB = globalThis.indexedDB,
             if (signal?.aborted)
                 throw signal.reason;
             const db = await open();
-            return transaction(db, 'readwrite', store => {
+            const bucket = appURI === undefined || sharedDigests?.has(key) ? SHARED_BUCKET : appURI;
+            return transaction(db, 'readwrite', (store, _set, tx) => {
+                const usage = tx.objectStore('usage');
                 const time = now();
                 if (compressed.byteLength <= maxBytes) {
                     store.put({ key, format: 'gzip-v1', bytes: compressed.buffer, originalBytes,
                         lastAccess: time });
+                    usage.put({ bucket, key, lastAccess: time });
                 }
-                else
+                else {
                     store.delete(key);
-                sweep(store, compressed.byteLength <= maxBytes ? key : null);
-            });
+                    usage.delete([bucket, key]);
+                }
+                sweep(store, usage, compressed.byteLength <= maxBytes ? key : null);
+            }, ['content', 'usage']);
         },
         async clear() {
             const db = await open();
-            return transaction(db, 'readwrite', store => { store.clear(); });
+            return transaction(db, 'readwrite', (store, _set, tx) => {
+                store.clear();
+                tx.objectStore('usage').clear();
+            }, ['content', 'usage']);
         },
         async getSize() {
             const db = await open();
@@ -152,6 +229,54 @@ export function createIndexedDBContentCache({ indexedDB = globalThis.indexedDB,
                 }), { entries: 0, bytes: 0 }));
             });
         },
+        async listBuckets() {
+            const db = await open();
+            return transaction(db, 'readonly', (store, set, tx) => {
+                const claims = tx.objectStore('usage').getAll();
+                const records = store.getAll();
+                claims.onsuccess = () => {
+                    records.onsuccess = () => {
+                        const sizes = new Map(records.result
+                            .map(record => [record.key, record.bytes?.byteLength || 0]));
+                        const totals = new Map();
+                        for (const claim of claims.result) {
+                            const total = totals.get(claim.bucket) || { entries: 0, bytes: 0 };
+                            total.entries++;
+                            total.bytes += sizes.get(claim.key) || 0;
+                            totals.set(claim.bucket, total);
+                        }
+                        set([...totals].map(([bucket, total]) => Object.freeze({ bucket, ...total })));
+                    };
+                };
+            }, ['content', 'usage']);
+        },
+        async listBucket(bucket) {
+            if (typeof bucket !== 'string' || !bucket)
+                throw new TypeError('A bucket name is required');
+            const db = await open();
+            return transaction(db, 'readonly', (store, set, tx) => {
+                const claims = tx.objectStore('usage').index('bucket').getAll(bucket);
+                const records = store.getAll();
+                claims.onsuccess = () => {
+                    records.onsuccess = () => {
+                        const byKey = new Map(records.result.map(record => [record.key, record]));
+                        set(claims.result.flatMap(claim => {
+                            const record = byKey.get(claim.key);
+                            if (!record)
+                                return [];
+                            return [Object.freeze({ bucket, key: claim.key, bytes: record.bytes?.byteLength || 0,
+                                    originalBytes: record.originalBytes, lastAccess: claim.lastAccess })];
+                        }));
+                    };
+                };
+            }, ['content', 'usage']);
+        },
+        deleteBucket(bucket) {
+            return release(bucket, null);
+        },
+        deleteFromBucket(bucket, keys) {
+            return release(bucket, keys);
+        },
         async close() {
             if (dbPromise) {
                 const db = await dbPromise;

package/dist/packager.js

@@ -57,8 +57,12 @@ export async function convertProjectSources(input, ports, { zip: Zip, targets =
         if (await digest(bytes) !== record.sha256)
             fail('CONVERSION_INTEGRITY', 'UTF-8 conversion changed verified source bytes');
         own(artifacts, record.id, new Uint8Array(bytes));
-        // Embedded and cached both keep a copy in the archive, so both need their entry written.
-        if (validated.source.type !== 'remote') {
+        // A `data:` carrier lives in the project document, and packaging refuses that document's
+        // legacy URLs outright, so there would be nowhere to put the bytes.
+        if (validated.source.type === 'embedded-data')
+            fail('UNSUPPORTED_SOURCE', 'Packaging cannot write a data: carrier');
+        // Only a file carrier has an archive entry to write.
+        if (validated.source.type === 'embedded-file') {
             const path = validated.source.path;
             if (outputPaths.has(path))
                 fail('DUPLICATE_EMBEDDED_PATH', 'Each extension needs a distinct embedded output path');
@@ -108,7 +112,7 @@ export async function prepareOfflinePackage(input, ports, options = {}) {
             resourceDependencies[spec.id].length) {
             fail('UNBUNDLED_DEPENDENCY', `Declare an empty external resource dependency list for ${spec.id}; external resources are not yet bundled`);
         }
-        own(targets, spec.id, { type: 'embedded', path: `extensions/${spec.id}-${spec.sha256}.js` });
+        own(targets, spec.id, { type: 'embedded-file', path: `extensions/${spec.id}-${spec.sha256}.js` });
     }
     // Options pass through unchanged; convertProjectSources reports a missing ZIP implementation.
     const result = await convertProjectSources(input, ports, { ...options, targets });
@@ -142,7 +146,7 @@ export async function migrateLegacyDataURL({ id, url, sha256, metadata }, ports,
         throw new LoaderError('INVALID_ENCODING', 'Invalid legacy Data URL encoding', id, cause);
     }
     const path = `extensions/${id}.js`;
-    const manifest = validateManifest({ schemaVersion: 1, extensions: [{ id, source: { type: 'embedded', path }, execution: 'unsandboxed', sha256 }] });
+    const manifest = validateManifest({ schemaVersion: 1, extensions: [{ id, source: { type: 'embedded-file', path }, execution: 'unsandboxed', sha256 }] });
     const [record] = await collect(manifest, { ...ports, embeddedReader: { async read() { return bytes; } } }, options.loaderOptions, options.signal);
     return Object.freeze({ spec: manifest.extensions[0], bytes: encoder.encode(record.code), metadata: metadataFor({ [id]: metadata }, id) });
 }

package/dist/project-authoring.d.ts

@@ -4,7 +4,7 @@ export type ExtensionAdditionRequest = {
     id: string;
     execution?: ExecutionMode;
     source: {
-        type: 'embedded';
+        type: 'embedded-file';
         path?: string;
     };
     bytes: Uint8Array | Blob;
@@ -12,7 +12,7 @@ export type ExtensionAdditionRequest = {
     id: string;
     execution?: ExecutionMode;
     source: {
-        type: 'remote';
+        type: 'remote-non-cacheable' | 'remote-cacheable';
         url: string;
     };
     bytes?: never;
@@ -31,3 +31,36 @@ export interface PreparedExtensionAddition {
 }
 /** Computes SHA-256 and reviews the candidate without executing code or changing the input. */
 export declare function prepareExtensionAddition(input: unknown, request: ExtensionAdditionRequest, ports: AuthoringPorts, options: ExtensionAdditionOptions): Promise<PreparedExtensionAddition>;
+/** Where an unchosen address is put, relative to whatever origin assigns it. */
+export declare 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 declare function createProjectUUID(): string;
+/**
+ * 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 declare function defaultProjectURI(origin: string, uuid: string): string;