sh3-core 0.9.0 → 0.9.1

package/dist/app/store/storeShard.svelte.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { diffPermissions } from './storeShard.svelte';
+describe('diffPermissions', () => {
+    it('returns empty added and removed when the sets are identical', () => {
+        expect(diffPermissions(['a', 'b'], ['a', 'b'])).toEqual({
+            added: [],
+            removed: [],
+        });
+    });
+    it('detects permissions added by the new version', () => {
+        expect(diffPermissions(['a'], ['a', 'b'])).toEqual({
+            added: ['b'],
+            removed: [],
+        });
+    });
+    it('detects permissions removed by the new version', () => {
+        expect(diffPermissions(['a', 'b'], ['a'])).toEqual({
+            added: [],
+            removed: ['b'],
+        });
+    });
+    it('reports both added and removed when the set changes in both directions', () => {
+        expect(diffPermissions(['a', 'b'], ['b', 'c'])).toEqual({
+            added: ['c'],
+            removed: ['a'],
+        });
+    });
+    it('treats an empty old set as "everything is new"', () => {
+        expect(diffPermissions([], ['a', 'b'])).toEqual({
+            added: ['a', 'b'],
+            removed: [],
+        });
+    });
+});

package/dist/documents/browse.d.ts

@@ -8,5 +8,35 @@ export interface BrowseCapability {
     watchDocuments(callback: (change: DocumentChange) => void): () => void;
     /** Enumerate shard ids with at least one document in the tenant. */
     listShards(): Promise<string[]>;
+    /**
+     * Read content from any shard's document namespace within the active
+     * tenant. Available only when the caller declares both
+     * `documents:browse` and `documents:read`. Returns the content string
+     * (text-format docs), ArrayBuffer (binary-format docs), or null if the
+     * document does not exist. Tenant-scoped — cannot cross tenants.
+     *
+     * Absent (undefined) on the capability object when `documents:read`
+     * is not declared; feature-detect with
+     * `typeof ctx.browse.readFrom === 'function'`.
+     */
+    readFrom?(shardId: string, path: string): Promise<string | ArrayBuffer | null>;
+    /**
+     * Write content into any shard's document namespace within the active
+     * tenant. Available only when the caller declares both
+     * `documents:browse` and `documents:write`. Emits a normal
+     * `DocumentChange` so other shards and the file-explorer pick up the
+     * new or updated document. Tenant-scoped — cannot cross tenants.
+     *
+     * Absent (undefined) on the capability object when `documents:write`
+     * is not declared; feature-detect with
+     * `typeof ctx.browse.writeTo === 'function'`.
+     */
+    writeTo?(shardId: string, path: string, content: string | ArrayBuffer): Promise<void>;
 }
-export declare function createBrowseCapability(tenantId: string, backend: DocumentBackend): BrowseCapability;
+export interface BrowseCapabilityOptions {
+    /** When true, the returned capability exposes `readFrom`. */
+    canRead: boolean;
+    /** When true, the returned capability exposes `writeTo`. */
+    canWrite: boolean;
+}
+export declare function createBrowseCapability(tenantId: string, backend: DocumentBackend, options?: BrowseCapabilityOptions): BrowseCapability;

package/dist/documents/browse.js

@@ -6,8 +6,8 @@
  * the owning shard's own ctx.documents() handle.
  */
 import { documentChanges } from './notifications';
