@pikku/core 0.12.72 → 0.12.77

package/dist/services/in-memory-workflow-service.js

@@ -1,21 +1,7 @@
 import { randomUUID } from 'crypto';
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
 import { isExpectedError } from '../errors/error-handler.js';
-/**
- * In-memory implementation of WorkflowService for inline-only execution
- *
- * This is a lightweight workflow service that stores all state in memory.
- * It only supports inline execution (no queue workers) and is ideal for:
- * - CLI tools that need workflow-like step orchestration
- * - Testing and development
- * - Single-process applications without persistence requirements
- *
- * @example
- * ```typescript
- * const workflowService = new InMemoryWorkflowService()
- * await workflowService.startWorkflow('myWorkflow', input, { type: 'cli' }, rpc, { inline: true })
- * ```
- */
+// knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
 export class InMemoryWorkflowService extends PikkuWorkflowService {
     constructor(options = {}) {
         super({ ...options, wireQueues: false });
@@ -99,7 +85,7 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         const key = `${runId}:${stepName}`;
         this.steps.set(key, step);
         this.stepData.set(stepId, { rpcName, data, stepName });
-        // Add to history (same reference so mutations are reflected)
+        // knowledge: decisions/internals/in-memory-workflow-history-aliases-the-live-step-object.md
         const history = this.stepHistory.get(runId) || [];
         history.push(step);
         this.stepHistory.set(runId, history);
@@ -170,7 +156,6 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         }
     }
     async createRetryAttemptImpl(failedStepId, status) {
-        // Find the failed step
         let failedStep;
         let runId;
         let stepName;
@@ -205,11 +190,10 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         }
         const key = `${runId}:${stepName}`;
         this.steps.set(key, newStep);
-        // Copy step data to new step
         if (failedStepData) {
             this.stepData.set(newStepId, { ...failedStepData });
         }
-        // Add to history (same reference so mutations are reflected)
+        // knowledge: decisions/internals/in-memory-workflow-history-aliases-the-live-step-object.md
         const history = this.stepHistory.get(runId) || [];
         history.push(newStep);
         this.stepHistory.set(runId, history);
@@ -265,11 +249,10 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         return existed;
     }
     async withRunLock(_id, fn) {
-        // In-memory service doesn't need locking for inline execution
+        // knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
         return fn();
     }
     async withStepLock(_runId, _stepName, fn) {
-        // In-memory service doesn't need locking for inline execution
         return fn();
     }
     async close() {
@@ -277,7 +260,6 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
             clearTimeout(timer);
         }
         this.sleepTimers.clear();
-        // Clear all in-memory state
         this.runs.clear();
         this.steps.clear();
         this.stepData.clear();
@@ -286,7 +268,6 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         this.branchKeys.clear();
         this.workflowVersions.clear();
     }
-    // Graph workflow methods
     async getCompletedGraphState(runId) {
         const completedNodeIds = [];
         const failedNodeIds = [];
@@ -314,16 +295,6 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         }
         return { completedNodeIds, failedNodeIds, branchKeys };
     }
