@pikku/core 0.12.138 → 0.12.139

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.12.139
+
+### Patch Changes
+
+- a196a21: A call over HTTP that names an add-on in `x-pikku-addon` can only reach that add-on's own functions and the add-ons it lists in `uses`. `rpc.exposed` now refuses anything else, including host functions and an add-on nobody wired, and `AddonNotUsedError` answers 403.
+- 53ac40d: An addon can ship screens: `wireAddon({ ui: true })` mounts what the package declares with `defineScreens`, the inspector reads them, `pikku all` emits the screens manifest and the installed-addons registry, and `x-pikku-addon` narrows a session to the addon's role. `pikku new addon --ui` scaffolds one; its tables must be prefixed `<name>_`.
+- 443fd40: Local content uploads stream to disk instead of being buffered in memory, and a rejected or aborted upload leaves no file behind. A 300 MB upload and read no longer grows the server's memory with the file.
+- 56c8047: Content services support `visibility: 'private' | 'public'` (default private). `ContentService` gains `getDownloadURL`, `deleteByPrefix` and `listFilesByPrefix`. `LocalContent` stores under `private/` and `public/` and serves public files unsigned at `<assetUrlPrefix>/_public/<bucket>/<key>`; unprefixed files from before still read as private, and a private bucket may not be named `_public`. S3 makes public objects `public-read` per object (the bucket must allow ACLs), Backblaze uses `publicBucketId` when set, and the scoped addon content service passes visibility through and keeps the new methods inside the addon's folder.
+
 ## 0.12.138
 
 ### Patch Changes

package/dist/middleware/addon-scope-cap.d.ts

@@ -0,0 +1,19 @@
+export declare const ADDON_HEADER = "x-pikku-addon";
+/**
+ * Narrows the session to what an addon is allowed to do. A call that names an
+ * addon in `x-pikku-addon` keeps only the scopes both the viewer and the
+ * addon's role hold, so an addon's screens can never act beyond what it
+ * declared, whoever is looking at them.
+ *
+ * The header is a selector, not a credential: naming an addon can only
+ * reduce a session, so a caller who sends it by hand has capped themselves. An
+ * addon the host does not know is refused, because ignoring it would let a
+ * misspelt name run uncapped.
+ *
+ * Register it after the session middleware: it narrows a session that is
+ * already resolved, and a call with no session has nothing to narrow.
+ */
+export declare const addonScopeCap: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
+    /** The scopes of the addon's role, or `undefined` when no such addon is installed. */
+    resolve: (name: string) => readonly string[] | undefined | Promise<readonly string[] | undefined>;
+}>;

package/dist/middleware/addon-scope-cap.js

@@ -0,0 +1,34 @@
+import { ForbiddenError } from '../errors/errors.js';
+import { intersectScopes } from '../scopes.js';
+import { pikkuMiddleware, pikkuMiddlewareFactory, } from './middleware-factories.js';
+export const ADDON_HEADER = 'x-pikku-addon';
+/**
+ * Narrows the session to what an addon is allowed to do. A call that names an
+ * addon in `x-pikku-addon` keeps only the scopes both the viewer and the
+ * addon's role hold, so an addon's screens can never act beyond what it
+ * declared, whoever is looking at them.
+ *
+ * The header is a selector, not a credential: naming an addon can only
+ * reduce a session, so a caller who sends it by hand has capped themselves. An
+ * addon the host does not know is refused, because ignoring it would let a
+ * misspelt name run uncapped.
+ *
+ * Register it after the session middleware: it narrows a session that is
+ * already resolved, and a call with no session has nothing to narrow.
+ */
+export const addonScopeCap = pikkuMiddlewareFactory(({ resolve }) => pikkuMiddleware(async (_services, { http, setSession, getSession }, next) => {
+    const name = http?.request?.header(ADDON_HEADER);
+    const session = await getSession?.();
+    if (!name || !setSession || !session) {
+        return next();
+    }
+    const role = await resolve(name);
+    if (!role) {
+        throw new ForbiddenError(`Unknown addon '${name}'`);
+    }
+    await setSession({
+        ...session,
+        scopes: intersectScopes(session.scopes, role),
+    });
+    return next();
+}));

package/dist/middleware/index.d.ts

@@ -1,6 +1,7 @@
 export { authAPIKey } from './auth-apikey.js';
 export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
+export { addonScopeCap, ADDON_HEADER, } from './addon-scope-cap.js';
 export { remoteJobsSecret } from './remote-jobs-secret.js';
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';

package/dist/middleware/index.js

