@pikku/core 0.12.74 → 0.12.77

package/dist/function/index.d.ts

@@ -1,4 +1,4 @@
 export { addFunction, getAllFunctionNames } from './function-runner.js';
 export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, pikkuApprovalDescription, } from './functions.types.js';
-export type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission, } from './functions.types.js';
+export type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuFunctionConfig, CorePikkuSessionlessFunctionConfig, CorePikkuAuth, CorePikkuAuthConfig, CorePikkuPermission, } from './functions.types.js';
 export type { ListInput, ListOutput, Filter, LeafFilter, LeafValue, } from './list.types.js';

package/dist/index.d.ts

@@ -36,8 +36,8 @@ export type { GatewayService } from './services/gateway-service.js';
 export type { TriggerService } from './services/trigger-service.js';
 export type { SchemaService } from './services/schema-service.js';
 export type { SessionService } from './services/user-session-service.js';
-export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './services/audit-service.js';
-export type { AuditActor, AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditLogWriteInput, AuditOutcome, AuditService, AuditSource, ResolvedAuditConfig, } from './services/audit-service.js';
+export { NoopAuditService, createInvocationAudit, resolveAuditConfig, resolveAuditUserIdentityFromWire, } from './services/audit-service.js';
+export type { AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditFacets, AuditLog, AuditLogWriteInput, AuditOutcome, AuditQuery, AuditQueryResult, AuditService, AuditSource, AuditUserIdentity, ResolvedAuditConfig, } from './services/audit-service.js';
 export type { AIAgentRunnerService, AIEmbedManyParams, AIEmbedManyResult, AIEmbedParams, AIEmbedResult, AIGenerateImageParams, AIGenerateImagePrompt, AIGenerateImageResult, AIGenerateSpeechParams, AIGenerateSpeechResult, AIProviderOptions, AIRerankParams, AIRerankResult, AITranscriptionParams, AITranscriptionResult, } from './services/ai-agent-runner-service.js';
 export type { AIEmbeddingService } from './services/ai-embedding-service.js';
 export type { AIRunStateService } from './services/ai-run-state-service.js';
@@ -59,4 +59,7 @@ export { getSingletonServices, getCreateWireServices, setSingletonServices, } fr
 export { clearPikkuRuntimeState } from './test-utils.js';
 export { type ScheduledTaskInfo, type ScheduledTaskSummary, } from './services/scheduler-service.js';
 export { SchedulerService } from './services/scheduler-service.js';
-export type { Private, Pii, Secret, Classification, AnonymizeStrategy, ColumnClassification, ClassificationManifest, } from './data-classification.js';
+export type { Private, Pii, Secret, Classification, AnonymizeStrategy, ColumnClassification, ClassificationManifest, ColumnForm, WrappedValue, SealedValue, HashedValue, } from './data-classification.js';
+export { hashToken, unsafeAsWrapped, unsafeAsSealed, unsafeAsHashed, } from './column-form.js';
+export type { SecretValue, Safe } from './secret-value.js';
+export { createSecretValue, isSecretValue, SecretCoercionError, REDACTED, } from './secret-value.js';

package/dist/index.js

