@pikku/core 0.12.138 → 0.12.139

package/dist/services/local-content.js

@@ -1,7 +1,9 @@
 import { createReadStream, createWriteStream, promises } from 'fs';
-import { mkdir, readFile } from 'fs/promises';
-import { resolve, normalize } from 'path';
+import { randomUUID } from 'crypto';
+import { mkdir, readFile, readdir, rename, rm, stat } from 'fs/promises';
+import { resolve, normalize, sep } from 'path';
 import { pipeline } from 'stream/promises';
+import { Transform } from 'stream';
 /**
  * The representation of an asset that gets bound into a signed URL's
  * signature, and that a server can reconstruct from an incoming request:
@@ -27,8 +29,122 @@ export const signedContentPath = (urlOrPath) => {
         return pathname;
     }
 };
+export const PUBLIC_URL_SEGMENT = '_public';
+export const CONTENT_VISIBILITIES = [
+    'private',
+    'public',
+];
+/**
+ * Splits the part of a content URL after the asset/upload prefix into the
+ * visibility it names and the `<bucket>/<key>` remainder. Only a leading
+ * `_public/` segment names the public side; anything else is private.
+ * Private buckets may therefore not be named `_public`.
+ */
+export const parseContentUrlPath = (key) => {
+    const [first, ...rest] = key.split('/');
+    if (first === PUBLIC_URL_SEGMENT) {
+        return { visibility: 'public', rest: rest.join('/'), prefixed: true };
+    }
+    return { visibility: 'private', rest: key, prefixed: false };
+};
+/**
+ * Resolves `<bucket>/<key>` against one side of the store. The side is a
+ * directory under the content root, and both the bucket and the key must stay
+ * inside it, so neither side can climb out or reach the other.
+ */
+export const resolveVisibilityPath = (basePath, visibility, bucket, key) => {
+    if (!CONTENT_VISIBILITIES.includes(visibility))
+        return null;
+    if (bucket.includes('\0') || key.includes('\0'))
+        return null;
+    if (visibility === 'private') {
+        const [first] = normalize(bucket).split(/[\\/]/);
+        if (first === PUBLIC_URL_SEGMENT)
+            return null;
+    }
+    const root = resolve(resolve(basePath), visibility);
+    const scoped = resolve(root, normalize(bucket));
+    const target = resolve(scoped, normalize(key));
+    const inside = (path) => path === root || path.startsWith(root + sep);
+    if (!inside(scoped) || !inside(target))
+        return null;
+    return target;
+};
+/**
+ * Maps the part of a content URL after the asset/upload prefix to a file under
+ * the content root: `_public/...` to the public side, anything else to the
+ * private side, falling back for reads to an unprefixed file from before the
+ * split. Returns `null` for a path that escapes its side or names no file.
+ * Every server of local content resolves through here, and skips the signature
+ * check only when the result is public.
+ */
+export const resolveContentRequestTarget = async (basePath, key, mode) => {
+    const parsed = parseContentUrlPath(key);
+    const root = resolve(resolve(basePath), parsed.visibility);
+    const path = resolveVisibilityPath(basePath, parsed.visibility, parsed.rest, '');
+    if (!path || path === root)
+        return null;
+    if (mode === 'read' && !parsed.prefixed) {
+        const exists = await stat(path).then(() => true, () => false);
+        if (!exists) {
+            const [first] = normalize(parsed.rest).split(/[\\/]/);
+            const base = resolve(basePath);
+            const legacy = resolve(base, normalize(parsed.rest));
+            if (first !== PUBLIC_URL_SEGMENT &&
+                first !== 'private' &&
+                legacy.startsWith(base + sep)) {
+                return { path: legacy, visibility: 'private' };
+            }
+        }
+    }
+    return { path, visibility: parsed.visibility };
+};
 /** How long a presigned upload URL stays valid. Short, like an S3 PUT URL. */
 const UPLOAD_URL_TTL_MS = 15 * 60 * 1000;
