@pikku/core 0.12.143 → 0.12.144

package/dist/analytics/analytics.d.ts

@@ -3,4 +3,18 @@ import type { Logger } from '../services/logger.js';
 import type { AnalyticsEventBase, AnalyticsEventInput, AnalyticsIdentityResolver, AnalyticsLog, AnalyticsService } from './analytics.types.js';
 /** Removes the discriminator, so `props` is free of the series key. */
 export declare const flattenAnalyticsEvent: (event: AnalyticsEventBase, at?: number) => AnalyticsEventInput;
+/**
+ * Creates the per-invocation `analytics` log handed to a function.
+ *
+ * Events are buffered and written to `service` in one batch on `flush()`/`close()`.
+ * Identity is stamped from the wire's session (never from the event payload), merged
+ * with whatever `resolveIdentity` returns. A failed write is logged as a warning and
+ * dropped, so analytics can never fail the request.
+ *
+ * @param service - The sink the batch is written to.
+ * @param wire - The invocation's wire; supplies session, trace and function ids.
+ * @param logger - Fallback logger when the wire carries none.
+ * @param resolveIdentity - Adds browser-originated ids and consent to each record.
+ * @internal
+ */
 export declare const createInvocationAnalytics: (service: AnalyticsService, wire: PikkuWire<any, any, any, CoreUserSession>, logger?: Logger, resolveIdentity?: AnalyticsIdentityResolver) => AnalyticsLog;

package/dist/analytics/analytics.js

@@ -55,4 +55,18 @@ class InvocationAnalyticsLog {
         };
     }
 }
+/**
+ * Creates the per-invocation `analytics` log handed to a function.
+ *
+ * Events are buffered and written to `service` in one batch on `flush()`/`close()`.
+ * Identity is stamped from the wire's session (never from the event payload), merged
+ * with whatever `resolveIdentity` returns. A failed write is logged as a warning and
+ * dropped, so analytics can never fail the request.
+ *
+ * @param service - The sink the batch is written to.
+ * @param wire - The invocation's wire; supplies session, trace and function ids.
+ * @param logger - Fallback logger when the wire carries none.
+ * @param resolveIdentity - Adds browser-originated ids and consent to each record.
+ * @internal
+ */
 export const createInvocationAnalytics = (service, wire, logger, resolveIdentity) => new InvocationAnalyticsLog(service, wire, logger, resolveIdentity);

package/dist/analytics/analytics.types.d.ts

@@ -11,6 +11,7 @@ export type AnalyticsEventBase = {
     /** The event name, as declared in `defineAnalyticsEvents`. */
     name: string;
 } & Record<string, unknown>;