@@ -1,6 +1,7 @@
 export { authAPIKey } from './auth-apikey.js';
 export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
+export { addonScopeCap, ADDON_HEADER, } from './addon-scope-cap.js';
 export { remoteJobsSecret } from './remote-jobs-secret.js';
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';

package/dist/scopes.d.ts

@@ -21,3 +21,11 @@ export declare const hasAnyScope: (candidates: readonly string[] | undefined, he
  * nothing.
  */
 export declare const verifyScopes: (required: readonly string[] | undefined, session: CoreUserSession | undefined) => void;
+/**
+ * The scopes both `held` and `cap` grant, by the same parent and wildcard rules
+ * as {@link hasScopes}. Where one side is broader, the narrower grant is kept:
+ * a holder of `invoices:*` capped to `invoices:read` ends with `invoices:read`,
+ * and a holder of `invoices:read` capped to `invoices:*` keeps `invoices:read`.
+ * Fails closed: nothing held, or an empty cap, yields nothing.
+ */
+export declare const intersectScopes: (held: Iterable<string> | undefined, cap: Iterable<string> | undefined) => string[];

package/dist/scopes.js

@@ -64,3 +64,26 @@ export const verifyScopes = (required, session) => {
         throw new MissingScopeError(missing);
     }
 };
+/**
+ * The scopes both `held` and `cap` grant, by the same parent and wildcard rules
+ * as {@link hasScopes}. Where one side is broader, the narrower grant is kept:
+ * a holder of `invoices:*` capped to `invoices:read` ends with `invoices:read`,
+ * and a holder of `invoices:read` capped to `invoices:*` keeps `invoices:read`.
+ * Fails closed: nothing held, or an empty cap, yields nothing.
+ */
+export const intersectScopes = (held, cap) => {
+    const heldSet = new Set(held ?? []);
+    const capSet = new Set(cap ?? []);
+    const result = new Set();
+    for (const scope of heldSet) {
+        if (holds(capSet, scope)) {
+            result.add(scope);
+        }
+    }
+    for (const scope of capSet) {
+        if (holds(heldSet, scope)) {
+            result.add(scope);
+        }
+    }
+    return [...result];
+};

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

@@ -1,6 +1,8 @@
+export type ContentVisibility = 'private' | 'public';
 export interface SignContentKeyArgs<TBucket extends string = string> {
     bucket: TBucket;
     contentKey: string;
+    visibility?: ContentVisibility;
     dateLessThan: Date;
     dateGreaterThan?: Date;
 }