+export class UploadTooLargeError extends Error {
+    constructor() {
+        super('content_too_large');
+    }
+}
+export const parseContentSizeLimit = (sizeLimit) => {
+    const match = /^(\d+(?:\.\d+)?)(b|kb|mb|gb)?$/i.exec(sizeLimit.trim());
+    if (!match) {
+        throw new Error(`Invalid size limit: ${sizeLimit}`);
+    }
+    const unit = (match[2] ?? 'b').toLowerCase();
+    const multiplier = unit === 'gb'
+        ? 1024 * 1024 * 1024
+        : unit === 'mb'
+            ? 1024 * 1024
+            : unit === 'kb'
+                ? 1024
+                : 1;
+    return Number(match[1]) * multiplier;
+};
+export const streamUploadToFile = async (source, targetPath, maxBytes) => {
+    await mkdir(resolve(targetPath, '..'), { recursive: true });
+    const partial = `${targetPath}.${process.pid}.${Date.now()}.${randomUUID()}.part`;
+    let bytes = 0;
+    const counter = new Transform({
+        transform(chunk, _encoding, callback) {
+            bytes += chunk.length;
+            if (bytes > maxBytes) {
+                callback(new UploadTooLargeError());
+                return;
+            }
+            callback(null, chunk);
+        },
+    });
+    try {
+        await pipeline(source, counter, createWriteStream(partial));
+        await rename(partial, targetPath);
+        return bytes;
+    }
+    catch (error) {
+        await rm(partial, { force: true });
+        throw error;
+    }
+};
 export class LocalContent {
     config;
     logger;
@@ -41,15 +157,39 @@ export class LocalContent {
             throw new Error('LocalContent requires a JWTService: without one it cannot sign asset URLs, and unsigned URLs cannot be verified.');
         }
     }