@@ -15,7 +15,7 @@ export { AIProviderAuthError, AIProviderNotConfiguredError, BadGatewayError, Bad
 export { PikkuError, isExpectedError } from './errors/error-handler.js';
 export { SecretAccessDeniedError, withoutSecrets, } from './services/secretless.js';
 export { SecretHostNotAllowedError, assertSecretAllowedForHost, } from './services/secret-host-binding.js';
-export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './services/audit-service.js';
+export { NoopAuditService, createInvocationAudit, resolveAuditConfig, resolveAuditUserIdentityFromWire, } from './services/audit-service.js';
 export { createGraph } from './wirings/workflow/graph/graph-node.js';
 export { wireAddon } from './wirings/rpc/wire-addon.js';
 export { wireRemoteAddon } from './wirings/rpc/wire-remote-addon.js';
@@ -26,3 +26,5 @@ export { isSerializable, stopSingletonServices, pikkuServerLifecycle, } from './
 export { getSingletonServices, getCreateWireServices, setSingletonServices, } from './pikku-state.js';
 export { clearPikkuRuntimeState } from './test-utils.js';
 export { SchedulerService } from './services/scheduler-service.js';
+export { hashToken, unsafeAsWrapped, unsafeAsSealed, unsafeAsHashed, } from './column-form.js';
+export { createSecretValue, isSecretValue, SecretCoercionError, REDACTED, } from './secret-value.js';

package/dist/middleware/auth-bearer.js

@@ -33,9 +33,10 @@ export const authBearer = pikkuMiddlewareFactory(({ token } = {}) => pikkuMiddle
             }
             else {
                 // An unset secret means the feature is off — never a request error.
-                expected = await secrets
+                const stored = await secrets
                     ?.getSecret(token.secretId)
                     .catch(() => undefined);
+                expected = stored?.reveal();
             }
             if (expected && constantTimeEqual(bearerToken, expected)) {
                 userSession = token.userSession;

package/dist/middleware/remote-auth.js

@@ -7,7 +7,7 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }
     }
     let secret;
     try {
-        secret = await secrets.getSecret('PIKKU_REMOTE_SECRET');
+        secret = (await secrets.getSecret('PIKKU_REMOTE_SECRET')).reveal();
     }
     catch {
         if (http.request.path().startsWith('/remote/rpc/')) {

package/dist/remote.js

@@ -11,7 +11,7 @@ export async function buildRemoteHeaders(jwt, secrets, funcName, session, traceI
     };
     let secret;
     try {
-        secret = await secrets?.getSecret('PIKKU_REMOTE_SECRET');
+        secret = (await secrets?.getSecret('PIKKU_REMOTE_SECRET'))?.reveal();
     }
     catch { }
     if (secret && jwt) {

package/dist/secret-value.d.ts

@@ -0,0 +1,56 @@
+import type { Secret } from './data-classification.js';
+declare const secretValueBrand: unique symbol;
+export declare const REDACTED = "[secret]";
+/** Runtime marker, resilient to duplicate copies of core. */
+declare const SECRET_VALUE: unique symbol;
+declare const NODE_INSPECT: unique symbol;
+export declare class SecretCoercionError extends Error {
+    constructor();
+}
+/**
+ * A vault secret. Nominal, so it is not assignable to `string` and every
+ * concretely-typed sink rejects it; `.reveal()` is the one way out, and every
+ * call is a deliberate, greppable disclosure.
+ *
+ * The revealed value carries the erasable `Secret<T>` classification brand, so
+ * the inspector can still follow it one hop past the call.
+ *
+ * Structured serialization redacts to `[secret]` — an audit or log write must
+ * stay honest about the field without crashing the request. String coercion
+ * throws, because a template literal or concatenation is always a leak.
+ */
+export declare class SecretValue<T = string> {
+    #private;
+    readonly [secretValueBrand]: true;
+    readonly [SECRET_VALUE] = true;
+    constructor(value: T);
+    reveal(): Secret<T>;
+    toJSON(): string;
+    [NODE_INSPECT](): string;
+    toString(): never;
+    [Symbol.toPrimitive](): never;
+}
+export declare const createSecretValue: <T>(value: T) => SecretValue<T>;
+export declare const isSecretValue: (value: unknown) => value is SecretValue<unknown>;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type Passthrough = Function | Date | RegExp | Error | ArrayBuffer | ArrayBufferView;
+/**
+ * Rejects a `SecretValue` anywhere in `T`, however deeply nested, by collapsing
+ * it to `never`.
+ *
+ * For sinks whose parameters are `any`, `unknown` or a free generic — loggers,
+ * queue payloads, channel messages — where nominality alone cannot help.
+ * `any` is passed through untouched: it cannot be guarded, and collapsing it
+ * would reject every legitimate call.
+ *
+ * `Promise`, `Map` and `Set` are recursed into rather than passed through. A
+ * mapped type cannot reach what they hold — mapping their keys yields their
+ * methods, not their contents — so treating them as opaque let a secret ride
+ * through inside one. `Promise` is the case that bites: `getSecret()` returns
+ * `Promise<SecretValue<T>>`, so a forgotten `await` would otherwise log a
+ * secret.
+ */
+export type Safe<T> = IsAny<T> extends true ? T : [Extract<T, SecretValue<any>>] extends [never] ? T extends Promise<infer V> ? Promise<Safe<V>> : T extends Map<infer K, infer V> ? Map<Safe<K>, Safe<V>> : T extends Set<infer V> ? Set<Safe<V>> : T extends Passthrough ? T : T extends object ? {
+    [K in keyof T]: Safe<T[K]>;
+} : T : never;
+export {};

package/dist/secret-value.js

@@ -0,0 +1,46 @@
+export const REDACTED = '[secret]';
+/** Runtime marker, resilient to duplicate copies of core. */
+const SECRET_VALUE = Symbol.for('pikku.secretValue');
+const NODE_INSPECT = Symbol.for('nodejs.util.inspect.custom');
+export class SecretCoercionError extends Error {
+    constructor() {
+        super(`A secret was coerced to a string, which would write it out in the clear. Unwrap it deliberately with .reveal() at the point it reaches the wire.`);
+        this.name = 'SecretCoercionError';
+    }
+}
+/**
+ * A vault secret. Nominal, so it is not assignable to `string` and every
+ * concretely-typed sink rejects it; `.reveal()` is the one way out, and every
+ * call is a deliberate, greppable disclosure.
+ *
+ * The revealed value carries the erasable `Secret<T>` classification brand, so
+ * the inspector can still follow it one hop past the call.
+ *
+ * Structured serialization redacts to `[secret]` — an audit or log write must
+ * stay honest about the field without crashing the request. String coercion
+ * throws, because a template literal or concatenation is always a leak.
+ */
+export class SecretValue {
+    [SECRET_VALUE] = true;
+    #value;
+    constructor(value) {
+        this.#value = value;
+    }
+    reveal() {
+        return this.#value;
+    }
+    toJSON() {
+        return REDACTED;
+    }
+    [NODE_INSPECT]() {
+        return REDACTED;
+    }
+    toString() {
+        throw new SecretCoercionError();
+    }
+    [Symbol.toPrimitive]() {
+        throw new SecretCoercionError();
+    }
+}
+export const createSecretValue = (value) => new SecretValue(value);
+export const isSecretValue = (value) => typeof value === 'object' && value !== null && SECRET_VALUE in value;

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

@@ -1,5 +1,6 @@
 import type { CoreUserSession, PikkuWire, PikkuWiringTypes } from '../types/core.types.js';
 import type { Logger } from './logger.js';
+import type { Safe } from '../secret-value.js';
 export type AuditDurability = 'best-effort' | 'transactional';
 export type AuditOutcome = 'success' | 'failed' | 'denied';
 export type AuditSource = 'auto' | 'explicit';
@@ -9,7 +10,19 @@ export type AuditConfig = boolean | {
 export type ResolvedAuditConfig = {
     durability: AuditDurability;
 };
-export type AuditActor = {
+/**
+ * Who an event happened under.
+ *
+ * A user, not an "actor": in pikku an actor is a synthetic person a scenario
+ * drives, flagged `actor` on the user row, and the overwhelming majority of
+ * audited events are caused by ordinary customers. Naming this `actor` made the
+ * synthetic case unsayable — `actor.actor === true` — and implied every
+ * recorded action was a test.
+ *
+ * `pikkuUserId` is the identity pikku resolves for every wire, so it is the one
+ * field a signed-out caller still leaves behind.
+ */
+export type AuditUserIdentity = {
     userId?: string;
     orgId?: string;
     pikkuUserId?: string;
@@ -26,26 +39,83 @@ export type AuditEvent = {
     traceId?: string;
     transactionId?: string | null;
     queryId?: string | null;
-    actor?: AuditActor;
+    userIdentity?: AuditUserIdentity;
     input?: unknown;
     metadata?: Record<string, unknown>;
 };
 export type AuditEventBatch = AuditEvent[];
+/**
+ * A page of the trail, newest first, narrowed by the filters a reader picked.
+ *
+ * Every field is a conjunction, and an empty array is not a filter — it is
+ * "match nothing", which would otherwise read as "match everything" and quietly
+ * widen a scoped query.
+ */
+export type AuditQuery = {
+    /** Restrict to these users. */
+    userIds?: string[];
+    /** Restrict to these `AuditEvent['type']` values. */
+    types?: string[];
+    /** Restrict to one organisation. */
+    orgId?: string;
+    /** Inclusive lower bound on `occurredAt` (ISO 8601). */
+    from?: string;
+    /** Exclusive upper bound on `occurredAt` (ISO 8601). */
+    to?: string;
+    limit?: number;
+    offset?: number;
+};
+/**
+ * The distinct values present in the trail, for populating filter controls.
+ *
+ * Computed over the whole trail rather than the current page — a filter list
+ * that only offered what the current page happens to show could never be used
+ * to reach anything else.
+ */
+export type AuditFacets = {
+    userIds: string[];
+    types: string[];
+};
+export type AuditQueryResult = {
+    events: AuditEvent[];
+    /** Offset of the next page, or `null` at the end. */
+    nextCursor: number | null;
+    /** Present only when the caller asked for it — it costs two extra scans. */
+    facets?: AuditFacets;
+};
 export interface AuditService {
     audit(event: AuditEvent): Promise<void>;
     write?(batch: AuditEventBatch): Promise<void>;
+    /**
+     * The read side. Optional because a sink can legitimately be write-only — a
+     * queue producer that hands events to another system has nothing to read
+     * back. A reader that finds this absent should say the trail is not readable
+     * here rather than that it is empty; the two are very different answers.
+     */
+    query?(query: AuditQuery): Promise<AuditQueryResult>;
+    /** Distinct users and types across the whole trail. Paired with {@link query}. */
+    facets?(): Promise<AuditFacets>;
 }
 export declare class NoopAuditService implements AuditService {
     audit(_event: AuditEvent): Promise<void>;
     write(_batch: AuditEventBatch): Promise<void>;
 }
 export type AuditLogWriteInput = Omit<AuditEvent, 'occurredAt'>;
+/**
+ * The audit an invocation writes to. `write` is `Safe<>`-guarded like the
+ * logger: an audit event carries `input` and `metadata` as `unknown`, so
+ * nominality alone cannot stop a `SecretValue` landing in one. A secret
+ * anywhere in the event, however deeply nested, collapses to `never`.
+ *
+ * An unrevealed `SecretValue` would serialize as `[secret]` anyway; the guard
+ * is what makes that an explicit choice rather than a near miss.
+ */
 export interface AuditLog {
     readonly config: ResolvedAuditConfig | undefined;
-    write(event: AuditLogWriteInput): Promise<void>;
+    write<E extends AuditLogWriteInput>(event: Safe<E>): Promise<void>;
     flush(): Promise<void>;
     close(): Promise<void>;
 }
 export declare const resolveAuditConfig: (config?: AuditConfig) => ResolvedAuditConfig | undefined;
 export declare const createInvocationAudit: (service: AuditService, wire: PikkuWire<any, any, any, CoreUserSession>, logger?: Logger) => AuditLog;
-export declare const resolveAuditActorFromWire: (wire: PikkuWire<any, any, any, CoreUserSession>) => AuditActor | undefined;
+export declare const resolveAuditUserIdentityFromWire: (wire: PikkuWire<any, any, any, CoreUserSession>) => AuditUserIdentity | undefined;

package/dist/services/audit-service.js

@@ -75,7 +75,7 @@ class InvocationAuditLog {
             wireType: this.wire.wireType,
             wireId: this.wire.wireId,
             traceId: this.wire.traceId,
-            actor: event.actor ?? resolveAuditActorFromWire(this.wire),
+            userIdentity: event.userIdentity ?? resolveAuditUserIdentityFromWire(this.wire),
             ...event,
             occurredAt: new Date().toISOString(),
         };
@@ -98,15 +98,17 @@ export const createInvocationAudit = (service, wire, logger) => {
     }
     return new InvocationAuditLog(wire.audit, service, wire, logger);
 };
-export const resolveAuditActorFromWire = (wire) => {
+export const resolveAuditUserIdentityFromWire = (wire) => {
     const session = wire.session;
-    const actor = {
+    const userIdentity = {
         userId: session?.userId,
         orgId: session?.orgId,
         pikkuUserId: wire.pikkuUserId,
     };
-    if (!actor.userId && !actor.orgId && !actor.pikkuUserId) {
+    if (!userIdentity.userId &&
+        !userIdentity.orgId &&
+        !userIdentity.pikkuUserId) {
         return undefined;
     }
-    return actor;
+    return userIdentity;
 };

package/dist/services/credential-wire-service.d.ts

@@ -9,6 +9,11 @@ export declare class PikkuCredentialWireService {
     private loadPromise;
     constructor(credentialService?: CredentialService | undefined, wire?: PikkuRawWire | undefined, aliases?: Record<string, string> | undefined);
     private resolveName;
+    /**
+     * A credential is one of the few places vault material is meant to end up, so
+     * a `SecretValue` is unwrapped here rather than rejected — `get` promises the
+     * raw material, and storing the wrapper would make that a lie.
+     */
     set(name: string, value: unknown): void;
     get<T = unknown>(name: string): T | null | Promise<T | null>;
     getAll(): Record<string, unknown> | Promise<Record<string, unknown>>;

package/dist/services/credential-wire-service.js

@@ -1,3 +1,4 @@
+import { isSecretValue } from '../secret-value.js';
 import { defaultPikkuUserIdResolver } from './pikku-user-id.js';
 export class PikkuCredentialWireService {
     credentialService;
@@ -14,8 +15,15 @@ export class PikkuCredentialWireService {
     resolveName(name) {
         return this.aliases?.[name] ?? name;
     }
+    /**
+     * A credential is one of the few places vault material is meant to end up, so
+     * a `SecretValue` is unwrapped here rather than rejected — `get` promises the
+     * raw material, and storing the wrapper would make that a lie.
+     */
     set(name, value) {
-        this.credentials[this.resolveName(name)] = value;
+        this.credentials[this.resolveName(name)] = isSecretValue(value)
+            ? value.reveal()
+            : value;
     }
     get(name) {
         const key = this.resolveName(name);

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

@@ -1,3 +1,4 @@
+import type { Safe } from '../secret-value.js';
 export interface EmailTemplateReference {
     name: string;
     locale?: string;
@@ -32,5 +33,5 @@ export interface SendEmailResult {
     messageId?: string;
 }
 export interface EmailService {
-    send(input: SendEmailInput): Promise<SendEmailResult>;
+    send<T extends SendEmailInput>(input: Safe<T>): Promise<SendEmailResult>;
 }

package/dist/services/index.d.ts

@@ -22,7 +22,7 @@ export type { JWTService } from './jwt-service.js';
 export type { EmailService, EmailTemplateReference, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
 export { DEFAULT_WEBHOOK_RETRIES, DEFAULT_WEBHOOK_SIGNATURE_HEADER, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, type SendWebhookInput, type SendWebhookResult, type WebhookAttemptRecord, type WebhookAttemptResult, type WebhookDeliveryRecord, type WebhookDeliveryWithAttempts, type WebhookJobData, type WebhookServiceConfig, } from './webhook-service.js';
 export type { Logger } from './logger.js';
-export type { SecretService } from './secret-service.js';
+export type { SecretService, SecretValues } from './secret-service.js';
 export type { VariablesService } from './variables-service.js';
 export type { SchemaService } from './schema-service.js';
 export type { SessionService } from './user-session-service.js';
@@ -44,8 +44,8 @@ export type { SessionStore } from './session-store.js';
 export type { ScopeService, Role } from './scope-service.js';
 export { assertRoleIsMutable, assertRoleNameAvailable, roleLockReason, } from './system-role-guard.js';
 export type { IsSystemRole } from './system-role-guard.js';
-export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './audit-service.js';
-export type { AuditActor, AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditLogWriteInput, AuditOutcome, AuditService, AuditSource, ResolvedAuditConfig, } from './audit-service.js';
+export { NoopAuditService, createInvocationAudit, resolveAuditConfig, resolveAuditUserIdentityFromWire, } from './audit-service.js';
+export type { AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditLogWriteInput, AuditOutcome, AuditService, AuditSource, AuditUserIdentity, ResolvedAuditConfig, } from './audit-service.js';
 export { InMemorySessionStore } from './in-memory-session-store.js';
 export type { MCPMeta, RPCMetaRecord, ServiceMeta, ServicesMetaRecord, MiddlewareDefinitionMeta, MiddlewareInstanceMeta, GroupMeta, MiddlewareGroupsMeta, PermissionDefinitionMeta, PermissionsGroupsMeta, FunctionsMeta, FunctionMeta, MiddlewareMeta, PermissionMeta, AgentsMeta, AgentMeta, EmailsMeta, EmailTemplateMeta, EmailTemplateLocaleMeta, EmailTemplateAssets, } from './meta-service.js';
 export type { CoverageService, CoverageSnapshot, LineHits, ScriptCoverage, FunctionCoverage, CoverageRange, CoverageStatus, FunctionCoverageEntry, FunctionCoverageReport, CoverageFunctionMeta, } from './v8-coverage-service.js';

package/dist/services/index.js

@@ -18,7 +18,7 @@ export { LocalGatewayService } from './local-gateway-service.js';
 export { DEFAULT_WEBHOOK_RETRIES, DEFAULT_WEBHOOK_SIGNATURE_HEADER, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
 export { TypedCredentialService } from './typed-credential-service.js';
 export { assertRoleIsMutable, assertRoleNameAvailable, roleLockReason, } from './system-role-guard.js';
-export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './audit-service.js';
+export { NoopAuditService, createInvocationAudit, resolveAuditConfig, resolveAuditUserIdentityFromWire, } from './audit-service.js';
 export { InMemorySessionStore } from './in-memory-session-store.js';
 export { StubTracker, createStubProxy, getStubTracker, isTestRun, stub, spy, } from './stub-tracker.js';
 export { SecretHostNotAllowedError, assertSecretAllowedForHost, } from './secret-host-binding.js';

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

@@ -0,0 +1,29 @@
+import type { JWTService, Logger } from '@pikku/core/services';
+import { type LocalContentConfig } from './local-content.js';
+/**
+ * The server half of {@link LocalContent}.
+ *
+ * `LocalContent` hands out `PUT <uploadUrlPrefix>/<key>` upload URLs and signed
+ * `GET <assetUrlPrefix>/<key>` read URLs, but it cannot answer either: it is a
+ * `ContentService`, not a transport. Something in the serving path has to, and
+ * until now only `@pikku/node-http-server` did — so the very same project served
+ * under Bun handed the browser upload URLs that 404ed, with nothing naming the
+ * cause.
+ *
+ * Expressed in Web `Request`/`Response` so every runtime can share one
+ * implementation rather than each re-deriving the signature check. Returns
+ * `null` for anything that is not a content request, which is the caller's
+ * signal to carry on with its normal routing.
+ */
+export type LocalContentRequestHandler = (request: Request) => Promise<Response | null>;
+export type LocalContentRequestHandlerOptions = {
+    content: LocalContentConfig;
+    logger: Logger;
+    /**
+     * Resolved per request rather than passed by value: a runtime may only be
+     * able to reach the signing service through `singletonServices`, which is not
+     * populated until after the server is constructed.
+     */
+    getJWT: () => JWTService | undefined;
+};
+export declare const createLocalContentRequestHandler: ({ content, logger, getJWT, }: LocalContentRequestHandlerOptions) => LocalContentRequestHandler;

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

@@ -0,0 +1,176 @@
+import { createReadStream } from 'fs';
+import { mkdir, stat, writeFile } from 'fs/promises';
+import { normalize, resolve } from 'path';
+import { Readable } from 'stream';
+import { signedContentPath } 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' },
+});
+export const createLocalContentRequestHandler = ({ content, logger, getJWT, }) => {
+    // Logged at most once. An unverifiable request is attacker-triggerable, so
+    // this reports a startup misconfiguration rather than per-request news.
+    let loggedMissingJWT = false;
+    const validateSignedAssetRequest = async (requestUrl) => {
+        const signedAtValue = requestUrl.searchParams.get('signedAt');
+        const expiresAtValue = requestUrl.searchParams.get('expiresAt');
+        const notBeforeValue = requestUrl.searchParams.get('notBefore');
+        const signature = requestUrl.searchParams.get('signature');
+        if (!signedAtValue || !expiresAtValue) {
+            return { ok: false, status: 403, body: 'Signed URL required' };
+        }
+        const signedAt = Number(signedAtValue);
+        const expiresAt = Number(expiresAtValue);
+        const notBefore = notBeforeValue == null ? undefined : Number(notBeforeValue);
+        if (!Number.isFinite(signedAt) ||
+            !Number.isFinite(expiresAt) ||
+            (notBefore != null && !Number.isFinite(notBefore))) {
+            return { ok: false, status: 403, body: 'Invalid signed URL' };
+        }
+        const now = Date.now();
+        if (now > expiresAt || (notBefore != null && now < notBefore)) {
+            return { ok: false, status: 403, body: 'Signed URL expired' };
+        }
+        const jwt = getJWT();
+        if (!jwt) {
+            if (!loggedMissingJWT) {
+                loggedMissingJWT = true;
+                logger.error('pikku: refusing signed asset reads — no JWTService is available to verify them. Pass `contentSigningJWT` (the same service LocalContent signs with) or expose it as `singletonServices.jwt`.');
+            }
+            return { ok: false, status: 403, body: 'Invalid signed URL' };
+        }
+        if (!signature) {
+            return { ok: false, status: 403, body: 'Signed URL signature required' };
+        }
+        try {
+            const payload = await jwt.decode(signature);
+            // Every claim is compared, the path included: without it a signature
+            // minted for one asset would read any other.
+            if (payload.signedAt !== signedAt ||
+                payload.expiresAt !== expiresAt ||
+                payload.notBefore !== notBefore ||
+                payload.path !== signedContentPath(requestUrl.pathname)) {
+                return { ok: false, status: 403, body: 'Invalid signed URL' };
+            }
+        }
+        catch {
+            return { ok: false, status: 403, body: 'Invalid signed URL' };
+        }
+        return { ok: true };
+    };
+    const handleUpload = async (request, pathname) => {
+        const key = contentKey(pathname, content.uploadUrlPrefix);
+        const targetPath = toTargetPath(content.localFileUploadPath, key);
+        if (!targetPath) {
+            return text(400, 'Invalid path');
+        }
+        const maxBytes = parseSizeLimit(content.sizeLimit ?? '1mb');
+        // Counted as it arrives and abandoned the moment it goes over, so an
+        // oversized upload costs the limit rather than its own size — `arrayBuffer()`
+        // would have to hold all of it first, which hands an unauthenticated caller
+        // a way to spend the server's memory. Mirrors node-http-server's
+        // `readRequestBody`, which aborts the same way.
+        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();
+            }
+        }
+        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) {
+            return text(400, 'Invalid path');
+        }
+        const signed = await validateSignedAssetRequest(requestUrl);
+        if (!signed.ok) {
+            return text(signed.status, signed.body);
+        }
+        try {
+            const file = await stat(targetPath);
+            if (!file.isFile()) {
+                return new Response(null, { status: 404 });
+            }
+            const headers = {
+                'content-length': String(file.size),
+                'content-type': 'application/octet-stream',
+            };
+            if (request.method === 'HEAD') {
+                return new Response(null, { status: 200, headers });
+            }
+            // Streamed rather than buffered: assets are user uploads, and their size
+            // is bounded by `sizeLimit` at write time, not by anything here.
+            return new Response(Readable.toWeb(createReadStream(targetPath)), { status: 200, headers });
+        }
+        catch {
+            return new Response(null, { status: 404 });
+        }
+    };
+    return async (request) => {
+        let requestUrl;
+        try {
+            requestUrl = new URL(request.url);
+        }
+        catch {
+            return null;
+        }
+        const pathname = decodeURIComponent(requestUrl.pathname);
+        if (request.method === 'PUT' &&
+            matchesPrefix(pathname, content.uploadUrlPrefix)) {
+            return handleUpload(request, pathname);
+        }
+        if ((request.method === 'GET' || request.method === 'HEAD') &&
+            matchesPrefix(pathname, content.assetUrlPrefix)) {
+            return handleAsset(request, requestUrl, pathname);
+        }
+        return null;
+    };
+};

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

@@ -1,13 +1,14 @@
-import type { SecretService } from './secret-service.js';
+import { type SecretValue } from '../secret-value.js';
+import type { SecretService, SecretValues } from './secret-service.js';
 import type { VariablesService } from './variables-service.js';
 export declare class LocalSecretService implements SecretService {
     private variables;
     private localSecrets;
     private parseSecret;
     constructor(variables?: VariablesService);
-    getSecret<T = string>(key: string): Promise<T>;
+    getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     setSecret(key: string, value: unknown): Promise<void>;
     hasSecret(key: string): Promise<boolean>;
     deleteSecret(key: string): Promise<void>;
-    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<T>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
 }