-export function createBrowseCapability(tenantId, backend) {
-    return {
+export function createBrowseCapability(tenantId, backend, options = { canRead: false, canWrite: false }) {
+    const capability = {
         listDocuments: () => backend.listAllDocuments(tenantId),
         listShards: () => backend.listAllShards(tenantId),
         watchDocuments: (callback) => documentChanges.subscribe((change) => {
@@ -16,4 +16,20 @@ export function createBrowseCapability(tenantId, backend) {
             callback(change);
         }),
     };
+    if (options.canRead) {
+        capability.readFrom = (shardId, path) => backend.read(tenantId, shardId, path);
+    }
+    if (options.canWrite) {
+        capability.writeTo = async (shardId, path, content) => {
+            const existed = await backend.exists(tenantId, shardId, path);
+            await backend.write(tenantId, shardId, path, content);
+            documentChanges.emit({
+                type: existed ? 'update' : 'create',
+                path,
+                tenantId,
+                shardId,
+            });
+        };
+    }
+    return capability;
 }

package/dist/documents/browse.test.js

@@ -38,4 +38,85 @@ describe('BrowseCapability', () => {
         documentChanges.emit({ type: 'create', path: 'f.txt', tenantId: 't1', shardId: 's1' });
         expect(cb).not.toHaveBeenCalled();
     });
+    describe('readFrom (documents:read gate)', () => {
+        it('is absent when canRead is false', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            expect(browse.readFrom).toBeUndefined();
+        });
+        it('is present when canRead is true', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(typeof browse.readFrom).toBe('function');
+        });
+        it('reads content from a foreign shard namespace', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t1', 'other', 'notes/ideas.md', 'hello');
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(await browse.readFrom('other', 'notes/ideas.md')).toBe('hello');
+        });
+        it('returns null when the foreign document does not exist', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(await browse.readFrom('other', 'nope.txt')).toBeNull();
+        });
+        it('never crosses tenants: a t1 capability cannot read t2 docs', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t2', 's', 'secret.txt', 'hidden');
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(await browse.readFrom('s', 'secret.txt')).toBeNull();
+        });
+    });
+    describe('writeTo (documents:write gate)', () => {
+        it('is absent when canWrite is false', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: false });
+            expect(browse.writeTo).toBeUndefined();
+        });
+        it('is present when canWrite is true', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            expect(typeof browse.writeTo).toBe('function');
+        });
+        it('writes into the target shard namespace and emits a create change', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await browse.writeTo('target-shard', 'notes/ideas.md', 'hello');
+            expect(await be.read('t1', 'target-shard', 'notes/ideas.md')).toBe('hello');
+            expect(events).toEqual([
+                { type: 'create', path: 'notes/ideas.md', tenantId: 't1', shardId: 'target-shard' },
+            ]);
+            unsub();
+        });
+        it('emits update (not create) when overwriting an existing document', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t1', 'target-shard', 'a.txt', 'v1');
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await browse.writeTo('target-shard', 'a.txt', 'v2');
+            expect(await be.read('t1', 'target-shard', 'a.txt')).toBe('v2');
+            expect(events).toEqual([
+                { type: 'update', path: 'a.txt', tenantId: 't1', shardId: 'target-shard' },
+            ]);
+            unsub();
+        });
+        it('never crosses tenants: cannot be tricked into writing into tenant b', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            await browse.writeTo('s', 'a.txt', 'x');
+            expect(await be.read('t1', 's', 'a.txt')).toBe('x');
+            expect(await be.read('t2', 's', 'a.txt')).toBeNull();
+        });
+    });
+    describe('read + write combined', () => {
+        it('round-trips content through readFrom after writeTo', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: true });
+            await browse.writeTo('shard-x', 'doc.txt', 'roundtrip');
+            expect(await browse.readFrom('shard-x', 'doc.txt')).toBe('roundtrip');
+        });
+    });
 });

package/dist/documents/types.d.ts

@@ -5,6 +5,35 @@
  * through the owning shard's own `ctx.documents()` handle.
  */
 export declare const PERMISSION_DOCUMENTS_BROWSE = "documents:browse";
+/**
+ * Manifest permission string: grants the shard the ability to read
+ * document content from any shard's namespace within the active tenant
+ * via `ctx.browse.readFrom(shardId, path)`. Requires `documents:browse`
+ * in the same manifest — the read surface hangs off `ctx.browse`, which
+ * only exists when `browse` is granted.
+ *
+ * `documents:browse` alone is metadata-only (listDocuments, listShards,
+ * watchDocuments). `documents:read` is the separate content-read gate so
+ * observer shards granted `browse` today do not silently gain content
+ * access.
+ *
+ * Tenant-scoped: reads cannot cross tenants.
+ */
+export declare const PERMISSION_DOCUMENTS_READ = "documents:read";
+/**
+ * Manifest permission string: grants the shard the ability to write
+ * documents into any shard's namespace within the active tenant via
+ * `ctx.browse.writeTo(shardId, path, content)`. Requires
+ * `documents:browse` in the same manifest — the write surface hangs off
+ * `ctx.browse`, which only exists when `browse` is granted.
+ *
+ * Tenant-scoped: writes cannot cross tenants. A shard declaring
+ * `browse` + `write` can overwrite any document owned by any shard in
+ * the current tenant, which is why the install-time consent modal
+ * surfaces this as a distinct line item rather than folding it into
+ * `browse`.
+ */
+export declare const PERMISSION_DOCUMENTS_WRITE = "documents:write";
 /**
  * Format hint for document content. Determines whether reads return a string
  * (`text`) or an `ArrayBuffer` (`binary`).

package/dist/documents/types.js

@@ -16,3 +16,32 @@
  * through the owning shard's own `ctx.documents()` handle.
  */
 export const PERMISSION_DOCUMENTS_BROWSE = 'documents:browse';