-    safePath(bucket, key) {
-        const base = resolve(this.config.localFileUploadPath);
-        const scoped = resolve(base, normalize(bucket));
-        const target = resolve(scoped, normalize(key));
-        if (!target.startsWith(base + '/') && target !== base) {
+    safePath(bucket, key, visibility = 'private') {
+        const target = resolveVisibilityPath(this.config.localFileUploadPath, visibility, bucket, key);
+        if (!target) {
             throw new Error('Invalid asset key');
         }
         return target;
     }
+    async existingPath(bucket, key, visibility = 'private') {
+        const path = this.safePath(bucket, key, visibility);
+        if (visibility === 'private') {
+            const exists = await stat(path).then(() => true, () => false);
+            if (!exists) {
+                const legacy = this.legacyPath(bucket, key);
+                if (legacy &&
+                    (await stat(legacy).then(() => true, () => false))) {
+                    return legacy;
+                }
+            }
+        }
+        return path;
+    }
+    legacyPath(bucket, key) {
+        const [first] = normalize(bucket).split(/[\\/]/);
+        if (first === PUBLIC_URL_SEGMENT || first === 'private')
+            return null;
+        const base = resolve(this.config.localFileUploadPath);
+        const target = resolve(base, normalize(bucket), normalize(key));
+        return target.startsWith(base + sep) ? target : null;
+    }
+    publicBase() {
+        const origin = this.config.server ?? '';
+        return `${origin}${this.config.assetUrlPrefix}/${PUBLIC_URL_SEGMENT}`;
+    }
     joinKey(bucket, key) {
         return `${bucket}/${key}`;
     }
@@ -82,16 +222,27 @@ export class LocalContent {
         return `${args.url}?${params}`;
     }
     async signContentKey(args) {
+        const visibility = args.visibility ?? 'private';
+        this.safePath(args.bucket, args.contentKey, visibility);
         const fullKey = this.joinKey(args.bucket, args.contentKey);
-        const base = this.config.server
-            ? `${this.config.server}${this.config.assetUrlPrefix}/${fullKey}`
-            : `${this.config.assetUrlPrefix}/${fullKey}`;
+        const origin = this.config.server ?? '';
+        if (visibility === 'public') {
+            return `${this.publicBase()}/${fullKey}`;
+        }
         return this.signURL({
-            url: base,
+            url: `${origin}${this.config.assetUrlPrefix}/${fullKey}`,
             dateLessThan: args.dateLessThan,
             dateGreaterThan: args.dateGreaterThan,
         });
     }
+    async getDownloadURL(args) {
+        return this.signContentKey({
+            bucket: args.bucket,
+            contentKey: args.key,
+            visibility: args.visibility,
+            dateLessThan: new Date(Date.now() + (args.expiresInSeconds ?? 3600) * 1000),
+        });
+    }
     /**
      * Presigned upload, mirroring the read side: the URL carries a short-lived,
      * path-bound signature that {@link createLocalContentRequestHandler} verifies
@@ -99,11 +250,12 @@ export class LocalContent {
      * now refuses one — so this must sign, or every upload 403s.
      */
     async getUploadURL(args) {
-        void args.visibility;
+        const visibility = args.visibility ?? 'private';
+        this.safePath(args.bucket, args.fileKey, visibility);
         const fullKey = this.joinKey(args.bucket, args.fileKey);
         this.logger.debug(`Going to upload with key: ${fullKey}`);
         const uploadUrl = await this.signURL({
-            url: `${this.config.uploadUrlPrefix}/${fullKey}`,
+            url: `${this.config.uploadUrlPrefix}/${visibility === 'public' ? `${PUBLIC_URL_SEGMENT}/` : ''}${fullKey}`,
             dateLessThan: new Date(Date.now() + UPLOAD_URL_TTL_MS),
         });
         return {
@@ -114,7 +266,7 @@ export class LocalContent {
     }
     async writeFile(args) {
         this.logger.debug(`Writing file: ${args.bucket}/${args.key}`);
-        const path = this.safePath(args.bucket, args.key);
+        const path = this.safePath(args.bucket, args.key, args.visibility);
         try {
             await this.createDirectoryForFile(path);
             const fileStream = createWriteStream(path);
@@ -130,7 +282,7 @@ export class LocalContent {
     async copyFile(args) {
         this.logger.debug(`Writing file: ${args.bucket}/${args.key}`);
         try {
-            const path = this.safePath(args.bucket, args.key);
+            const path = this.safePath(args.bucket, args.key, args.visibility);
             await this.createDirectoryForFile(path);
             await promises.copyFile(args.fromAbsolutePath, path);
             return true;
@@ -143,7 +295,7 @@ export class LocalContent {
     }
     async readFile(args) {
         this.logger.debug(`Getting key: ${args.bucket}/${args.key}`);
-        const filePath = this.safePath(args.bucket, args.key);
+        const filePath = await this.existingPath(args.bucket, args.key, args.visibility);
         try {
             const stream = createReadStream(filePath);
             stream.on('error', (err) => {
@@ -157,14 +309,14 @@ export class LocalContent {
         }
     }
     async readFileAsBuffer(args) {
-        const filePath = this.safePath(args.bucket, args.key);
+        const filePath = await this.existingPath(args.bucket, args.key, args.visibility);
         this.logger.debug(`Reading file as buffer: ${args.bucket}/${args.key}`);
         return readFile(filePath);
     }
     async deleteFile(args) {
         this.logger.debug(`deleting key: ${args.bucket}/${args.key}`);
         try {
-            await promises.unlink(this.safePath(args.bucket, args.key));
+            await promises.unlink(this.safePath(args.bucket, args.key, args.visibility));
             return true;
         }
         catch (e) {
@@ -172,6 +324,38 @@ export class LocalContent {
         }
         return false;
     }
+    async listFilesByPrefix(bucket, prefix, visibility = 'private') {
+        const root = this.safePath(bucket, '', visibility);
+        const keys = [];
+        const walk = async (dir, rel) => {
+            let entries;
+            try {
+                entries = await readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                const next = rel ? `${rel}/${entry.name}` : entry.name;
+                if (entry.isDirectory())
+                    await walk(resolve(dir, entry.name), next);
+                else if (entry.isFile() && next.startsWith(prefix))
+                    keys.push(next);
+            }
+        };
+        this.safePath(bucket, prefix, visibility);
+        await walk(root, '');
+        return keys.sort();
+    }
+    async deleteByPrefix(bucket, prefix, visibility = 'private') {
+        const keys = await this.listFilesByPrefix(bucket, prefix, visibility);
+        let deleted = 0;
+        for (const key of keys) {
+            if (await this.deleteFile({ bucket, key, visibility }))
+                deleted++;
+        }
+        return deleted;
+    }
     async createDirectoryForFile(path) {
         const dir = path.split('/').slice(0, -1).join('/');
         await mkdir(dir, { recursive: true });

package/dist/services/scoped-content-service.d.ts

@@ -0,0 +1,35 @@
+import type { BucketKeyArgs, ContentService, ContentVisibility, CopyFileArgs, GetDownloadURLArgs, GetUploadURLArgs, SignContentKeyArgs, SignURLArgs, UploadURLResult, WriteFileArgs } from './content-service.js';
+export type ContentGrantMode = 'read' | 'write';
+export declare const normaliseContentPath: (value: string) => string;
+/**
+ * A `ContentService` narrowed to one folder of the store.
+ *
+ * Whatever bucket the addon names lands under `<root>/<bucket>`, and the keys
+ * and buckets it passes are refused if they climb out. Starting a bucket with
+ * `@` names a path from the root of the store instead, which only works under
+ * a prefix the host granted: `read` allows reads and signed downloads, `write`
+ * adds uploads, writes and deletes, and the longest matching prefix decides.
+ * `signURL` and `copyFile` take a finished URL or a local filesystem path, so
+ * neither can be narrowed to a folder and both are refused.
+ */
+export declare class ScopedContentService implements ContentService {
+    private content;
+    private root;
+    private grants;
+    constructor(content: ContentService, root: string, grants?: Record<string, ContentGrantMode>);
+    private resolve;
+    private resolveClean;
+    signContentKey(args: SignContentKeyArgs): Promise<string>;
+    signURL(_args: SignURLArgs): Promise<string>;
+    getUploadURL(args: GetUploadURLArgs): Promise<UploadURLResult>;
+    deleteFile(args: BucketKeyArgs): Promise<boolean>;
+    writeFile(args: WriteFileArgs): Promise<boolean>;
+    copyFile(_args: CopyFileArgs): Promise<boolean>;
+    readFile(args: BucketKeyArgs): Promise<ReadableStream | NodeJS.ReadableStream>;
+    readFileAsBuffer(args: BucketKeyArgs): ReturnType<ContentService['readFileAsBuffer']>;
+    getDownloadURL(args: GetDownloadURLArgs): Promise<string>;
+    deleteByPrefix(bucket: string, prefix: string, visibility?: ContentVisibility): Promise<number>;
+    listFilesByPrefix(bucket: string, prefix: string, visibility?: ContentVisibility): Promise<string[]>;
+    private keysUnder;
+    private resolvePrefix;
+}

package/dist/services/scoped-content-service.js

@@ -0,0 +1,171 @@
+const MAX_DECODE_PASSES = 4;
+const denied = (value) => {
+    throw new Error(`Access denied to content path: ${value}`);
+};
+const decoded = (value) => {
+    const passes = [value];
+    let current = value;
+    for (let i = 0; i < MAX_DECODE_PASSES; i++) {
+        let next;
+        try {
+            next = decodeURIComponent(current);
+        }
+        catch {
+            return denied(value);
+        }
+        if (next === current)
+            return passes;
+        passes.push(next);
+        current = next;
+    }
+    return denied(value);
+};
+export const normaliseContentPath = (value) => {
+    for (const pass of decoded(value)) {
+        if (pass.includes('\0'))
+            denied(value);
+        if (pass.startsWith('/') || pass.startsWith('\\'))
+            denied(value);
+        for (const segment of pass.split(/[\\/]/)) {
+            if (segment === '..' || segment === '.')
+                denied(value);
+        }
+    }
+    const segments = value.split('/').filter((segment) => segment !== '');
+    return segments.join('/');
+};
+const under = (path, prefix) => path === prefix || path.startsWith(`${prefix}/`);
+const join = (...parts) => parts.filter((part) => part !== '').join('/');
+/**
+ * A `ContentService` narrowed to one folder of the store.
+ *
+ * Whatever bucket the addon names lands under `<root>/<bucket>`, and the keys
+ * and buckets it passes are refused if they climb out. Starting a bucket with
+ * `@` names a path from the root of the store instead, which only works under
+ * a prefix the host granted: `read` allows reads and signed downloads, `write`
+ * adds uploads, writes and deletes, and the longest matching prefix decides.
+ * `signURL` and `copyFile` take a finished URL or a local filesystem path, so
+ * neither can be narrowed to a folder and both are refused.
+ */
+export class ScopedContentService {
+    content;
+    root;
+    grants;
+    constructor(content, root, grants = {}) {
+        this.content = content;
+        this.root = normaliseContentPath(root);
+        if (!this.root)
+            denied(root);
+        this.grants = Object.entries(grants)
+            .map(([prefix, mode]) => {
+            const clean = normaliseContentPath(prefix);
+            if (!clean)
+                denied(prefix);
+            if (mode !== 'read' && mode !== 'write') {
+                throw new Error(`Content grant '${prefix}' must be 'read' or 'write'`);
+            }
+            return [clean, mode];
+        })
+            .sort(([a], [b]) => b.length - a.length);
+    }
+    resolve(bucket, key, need) {
+        const cleanKey = normaliseContentPath(key);
+        return this.resolveClean(bucket, cleanKey, need);
+    }
+    resolveClean(bucket, cleanKey, need) {
+        if (!bucket.startsWith('@')) {
+            return {
+                bucket: join(this.root, normaliseContentPath(bucket)),
+                key: cleanKey,
+            };
+        }
+        const path = normaliseContentPath(bucket.slice(1));
+        const full = join(path, cleanKey);
+        if (under(full, this.root))
+            return { bucket: path, key: cleanKey };
+        const grant = this.grants.find(([prefix]) => under(full, prefix));
+        if (!grant || (need === 'write' && grant[1] !== 'write')) {
+            return denied(bucket);
+        }
+        return { bucket: path, key: cleanKey };
+    }
+    async signContentKey(args) {
+        const { bucket, key } = this.resolve(args.bucket, args.contentKey, 'read');
+        return this.content.signContentKey({ ...args, bucket, contentKey: key });
+    }
+    async signURL(_args) {
+        throw new Error('signURL is not allowed in scoped content service');
+    }
+    async getUploadURL(args) {
+        const { bucket, key } = this.resolve(args.bucket, args.fileKey, 'write');
+        return this.content.getUploadURL({ ...args, bucket, fileKey: key });
+    }
+    async deleteFile(args) {
+        const { bucket, key } = this.resolve(args.bucket, args.key, 'write');
+        return this.content.deleteFile({ ...args, bucket, key });
+    }
+    async writeFile(args) {
+        const { bucket, key } = this.resolve(args.bucket, args.key, 'write');
+        return this.content.writeFile({ ...args, bucket, key });
+    }
+    async copyFile(_args) {
+        throw new Error('copyFile is not allowed in scoped content service');
+    }
+    async readFile(args) {
+        const { bucket, key } = this.resolve(args.bucket, args.key, 'read');
+        return this.content.readFile({ ...args, bucket, key });
+    }
+    async readFileAsBuffer(args) {
+        const { bucket, key } = this.resolve(args.bucket, args.key, 'read');
+        return this.content.readFileAsBuffer({ ...args, bucket, key });
+    }
+    async getDownloadURL(args) {
+        const { bucket, key } = this.resolve(args.bucket, args.key, 'read');
+        return this.content.getDownloadURL({ ...args, bucket, key });
+    }
+    async deleteByPrefix(bucket, prefix, visibility) {
+        const keys = await this.keysUnder(bucket, prefix, 'write', visibility);
+        const target = this.resolvePrefix(bucket, prefix, 'write');
+        let deleted = 0;
+        for (const key of keys) {
+            if (await this.content.deleteFile({
+                bucket: target.bucket,
+                key,
+                visibility,
+            })) {
+                deleted++;
+            }
+        }
+        return deleted;
+    }
+    async listFilesByPrefix(bucket, prefix, visibility) {
+        return this.keysUnder(bucket, prefix, 'read', visibility);
+    }
+    async keysUnder(bucket, prefix, need, visibility) {
+        const target = this.resolvePrefix(bucket, prefix, need);
+        const keys = await this.content.listFilesByPrefix(target.bucket, target.prefix, visibility);
+        if (!bucket.startsWith('@'))
+            return keys;
+        return keys.filter((key) => {
+            try {
+                this.resolveClean(bucket, normaliseContentPath(key), need);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    resolvePrefix(bucket, prefix, need) {
+        const clean = normaliseContentPath(prefix);
+        const cleanPrefix = clean && prefix.endsWith('/') ? `${clean}/` : clean;
+        if (!bucket.startsWith('@')) {
+            return {
+                bucket: join(this.root, normaliseContentPath(bucket)),
+                prefix: cleanPrefix,
+            };
+        }
+        const resolved = this.resolveClean(bucket, clean, need);
+        return { bucket: resolved.bucket, prefix: cleanPrefix };
+    }
+}

package/dist/types/state.types.d.ts

@@ -42,6 +42,8 @@ export interface PikkuPackageState {
             expose?: boolean | string[];
             /** Required of every function in this package, on top of the function's own */
             scopes?: string[];
+            /** Addons this instance may call: the package it was written against -> the namespace it is wired under here */
+            uses?: Record<string, string>;
             /** Per-instance name-aliases: logical name the addon reads -> actual project secret name */
             secretOverrides?: Record<string, string>;
             /** Per-instance name-aliases: logical name the addon reads -> actual project variable name */
@@ -56,6 +58,12 @@ export interface PikkuPackageState {
             globalSecrets?: string;
             /** Why this instance gets the whole `CredentialService` rather than one scoped to its declared credentials */
             globalCredentials?: string;
+            /** The folder of the content store this instance owns; defaults to its wired name */
+            contentBucket?: string;
+            /** Paths outside its own folder this instance may read or write, by path prefix */
+            contentGrants?: Record<string, 'read' | 'write'>;
+            /** Why this instance gets the whole `ContentService` rather than one scoped to its folder */
+            globalContent?: string;
             /** Set by `wireRemoteAddon`: this namespace is consumed remotely over HTTP, not bundled */
             remote?: boolean;
             /** Remote host base URL (wireRemoteAddon) — string or resolver over singleton services */

package/dist/wirings/addon/addon-reach.d.ts

@@ -0,0 +1,3 @@
+import type { PikkuRawWire } from '../../types/core.types.js';
+export declare const addonMayReach: (caller: string, funcName: string) => boolean;
+export declare const addonCallerOf: (wire: PikkuRawWire) => string | undefined;

package/dist/wirings/addon/addon-reach.js

@@ -0,0 +1,21 @@
+import { ForbiddenError } from '../../errors/errors.js';
+import { ADDON_HEADER } from '../../middleware/addon-scope-cap.js';
+import { pikkuState } from '../../pikku-state.js';
+export const addonMayReach = (caller, funcName) => {
+    const target = funcName.slice(0, Math.max(funcName.indexOf(':'), 0));
+    if (!target)
+        return false;
+    if (target === caller)
+        return true;
+    const uses = pikkuState(null, 'addons', 'packages').get(caller)?.uses;
+    return !!uses && Object.values(uses).includes(target);
+};
+export const addonCallerOf = (wire) => {
+    const name = wire.http?.request?.header(ADDON_HEADER);
+    if (!name)
+        return undefined;
+    if (!pikkuState(null, 'addons', 'packages').has(name)) {
+        throw new ForbiddenError(`Unknown addon '${name}'`);
+    }
+    return name;
+};

package/dist/wirings/addon/addon-runner.d.ts

@@ -13,6 +13,12 @@ export type AddonInstance = {
     globalSecrets?: string;
     /** Set by the consuming app to opt this instance out of credential scoping. */
     globalCredentials?: string;
+    /** Set by the consuming app: the folder of the content store this instance owns. */
+    contentBucket?: string;
+    /** Set by the consuming app: paths outside its folder this instance may read or write. */
+    contentGrants?: Record<string, 'read' | 'write'>;
+    /** Set by the consuming app to opt this instance out of content scoping. */
+    globalContent?: string;
 };
 export declare const getOrCreatePackageSingletonServices: (packageName: string, parentServices: CoreSingletonServices, addonInstance?: AddonInstance) => Promise<CoreSingletonServices>;
 export declare const addonInstanceForNamespace: (namespace: string | undefined, expectedPackage: string) => AddonInstance | undefined;

package/dist/wirings/addon/addon-runner.js

@@ -1,6 +1,7 @@
 import { pikkuState } from '../../pikku-state.js';
 import { ScopedSecretService } from '../../services/scoped-secret-service.js';
 import { ScopedCredentialService } from '../../services/scoped-credential-service.js';
+import { ScopedContentService } from '../../services/scoped-content-service.js';
 /**
  * What the addon declared, plus what the host lent it. Scoping runs outside the
  * aliaser, so every name here is the one the addon reads — which is why an
@@ -105,6 +106,7 @@ const scopeWebhookService = (service, namespace) => {
     return scoped;
 };
 export const getOrCreatePackageSingletonServices = async (packageName, parentServices, addonInstance) => {
+    addonInstance ??= addonInstanceForNamespace(findAddonNamespaceForPackage(packageName) ?? undefined, packageName);
     const cacheKey = addonInstance?.namespace ?? packageName;
     const cachedServices = pikkuState(cacheKey, 'package', 'singletonServices');
     if (cachedServices) {
@@ -137,6 +139,14 @@ export const getOrCreatePackageSingletonServices = async (packageName, parentSer
         };
     }
     const namespace = addonInstance?.namespace ?? findAddonNamespaceForPackage(packageName);
+    if (!addonInstance?.globalContent && existingServices.content) {
+        existingServices = {
+            ...existingServices,
+            content: new ScopedContentService(existingServices.content, addonInstance?.contentBucket ??
+                namespace ??
+                packageName.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, ''), addonInstance?.contentGrants),
+        };
+    }
     if (namespace && existingServices.webhookService) {
         existingServices = {
             ...existingServices,
@@ -176,5 +186,8 @@ export const addonInstanceForNamespace = (namespace, expectedPackage) => {
         credentialGrants: cfg.credentialGrants,
         globalSecrets: cfg.globalSecrets,
         globalCredentials: cfg.globalCredentials,
+        contentBucket: cfg.contentBucket,
+        contentGrants: cfg.contentGrants,
+        globalContent: cfg.globalContent,
     };
 };

package/dist/wirings/addon/define-screens.d.ts

@@ -0,0 +1,32 @@
+type AddonScreenBase = {
+    /** Where the screen mounts under the addon, e.g. `/` or `/:id`. */
+    path: string;
+    title: string;
+    /** Lists the screen in the host's navigation. */
+    nav?: boolean;
+    /** Required of the viewer to see the screen. The addon's functions must enforce the same scopes: hiding a screen is not access control. */
+    scopes?: string[];
+};
+/** A screen rendered by the host from the addon's source. */
+export type AddonComponentScreen = AddonScreenBase & {
+    component: () => Promise<{
+        default: unknown;
+    }>;
+};
+/** A static program the host serves in a sandboxed iframe. */
+export type AddonAppScreen = AddonScreenBase & {
+    /** Directory of the built program, relative to the addon package. */
+    app: string;
+};
+export type AddonScreen = AddonComponentScreen | AddonAppScreen;
+export type ScreensManifest = {
+    title: string;
+    icon?: string;
+    screens: AddonScreen[];
+};
+/**
+ * Declares the screens an addon ships, which the host mounts when it is wired
+ * with `ui: true`. Read statically by `pikku all`, so `path`, `title`, `nav`, `scopes` and `app` must be literals.
+ */
+export declare const defineScreens: (manifest: ScreensManifest) => ScreensManifest;
+export {};

package/dist/wirings/addon/define-screens.js

@@ -0,0 +1,5 @@
+/**
+ * Declares the screens an addon ships, which the host mounts when it is wired
+ * with `ui: true`. Read statically by `pikku all`, so `path`, `title`, `nav`, `scopes` and `app` must be literals.
+ */
+export const defineScreens = (manifest) => manifest;

package/dist/wirings/addon/index.d.ts

@@ -1,5 +1,7 @@
 export { wireAddon } from './wire-addon.js';
 export type { WireAddonConfig } from './wire-addon.js';
+export { defineScreens } from './define-screens.js';
+export type { ScreensManifest, AddonScreen, AddonComponentScreen, AddonAppScreen, } from './define-screens.js';
 export { wireRemoteAddon } from './wire-remote-addon.js';
 export type { WireRemoteAddonConfig, RemoteAddonAuth, } from './wire-remote-addon.js';
 export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';

package/dist/wirings/addon/index.js

@@ -1,3 +1,4 @@
 export { wireAddon } from './wire-addon.js';
+export { defineScreens } from './define-screens.js';
 export { wireRemoteAddon } from './wire-remote-addon.js';
 export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';