@pikku/core 0.12.97 → 0.12.98

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## 0.12.98
+
+### Patch Changes
+
+- 80eb5c0: Remove the `addMiddleware` alias of `addTagMiddleware`.
+
+  The CLI inspector decides what registers tag middleware by matching the call's
+  identifier text, so `addMiddleware(...)` compiled, exported and registered
+  nothing — no error, no warning, and the middleware simply never ran. The name
+  was also the one the concept-mapping skill taught.
+
+  `addTagMiddleware` is the newer name and the scope-matched sibling of
+  `addGlobalMiddleware`; the alias was reintroduced after the rename that
+  established that pair.
+
+- 2252016: Decide whether a virtual-user run is against production from the configured
+  environment rather than `NODE_ENV`.
+
+  A deployment whose staging is a production mirror runs `NODE_ENV=production`
+  there too, so the old check refused every disposition on the one environment
+  they exist to be used on. `startVirtualUserRun` now takes the `environments`
+  generated beside the personas and the environment this process is (`PIKKU_ENV`
+  by default), which is the same signal `personaEnvironmentRefusal` already
+  checks at sign-in; the generated scaffold passes them. An environment that
+  cannot be resolved is treated as production. `NODE_ENV` remains the answer for
+  a project that configures no environments at all.
+
 ## 0.12.97
 
 ### Patch Changes

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

