@pikku/core 0.12.97 → 0.12.99

package/CHANGELOG.md

@@ -1,3 +1,81 @@
+## 0.12.99
+
+### Patch Changes
+
+- ee9da9e: Reading an optional secret that is not set no longer makes `hasSecret` report it as set. `TypedSecretService` caches `undefined` to remember the absence, and the cache probe read that as a value.
+- 7a15c9c: An actor credential is one persona's, not everyone's
+
+  `SCENARIO_ACTOR_SECRET` was a skeleton key. Anyone holding it could post any
+  `actor: true` address to `/auth/sign-in/actor` and get that persona's session —
+  including the `admin` persona, which provisioning grants real admin. The browser
+  switcher held it too, baked into the dev bundle as `VITE_SCENARIO_ACTOR_SECRET`,
+  so "the reviewer can sign in as each kind of user" and "the reviewer's bundle is
+  entitled to every persona" were the same fact.
+
+  It is now a root that credentials derive from, never one that is presented:
+
+  ```ts
+  deriveActorSecret(root, email) // HKDF-expanded HMAC-SHA256 over the address
+  ```
+
+  The endpoint re-derives the expected value for whichever address is signing in
+  and compares, so nothing is stored or looked up, a credential minted for one
+  persona is refused for every other, and rotating the root invalidates all of
+  them at once. The root itself is no longer a valid credential, and a root under
+  32 characters refuses the endpoint rather than deriving weak credentials from
+  it — the server log says why, the client is not told.
+
+  What that buys, in the places that used to need the whole key:
+
+  - **`pikku dev`** mints one credential per declared persona into
+    `VITE_DEV_ACTOR_SECRETS` and no longer writes `VITE_SCENARIO_ACTOR_SECRET` at
+    all. The root stays on the server.
+  - **`pikku persona secret <id>`** mints them for anything else, and a run given
+    `PIKKU_PERSONA_SECRETS=id=secret,…` can sign in as those personas and no
+    others — asking for one outside the list throws naming the persona instead of
+    falling back to the root.
+
+  `useDevActors()` and `<DevActorSwitcher />` take `secrets` (one per address)
+  where they took `secret`, and an actor with no credential is no longer offered
+  rather than rendering a row that 401s. `HttpPersonasConfig.secret` and the
+  Playwright provider's `secret` additionally accept a resolver, which is how a
+  partially-credentialled run is expressed.
+
+- ee9da9e: the surface gate measures the surface it actually ships
+
+  The doc-quality gate went in with ceilings of 112, 823 and 10 beside a surface
+  that measured 160, 1210 and 15, so it never passed on any build. Re-baselined to
+  the real measurements, and the key-documentation floor earned its way from 76%
+  to 79% by documenting what a caller has to put in `defineSecret`, the gateway
+  message shapes, and the scorer and judge configs.
+
+## 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/services/http-personas.d.ts

@@ -1,6 +1,6 @@
 import type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, ScenarioInvokeOptions, ScenarioHttpResponse } from './personas-service.js';
 import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