@@ -14,7 +16,7 @@ export interface GetUploadURLArgs<TBucket extends string = string> {
     fileKey: string;
     contentType: string;
     size?: number;
-    visibility?: 'private' | 'public';
+    visibility?: ContentVisibility;
 }
 export interface UploadURLResult {
     uploadUrl: string;
@@ -25,6 +27,10 @@ export interface UploadURLResult {
 export interface BucketKeyArgs<TBucket extends string = string> {
     bucket: TBucket;
     key: string;
+    visibility?: ContentVisibility;
+}
+export interface GetDownloadURLArgs<TBucket extends string = string> extends BucketKeyArgs<TBucket> {
+    expiresInSeconds?: number;
 }
 export interface WriteFileArgs<TBucket extends string = string> extends BucketKeyArgs<TBucket> {
     stream: ReadableStream | NodeJS.ReadableStream;
@@ -42,4 +48,10 @@ export interface ContentService<TBucket extends string = string> {
     copyFile(args: CopyFileArgs<TBucket>): Promise<boolean>;
     readFile(args: BucketKeyArgs<TBucket>): Promise<ReadableStream | NodeJS.ReadableStream>;
     readFileAsBuffer(args: BucketKeyArgs<TBucket>): Promise<Buffer>;
+    /** A signed URL for private content, the plain URL for public content. */
+    getDownloadURL(args: GetDownloadURLArgs<TBucket>): Promise<string>;
+    /** Returns how many files were deleted. */
+    deleteByPrefix(bucket: TBucket, prefix: string, visibility?: ContentVisibility): Promise<number>;
+    /** Returns the keys, relative to the bucket, that start with the prefix. */
+    listFilesByPrefix(bucket: TBucket, prefix: string, visibility?: ContentVisibility): Promise<string[]>;
 }

package/dist/services/index.d.ts

@@ -1,6 +1,7 @@
 export { LogLevel } from './logger.js';
 export { ScopedSecretService } from './scoped-secret-service.js';
 export { ScopedCredentialService } from './scoped-credential-service.js';
+export { ScopedContentService } from './scoped-content-service.js';
 export { PikkuSessionService, createMiddlewareSessionWireProps, } from './user-session-service.js';
 export { TypedSecretService } from './typed-secret-service.js';
 export { PikkuCredentialWireService } from './credential-wire-service.js';
@@ -21,7 +22,7 @@ export { LeaseLostError, LeaseTakenError, holdLease, type Lease, type LeaseServi
 export { InMemoryLeaseService } from './in-memory-lease-service.js';
 export { InMemoryAgentRunStateService } from './in-memory-agent-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
-export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
+export type { ContentService, ContentVisibility, GetDownloadURLArgs, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
 export type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, } from './personas-service.js';
 export type { JWTService } from './jwt-service.js';
 export type { EmailAttachment, EmailService, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';

package/dist/services/index.js

@@ -1,6 +1,7 @@
 export { LogLevel } from './logger.js';
 export { ScopedSecretService } from './scoped-secret-service.js';
 export { ScopedCredentialService } from './scoped-credential-service.js';
+export { ScopedContentService } from './scoped-content-service.js';
 export { PikkuSessionService, createMiddlewareSessionWireProps, } from './user-session-service.js';
 export { TypedSecretService } from './typed-secret-service.js';
 export { PikkuCredentialWireService } from './credential-wire-service.js';

package/dist/services/local-content-request-handler.js

@@ -1,37 +1,9 @@
 import { createReadStream } from 'fs';
-import { mkdir, stat, writeFile } from 'fs/promises';
-import { normalize, resolve } from 'path';
+import { stat } from 'fs/promises';
 import { Readable } from 'stream';
-import { signedContentPath } from './local-content.js';
+import { UploadTooLargeError, parseContentSizeLimit, resolveContentRequestTarget, signedContentPath, streamUploadToFile, } from './local-content.js';
 const matchesPrefix = (pathname, prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`);
 const contentKey = (pathname, prefix) => pathname.slice(prefix.length).replace(/^\/+/, '');
-/**
- * Resolve a key against the content root, or `null` if it escapes. `normalize`
- * first so `..` segments are collapsed before the prefix check, and the
- * comparison carries a trailing separator so a sibling directory whose name
- * merely starts with the root's cannot pass as being inside it.
- */
-const toTargetPath = (basePath, key) => {
-    const normalizedBasePath = resolve(basePath);
-    const targetPath = resolve(normalizedBasePath, normalize(key));
-    return targetPath.startsWith(`${normalizedBasePath}/`) ? targetPath : null;
-};
-const parseSizeLimit = (sizeLimit) => {
-    const match = /^(\d+(?:\.\d+)?)(b|kb|mb|gb)?$/i.exec(sizeLimit.trim());
-    if (!match) {
-        throw new Error(`Invalid size limit: ${sizeLimit}`);
-    }
-    const value = Number(match[1]);
-    const unit = (match[2] ?? 'b').toLowerCase();
-    const multiplier = unit === 'gb'
-        ? 1024 * 1024 * 1024
-        : unit === 'mb'
-            ? 1024 * 1024
-            : unit === 'kb'
-                ? 1024
-                : 1;
-    return value * multiplier;
-};
 const text = (status, body) => new Response(body, {
     status,
     headers: { 'content-type': 'text/plain; charset=utf-8' },
@@ -112,47 +84,36 @@ export const createLocalContentRequestHandler = ({ content, logger, getJWT, }) =
             return text(signed.status, signed.body);
         }
         const key = contentKey(pathname, content.uploadUrlPrefix);
-        const targetPath = toTargetPath(content.localFileUploadPath, key);
-        if (!targetPath) {
+        const target = await resolveContentRequestTarget(content.localFileUploadPath, key, 'write');
+        if (!target) {
             return text(400, 'Invalid path');
         }
-        const maxBytes = parseSizeLimit(content.sizeLimit ?? '1mb');
-        // knowledge: decisions/security/an-upload-is-counted-as-it-arrives-not-buffered-then-measured.md
-        const chunks = [];
-        let bytesRead = 0;
-        const reader = request.body?.getReader();
-        if (reader) {
-            try {
-                for (;;) {
-                    const { done, value } = await reader.read();
-                    if (done)
-                        break;
-                    bytesRead += value.byteLength;
-                    if (bytesRead > maxBytes) {
-                        await reader.cancel();
-                        return text(413, 'Content too large');
-                    }
-                    chunks.push(Buffer.from(value));
-                }
-            }
-            finally {
-                reader.releaseLock();
+        try {
+            await streamUploadToFile(request.body
+                ? Readable.fromWeb(request.body)
+                : (async function* () { })(), target.path, parseContentSizeLimit(content.sizeLimit ?? '1mb'));
+        }
+        catch (error) {
+            if (error instanceof UploadTooLargeError) {
+                return text(413, 'Content too large');
             }
+            throw error;
         }
-        await mkdir(resolve(targetPath, '..'), { recursive: true });
-        await writeFile(targetPath, Buffer.concat(chunks));
         return new Response(null, { status: 200 });
     };
     const handleAsset = async (request, requestUrl, pathname) => {
         const key = contentKey(pathname, content.assetUrlPrefix);
-        const targetPath = toTargetPath(content.localFileUploadPath, key);
-        if (!targetPath) {
+        const target = await resolveContentRequestTarget(content.localFileUploadPath, key, 'read');
+        if (!target) {
             return text(400, 'Invalid path');
         }
-        const signed = await validateSignedAssetRequest(requestUrl);
-        if (!signed.ok) {
-            return text(signed.status, signed.body);
+        if (target.visibility === 'private') {
+            const signed = await validateSignedAssetRequest(requestUrl);
+            if (!signed.ok) {
+                return text(signed.status, signed.body);
+            }
         }
+        const targetPath = target.path;
         try {
             const file = await stat(targetPath);
             if (!file.isFile()) {

package/dist/services/local-content.d.ts

@@ -1,4 +1,4 @@
-import type { BucketKeyArgs, ContentService, CopyFileArgs, GetUploadURLArgs, JWTService, Logger, SignContentKeyArgs, SignURLArgs, UploadURLResult, WriteFileArgs } from '@pikku/core/services';
+import type { BucketKeyArgs, ContentService, ContentVisibility, GetDownloadURLArgs, CopyFileArgs, GetUploadURLArgs, JWTService, Logger, SignContentKeyArgs, SignURLArgs, UploadURLResult, WriteFileArgs } from '@pikku/core/services';
 export interface LocalContentConfig {
     localFileUploadPath: string;
     uploadUrlPrefix: string;
@@ -17,17 +17,59 @@ export interface LocalContentConfig {
  * rather than throwing, which keeps both sides in agreement.
  */
 export declare const signedContentPath: (urlOrPath: string) => string;
+export declare const PUBLIC_URL_SEGMENT = "_public";
+export declare const CONTENT_VISIBILITIES: readonly ContentVisibility[];
+export type ContentUrlPath = {
+    visibility: ContentVisibility;
+    rest: string;
+    prefixed: boolean;
+};
+/**
+ * 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 declare const parseContentUrlPath: (key: string) => ContentUrlPath;
+/**
+ * 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 declare const resolveVisibilityPath: (basePath: string, visibility: ContentVisibility, bucket: string, key: string) => string | null;
+export type ContentRequestTarget = {
+    path: string;
+    visibility: ContentVisibility;
+};
+/**
+ * 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 declare const resolveContentRequestTarget: (basePath: string, key: string, mode: 'read' | 'write') => Promise<ContentRequestTarget | null>;
+export declare class UploadTooLargeError extends Error {
+    constructor();
+}
+export declare const parseContentSizeLimit: (sizeLimit: string) => number;
+export declare const streamUploadToFile: (source: AsyncIterable<Uint8Array>, targetPath: string, maxBytes: number) => Promise<number>;
 export declare class LocalContent implements ContentService {
     private config;
     private logger;
     private jwt;
     constructor(config: LocalContentConfig, logger: Logger, jwt: JWTService);
     private safePath;
+    private existingPath;
+    private legacyPath;
+    private publicBase;
     private joinKey;
     init(): Promise<void>;
     private signParams;
     signURL(args: SignURLArgs): Promise<string>;
     signContentKey(args: SignContentKeyArgs): Promise<string>;
+    getDownloadURL(args: GetDownloadURLArgs): Promise<string>;
     /**
      * Presigned upload, mirroring the read side: the URL carries a short-lived,
      * path-bound signature that {@link createLocalContentRequestHandler} verifies
@@ -40,5 +82,7 @@ export declare class LocalContent implements ContentService {
     readFile(args: BucketKeyArgs): Promise<ReadableStream | NodeJS.ReadableStream>;
     readFileAsBuffer(args: BucketKeyArgs): Promise<Buffer>;
     deleteFile(args: BucketKeyArgs): Promise<boolean>;
+    listFilesByPrefix(bucket: string, prefix: string, visibility?: ContentVisibility): Promise<string[]>;
+    deleteByPrefix(bucket: string, prefix: string, visibility?: ContentVisibility): Promise<number>;
     private createDirectoryForFile;
 }