@@ -55,6 +55,16 @@ export interface ColumnClassification {
     anonymize_strategy: AnonymizeStrategy;
     /** At-rest representation. Absent means `plain`. */
     form?: ColumnForm;
+    /**
+     * Which key protects this column, for a `wrapped` or `sealed` form. Absent
+     * means the deployment's default key.
+     *
+     * It is a purpose, not a tenant: naming one here says "these columns open
+     * together and separately from the rest", so the key that opens notes need
+     * not open credentials. The id is stored in the value, so a column that
+     * changes key is a rewrap rather than a migration.
+     */
+    keyId?: string;
     description?: string;
 }
 export type ClassificationManifest = {

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

@@ -0,0 +1,80 @@
+import type { WrappedValue } from './data-classification.js';
+export type LockState = 'uninitialized' | 'locked' | 'unlocked';
+/**
+ * One KEK's stored material: everything a passphrase has to reproduce, and
+ * nothing a passphrase could be recovered from.
+ */
+export type LockRecord = {
+    keyId: string;
+    keyVersion: number;
+    salt: string;
+    /**
+     * A DEK sealed under this KEK. Unwrapping it is the passphrase check — AES-GCM
+     * fails its authentication tag under the wrong key, so a bad passphrase is
+     * caught before it can produce a single garbled row.
+     */
+    verifier: WrappedValue;
+};
+/**
+ * Where lock records live.
+ *
+ * Necessarily readable while locked — a store that needed its own key to find
+ * out how to unlock itself could never be opened. It holds no plaintext key
+ * material, so this costs nothing.
+ */
+export interface LockVault {
+    read(): Promise<LockRecord[]>;
+    write(records: LockRecord[]): Promise<void>;
+}
+/**
+ * The gate in front of every classified column.
+ *
+ * A key is never held at construction: the server boots locked and serves the
+ * unlock screen, so the passphrase arrives over HTTP long after services are
+ * built. `getKEK` is what a Kysely classification resolver calls per operation,
+ * and it throws rather than returning a falsy key — silently writing plaintext
+ * into a column the manifest calls `wrapped` would look like a working app
+ * while the data sat exposed.
+ */
+export declare class DataLock {
+    private readonly vault;
+    private keks;
+    private records;
+    private initialized;
+    private failures;
+    private lockedOutUntil;
+    private readonly now;
+    constructor(vault: LockVault, options?: {
+        now?: () => number;
+    });
+    get state(): LockState;
+    /**
+     * How long before another guess will be looked at, or 0.
+     *
+     * Exposed so an unlock screen can show the wait instead of discovering it by
+     * guessing again — a guess made during a lockout is itself a failure, and
+     * extends the window it was trying to wait out.
+     */
+    get retryAfterMs(): number;
+    /** Read what the store already has, so `state` can answer. */
+    init(): Promise<LockState>;
+    /**
+     * First run: mint a salt and verifier per key and leave the store open, since
+     * whoever chose the passphrase a moment ago does not need to retype it.
+     */
+    initialize(passphrase: string, keyIds?: string[]): Promise<void>;
+    unlock(passphrase: string): Promise<void>;
+    lock(): void;
+    getKEK(keyId: string): Promise<CryptoKey>;
+    /**
+     * The version to stamp into a value written under `keyId`.
+     *
+     * Separate from `getKEK` because only a write has to ask: a stored value
+     * carries the version it was sealed under, so a read already knows. Readable
+     * while locked, since a version number is not key material.
+     */
+    getKeyVersion(keyId: string): number;
+    private assertKnownKeyId;
+    private recordFailure;
+    private assertInitialized;
+}

package/dist/classification/data-lock.js

@@ -0,0 +1,146 @@
+import { deriveKEK, generateDEK, generateKEKSalt, unwrapDEK, wrapDEK, } from '../crypto-utils.js';
+import { DataLockedError, InvalidPassphraseError, TooManyAttemptsError, } from '../errors/errors.js';
+import { DEFAULT_KEY_ID } from './key-ids.js';
+/** Wrong guesses tolerated before a lockout window opens. */
+const MAX_ATTEMPTS = 5;
+const LOCKOUT_MS = 30_000;
+const MAX_LOCKOUT_MS = 15 * 60_000;
+/**
+ * The gate in front of every classified column.
+ *
+ * A key is never held at construction: the server boots locked and serves the
+ * unlock screen, so the passphrase arrives over HTTP long after services are
+ * built. `getKEK` is what a Kysely classification resolver calls per operation,
+ * and it throws rather than returning a falsy key — silently writing plaintext
+ * into a column the manifest calls `wrapped` would look like a working app
+ * while the data sat exposed.
+ */
+export class DataLock {
+    vault;
+    keks = new Map();
+    records = [];
+    initialized = false;
+    failures = 0;
+    lockedOutUntil = 0;
+    now;
+    constructor(vault, options = {}) {
+        this.vault = vault;
+        this.now = options.now ?? Date.now;
+    }
+    get state() {
+        if (!this.records.length) {
+            return 'uninitialized';
+        }
+        return this.keks.size ? 'unlocked' : 'locked';
+    }
+    /**
+     * How long before another guess will be looked at, or 0.
+     *
+     * Exposed so an unlock screen can show the wait instead of discovering it by
+     * guessing again — a guess made during a lockout is itself a failure, and
+     * extends the window it was trying to wait out.
+     */
+    get retryAfterMs() {
+        return Math.max(0, this.lockedOutUntil - this.now());
+    }
+    /** Read what the store already has, so `state` can answer. */
+    async init() {
+        this.records = await this.vault.read();
+        this.initialized = true;
+        return this.state;
+    }
+    /**
+     * First run: mint a salt and verifier per key and leave the store open, since
+     * whoever chose the passphrase a moment ago does not need to retype it.
+     */
+    async initialize(passphrase, keyIds = [DEFAULT_KEY_ID]) {
+        this.assertInitialized();
+        if (this.records.length) {
+            throw new Error('This store is already initialized. Re-initializing would seal it under a new key while every existing row stayed sealed under the old one.');
+        }
+        const records = [];
+        for (const keyId of keyIds) {
+            const salt = generateKEKSalt();
+            const kek = await deriveKEK(passphrase, salt);
+            records.push({
+                keyId,
+                keyVersion: 1,
+                salt,
+                verifier: await wrapDEK(kek, await generateDEK()),
+            });
+            this.keks.set(keyId, kek);
+        }
+        await this.vault.write(records);
+        this.records = records;
+    }
+    async unlock(passphrase) {
+        this.assertInitialized();
+        if (this.now() < this.lockedOutUntil) {
+            // A correct passphrase waits too. Exempting it would hand an attacker the
+            // oracle the throttle exists to deny: a guess that behaves differently is
+            // a guess that has been confirmed.
+            throw new TooManyAttemptsError();
+        }
+        const opened = new Map();
+        for (const record of this.records) {
+            const kek = await deriveKEK(passphrase, record.salt);
+            try {
+                await unwrapDEK(kek, record.verifier);
+            }
+            catch {
+                this.recordFailure();
+                // Which record failed says which key the passphrase was not for, so the
+                // whole attempt fails as one rather than naming it.
+                throw new InvalidPassphraseError();
+            }
+            opened.set(record.keyId, kek);
+        }
+        this.failures = 0;
+        this.lockedOutUntil = 0;
+        this.keks = opened;
+    }
+    lock() {
+        this.keks.clear();
+    }
+    async getKEK(keyId) {
+        // A keyId nobody initialized is a configuration error, and saying "locked"
+        // about it sends whoever reads that log hunting for a passphrase to a
+        // store that is already open. `DataLockedError` means only the lock state.
+        this.assertKnownKeyId(keyId);
+        const kek = this.keks.get(keyId);
+        if (!kek) {
+            throw new DataLockedError();
+        }
+        return kek;
+    }
+    /**
+     * The version to stamp into a value written under `keyId`.
+     *
+     * Separate from `getKEK` because only a write has to ask: a stored value
+     * carries the version it was sealed under, so a read already knows. Readable
+     * while locked, since a version number is not key material.
+     */
+    getKeyVersion(keyId) {
+        this.assertKnownKeyId(keyId);
+        return this.records.find((record) => record.keyId === keyId).keyVersion;
+    }
+    assertKnownKeyId(keyId) {
+        if (!this.records.some((record) => record.keyId === keyId)) {
+            throw new Error(`No lock record for key "${keyId}" — every keyId a column names has to be passed to initialize(). Derive the list from the classification manifest with keyIdsFromManifest() so the two cannot drift.`);
+        }
+    }
+    recordFailure() {
+        this.failures += 1;
+        if (this.failures < MAX_ATTEMPTS) {
+            return;
+        }
+        const escalation = this.failures - MAX_ATTEMPTS;
+        this.lockedOutUntil =
+            this.now() + Math.min(LOCKOUT_MS * 2 ** escalation, MAX_LOCKOUT_MS);
+    }
+    assertInitialized() {
+        if (!this.initialized) {
+            throw new Error('DataLock.init() must run before the store is used');
+        }
+    }
+}

package/dist/classification/index.d.ts

@@ -11,3 +11,4 @@ export type { Private, Pii, Secret, Classification, AnonymizeStrategy, ColumnFor
 export { hashToken, unsafeAsWrapped, unsafeAsSealed, unsafeAsHashed, } from './column-form.js';
 export { REDACTED, SecretCoercionError, SecretValue, createSecretValue, isSecretValue, } from './secret-value.js';
 export type { Safe } from './secret-value.js';
+export { DEFAULT_KEY_ID } from './key-ids.js';

package/dist/classification/index.js

@@ -1,2 +1,3 @@
 export { hashToken, unsafeAsWrapped, unsafeAsSealed, unsafeAsHashed, } from './column-form.js';
 export { REDACTED, SecretCoercionError, SecretValue, createSecretValue, isSecretValue, } from './secret-value.js';
+export { DEFAULT_KEY_ID } from './key-ids.js';

package/dist/classification/key-ids.d.ts

@@ -0,0 +1,2 @@
+/** The key a column protects itself with when it names none. */
+export declare const DEFAULT_KEY_ID = "default";

package/dist/classification/key-ids.js

@@ -0,0 +1,2 @@
+/** The key a column protects itself with when it names none. */
+export const DEFAULT_KEY_ID = 'default';

package/dist/middleware/index.d.ts

@@ -5,7 +5,7 @@ export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';
 export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';
-export { addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, runMiddleware, } from '../middleware-runner.js';
+export { addTagMiddleware, addGlobalMiddleware, runMiddleware, } from '../middleware-runner.js';
 export { addGlobalPermission } from '../permissions.js';
 export type { CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, MiddlewareMetadata, MiddlewarePriority, } from './middleware.types.js';
 export { pikkuAgentMiddleware, pikkuChannelMiddleware, pikkuChannelMiddlewareFactory, pikkuMiddleware, pikkuMiddlewareFactory, } from './middleware-factories.js';

package/dist/middleware/index.js

@@ -5,6 +5,6 @@ export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';
 export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js';
 export { telemetryOuter, telemetryInner } from './telemetry.js';
-export { addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, runMiddleware, } from '../middleware-runner.js';
+export { addTagMiddleware, addGlobalMiddleware, runMiddleware, } from '../middleware-runner.js';
 export { addGlobalPermission } from '../permissions.js';
 export { pikkuAgentMiddleware, pikkuChannelMiddleware, pikkuChannelMiddlewareFactory, pikkuMiddleware, pikkuMiddlewareFactory, } from './middleware-factories.js';

package/dist/middleware/require-unlocked.d.ts

@@ -0,0 +1,23 @@
+import type { DataLock } from '../classification/data-lock.js';
+/**
+ * Refuses a request while the encrypted store is locked.
+ *
+ * Applied by tag or route rather than globally, because the unlock endpoint and
+ * the static frontend have to stay reachable — a store that gated its own
+ * unlock screen could never be opened. Static mounts serve a file hit before
+ * dispatch, so the app shell is already outside this gate; the unlock function
+ * is the one wiring that must not carry it.
+ *
+ * The gate is deliberately in front of the function rather than inside the
+ * query layer. Both refuse, but only this one refuses before the handler has
+ * touched the database.
+ */
+export declare const requireUnlocked: (lock: DataLock) => import("./middleware.types.js").CorePikkuMiddleware<import("../types/core.types.js").CoreSingletonServices<{
+    logLevel?: import("../services/logger.js").LogLevel;
+    secrets?: {
+        requireAllowedHosts?: boolean;
+    };
+    workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+    webhook?: import("../services/webhook-service.js").WebhookServiceConfig;
+    postgres?: import("../types/core.types.js").PostgresConfig;
+}>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/require-unlocked.js

@@ -0,0 +1,21 @@
+import { DataLockedError } from '../errors/errors.js';
+import { pikkuMiddleware } from './middleware-factories.js';
+/**
+ * Refuses a request while the encrypted store is locked.
+ *
+ * Applied by tag or route rather than globally, because the unlock endpoint and
+ * the static frontend have to stay reachable — a store that gated its own
+ * unlock screen could never be opened. Static mounts serve a file hit before
+ * dispatch, so the app shell is already outside this gate; the unlock function
+ * is the one wiring that must not carry it.
+ *
+ * The gate is deliberately in front of the function rather than inside the
+ * query layer. Both refuse, but only this one refuses before the handler has
+ * touched the database.
+ */
+export const requireUnlocked = (lock) => pikkuMiddleware(async (_services, _wires, next) => {
+    if (lock.state !== 'unlocked') {
+        throw new DataLockedError();
+    }
+    return next();
+});

package/dist/wirings/data-lock/data-lock-wiring.d.ts

@@ -0,0 +1,40 @@
+import type { DataLock, LockState } from '../../classification/data-lock.js';
+export type DataLockStatus = {
+    state: LockState;
+    /**
+     * Milliseconds before another guess will be looked at, or 0.
+     *
+     * The unlock screen shows this as a countdown; without it the only way to
+     * learn the wait is over is to guess again, and a guess made during a
+     * lockout is itself a failure that extends it.
+     */
+    retryAfterMs: number;
+};
+export type DataLockWiringOptions = {
+    /** Where the lock routes are mounted. Defaults to `/_pikku/data`. */
+    prefix?: string;
+    /**
+     * Which keys first-run initialization mints. Derive it with
+     * `keyIdsFromManifest`.
+     *
+     * It is fixed here rather than sent by the caller because the unlock screen
+     * posts a passphrase and nothing else — and because a key the schema names
+     * but nobody minted does not fail at startup, it fails at the first write to
+     * that one column.
+     */
+    keyIds?: string[];
+};
+/**
+ * Puts the passphrase gate on HTTP, so unlocking is a page in the app rather
+ * than a prompt in whatever happens to have launched the server.
+ *
+ * That is what lets one story cover both shapes pikku ships in: a desktop
+ * build whose window is pointed at the local server, and a headless
+ * `pikku serve` somewhere else, unlock the same way and share the unlock
+ * screen. A native prompt in the desktop shell would have left the headless
+ * case with nothing.
+ *
+ * The routes are registered here rather than generated because they belong to
+ * core: an app has no source file for them to be discovered in.
+ */
+export declare const wireDataLock: (lock: DataLock, { prefix, keyIds }?: DataLockWiringOptions) => void;

package/dist/wirings/data-lock/data-lock-wiring.js

@@ -0,0 +1,77 @@
+import { pikkuState } from '../../pikku-state.js';
+import { wireHTTP } from '../http/http-runner.js';
+import { httpRouter } from '../http/routers/http-router.js';
+const helperFunctionMeta = (funcId) => ({
+    pikkuFuncId: funcId,
+    sessionless: true,
+    functionType: 'helper',
+    inputSchemaName: null,
+    outputSchemaName: null,
+});
+const DEFAULT_PREFIX = '/_pikku/data';
+/**
+ * Puts the passphrase gate on HTTP, so unlocking is a page in the app rather
+ * than a prompt in whatever happens to have launched the server.
+ *
+ * That is what lets one story cover both shapes pikku ships in: a desktop
+ * build whose window is pointed at the local server, and a headless
+ * `pikku serve` somewhere else, unlock the same way and share the unlock
+ * screen. A native prompt in the desktop shell would have left the headless
+ * case with nothing.
+ *
+ * The routes are registered here rather than generated because they belong to
+ * core: an app has no source file for them to be discovered in.
+ */
+export const wireDataLock = (lock, { prefix = DEFAULT_PREFIX, keyIds } = {}) => {
+    const status = () => ({
+        state: lock.state,
+        retryAfterMs: lock.retryAfterMs,
+    });
+    register(prefix, 'get', '/status', 'pikkuDataLockStatus', async () => status());
+    register(prefix, 'post', '/initialize', 'pikkuDataLockInitialize', async (_services, { passphrase }) => {
+        await lock.initialize(passphrase, keyIds);
+        return status();
+    });
+    register(prefix, 'post', '/unlock', 'pikkuDataLockUnlock', async (_services, { passphrase }) => {
+        await lock.unlock(passphrase);
+        return status();
+    });
+    register(prefix, 'post', '/lock', 'pikkuDataLockLock', async (_services, { passphrase }) => {
+        // Locking proves ownership first. An open POST here would be a
+        // one-request denial of service: the store shuts and stays shut until
+        // someone is around to type the passphrase back in.
+        await lock.unlock(passphrase);
+        lock.lock();
+        return status();
+    });
+    // A router that has already compiled its table would otherwise answer 404
+    // for everything registered after it woke up.
+    httpRouter.reset();
+};
+const register = (prefix, method, path, funcId, func) => {
+    const route = `${prefix}${path}`;
+    const routes = pikkuState(null, 'http', 'routes');
+    if (routes.get(method)?.has(route)) {
+        return;
+    }
+    const httpMeta = pikkuState(null, 'http', 'meta');
+    httpMeta[method][route] = {
+        pikkuFuncId: funcId,
+        route,
+        method,
+        // Never a session. The gate cannot sit in front of its own key: a session
+        // may itself live in a column this lock is holding shut.
+        auth: false,
+        requiresSession: false,
+    };
+    const functionsMeta = pikkuState(null, 'function', 'meta');
+    if (!functionsMeta[funcId]) {
+        functionsMeta[funcId] = helperFunctionMeta(funcId);
+    }
+    wireHTTP({
+        method,
+        route,
+        func: { func },
+        auth: false,
+    });
+};

package/dist/wirings/data-lock/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The HTTP face of {@link DataLock}: the routes an unlock screen talks to.
+ *
+ * Separate from `@pikku/core/classification` on purpose — that entry point is
+ * types and crypto, and a runtime that never serves HTTP should not have to
+ * load a router to use it.
+ */
+export { wireDataLock } from './data-lock-wiring.js';
+export type { DataLockStatus, DataLockWiringOptions, } from './data-lock-wiring.js';

package/dist/wirings/data-lock/index.js

@@ -0,0 +1,8 @@
+/**
+ * The HTTP face of {@link DataLock}: the routes an unlock screen talks to.
+ *
+ * Separate from `@pikku/core/classification` on purpose — that entry point is
+ * types and crypto, and a runtime that never serves HTTP should not have to
+ * load a router to use it.
+ */
+export { wireDataLock } from './data-lock-wiring.js';

package/dist/wirings/virtual-user/virtual-user-scaffold.d.ts

@@ -4,6 +4,7 @@ import type { VariablesService } from '../../services/variables-service.js';
 import type { AgentRunnerService } from '../../services/agent-runner-service.js';
 import type { HttpPersonasConfig } from '../../services/http-personas.js';
 import type { ResolvedPersona, ScenarioPersonas } from '../../services/personas-service.js';
+import type { PersonaEnvironment } from '../persona/persona-environments.js';
 import type { StepRecord, VirtualUserDisposition } from './virtual-user.types.js';
 import type { VirtualUserRunRecord, VirtualUserRunStore } from './virtual-user-run-store.js';
 import type { VirtualUserScheduleRecord, VirtualUserScheduleStore } from './virtual-user-schedule-store.js';
@@ -84,10 +85,15 @@ export interface StartVirtualUserRunParams {
     /**
      * The app's config, read only for `nodeEnv` — structural because an
      * application's Config is its own interface and need not declare it at all.
+     * The fallback signal, used only by a project that configures no environments.
      */
     config: {
         nodeEnv?: string;
     } | undefined;
+    /** `environments` from pikku.config.json, as generated beside the personas. */
+    environments?: Readonly<Record<string, PersonaEnvironment>>;
+    /** Which of them this process is. Defaults to `PIKKU_ENV`. */
+    environment?: string;
     persona: string;
     disposition?: string;
     seed?: number;
@@ -112,7 +118,7 @@ export interface StartedVirtualUserRun {
  * scheduled tick have in common. The dispatch that follows is typed off the
  * app's RPC map, so it stays in the generated wiring.
  */
-export declare const startVirtualUserRun: ({ store, personas, config, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }: StartVirtualUserRunParams) => Promise<StartedVirtualUserRun>;
+export declare const startVirtualUserRun: ({ store, personas, config, environments, environment, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }: StartVirtualUserRunParams) => Promise<StartedVirtualUserRun>;
 /**
  * One run on the wire.
  *

package/dist/wirings/virtual-user/virtual-user-scaffold.js

@@ -85,6 +85,28 @@ export const requireVirtualUserScheduleStore = (store) => {
     }
     return store;
 };
+/**
+ * Whether this process is running against production, for the disposition rule.
+ *
+ * The configured environment wins over `NODE_ENV` because they answer different
+ * questions. A deployment whose staging is a production *mirror* runs
+ * `NODE_ENV=production` there too — keying on it refuses every disposition on
+ * the one environment they exist to be used on. `PIKKU_ENV` names which of the
+ * configured environments this is, which is the question actually being asked,
+ * and it is the same signal `personaEnvironmentRefusal` already checks at
+ * sign-in.
+ *
+ * Unresolved is treated as production: an environment nobody can name is one
+ * whose data nobody can vouch for. `NODE_ENV` remains the answer only for a
+ * project that configures no environments at all, which has no production
+ * environment declared for this to be wrong about.
+ */
+const isProductionRun = (config, environments, environment) => {
+    if (!environments || Object.keys(environments).length === 0) {
+        return config?.nodeEnv === 'production';
+    }
+    return environment ? Boolean(environments[environment]?.production) : true;
+};
 /**
  * Resolves a request against the declaration and records the run.
  *
@@ -92,7 +114,7 @@ export const requireVirtualUserScheduleStore = (store) => {
  * scheduled tick have in common. The dispatch that follows is typed off the
  * app's RPC map, so it stays in the generated wiring.
  */
-export const startVirtualUserRun = async ({ store, personas, config, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }) => {
+export const startVirtualUserRun = async ({ store, personas, config, environments, environment = process.env.PIKKU_ENV, persona: personaId, disposition: requested, seed: requestedSeed, goals, memory, startedBy, }) => {
     const runStore = requireVirtualUserRunStore(store);
     const persona = runnablePersona(personas, personaId);
     const disposition = (requested ??
@@ -101,8 +123,8 @@ export const startVirtualUserRun = async ({ store, personas, config, persona: pe
     // Every disposition other than this one exists to find out what the product
     // does wrong, which is not a thing to do to real customers' data. Checked
     // against the effective disposition, so an override cannot smuggle one in.
-    if (config?.nodeEnv === 'production' &&
-        disposition !== PRODUCTION_DISPOSITION) {
+    if (disposition !== PRODUCTION_DISPOSITION &&
+        isProductionRun(config, environments, environment)) {
         throw new Error(`Only the '${PRODUCTION_DISPOSITION}' disposition may run against production; "${personaId}" is ${disposition}`);
     }
     // Seeded here rather than inside the engine so the record carries the seed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.97",
+  "version": "0.12.98",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/classification/data-classification.ts

@@ -54,6 +54,16 @@ export interface ColumnClassification {
   anonymize_strategy: AnonymizeStrategy
   /** At-rest representation. Absent means `plain`. */
   form?: ColumnForm
+  /**
+   * Which key protects this column, for a `wrapped` or `sealed` form. Absent
+   * means the deployment's default key.
+   *
+   * It is a purpose, not a tenant: naming one here says "these columns open
+   * together and separately from the rest", so the key that opens notes need
+   * not open credentials. The id is stored in the value, so a column that
+   * changes key is a rewrap rather than a migration.
+   */
+  keyId?: string
   description?: string
 }
 

package/src/classification/index.ts

@@ -36,3 +36,5 @@ export {
   isSecretValue,
 } from './secret-value.js'
 export type { Safe } from './secret-value.js'
+
+export { DEFAULT_KEY_ID } from './key-ids.js'

package/src/classification/key-ids.ts

@@ -0,0 +1,2 @@
+/** The key a column protects itself with when it names none. */
+export const DEFAULT_KEY_ID = 'default'

package/src/middleware/index.ts

@@ -7,7 +7,6 @@ export { requireOrigin, isAllowedOrigin, toOrigin } from './require-origin.js'
 export { telemetryOuter, telemetryInner } from './telemetry.js'
 export {
   addTagMiddleware,
-  addTagMiddleware as addMiddleware,
   addGlobalMiddleware,
   runMiddleware,
 } from '../middleware-runner.js'

package/src/public-surface.json

@@ -4,7 +4,6 @@
   "./middleware": [
     "addGlobalMiddleware",
     "addGlobalPermission",
-    "addMiddleware",
     "addTagMiddleware",
     "authAPIKey",
     "authBearer",
@@ -454,6 +453,7 @@
     "setSingletonServices"
   ],
   "./classification": [
+    "DEFAULT_KEY_ID",
     "REDACTED",
     "SecretCoercionError",
     "SecretValue",