+/** An event as a caller submits it: name, free-form props and an optional client timestamp (ms). */
 export interface AnalyticsEventInput {
     name: string;
     props?: Record<string, unknown>;

package/dist/analytics/anonymous-analytics-identity.d.ts

@@ -1,5 +1,6 @@
 import type { SerializeOptions } from 'cookie';
 import type { AnalyticsIdentityResolver } from './analytics.types.js';
+/** Options for `anonymousAnalyticsIdentity`. */
 export interface AnonymousAnalyticsIdentityOptions {
     /** Cookie name. Defaults to `pikku_aid`. */
     name?: string;

package/dist/analytics/cookie-analytics-identity.d.ts

@@ -1,4 +1,5 @@
 import type { AnalyticsIdentityResolver } from './analytics.types.js';
+/** Options for `cookieAnalyticsIdentity`: which cookies carry vendor ids and which grant consent. */
 export interface CookieAnalyticsIdentityOptions {
     /** Identity key to read it from, e.g. `{ gaClientId: '_ga' }`. */
     vendorIds?: Record<string, string>;

package/dist/analytics/mint-cookie.d.ts

@@ -1,6 +1,7 @@
 import type { SerializeOptions } from 'cookie';
 import type { CoreUserSession, PikkuWire } from '../types/core.types.js';
 type AnyWire = PikkuWire<any, any, any, CoreUserSession>;
+/** Options for `mintCookie`, including the consent purposes that gate writing it. */
 export interface MintCookieOptions {
     /** Cookie attributes. Long-lived and first-party is the usual shape. */
     cookie: SerializeOptions;

package/dist/{wirings/channel/channel-middleware-runner.d.ts → channel-middleware-runner.d.ts}

@@ -1,8 +1,22 @@
-import type { CoreSingletonServices, PikkuRawWire } from '../../types/core.types.js';
-import type { MiddlewareMetadata } from '../../middleware/middleware.types.js';
-import type { CorePikkuChannelMiddleware } from './channel.types.js';
+import type { CoreSingletonServices, PikkuRawWire } from './types/core.types.js';
+import type { MiddlewareMetadata } from './middleware/middleware.types.js';
+import type { CorePikkuChannelMiddleware } from './wirings/channel/channel.types.js';
+/**
+ * Registers channel middleware for every channel carrying `tag`. It wraps each
+ * message the channel sends. Registering the same tag again replaces its
+ * group rather than appending to it.
+ *
+ * @returns The middleware it was given.
+ * @example snippet: addChannelMiddleware
+ */
 export declare const addChannelMiddleware: (tag: string, middleware: CorePikkuChannelMiddleware[], packageName?: string | null) => CorePikkuChannelMiddleware[];
 export declare const clearChannelMiddlewareCache: () => void;
+/**
+ * Resolves the channel middleware for one wiring: the tag and named middleware
+ * its metadata inherits, then the wiring's own, de-duplicated. The inherited
+ * part is cached per wiring.
+ * @internal
+ */
 export declare const combineChannelMiddleware: (wireType: string, uid: string, { wireInheritedChannelMiddleware, wireChannelMiddleware, packageName, }?: {
     wireInheritedChannelMiddleware?: MiddlewareMetadata[];
     wireChannelMiddleware?: CorePikkuChannelMiddleware[];

package/dist/{wirings/channel/channel-middleware-runner.js → channel-middleware-runner.js}

@@ -1,14 +1,24 @@
-import { pikkuState } from '../../pikku-state.js';
-import { freezeDedupe, getTagGroups } from '../../utils.js';
+import { pikkuState } from './pikku-state.js';
+import { freezeDedupe, getTagGroups } from './utils.js';
+/**
+ * Registers channel middleware for every channel carrying `tag`. It wraps each
+ * message the channel sends. Registering the same tag again replaces its
+ * group rather than appending to it.
+ *
+ * @returns The middleware it was given.
+ * @example snippet: addChannelMiddleware
+ */
 export const addChannelMiddleware = (tag, middleware, packageName = null) => {
     const tagGroups = pikkuState(packageName, 'channelMiddleware', 'tagGroup');
     tagGroups[tag] = middleware;
     return middleware;
 };
-const getChannelMiddlewareByName = (name) => {
-    const store = pikkuState(null, 'misc', 'channelMiddleware');
-    const middleware = store[name];
-    return middleware?.[0];
+/** Like `getMiddlewareByName`: the package's own namespace, then the application's. */
+const getChannelMiddlewareByName = (name, packageName) => {
+    const own = pikkuState(packageName, 'misc', 'channelMiddleware')[name]?.[0];
+    if (own || packageName === null)
+        return own;
+    return pikkuState(null, 'misc', 'channelMiddleware')[name]?.[0];
 };
 const channelMiddlewareCache = {};
 export const clearChannelMiddlewareCache = () => {
@@ -16,8 +26,14 @@ export const clearChannelMiddlewareCache = () => {
         delete channelMiddlewareCache[key];
     }
 };
+/**
+ * Resolves the channel middleware for one wiring: the tag and named middleware
+ * its metadata inherits, then the wiring's own, de-duplicated. The inherited
+ * part is cached per wiring.
+ * @internal
+ */
 export const combineChannelMiddleware = (wireType, uid, { wireInheritedChannelMiddleware, wireChannelMiddleware, packageName = null, } = {}) => {
-    const cacheKey = `${wireType}:${uid}`;
+    const cacheKey = `${packageName ?? ''}\0${wireType}:${uid}`;
     let inherited = channelMiddlewareCache[cacheKey];
     if (!inherited) {
         const resolved = [];
@@ -30,7 +46,7 @@ export const combineChannelMiddleware = (wireType, uid, { wireInheritedChannelMi
                     }
                 }
                 else if (meta.type === 'wire') {
-                    const middleware = getChannelMiddlewareByName(meta.name);
+                    const middleware = getChannelMiddlewareByName(meta.name, packageName);
                     if (middleware) {
                         resolved.push(middleware);
                     }

package/dist/classification/data-classification.d.ts

@@ -1,13 +1,24 @@
+/**
+ * Brands a value as private: personal data that may be stored but must not leave in a response unchecked.
+ * The brand is optional, so plain values are still assignable; the inspector reads it statically.
+ */
 export type Private<T> = T & {
     readonly __classification__?: 'private';
 };
+/** Brands a value as personally identifiable information. Same erasable, optional brand as `Private<T>`. */
 export type Pii<T> = T & {
     readonly __classification__?: 'pii';
 };
+/**
+ * Brands a value as secret (credentials, tokens). Same erasable, optional brand as `Private<T>`;
+ * `SecretValue.reveal()` returns this so the inspector can follow a revealed secret.
+ */
 export type Secret<T> = T & {
     readonly __classification__?: 'secret';
 };
+/** Sensitivity level of a value or column, from least to most sensitive. */
 export type Classification = 'public' | 'private' | 'pii' | 'secret';
+/** How a column is rewritten when data is anonymized; `null` means no strategy has been chosen. */
 export type AnonymizeStrategy = 'fake:email' | 'fake:name' | 'hash' | 'keep' | null;
 /**
  * How a column's bytes are represented at rest, as distinct from how sensitive
@@ -50,6 +61,7 @@ export type SealedValue = string & {
 export type HashedValue = string & {
     readonly [hashedBrand]: true;
 };
+/** One column's entry in the classification manifest: its sensitivity, anonymize strategy and at-rest form. */
 export interface ColumnClassification {
     classification: Classification;
     anonymize_strategy: AnonymizeStrategy;
@@ -67,6 +79,7 @@ export interface ColumnClassification {
     keyId?: string;
     description?: string;
 }
+/** Per-table, per-column classification manifest, generated as `classification.gen.ts` by `pikku db migrate`. */
 export type ClassificationManifest = {
     version: 1;
     tables: Record<string, Record<string, ColumnClassification>>;

package/dist/classification/secret-value.d.ts

@@ -1,9 +1,14 @@
 import type { Secret } from './data-classification.js';
 declare const secretValueBrand: unique symbol;
+/** The placeholder a `SecretValue` serializes to in JSON and `util.inspect` output. */
 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;
+/**
+ * Thrown when a `SecretValue` is coerced to a string (template literal, concatenation, `String()`),
+ * which would otherwise write the secret out in the clear. Call `.reveal()` instead.
+ */
 export declare class SecretCoercionError extends Error {
     constructor();
 }
@@ -30,7 +35,9 @@ export declare class SecretValue<T = string> {
     toString(): never;
     [Symbol.toPrimitive](): never;
 }
+/** Wraps a value in a `SecretValue`, so it redacts when serialized and throws when coerced to a string. */
 export declare const createSecretValue: <T>(value: T) => SecretValue<T>;
+/** Whether `value` is a `SecretValue`. Uses a global symbol, so it recognises instances from duplicate copies of core. */
 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;

package/dist/classification/secret-value.js

@@ -1,7 +1,12 @@
+/** The placeholder a `SecretValue` serializes to in JSON and `util.inspect` output. */
 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');
+/**
+ * Thrown when a `SecretValue` is coerced to a string (template literal, concatenation, `String()`),
+ * which would otherwise write the secret out in the clear. Call `.reveal()` instead.
+ */
 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.`);
@@ -42,5 +47,7 @@ export class SecretValue {
         throw new SecretCoercionError();
     }
 }
+/** Wraps a value in a `SecretValue`, so it redacts when serialized and throws when coerced to a string. */
 export const createSecretValue = (value) => new SecretValue(value);
+/** Whether `value` is a `SecretValue`. Uses a global symbol, so it recognises instances from duplicate copies of core. */
 export const isSecretValue = (value) => typeof value === 'object' && value !== null && SECRET_VALUE in value;

package/dist/crypto-utils.d.ts

@@ -1,16 +1,75 @@
 import type { WrappedValue } from './classification/data-classification.js';
+/**
+ * Encrypts a JSON-serialisable value with AES-256-GCM under a key derived from
+ * `secret` by PBKDF2-SHA256 (600,000 iterations, fresh random 16-byte salt).
+ *
+ * Meant for low-entropy secrets such as passphrases; for high-entropy key material
+ * use {@link encryptWithKeyMaterial}, which skips the deliberately slow KDF.
+ *
+ * @param secret - The passphrase the key is derived from.
+ * @param value - Any value `JSON.stringify` accepts.
+ * @returns A base64url token of `salt || iv || ciphertext+tag`.
+ * @throws Error when WebCrypto is not available in the runtime.
+ */
 export declare const encryptJSON: (secret: string, value: unknown) => Promise<string>;
+/**
+ * Reverses {@link encryptJSON}: re-derives the key from `secret` and the salt in
+ * the token, then decrypts and parses the JSON.
+ *
+ * @param secret - The passphrase the token was encrypted with.
+ * @param token - The base64url token `encryptJSON` returned.
+ * @returns The parsed value, cast to `T` without validation.
+ * @throws Error on a truncated token; the WebCrypto `OperationError` when the
+ *   secret is wrong or the token was tampered with (the GCM tag fails).
+ */
 export declare const decryptJSON: <T>(secret: string, token: string) => Promise<T>;
 /**
  * Namespaces the remote-RPC session key so the same deployment secret used for
  * another purpose derives a different key. See knowledge/crypto.md.
  */
 export declare const REMOTE_SESSION_INFO = "pikku:remote-session";
+/** Shortest key material, in characters, that the `*WithKeyMaterial` helpers accept. */
 export declare const MIN_KEY_MATERIAL_LENGTH = 32;
+/**
+ * Refuses key material shorter than {@link MIN_KEY_MATERIAL_LENGTH}. HKDF does no
+ * stretching, so a short secret would be brute-forceable.
+ *
+ * @param name - The secret's name, used in the error message (the value is never included).
+ * @param keyMaterial - The material to check.
+ * @throws WeakKeyMaterialError when the material is too short.
+ */
 export declare const assertStrongKeyMaterial: (name: string, keyMaterial: string) => void;
+/**
+ * Encrypts a JSON-serialisable value with AES-256-GCM under a key expanded from
+ * high-entropy key material by HKDF-SHA256, with a fresh random salt per call.
+ *
+ * `info` domain-separates the derived key, so the same deployment secret used for
+ * two purposes (e.g. {@link REMOTE_SESSION_INFO}) yields two unrelated keys.
+ *
+ * @param name - The key material's name, for the weak-key error.
+ * @param keyMaterial - At least {@link MIN_KEY_MATERIAL_LENGTH} characters.
+ * @param info - The HKDF context string; decryption must pass the same one.
+ * @param value - Any value `JSON.stringify` accepts.
+ * @returns A base64url token of `salt || iv || ciphertext+tag`.
+ * @throws WeakKeyMaterialError when `keyMaterial` is too short.
+ */
 export declare const encryptWithKeyMaterial: (name: string, keyMaterial: string, info: string, value: unknown) => Promise<string>;
+/**
+ * Reverses {@link encryptWithKeyMaterial}.
+ *
+ * @param name - The key material's name, for the weak-key error.
+ * @param keyMaterial - The material the token was encrypted under.
+ * @param info - The same HKDF context string used to encrypt.
+ * @param token - The base64url token to decrypt.
+ * @returns The parsed value, cast to `T` without validation.
+ * @throws WeakKeyMaterialError when `keyMaterial` is too short; Error on a
+ *   truncated token; the WebCrypto `OperationError` when the key, `info` or
+ *   token is wrong.
+ */
 export declare const decryptWithKeyMaterial: <T>(name: string, keyMaterial: string, info: string, token: string) => Promise<T>;
+/** UTF-8 encodes a string and returns it as unpadded base64url. An encoding, not encryption. */
 export declare const encodeBase64UrlText: (value: string) => string;
+/** Decodes unpadded (or padded) base64url back to a UTF-8 string. */
 export declare const decodeBase64UrlText: (value: string) => string;
 /**
  * HMAC-SHA256 over `payload` under a key expanded from high-entropy key
@@ -20,19 +79,48 @@ export declare const decodeBase64UrlText: (value: string) => string;
 export declare const signWithKeyMaterial: (name: string, keyMaterial: string, info: string, payload: string) => Promise<string>;
 /** False — never throws — for a malformed, truncated or mismatched signature. */
 export declare const verifyWithKeyMaterial: (name: string, keyMaterial: string, info: string, payload: string, signature: string) => Promise<boolean>;
+/**
+ * Generates a random 256-bit data-encryption key for envelope encryption.
+ *
+ * @returns The raw key as base64url. It is plaintext key material: wrap it with
+ *   {@link wrapDEK} before storing it.
+ */
 export declare const generateDEK: () => Promise<string>;
 /**
  * One salt per (deployment, key version), stored beside the wrapped DEKs.
  * See knowledge/crypto.md.
  */
 export declare const generateKEKSalt: () => string;
+/**
+ * Derives the AES-256-GCM key-encryption key from a passphrase and a salt from
+ * {@link generateKEKSalt}, by PBKDF2-SHA256 (600,000 iterations). The key is
+ * non-extractable.
+ *
+ * @param passphrase - The deployment's master passphrase.
+ * @param salt - The base64url salt stored beside the wrapped DEKs.
+ */
 export declare const deriveKEK: (passphrase: string, salt: string) => Promise<CryptoKey>;
+/** Encrypts a plaintext DEK under the KEK (AES-GCM, random IV) so it can be stored. */
 export declare const wrapDEK: (kek: CryptoKey, plaintextDEK: string) => Promise<WrappedValue>;
+/**
+ * Decrypts a DEK wrapped by {@link wrapDEK}.
+ *
+ * @throws Error on a truncated token; the WebCrypto `OperationError` when the KEK is wrong.
+ */
 export declare const unwrapDEK: (kek: CryptoKey, wrappedDEK: string) => Promise<string>;
+/** The two values {@link envelopeEncrypt} returns; both are needed to decrypt and both are safe to store. */
 export interface EnvelopeEncryptResult {
     ciphertext: WrappedValue;
     wrappedDEK: WrappedValue;
 }
+/**
+ * Envelope-encrypts a value: a fresh DEK encrypts the value, and the KEK encrypts
+ * the DEK. Rotating the KEK then only needs {@link envelopeRewrap} on each
+ * wrapped DEK, not re-encryption of the data.
+ *
+ * @param kek - The key-encryption key from {@link deriveKEK}.
+ * @param value - Any value `JSON.stringify` accepts.
+ */
 export declare const envelopeEncrypt: (kek: CryptoKey, value: unknown) => Promise<EnvelopeEncryptResult>;
 /**
  * Note the inputs are plain `string`, not `WrappedValue`.
@@ -45,4 +133,9 @@ export declare const envelopeEncrypt: (kek: CryptoKey, value: unknown) => Promis
  * wire, which is exactly where casts are least reviewable.
  */
 export declare const envelopeDecrypt: <T>(kek: CryptoKey, ciphertext: string, wrappedDEK: string) => Promise<T>;
+/**
+ * Re-wraps a DEK under a new KEK for key rotation. The data ciphertext is unchanged.
+ *
+ * @throws The WebCrypto `OperationError` when `oldKEK` did not wrap this DEK.
+ */
 export declare const envelopeRewrap: (oldKEK: CryptoKey, newKEK: CryptoKey, wrappedDEK: string) => Promise<WrappedValue>;

package/dist/crypto-utils.js

@@ -55,6 +55,18 @@ const deriveKey = async (secret, salt) => {
         hash: 'SHA-256',
     }, material, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
 };
+/**
+ * Encrypts a JSON-serialisable value with AES-256-GCM under a key derived from
+ * `secret` by PBKDF2-SHA256 (600,000 iterations, fresh random 16-byte salt).
+ *
+ * Meant for low-entropy secrets such as passphrases; for high-entropy key material
+ * use {@link encryptWithKeyMaterial}, which skips the deliberately slow KDF.
+ *
+ * @param secret - The passphrase the key is derived from.
+ * @param value - Any value `JSON.stringify` accepts.
+ * @returns A base64url token of `salt || iv || ciphertext+tag`.
+ * @throws Error when WebCrypto is not available in the runtime.
+ */
 export const encryptJSON = async (secret, value) => {
     const crypto = globalThis.crypto;
     if (!crypto?.getRandomValues) {
@@ -73,6 +85,16 @@ export const encryptJSON = async (secret, value) => {
     out.set(cipherBytes, salt.length + iv.length);
     return toBase64Url(out);
 };
+/**
+ * Reverses {@link encryptJSON}: re-derives the key from `secret` and the salt in
+ * the token, then decrypts and parses the JSON.
+ *
+ * @param secret - The passphrase the token was encrypted with.
+ * @param token - The base64url token `encryptJSON` returned.
+ * @returns The parsed value, cast to `T` without validation.
+ * @throws Error on a truncated token; the WebCrypto `OperationError` when the
+ *   secret is wrong or the token was tampered with (the GCM tag fails).
+ */
 export const decryptJSON = async (secret, token) => {
     const subtle = getSubtle();
     const data = fromBase64Url(token);
@@ -91,7 +113,16 @@ export const decryptJSON = async (secret, token) => {
  * another purpose derives a different key. See knowledge/crypto.md.
  */
 export const REMOTE_SESSION_INFO = 'pikku:remote-session';
+/** Shortest key material, in characters, that the `*WithKeyMaterial` helpers accept. */
 export const MIN_KEY_MATERIAL_LENGTH = 32;
+/**
+ * Refuses key material shorter than {@link MIN_KEY_MATERIAL_LENGTH}. HKDF does no
+ * stretching, so a short secret would be brute-forceable.
+ *
+ * @param name - The secret's name, used in the error message (the value is never included).
+ * @param keyMaterial - The material to check.
+ * @throws WeakKeyMaterialError when the material is too short.
+ */
 export const assertStrongKeyMaterial = (name, keyMaterial) => {
     if (keyMaterial.length < MIN_KEY_MATERIAL_LENGTH) {
         throw new WeakKeyMaterialError(name, MIN_KEY_MATERIAL_LENGTH, keyMaterial.length);
@@ -107,6 +138,20 @@ const expandKeyMaterial = async (keyMaterial, info, salt) => {
         info: encoder.encode(info),
     }, material, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
 };
+/**
+ * Encrypts a JSON-serialisable value with AES-256-GCM under a key expanded from
+ * high-entropy key material by HKDF-SHA256, with a fresh random salt per call.
+ *
+ * `info` domain-separates the derived key, so the same deployment secret used for
+ * two purposes (e.g. {@link REMOTE_SESSION_INFO}) yields two unrelated keys.
+ *
+ * @param name - The key material's name, for the weak-key error.
+ * @param keyMaterial - At least {@link MIN_KEY_MATERIAL_LENGTH} characters.
+ * @param info - The HKDF context string; decryption must pass the same one.
+ * @param value - Any value `JSON.stringify` accepts.
+ * @returns A base64url token of `salt || iv || ciphertext+tag`.
+ * @throws WeakKeyMaterialError when `keyMaterial` is too short.
+ */
 export const encryptWithKeyMaterial = async (name, keyMaterial, info, value) => {
     assertStrongKeyMaterial(name, keyMaterial);
     const crypto = globalThis.crypto;
@@ -125,6 +170,18 @@ export const encryptWithKeyMaterial = async (name, keyMaterial, info, value) =>
     out.set(cipherBytes, salt.length + iv.length);
     return toBase64Url(out);
 };
+/**
+ * Reverses {@link encryptWithKeyMaterial}.
+ *
+ * @param name - The key material's name, for the weak-key error.
+ * @param keyMaterial - The material the token was encrypted under.
+ * @param info - The same HKDF context string used to encrypt.
+ * @param token - The base64url token to decrypt.
+ * @returns The parsed value, cast to `T` without validation.
+ * @throws WeakKeyMaterialError when `keyMaterial` is too short; Error on a
+ *   truncated token; the WebCrypto `OperationError` when the key, `info` or
+ *   token is wrong.
+ */
 export const decryptWithKeyMaterial = async (name, keyMaterial, info, token) => {
     assertStrongKeyMaterial(name, keyMaterial);
     const subtle = getSubtle();
@@ -139,7 +196,9 @@ export const decryptWithKeyMaterial = async (name, keyMaterial, info, token) =>
     const decrypted = await subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
     return JSON.parse(decoder.decode(new Uint8Array(decrypted)));
 };
+/** UTF-8 encodes a string and returns it as unpadded base64url. An encoding, not encryption. */
 export const encodeBase64UrlText = (value) => toBase64Url(encoder.encode(value));
+/** Decodes unpadded (or padded) base64url back to a UTF-8 string. */
 export const decodeBase64UrlText = (value) => decoder.decode(fromBase64Url(value));
 const expandSigningKeyMaterial = async (keyMaterial, info) => {
     const subtle = getSubtle();
@@ -199,6 +258,12 @@ const decryptWithCryptoKey = async (key, token) => {
     const decrypted = await subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
     return JSON.parse(decoder.decode(new Uint8Array(decrypted)));
 };
+/**
+ * Generates a random 256-bit data-encryption key for envelope encryption.
+ *
+ * @returns The raw key as base64url. It is plaintext key material: wrap it with
+ *   {@link wrapDEK} before storing it.
+ */
 export const generateDEK = async () => {
     const raw = globalThis.crypto.getRandomValues(new Uint8Array(32));
     return toBase64Url(raw);
@@ -214,6 +279,14 @@ export const generateKEKSalt = () => {
     }
     return toBase64Url(crypto.getRandomValues(new Uint8Array(SALT_BYTES)));
 };
+/**
+ * Derives the AES-256-GCM key-encryption key from a passphrase and a salt from
+ * {@link generateKEKSalt}, by PBKDF2-SHA256 (600,000 iterations). The key is
+ * non-extractable.
+ *
+ * @param passphrase - The deployment's master passphrase.
+ * @param salt - The base64url salt stored beside the wrapped DEKs.
+ */
 export const deriveKEK = async (passphrase, salt) => {
     return deriveKey(passphrase, fromBase64Url(salt));
 };
@@ -223,9 +296,15 @@ export const deriveKEK = async (passphrase, salt) => {
  * once and audited once instead of at each call site.
  */
 const asWrapped = (ciphertext) => ciphertext;
+/** Encrypts a plaintext DEK under the KEK (AES-GCM, random IV) so it can be stored. */
 export const wrapDEK = async (kek, plaintextDEK) => {
     return asWrapped(await encryptWithCryptoKey(kek, plaintextDEK));
 };
+/**
+ * Decrypts a DEK wrapped by {@link wrapDEK}.
+ *
+ * @throws Error on a truncated token; the WebCrypto `OperationError` when the KEK is wrong.
+ */
 export const unwrapDEK = async (kek, wrappedDEK) => {
     return decryptWithCryptoKey(kek, wrappedDEK);
 };
@@ -235,6 +314,14 @@ const encryptWithDEK = async (dekBase64, value) => {
 const decryptWithDEK = async (dekBase64, token) => {
     return decryptWithCryptoKey(await importRawKey(fromBase64Url(dekBase64)), token);
 };
+/**
+ * Envelope-encrypts a value: a fresh DEK encrypts the value, and the KEK encrypts
+ * the DEK. Rotating the KEK then only needs {@link envelopeRewrap} on each
+ * wrapped DEK, not re-encryption of the data.
+ *
+ * @param kek - The key-encryption key from {@link deriveKEK}.
+ * @param value - Any value `JSON.stringify` accepts.
+ */
 export const envelopeEncrypt = async (kek, value) => {
     const dek = await generateDEK();
     const ciphertext = asWrapped(await encryptWithDEK(dek, value));
@@ -255,6 +342,11 @@ export const envelopeDecrypt = async (kek, ciphertext, wrappedDEK) => {
     const dek = await unwrapDEK(kek, wrappedDEK);
     return decryptWithDEK(dek, ciphertext);
 };
+/**
+ * Re-wraps a DEK under a new KEK for key rotation. The data ciphertext is unchanged.
+ *
+ * @throws The WebCrypto `OperationError` when `oldKEK` did not wrap this DEK.
+ */
 export const envelopeRewrap = async (oldKEK, newKEK, wrappedDEK) => {
     const dek = await unwrapDEK(oldKEK, wrappedDEK);
     return wrapDEK(newKEK, dek);

package/dist/dev/hot-reload.d.ts

@@ -4,10 +4,26 @@ interface PikkuDevReloaderOptions {
     srcDirectories: string[];
     logger: Logger;
 }
+/** Controls a running {@link pikkuDevReloader}. */
 export interface PikkuDevReloaderHandle {
     close: () => void;
     /** Re-import every file changed since the last drain (post-codegen, once
      *  fresh meta is in state). */
     reimportPending: () => Promise<void>;
 }
+/**
+ * Watches the source directories and hot-swaps changed function exports into the
+ * running process, for `pikku dev`.
+ *
+ * Each changed `.ts` file (not tests, `.d.ts`, `.gen.ts` or hidden files) is
+ * re-imported after a 50ms debounce; every export that looks like a function
+ * config replaces the registered one, and the HTTP router and middleware,
+ * permission and channel-middleware caches are reset so re-run wirings take
+ * effect. A file that fails to import is logged and the old code is kept.
+ *
+ * Development only: it executes whatever is written to the watched directories.
+ *
+ * @param options - `srcDirectories` to watch and the `logger` reloads report to.
+ * @returns A handle to stop watching and to re-import files after codegen.
+ */
 export declare function pikkuDevReloader(options: PikkuDevReloaderOptions): Promise<PikkuDevReloaderHandle>;

package/dist/dev/hot-reload.js

@@ -3,7 +3,7 @@ import { basename, join, resolve, relative } from 'node:path';
 import { pikkuState } from '../pikku-state.js';
 import { clearMiddlewareCache } from '../middleware-runner.js';
 import { clearPermissionsCache } from '../permissions.js';
-import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middleware-runner.js';
+import { clearChannelMiddlewareCache } from '../channel-middleware-runner.js';
 import { httpRouter } from '../wirings/http/routers/http-router.js';
 import { createModuleRunner, isTopLevelAwaitLimitation, } from './module-runner.js';
 export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js';
@@ -35,6 +35,21 @@ const reloadFailureReason = (error) => {
     }
     return `  ${error.stack ?? error.message}`;
 };
+/**
+ * Watches the source directories and hot-swaps changed function exports into the
+ * running process, for `pikku dev`.
+ *
+ * Each changed `.ts` file (not tests, `.d.ts`, `.gen.ts` or hidden files) is
+ * re-imported after a 50ms debounce; every export that looks like a function
+ * config replaces the registered one, and the HTTP router and middleware,
+ * permission and channel-middleware caches are reset so re-run wirings take
+ * effect. A file that fails to import is logged and the old code is kept.
+ *
+ * Development only: it executes whatever is written to the watched directories.
+ *
+ * @param options - `srcDirectories` to watch and the `logger` reloads report to.
+ * @returns A handle to stop watching and to re-import files after codegen.
+ */
 export async function pikkuDevReloader(options) {
     const { srcDirectories, logger } = options;
     const absSrcDirs = srcDirectories.map((d) => resolve(d));

package/dist/dev/module-runner.js

@@ -7,9 +7,13 @@ let transformSync;
 const loadTransform = async () => {
     if (transformSync)
         return transformSync;
-    // esbuild is a dev-only dependency hoisted from @pikku/cli at runtime; the
-    // `./dev` export is dev-only so it is never loaded in production runtimes.
-    const esbuild = await import('esbuild');
+    // esbuild is an optional peer: only the dev-only `./dev` export needs it, so
+    // production installs never have to carry it.
+    const esbuild = await import('esbuild').catch((e) => {
+        if (e?.code !== 'ERR_MODULE_NOT_FOUND')
+            throw e;
+        throw new Error("@pikku/core/dev needs the optional peer dependency 'esbuild'. Install it in your project (npm install -D esbuild).", { cause: e });
+    });
     transformSync = esbuild.transformSync;
     return transformSync;
 };

package/dist/dev/reload-meta.js

@@ -4,7 +4,7 @@ import { pikkuState } from '../pikku-state.js';
 import { addSchema, compileAllSchemas } from '../schema.js';
 import { clearMiddlewareCache } from '../middleware-runner.js';
 import { clearPermissionsCache } from '../permissions.js';
-import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middleware-runner.js';
+import { clearChannelMiddlewareCache } from '../channel-middleware-runner.js';
 import { httpRouter } from '../wirings/http/routers/http-router.js';
 const readJson = async (logger, file) => {
     let raw;

package/dist/errors/error-handler.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Base class for errors a function throws on purpose. Subclass it and register
+ * the subclass with {@link addError} to choose the status and message the
+ * caller gets; an unregistered error answers 500. `name` is set to the
+ * subclass's name, and {@link isExpectedError} treats every `PikkuError` as
+ * expected, so it is logged by message rather than with a stack trace.
+ * @group Error
+ */
 export declare class PikkuError extends Error {
     constructor(message?: string);
 }
@@ -10,6 +18,7 @@ export declare class PikkuError extends Error {
  * @example snippet: isExpectedError
  */
 export declare const isExpectedError: (error: unknown) => boolean;
+/** What {@link addError} registers against an error class. */
 export interface ErrorDetails {
     /** The HTTP status this error answers with, instead of a 500. */
     status: number;