-import { type OperatorSignInOptions } from './persona-sign-in.js';
+import { type ActorSecretResolver, type OperatorSignInOptions } from './persona-sign-in.js';
 export interface HttpPersonasConfig {
     /**
      * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.
@@ -10,13 +10,19 @@ export interface HttpPersonasConfig {
      */
     apiUrl: string;
     /**
-     * The impersonation secret. Sign-in only ever works for user rows flagged
-     * `actor: true` — knowing the secret never impersonates real users.
+     * The ROOT actor secret, from which each persona's own credential is derived
+     * and bound to their address. Sign-in only ever works for user rows flagged
+     * `actor: true`, and a derived credential only ever works for the one address
+     * it was derived for.
+     *
+     * Pass an {@link ActorSecretResolver} instead to drive personas whose
+     * credentials were minted elsewhere — a caller entitled to one persona then
+     * never holds the root.
      *
      * The local-development credential. A deployed stage has none, and passes
      * {@link HttpPersonasConfig.operator} instead.
      */
-    secret?: string;
+    secret?: string | ActorSecretResolver;
     /**
      * Fabric operator credentials, for signing personas into a DEPLOYED stage.
      *

package/dist/services/index.d.ts

@@ -23,6 +23,7 @@ export type { JWTService } from './jwt-service.js';
 export type { EmailService, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
 export { renderEmail, type EmailAssets, type EmailTemplateAssets, type EmailTemplateHashes, type RenderEmailRequest, type RenderedEmailResult, } from './email-template.js';
 export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, type SendWebhookInput, type SendWebhookResult, type WebhookAttemptResult, type WebhookDeliveryRecord, type WebhookDeliveryWithAttempts, type WebhookJobData, type WebhookServiceConfig, } from './webhook-service.js';
+export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from './persona-actor-secret.js';
 export type { Logger } from './logger.js';
 export type { SecretService, SecretValues } from './secret-service.js';
 export type { VariablesService } from './variables-service.js';

package/dist/services/index.js

@@ -19,6 +19,7 @@ export { LocalGatewayService } from './local-gateway-service.js';
 export { FileScenarioRunStore, scenarioArtifactContentType, scenarioRunSummary, } from './file-scenario-run-store.js';
 export { renderEmail, } from './email-template.js';
 export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
+export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from './persona-actor-secret.js';
 export { SchedulerService } from './scheduler-service.js';
 export { TypedCredentialService } from './typed-credential-service.js';
 export { NoopAuditService, createInvocationAudit } from './audit-service.js';

package/dist/services/persona-actor-secret.d.ts

@@ -0,0 +1,38 @@
+/** The name the root secret is held under, used only in error messages. */
+export declare const ACTOR_SECRET_NAME = "SCENARIO_ACTOR_SECRET";
+/**
+ * Namespaces the derivation so the same root secret used for anything else
+ * produces different values. See knowledge/crypto.md.
+ */
+export declare const ACTOR_SECRET_INFO = "pikku:actor-sign-in";
+/** The root must be strong: every persona's credential is derived from it. */
+export declare const ACTOR_ROOT_SECRET_MIN_LENGTH = 32;
+/**
+ * What the derivation is bound to. Lowercased because the sign-in endpoint
+ * looks the user up by lowercased address, and a credential that verified
+ * against a different string than the row it opens is a credential for nothing.
+ */
+export declare const actorSecretSubject: (email: string) => string;
+/**
+ * One persona's actor credential: `HMAC-SHA256(root, email)`, base64url.
+ *
+ * The root secret is not itself a valid credential and never travels: what a
+ * scenario run, a CI job or a virtual user is handed is the derived value for
+ * the one address it is entitled to. Presenting it for any other address fails,
+ * so a leaked credential is worth exactly one synthetic account rather than the
+ * whole actor population.
+ *
+ * Deterministic, so nothing is stored and nothing is provisioned — the target
+ * re-derives the expected value from the address being signed in as. Rotating
+ * the root invalidates every derived credential at once, which is the property
+ * a per-persona secret table would have to implement by hand.
+ */
+export declare const deriveActorSecret: (rootSecret: string, email: string) => Promise<string>;
+/**
+ * Whether `presented` is the credential for `email` under `rootSecret`.
+ *
+ * False — never throws — for a malformed, truncated or mismatched value, and
+ * the comparison is WebCrypto's own HMAC verify, so it does not exit early on
+ * the first differing byte.
+ */
+export declare const verifyActorSecret: (rootSecret: string, email: string, presented: string) => Promise<boolean>;

package/dist/services/persona-actor-secret.js

@@ -0,0 +1,39 @@
+import { MIN_KEY_MATERIAL_LENGTH, signWithKeyMaterial, verifyWithKeyMaterial, } from '../crypto-utils.js';
+/** The name the root secret is held under, used only in error messages. */
+export const ACTOR_SECRET_NAME = 'SCENARIO_ACTOR_SECRET';
+/**
+ * Namespaces the derivation so the same root secret used for anything else
+ * produces different values. See knowledge/crypto.md.
+ */
+export const ACTOR_SECRET_INFO = 'pikku:actor-sign-in';
+/** The root must be strong: every persona's credential is derived from it. */
+export const ACTOR_ROOT_SECRET_MIN_LENGTH = MIN_KEY_MATERIAL_LENGTH;
+/**
+ * What the derivation is bound to. Lowercased because the sign-in endpoint
+ * looks the user up by lowercased address, and a credential that verified
+ * against a different string than the row it opens is a credential for nothing.
+ */
+export const actorSecretSubject = (email) => email.trim().toLowerCase();
+/**
+ * One persona's actor credential: `HMAC-SHA256(root, email)`, base64url.
+ *
+ * The root secret is not itself a valid credential and never travels: what a
+ * scenario run, a CI job or a virtual user is handed is the derived value for
+ * the one address it is entitled to. Presenting it for any other address fails,
+ * so a leaked credential is worth exactly one synthetic account rather than the
+ * whole actor population.
+ *
+ * Deterministic, so nothing is stored and nothing is provisioned — the target
+ * re-derives the expected value from the address being signed in as. Rotating
+ * the root invalidates every derived credential at once, which is the property
+ * a per-persona secret table would have to implement by hand.
+ */
+export const deriveActorSecret = async (rootSecret, email) => signWithKeyMaterial(ACTOR_SECRET_NAME, rootSecret, ACTOR_SECRET_INFO, actorSecretSubject(email));
+/**
+ * Whether `presented` is the credential for `email` under `rootSecret`.
+ *
+ * False — never throws — for a malformed, truncated or mismatched value, and
+ * the comparison is WebCrypto's own HMAC verify, so it does not exit early on
+ * the first differing byte.
+ */
+export const verifyActorSecret = async (rootSecret, email, presented) => verifyWithKeyMaterial(ACTOR_SECRET_NAME, rootSecret, ACTOR_SECRET_INFO, actorSecretSubject(email), presented);

package/dist/services/persona-sign-in.d.ts

@@ -26,6 +26,11 @@ export interface PersonaSignIn {
     /** Headers every request after `login` must carry. */
     headers(): Record<string, string>;
 }
+/**
+ * Yields the credential for one persona, for a caller that holds that persona's
+ * derived secret and not the root it came from.
+ */
+export type ActorSecretResolver = (persona: ResolvedPersona) => string | Promise<string>;
 /**
  * Sign a persona in through the Better Auth actor plugin — the local-development
  * path.
@@ -34,12 +39,17 @@ export interface PersonaSignIn {
  * for it. Passwordless by design and refused for any row not carrying that flag,
  * so the secret can never reach a real user's account; the plugin still declines
  * to serve the endpoint at all outside `pikku dev`.
+ *
+ * What is presented is the persona's own credential, derived from the root and
+ * bound to their address. A run driving many personas holds the root and
+ * derives as it goes; a run entitled to one persona is handed that one value
+ * through a resolver and can sign in as nobody else.
  */
 export declare class ActorSignIn implements PersonaSignIn {
     private readonly apiUrl;
     private readonly secret;
     private readonly signInPath;
-    constructor(apiUrl: string, secret: string, signInPath: string);
+    constructor(apiUrl: string, secret: string | ActorSecretResolver, signInPath: string);
     login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void>;
     headers(): Record<string, string>;
 }

package/dist/services/persona-sign-in.js

@@ -1,3 +1,4 @@
+import { deriveActorSecret } from './persona-actor-secret.js';
 /**
  * The header `resolveImpersonatedSession` reads the target user id from.
  *
@@ -18,6 +19,11 @@ const failed = async (what, personaId, res) => {
  * for it. Passwordless by design and refused for any row not carrying that flag,
  * so the secret can never reach a real user's account; the plugin still declines
  * to serve the endpoint at all outside `pikku dev`.
+ *
+ * What is presented is the persona's own credential, derived from the root and
+ * bound to their address. A run driving many personas holds the root and
+ * derives as it goes; a run entitled to one persona is handed that one value
+ * through a resolver and can sign in as nobody else.
  */
 export class ActorSignIn {
     apiUrl;
@@ -29,13 +35,16 @@ export class ActorSignIn {
         this.signInPath = signInPath;
     }
     async login(jar, persona) {
+        const secret = typeof this.secret === 'function'
+            ? await this.secret(persona)
+            : await deriveActorSecret(this.secret, persona.email);
         const res = await jar.fetch(`${this.apiUrl}${this.signInPath}`, {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
             body: JSON.stringify({
                 email: persona.email,
                 name: persona.name,
-                secret: this.secret,
+                secret,
             }),
         });
         if (!res.ok) {

package/dist/services/typed-secret-service.js

@@ -21,8 +21,11 @@ export class TypedSecretService {
         return value;
     }
     async hasSecret(key) {
+        // `undefined` is cached for an optional secret that resolved absent, so a
+        // cache hit means "already looked", not "there is a value". Reporting true
+        // for it would let a read of an optional secret assert its own presence.
         if (this.cache.has(key)) {
-            return true;
+            return this.cache.get(key) !== undefined;
         }
         return this.secrets.hasSecret(key);
     }