+/**
+ * Manifest permission string: grants the shard the ability to read
+ * document content from any shard's namespace within the active tenant
+ * via `ctx.browse.readFrom(shardId, path)`. Requires `documents:browse`
+ * in the same manifest — the read surface hangs off `ctx.browse`, which
+ * only exists when `browse` is granted.
+ *
+ * `documents:browse` alone is metadata-only (listDocuments, listShards,
+ * watchDocuments). `documents:read` is the separate content-read gate so
+ * observer shards granted `browse` today do not silently gain content
+ * access.
+ *
+ * Tenant-scoped: reads cannot cross tenants.
+ */
+export const PERMISSION_DOCUMENTS_READ = 'documents:read';
+/**
+ * Manifest permission string: grants the shard the ability to write
+ * documents into any shard's namespace within the active tenant via
+ * `ctx.browse.writeTo(shardId, path, content)`. Requires
+ * `documents:browse` in the same manifest — the write surface hangs off
+ * `ctx.browse`, which only exists when `browse` is granted.
+ *
+ * Tenant-scoped: writes cannot cross tenants. A shard declaring
+ * `browse` + `write` can overwrite any document owned by any shard in
+ * the current tenant, which is why the install-time consent modal
+ * surfaces this as a distinct line item rather than folding it into
+ * `browse`.
+ */
+export const PERMISSION_DOCUMENTS_WRITE = 'documents:write';

package/dist/registry/client.js