-    async getNodesWithoutSteps(runId, nodeIds) {
-        const existingSteps = new Set();
-        const prefix = `${runId}:`;
-        for (const [key] of this.steps.entries()) {
-            if (key.startsWith(prefix)) {
-                existingSteps.add(key.substring(prefix.length));
-            }
-        }
-        return nodeIds.filter((id) => !existingSteps.has(id));
-    }
     async listStepStates(runId) {
         const prefix = `${runId}:`;
         const steps = [];

package/dist/services/index.d.ts

@@ -1,6 +1,3 @@
-/**
- * @module @pikku/core
- */
 export { LogLevel } from './logger.js';
 export { ScopedSecretService } from './scoped-secret-service.js';
 export { PikkuSessionService, createMiddlewareSessionWireProps, createFunctionSessionWireProps, } from './user-session-service.js';
@@ -19,14 +16,13 @@ export { InMemoryTriggerService } from './in-memory-trigger-service.js';
 export { InMemoryAIRunStateService } from './in-memory-ai-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 { ScenarioActor, ScenarioActorConfig, ScenarioActorOf, ScenarioActors, ScenarioInvokeOptions, ScenarioRpcMap, ScenarioHttpResponse, } from './scenario-actors-service.js';
-export { readScenarioHttpResponse } from './scenario-actors-service.js';
-export { HttpScenarioActor, createHttpScenarioActors, type HttpScenarioActorsConfig, } from './http-scenario-actors.js';
+export type { ScenarioPersona, ResolvedPersona, ScenarioPersonaOf, ScenarioPersonas, ScenarioInvokeOptions, ScenarioRpcMap, ScenarioHttpResponse, } from './personas-service.js';
+export type { HttpPersonasConfig } from './http-personas.js';
 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';
@@ -46,9 +42,12 @@ export type { VariableStatus, VariableMeta } from './typed-variables-service.js'
 export type { MetaService } from './meta-service.js';
 export type { SessionStore } from './session-store.js';
 export type { ScopeService, Role } from './scope-service.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 { assertRoleIsMutable, assertRoleNameAvailable, roleLockReason, } from './system-role-guard.js';
+export type { IsSystemRole } from './system-role-guard.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';
 export { StubTracker, createStubProxy, getStubTracker, isTestRun, stub, spy, type StubCall, } from './stub-tracker.js';
+export { SecretHostNotAllowedError, assertSecretAllowedForHost, } from './secret-host-binding.js';

package/dist/services/index.js

@@ -1,6 +1,3 @@
-/**
- * @module @pikku/core
- */
 export { LogLevel } from './logger.js';
 export { ScopedSecretService } from './scoped-secret-service.js';
 export { PikkuSessionService, createMiddlewareSessionWireProps, createFunctionSessionWireProps, } from './user-session-service.js';
@@ -18,10 +15,10 @@ export { InMemoryQueueService } from './in-memory-queue-service.js';
 export { InMemoryTriggerService } from './in-memory-trigger-service.js';
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
-export { readScenarioHttpResponse } from './scenario-actors-service.js';
-export { HttpScenarioActor, createHttpScenarioActors, } from './http-scenario-actors.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 { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './audit-service.js';
+export { assertRoleIsMutable, assertRoleNameAvailable, roleLockReason, } from './system-role-guard.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/istanbul-coverage-service.d.ts

@@ -1,9 +1,5 @@
 import type { CoverageService, CoverageSnapshot } from './v8-coverage-service.js';
-/**
- * Reads istanbul-instrumented counters from the `__coverage__` global —
- * the coverage backend for runtimes without V8 precise coverage (e.g. Bun,
- * where source files are instrumented at load time by a Bun loader plugin).
- */
+/** The coverage backend for runtimes without V8 precise coverage, e.g. Bun. */
 export declare class IstanbulCoverageService implements CoverageService {
     start(): Promise<void>;
     takeCoverage(): Promise<CoverageSnapshot>;

package/dist/services/istanbul-coverage-service.js

@@ -1,9 +1,5 @@
 const getCoverageGlobal = () => globalThis.__coverage__;
-/**
- * Reads istanbul-instrumented counters from the `__coverage__` global —
- * the coverage backend for runtimes without V8 precise coverage (e.g. Bun,
- * where source files are instrumented at load time by a Bun loader plugin).
- */
+/** The coverage backend for runtimes without V8 precise coverage, e.g. Bun. */
 export class IstanbulCoverageService {
     async start() { }
     async takeCoverage() {
@@ -15,9 +11,7 @@ export class IstanbulCoverageService {
                 hits = new Map();
                 lineHits.set(file.path, hits);
             }
-            // istanbul line semantics: a statement's count belongs to its start
-            // line only, so an enclosing multi-line statement never masks an
-            // unexecuted inner statement (e.g. a throw inside a taken if).
+            // knowledge: decisions/internals/istanbul-statement-counts-attach-to-the-start-line-only.md
             for (const [id, location] of Object.entries(file.statementMap)) {
                 const count = file.s[id] ?? 0;
                 const line = location.start.line;

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

@@ -1,21 +1,6 @@
 import type { RelativeTimeInput } from '../time-utils.js';
-/**
- * Interface for handling JSON Web Tokens (JWT).
- */
 export interface JWTService {
-    /**
-     * Encodes a payload into a JWT.
-     * @param expiresIn - The expiration time of the token.
-     * @param payload - The payload to encode.
-     * @returns A promise that resolves to the encoded JWT.
-     */
     encode: <T extends any>(expiresIn: RelativeTimeInput, payload: T) => Promise<string>;
-    /**
-     * Decodes a JWT into its payload.
-     * @param hash - The JWT to decode.
-     * @param invalidHashError - An optional error to throw if the hash is invalid.
-     * @param debug - An optional flag for debugging.
-     * @returns A promise that resolves to the decoded payload.
-     */
+    /** `invalidHashError` replaces the implementation's own error when the hash does not verify. */
     decode: <T>(hash: string, invalidHashError?: Error, debug?: boolean) => Promise<T>;
 }

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-content.d.ts

@@ -6,11 +6,22 @@ export interface LocalContentConfig {
     server?: string;
     sizeLimit?: string;
 }
+/**
+ * The representation of an asset that gets bound into a signed URL's
+ * signature, and that a server can reconstruct from an incoming request:
+ * the decoded path, without origin or query string.
+ *
+ * Both sides must derive it the same way, so signer and verifier share this
+ * function. Percent escapes are decoded so that a client re-encoding an
+ * optional character still matches; a malformed escape is left verbatim
+ * rather than throwing, which keeps both sides in agreement.
+ */
+export declare const signedContentPath: (urlOrPath: string) => string;
 export declare class LocalContent implements ContentService {
     private config;
     private logger;
-    private jwt?;
-    constructor(config: LocalContentConfig, logger: Logger, jwt?: JWTService | undefined);
+    private jwt;
+    constructor(config: LocalContentConfig, logger: Logger, jwt: JWTService);
     private safePath;
     private joinKey;
     init(): Promise<void>;

package/dist/services/local-content.js

@@ -2,6 +2,31 @@ import { createReadStream, createWriteStream, promises } from 'fs';
 import { mkdir, readFile } from 'fs/promises';
 import { resolve, normalize } from 'path';
 import { pipeline } from 'stream/promises';
+/**
+ * The representation of an asset that gets bound into a signed URL's
+ * signature, and that a server can reconstruct from an incoming request:
+ * the decoded path, without origin or query string.
+ *
+ * Both sides must derive it the same way, so signer and verifier share this
+ * function. Percent escapes are decoded so that a client re-encoding an
+ * optional character still matches; a malformed escape is left verbatim
+ * rather than throwing, which keeps both sides in agreement.
+ */
+export const signedContentPath = (urlOrPath) => {
+    let pathname;
+    try {
+        pathname = new URL(urlOrPath, 'http://pikku.local').pathname;
+    }
+    catch {
+        pathname = urlOrPath;
+    }
+    try {
+        return decodeURIComponent(pathname);
+    }
+    catch {
+        return pathname;
+    }
+};
 export class LocalContent {
     config;
     logger;
@@ -10,6 +35,9 @@ export class LocalContent {
         this.config = config;
         this.logger = logger;
         this.jwt = jwt;
+        if (!jwt) {
+            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);
@@ -24,7 +52,7 @@ export class LocalContent {
         return `${bucket}/${key}`;
     }
     async init() { }
-    async signParams(dateLessThan, dateGreaterThan) {
+    async signParams(url, dateLessThan, dateGreaterThan) {
         const signedAt = Date.now();
         const expiresAt = dateLessThan.getTime();
         const params = new URLSearchParams({
@@ -34,22 +62,21 @@ export class LocalContent {
         if (dateGreaterThan) {
             params.set('notBefore', String(dateGreaterThan.getTime()));
         }
-        if (this.jwt) {
-            const expiresInSeconds = Math.max(1, Math.floor((expiresAt - signedAt) / 1000));
-            const payload = {
-                signedAt,
-                expiresAt,
-            };
-            if (dateGreaterThan) {
-                payload.notBefore = dateGreaterThan.getTime();
-            }
-            const signature = await this.jwt.encode({ value: expiresInSeconds, unit: 'second' }, payload);
-            params.set('signature', signature);
+        const expiresInSeconds = Math.max(1, Math.floor((expiresAt - signedAt) / 1000));
+        const payload = {
+            signedAt,
+            expiresAt,
+            path: signedContentPath(url),
+        };
+        if (dateGreaterThan) {
+            payload.notBefore = dateGreaterThan.getTime();
         }
+        const signature = await this.jwt.encode({ value: expiresInSeconds, unit: 'second' }, payload);
+        params.set('signature', signature);
         return params.toString();
     }
     async signURL(args) {
-        const params = await this.signParams(args.dateLessThan, args.dateGreaterThan);
+        const params = await this.signParams(args.url, args.dateLessThan, args.dateGreaterThan);
         return `${args.url}?${params}`;
     }
     async signContentKey(args) {

package/dist/services/local-gateway-service.d.ts

@@ -1,20 +1,4 @@
 import type { GatewayService } from './gateway-service.js';
-/**
- * Local GatewayService implementation.
- *
- * Starts all registered listener gateways unconditionally (single-process).
- * For distributed deployments, implement `GatewayService` with leader
- * election or similar coordination.
- *
- * @example
- * ```typescript
- * const gatewayService = new LocalGatewayService()
- * await gatewayService.start()
- *
- * // On shutdown
- * await gatewayService.stop()
- * ```
- */
 export declare class LocalGatewayService implements GatewayService {
     private activeAdapters;
     start(): Promise<void>;

package/dist/services/local-gateway-service.js

@@ -1,21 +1,6 @@
 import { pikkuState, getSingletonServices } from '../pikku-state.js';
 import { createListenerMessageHandler, resolveGatewayAdapter, } from '../wirings/gateway/gateway-runner.js';
-/**
- * Local GatewayService implementation.
- *
- * Starts all registered listener gateways unconditionally (single-process).
- * For distributed deployments, implement `GatewayService` with leader
- * election or similar coordination.
- *
- * @example
- * ```typescript
- * const gatewayService = new LocalGatewayService()
- * await gatewayService.start()
- *
- * // On shutdown
- * await gatewayService.stop()
- * ```
- */
+// knowledge: decisions/internals/local-trigger-and-gateway-services-assume-a-single-process.md
 export class LocalGatewayService {
     activeAdapters = new Map();
     async start() {
@@ -43,7 +28,7 @@ export class LocalGatewayService {
                     getSingletonServices().logger.error(`Error closing listener gateway '${name}':`, e);
                 }
                 catch {
-                    // logger may not be available during shutdown
+                    // The logger may already be gone during shutdown.
                 }
             }
         }

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

@@ -1,17 +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';
-/**
- * Service for retrieving secrets from environment variables.
- * Supports storing secrets locally in memory for CLI operations.
- */
 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>>>;
 }

package/dist/services/local-secrets.js

@@ -1,8 +1,5 @@
+import { createSecretValue, isSecretValue, } from '../secret-value.js';
 import { LocalVariablesService } from './local-variables.js';
-/**
- * Service for retrieving secrets from environment variables.
- * Supports storing secrets locally in memory for CLI operations.
- */
 export class LocalSecretService {
     variables;
     localSecrets = new Map();
@@ -20,16 +17,19 @@ export class LocalSecretService {
     async getSecret(key) {
         const localValue = this.localSecrets.get(key);
         if (localValue) {
-            return this.parseSecret(localValue);
+            return createSecretValue(this.parseSecret(localValue));
         }
         const value = await this.variables.get(key);
         if (value) {
-            return this.parseSecret(value);
+            return createSecretValue(this.parseSecret(value));
         }
         throw new Error('Requested secret not found');
     }
     async setSecret(key, value) {
-        this.localSecrets.set(key, typeof value === 'string' ? value : JSON.stringify(value));
+        // Storing the wrapper would serialize it to '[secret]', so unwrap first —
+        // writing a secret back to the vault is exactly what this method is for.
+        const raw = isSecretValue(value) ? value.reveal() : value;
+        this.localSecrets.set(key, typeof raw === 'string' ? raw : JSON.stringify(raw));
     }
     async hasSecret(key) {
         if (this.localSecrets.has(key)) {