@@ -81,6 +81,9 @@ export async function fetchRegistries(urls) {
  * @throws If the fetch fails, the server returns a non-OK status, or the integrity check fails.
  */
 export async function fetchBundle(version, sourceRegistry) {
+    if (!version.bundleUrl || !version.integrity) {
+        throw new Error('fetchBundle called on a version with no client bundle');
+    }
     let url = version.bundleUrl;
     if (sourceRegistry && !/^https?:\/\//i.test(url)) {
         url = new URL(url, sourceRegistry).href;

package/dist/registry/installer.d.ts

@@ -14,6 +14,7 @@
  *   3. `loadInstalledPackages()` -- called at boot, re-loads all installed
  *      packages from IndexedDB and registers them.
  */
+import { type LoadedBundle } from './loader';
 import type { InstalledPackage, InstallResult, PackageMeta } from './types';
 /**
  * Install a package from raw bundle bytes and metadata.
@@ -28,7 +29,9 @@ import type { InstalledPackage, InstallResult, PackageMeta } from './types';
  * @param meta - Provenance metadata for the install record.
  * @returns Result object indicating success/failure and hot-load status.
  */
-export declare function installPackage(bundle: ArrayBuffer, meta: PackageMeta): Promise<InstallResult>;
+export declare function installPackage(bundle: ArrayBuffer, meta: PackageMeta, options?: {
+    loaded?: LoadedBundle;
+}): Promise<InstallResult>;
 /**
  * Uninstall a package by id.
  *

package/dist/registry/installer.js

@@ -20,6 +20,7 @@ import { verifyIntegrity } from './integrity';
 import { deactivateShard } from '../shards/activate.svelte';
 import { unregisterApp } from '../apps/lifecycle';
 import { registerLoadedBundle } from './register';
+import { extractBundlePermissions } from './permission-descriptions';
 /**
  * Install a package from raw bundle bytes and metadata.
  *
@@ -33,30 +34,42 @@ import { registerLoadedBundle } from './register';
  * @param meta - Provenance metadata for the install record.
  * @returns Result object indicating success/failure and hot-load status.
  */
-export async function installPackage(bundle, meta) {
+export async function installPackage(bundle, meta, options) {
     // 1. Verify bundle integrity before executing any code.
-    try {
-        await verifyIntegrity(bundle, meta.integrity);
-    }
-    catch (err) {
+    if (!meta.integrity) {
         return {
             success: false,
             hotLoaded: false,
-            error: `Integrity check failed: ${err instanceof Error ? err.message : String(err)}`,
+            error: 'Missing integrity hash — refusing to install unverified bundle',
         };
     }
-    // 2. Load the module from verified bytes.
-    let loaded;
     try {
-        loaded = await loadBundleModule(bundle);
+        await verifyIntegrity(bundle, meta.integrity);
     }
     catch (err) {
         return {
             success: false,
             hotLoaded: false,
-            error: `Failed to load bundle: ${err instanceof Error ? err.message : String(err)}`,
+            error: `Integrity check failed: ${err instanceof Error ? err.message : String(err)}`,
         };
     }
+    // 2. Load the module from verified bytes (or reuse the caller's copy).
+    let loaded;
+    if (options === null || options === void 0 ? void 0 : options.loaded) {
+        loaded = options.loaded;
+    }
+    else {
+        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 {
@@ -72,7 +85,7 @@ export async function installPackage(bundle, meta) {
             error: `Package "${meta.id}" declared type "app" but bundle contains no valid app`,
         };
     }
-    // 4. Persist to IndexedDB.
+    // 4. Persist to IndexedDB. Permissions captured from manifest(s).
     const record = {
         id: meta.id,
         type: meta.type,
@@ -80,6 +93,7 @@ export async function installPackage(bundle, meta) {
         sourceRegistry: meta.sourceRegistry,
         contractVersion: meta.contractVersion,
         installedAt: new Date().toISOString(),
+        permissions: extractBundlePermissions(loaded),
     };
     try {
         await savePackage(meta.id, bundle, record);

package/dist/registry/permission-descriptions.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Human-friendly descriptions for manifest-declared permissions.
+ *
+ * The app store's install/update confirmation modal renders each permission
+ * via `describePermission`. Unknown permission IDs fall back to showing the
+ * raw ID with a generic placeholder so newer packages don't crash older
+ * cores.
+ */
+import type { LoadedBundle } from './loader';
+export interface PermissionDescription {
+    title: string;
+    description: string;
+}
+export declare const PERMISSION_DESCRIPTIONS: Record<string, PermissionDescription>;
+export declare function describePermission(id: string): PermissionDescription;
+/**
+ * Compute the deduped union of declared permissions across every shard
+ * and app exported by a bundle. For a plain shard or app bundle this is
+ * just that manifest's permissions; for combos it merges both halves.
+ */
+export declare function extractBundlePermissions(loaded: LoadedBundle): string[];

package/dist/registry/permission-descriptions.js

@@ -0,0 +1,67 @@
+/**
+ * Human-friendly descriptions for manifest-declared permissions.
+ *
+ * The app store's install/update confirmation modal renders each permission
+ * via `describePermission`. Unknown permission IDs fall back to showing the
+ * raw ID with a generic placeholder so newer packages don't crash older
+ * cores.
+ */
+export const PERMISSION_DESCRIPTIONS = {
+    'state:manage': {
+        title: 'Manage shell state zones',
+        description: 'Read and write state zones belonging to other shards.',
+    },
+    'documents:browse': {
+        title: 'Browse tenant documents',
+        description: 'Observe all documents stored by the current tenant.',
+    },
+    'documents:read': {
+        title: 'Read tenant documents',
+        description: 'Read the content of any document in the current tenant, across all shards. Required for backup connectors that need to pull document bodies (not just metadata) out of other shards.',
+    },
+    'documents:write': {
+        title: 'Write tenant documents',
+        description: 'Create and overwrite documents in any shard\'s namespace within the current tenant. Required for restore-class connectors that re-import documents back into their owning shards.',
+    },
+    'documents:sync': {
+        title: 'Sync documents with peers',
+        description: 'Participate in cross-peer document synchronization.',
+    },
+    'sync:peer': {
+        title: 'Act as a sync peer',
+        description: 'Exchange document updates with remote peers.',
+    },
+    'sync:policy': {
+        title: 'Define sync policy',
+        description: 'Configure which documents sync and with whom.',
+    },
+    'keys:mint': {
+        title: 'Mint API keys',
+        description: 'Issue long-lived access tokens for this shell.',
+    },
+};
+export function describePermission(id) {
+    var _a;
+    return (_a = PERMISSION_DESCRIPTIONS[id]) !== null && _a !== void 0 ? _a : {
+        title: id,
+        description: 'Unknown permission.',
+    };
+}
+/**
+ * Compute the deduped union of declared permissions across every shard
+ * and app exported by a bundle. For a plain shard or app bundle this is
+ * just that manifest's permissions; for combos it merges both halves.
+ */
+export function extractBundlePermissions(loaded) {
+    var _a, _b;
+    const perms = new Set();
+    for (const s of loaded.shards) {
+        for (const p of (_a = s.manifest.permissions) !== null && _a !== void 0 ? _a : [])
+            perms.add(p);
+    }
+    for (const a of loaded.apps) {
+        for (const p of (_b = a.manifest.permissions) !== null && _b !== void 0 ? _b : [])
+            perms.add(p);
+    }
+    return [...perms];
+}

package/dist/registry/permission-descriptions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/registry/permission-descriptions.test.js

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest';
+import { describePermission, extractBundlePermissions, PERMISSION_DESCRIPTIONS, } from './permission-descriptions';
+describe('describePermission', () => {
+    it('returns the registered entry for a known permission id', () => {
+        const result = describePermission('state:manage');
+        expect(result.title).toBe('Manage shell state zones');
+        expect(result.description).toContain('state zones');
+    });
+    it('covers every permission advertised in the module registry', () => {
+        expect(PERMISSION_DESCRIPTIONS['state:manage']).toBeDefined();
+        expect(PERMISSION_DESCRIPTIONS['documents:browse']).toBeDefined();
+        expect(PERMISSION_DESCRIPTIONS['documents:sync']).toBeDefined();
+        expect(PERMISSION_DESCRIPTIONS['sync:peer']).toBeDefined();
+        expect(PERMISSION_DESCRIPTIONS['sync:policy']).toBeDefined();
+        expect(PERMISSION_DESCRIPTIONS['keys:mint']).toBeDefined();
+        expect(PERMISSION_DESCRIPTIONS['documents:read']).toBeDefined();
+        expect(PERMISSION_DESCRIPTIONS['documents:write']).toBeDefined();
+    });
+    it('falls back to the raw id and a generic description for unknown ids', () => {
+        const result = describePermission('imaginary:unknown');
+        expect(result.title).toBe('imaginary:unknown');
+        expect(result.description).toMatch(/unknown/i);
+    });
+});
+describe('describePermission — documents:read / documents:write', () => {
+    it('returns a read-oriented title and description for documents:read', () => {
+        const result = describePermission('documents:read');
+        expect(result.title).toMatch(/read/i);
+        expect(result.description).toMatch(/document/i);
+        expect(result).not.toEqual(describePermission('documents:browse'));
+    });
+    it('returns a write-oriented title and description for documents:write', () => {
+        const result = describePermission('documents:write');
+        expect(result.title).toMatch(/write/i);
+        expect(result.description).toMatch(/document/i);
+        expect(result).not.toEqual(describePermission('documents:browse'));
+        expect(result).not.toEqual(describePermission('documents:read'));
+    });
+});
+function shardWithPerms(id, perms) {
+    return {
+        manifest: { id, label: id, version: '0.0.0', views: [], permissions: perms },
+        activate: () => { },
+    };
+}
+function appWithPerms(id, perms) {
+    return {
+        manifest: {
+            id,
+            label: id,
+            version: '0.0.0',
+            initialLayout: { kind: 'leaf', view: '' },
+            requiredShards: [],
+            layoutVersion: 1,
+            permissions: perms,
+        },
+        activate: () => { },
+    };
+}
+describe('extractBundlePermissions', () => {
+    it('returns an empty array when no shards or apps declare permissions', () => {
+        const bundle = { shards: [shardWithPerms('a')], apps: [] };
+        expect(extractBundlePermissions(bundle)).toEqual([]);
+    });
+    it('returns declared permissions for a single shard', () => {
+        const bundle = {
+            shards: [shardWithPerms('a', ['state:manage', 'documents:browse'])],
+            apps: [],
+        };
+        expect(extractBundlePermissions(bundle).sort()).toEqual(['documents:browse', 'state:manage']);
+    });
+    it('dedupes the union of shard and app permissions (combo case)', () => {
+        const bundle = {
+            shards: [shardWithPerms('a', ['state:manage', 'documents:browse'])],
+            apps: [appWithPerms('a-app', ['state:manage', 'keys:mint'])],
+        };
+        expect(extractBundlePermissions(bundle).sort()).toEqual(['documents:browse', 'keys:mint', 'state:manage']);
+    });
+    it('tolerates manifests with missing permissions arrays', () => {
+        const bundle = {
+            shards: [shardWithPerms('a', undefined)],
+            apps: [appWithPerms('b', ['keys:mint'])],
+        };
+        expect(extractBundlePermissions(bundle)).toEqual(['keys:mint']);
+    });
+});

package/dist/registry/schema.js

@@ -113,16 +113,29 @@ function validatePackageVersion(data, path) {
     const obj = data;
     requireString(obj, 'version', path);
     requireString(obj, 'contractVersion', path);
-    requireString(obj, 'bundleUrl', path);
-    requireString(obj, 'integrity', path);
-    // Optional server bundle URL
-    if ('serverBundleUrl' in obj && obj.serverBundleUrl !== undefined) {
+    // Client bundle fields — optional individually, but if either is present both must be.
+    const hasBundleUrl = 'bundleUrl' in obj && obj.bundleUrl !== undefined;
+    const hasIntegrity = 'integrity' in obj && obj.integrity !== undefined;
+    if (hasBundleUrl)
+        requireString(obj, 'bundleUrl', path);
+    if (hasIntegrity)
+        requireString(obj, 'integrity', path);
+    if (hasBundleUrl !== hasIntegrity) {
+        throw new RegistryValidationError(path, 'bundleUrl and integrity must be provided together');
+    }
+    // Optional server bundle URL.
+    const hasServerBundleUrl = 'serverBundleUrl' in obj && obj.serverBundleUrl !== undefined;
+    if (hasServerBundleUrl) {
         requireString(obj, 'serverBundleUrl', path);
     }
     // Optional server bundle integrity hash — provisional, see ADR-015.
     if ('serverIntegrity' in obj && obj.serverIntegrity !== undefined) {
         requireString(obj, 'serverIntegrity', path);
     }
+    // A version must ship at least one bundle.
+    if (!hasBundleUrl && !hasServerBundleUrl) {
+        throw new RegistryValidationError(path, 'expected at least one of bundleUrl+integrity or serverBundleUrl');
+    }
     let requires;
     if (obj['requires'] !== undefined) {
         if (!Array.isArray(obj['requires'])) {
@@ -133,8 +146,8 @@ function validatePackageVersion(data, path) {
     return {
         version: obj['version'],
         contractVersion: obj['contractVersion'],
-        bundleUrl: obj['bundleUrl'],
-        integrity: obj['integrity'],
+        bundleUrl: typeof obj['bundleUrl'] === 'string' ? obj['bundleUrl'] : undefined,
+        integrity: typeof obj['integrity'] === 'string' ? obj['integrity'] : undefined,
         serverBundleUrl: typeof obj['serverBundleUrl'] === 'string' ? obj['serverBundleUrl'] : undefined,
         serverIntegrity: typeof obj['serverIntegrity'] === 'string' ? obj['serverIntegrity'] : undefined,
         requires,

package/dist/registry/types.d.ts

@@ -100,16 +100,18 @@ export interface PackageVersion {
     /**
      * Absolute or registry-relative URL to the pre-built ESM bundle.
      * The client fetches this URL and verifies the download against `integrity`
-     * before executing.
+     * before executing. Optional for server-only packages that ship only a
+     * `serverBundleUrl` — in that case `integrity` must also be omitted.
      */
-    bundleUrl: string;
+    bundleUrl?: string;
     /**
      * SRI integrity hash for the bundle file.
      * Format: `"<algorithm>-<base64digest>"` (e.g. `"sha384-abc123..."`).
      * Algorithms: sha256, sha384 (recommended), sha512.
      * See: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
+     * Omitted when the package has no client bundle.
      */
-    integrity: string;
+    integrity?: string;
     /**
      * Optional URL to the server-side bundle for shards that have a backend
      * component. Same resolution rules as `bundleUrl` (absolute or registry-
@@ -191,6 +193,15 @@ export interface InstalledPackage {
      * Example: `"2026-04-06T12:34:56.789Z"`.
      */
     installedAt: string;
+    /**
+     * Declared permissions captured from the bundle's manifest(s) at install
+     * time. For a shard or app, this is `manifest.permissions ?? []`. For a
+     * combo, the deduped union of the shard's and app's permissions.
+     *
+     * Legacy records written before this field existed may omit it; consumers
+     * must treat a missing value as `[]`.
+     */
+    permissions: string[];
 }
 /**
  * Result of an install operation.
@@ -250,9 +261,10 @@ export interface PackageMeta {
     sourceRegistry: string;
     /**
      * SRI hash to verify the downloaded bundle against before executing.
-     * Must match `PackageVersion.integrity`.
+     * Must match `PackageVersion.integrity`. Omitted for server-only packages
+     * that ship no client bundle.
      */
-    integrity: string;
+    integrity?: string;
     /**
      * Declared shard dependencies. Mirrors `PackageVersion.requires`.
      * Undefined if no dependencies.