@pikku/core 0.12.96 → 0.12.98

package/CHANGELOG.md

@@ -1,3 +1,53 @@
+## 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
+
+- 8154b1c: Restore the `SecretService.getSecret` JSDoc noting its failure mode, and state the `optional` carve-out `defineSecret` already documents: a key declared `optional` resolves `undefined` when absent rather than throwing. The line was on `main` and was removed by mistake in a comment cleanup on #1411 — the PR that changes what that throw says — leaving `getSecret` the only one of the interface's methods without its documented failure mode.
+- 6d9c09c: Resolve a variable's declared default instead of dropping it.
+
+  `defineVariable` takes a schema, and a schema can carry a default — `z.enum(['https://api.github.com']).default('https://api.github.com')` is the shape most addons declare their base URL with. Nothing read it. `variables.get('GITHUB_BASE_URL')` returned `undefined` on a host that had not set it, and the `as string` at the call site hid that until a request went to `undefined/repos/...`.
+
+  The default now resolves in `TypedVariablesService`, which is the layer that knows what was declared — `VariablesService` only knows what a host put in it. A stored value always wins; a schema with no default still resolves to `undefined`.
+
+  `VariableStatus` gains `hasDefault`, and `getMissing()` no longer lists a variable that defaults: it has a value, just not one anybody has to supply. `isConfigured` still means what it said — that a host set it.
+
+  For this to work the generated `TYPED_VARIABLES_META` now carries the schema as a value rather than only `z.infer`-ing its type, so the schema module is retained in the emit instead of being elided.
+
+- 239332b: Move first-party product analytics out of application code and into the framework.
+
+  `createAnalytics<Event>({ endpoint })` in `@pikku/react` is the buffered beacon client: it is typed against the app's own event union, flushes on an interval, on size and on `pagehide`/`visibilitychange` (via `sendBeacon`, so the abandon-point events survive unload), never surfaces a failure to the user and never retries. It also carries the delegated `data-analytics-click` listener, registered in the capture phase so a component calling `stopPropagation()` cannot silence instrumentation, and merging `data-analytics-meta` from ancestors with nearest-wins. Put the client on the Pikku instance and `usePikkuAnalytics<Event>()` reaches it from the provider, alongside `usePikkuFetch` and `usePikkuRPC`.
+
+  `requireOrigin()` in `@pikku/core/middleware` is a server-side origin lock for any unauthed route, and is re-exported from the generated `#pikku/middleware` leaf alongside `cors`. Unlike `cors()` — which only sets response headers a non-browser client ignores — it rejects with a 403 before the function body. Comparison is exact on the parsed origin, so `https://evil-myapp.com` cannot suffix-match `myapp.com`, and a missing `Origin` is rejected because a real browser always sets one on a cross-origin-capable POST. Allowed origins default to the request's own host and can be extended with a list or a resolver over services. `isAllowedOrigin` and `toOrigin` are exported for direct unit testing.
+
+  Together these let an app keep only its event registry and its wiring, instead of a few hundred lines of copied transport.
+
 ## 0.12.96
 
 ### 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

@@ -3,8 +3,9 @@ export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
 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

@@ -3,7 +3,8 @@ export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
 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-origin.d.ts

@@ -0,0 +1,23 @@
+import type { CoreSingletonServices } from '../types/core.types.js';
+/** Scheme + host + port, or null for anything unparseable including the literal `"null"` origin. */
+export declare const toOrigin: (value: string | null | undefined) => string | null;
+/**
+ * Whether a request origin may post to an origin-locked route.
+ *
+ * The comparison is exact on the parsed origin, never a suffix match:
+ * `endsWith('myapp.com')` also accepts `https://evil-myapp.com`.
+ */
+export declare const isAllowedOrigin: (requestOrigin: string | null, hostOrigin: string | null, configuredOrigins: string[]) => boolean;
+/**
+ * Rejects a request with a 403 unless its `Origin` is this app's own or explicitly allowed.
+ *
+ * This is not what `cors()` does. CORS sets response headers and is enforced by the
+ * browser, so a non-browser client ignores them and the request still runs; this rejects
+ * before the function body. It stops another site's page from posting to an unauthed
+ * route — it is not flood control, because `Origin` is trusted from nobody but a browser.
+ * A missing `Origin` is rejected too: a real browser sets one on a cross-origin-capable POST.
+ */
+export declare const requireOrigin: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
+    /** Extra allowed origins beyond the request's own host, or a resolver for them. */
+    origins?: string[] | ((services: CoreSingletonServices) => string[] | Promise<string[]>);
+}>;

package/dist/middleware/require-origin.js

@@ -0,0 +1,57 @@
+import { InvalidOriginError } from '../errors/errors.js';
+import { pikkuMiddleware, pikkuMiddlewareFactory, } from './middleware-factories.js';
+/** Scheme + host + port, or null for anything unparseable including the literal `"null"` origin. */
+export const toOrigin = (value) => {
+    if (!value)
+        return null;
+    try {
+        const url = new URL(value);
+        return url.protocol && url.host ? url.origin : null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Whether a request origin may post to an origin-locked route.
+ *
+ * The comparison is exact on the parsed origin, never a suffix match:
+ * `endsWith('myapp.com')` also accepts `https://evil-myapp.com`.
+ */
+export const isAllowedOrigin = (requestOrigin, hostOrigin, configuredOrigins) => {
+    if (!requestOrigin)
+        return false;
+    if (hostOrigin && requestOrigin === hostOrigin)
+        return true;
+    return configuredOrigins.some((allowed) => toOrigin(allowed) === requestOrigin);
+};
+/**
+ * Rejects a request with a 403 unless its `Origin` is this app's own or explicitly allowed.
+ *
+ * This is not what `cors()` does. CORS sets response headers and is enforced by the
+ * browser, so a non-browser client ignores them and the request still runs; this rejects
+ * before the function body. It stops another site's page from posting to an unauthed
+ * route — it is not flood control, because `Origin` is trusted from nobody but a browser.
+ * A missing `Origin` is rejected too: a real browser sets one on a cross-origin-capable POST.
+ */
+export const requireOrigin = pikkuMiddlewareFactory(({ origins = [] } = {}) => pikkuMiddleware({
+    name: 'requireOrigin',
+    description: 'Rejects requests that did not come from this app.',
+    func: async (services, { http }, next) => {
+        const request = http?.request;
+        if (!request)
+            return next();
+        const requestOrigin = toOrigin(request.header('origin')) ??
+            toOrigin(request.header('referer'));
+        const host = request.header('host');
+        const proto = request.header('x-forwarded-proto') ?? 'https';
+        const hostOrigin = host ? toOrigin(`${proto}://${host}`) : null;
+        const configured = typeof origins === 'function'
+            ? await origins(services)
+            : origins;
+        if (!isAllowedOrigin(requestOrigin, hostOrigin, configured)) {
+            throw new InvalidOriginError(`Rejected origin ${requestOrigin ?? '(none)'}`);
+        }
+        return next();
+    },
+}));

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/secret-service.d.ts

@@ -4,6 +4,11 @@ export type SecretValues<T> = {
     [K in keyof T]: SecretValue<T[K]>;
 };
 export interface SecretService {
+    /**
+     * Throws if the secret is not found, unless `defineSecret` declared it
+     * `optional` — then absence resolves `undefined`. Unwrap the result with
+     * `.reveal()`.
+     */
     getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     /** Answers for any key, including a disallowed one — it must not throw. */
     hasSecret(key: string): Promise<boolean>;

package/dist/services/typed-variables-service.d.ts

@@ -1,14 +1,34 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { VariablesService } from './variables-service.js';
 export interface VariableStatus {
     variableId: string;
     name: string;
     displayName: string;
     isConfigured: boolean;
+    /** Whether the declaration answers for itself when the host sets nothing. */
+    hasDefault: boolean;
 }
 export type VariableMeta = {
     name: string;
     displayName: string;
+    /**
+     * The shape the variable was declared with. It is the schema itself rather
+     * than a description of it, because a default is only knowable by running it:
+     * `undefined` goes in and, if the declaration carries one, the default comes
+     * back out.
+     *
+     * A thunk is accepted, and is what code generation emits. The generated file
+     * and the file declaring the schema import each other, so reading the schema
+     * while the modules are still initializing throws — deferring the read until
+     * a variable is actually asked for is what keeps the cycle harmless.
+     */
+    schema?: StandardSchemaV1 | (() => StandardSchemaV1);
 };
+/**
+ * A declared default is the answer to a variable nobody set, so it is resolved
+ * here rather than in `VariablesService`: the store knows what a host has put
+ * in it, and only this layer knows what was declared.
+ */
 export declare class TypedVariablesService<TMap = Record<string, unknown>> implements VariablesService {
     private variables;
     private variablesMeta;
@@ -21,5 +41,19 @@ export declare class TypedVariablesService<TMap = Record<string, unknown>> imple
     has(name: string): Promise<boolean> | boolean;
     delete(name: string): Promise<void> | void;
     getAllStatus(): Promise<VariableStatus[]>;
+    /**
+     * What a deployment still has to be told. A variable that defaults is not on
+     * this list — it has a value, just not one anybody has to supply.
+     */
     getMissing(): Promise<VariableStatus[]>;
+    /**
+     * The value the declaration answers with when the host set nothing, or
+     * `undefined` when it does not answer for itself.
+     */
+    private resolveDefault;
+    /**
+     * Kept synchronous when the defaults resolve synchronously, so a caller that
+     * did not await `getVariables` before does not have to start.
+     */
+    private withDefaults;
 }

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

@@ -1,3 +1,9 @@
+const isPromise = (value) => typeof value?.then === 'function';
+/**
+ * A declared default is the answer to a variable nobody set, so it is resolved
+ * here rather than in `VariablesService`: the store knows what a host has put
+ * in it, and only this layer knows what was declared.
+ */
 export class TypedVariablesService {
     variables;
     variablesMeta;
@@ -6,10 +12,18 @@ export class TypedVariablesService {
         this.variablesMeta = variablesMeta;
     }
     get(name) {
-        return this.variables.get(name);
+        const stored = this.variables.get(name);
+        if (isPromise(stored)) {
+            return stored.then((value) => value === undefined ? this.resolveDefault(name) : value);
+        }
+        return stored === undefined ? this.resolveDefault(name) : stored;
     }
     getVariables(names) {
-        return this.variables.getVariables(names);
+        const stored = this.variables.getVariables(names);
+        if (isPromise(stored)) {
+            return stored.then((values) => this.withDefaults(names, values));
+        }
+        return this.withDefaults(names, stored);
     }
     getAll() {
         return this.variables.getAll();
@@ -32,12 +46,64 @@ export class TypedVariablesService {
                 name: meta.name,
                 displayName: meta.displayName,
                 isConfigured: all[variableId] !== undefined,
+                hasDefault: (await this.resolveDefault(variableId)) !== undefined,
             });
         }
         return results;
     }
+    /**
+     * What a deployment still has to be told. A variable that defaults is not on
+     * this list — it has a value, just not one anybody has to supply.
+     */
     async getMissing() {
         const all = await this.getAllStatus();
-        return all.filter((v) => !v.isConfigured);
+        return all.filter((v) => !v.isConfigured && !v.hasDefault);
+    }
+    /**
+     * The value the declaration answers with when the host set nothing, or
+     * `undefined` when it does not answer for itself.
+     */
+    resolveDefault(name) {
+        const declared = this.variablesMeta[name]?.schema;
+        if (!declared) {
+            return undefined;
+        }
+        const schema = typeof declared === 'function' ? declared() : declared;
+        const result = schema['~standard'].validate(undefined);
+        if (isPromise(result)) {
+            return result.then(unwrapDefault);
+        }
+        return unwrapDefault(result);
+    }
+    /**
+     * Kept synchronous when the defaults resolve synchronously, so a caller that
+     * did not await `getVariables` before does not have to start.
+     */
+    withDefaults(names, values) {
+        const out = { ...values };
+        const pending = [];
+        for (const name of names) {
+            if (out[name] !== undefined)
+                continue;
+            const fallback = this.resolveDefault(name);
+            if (isPromise(fallback)) {
+                pending.push(fallback.then((value) => {
+                    if (value !== undefined)
+                        out[name] = value;
+                }));
+            }
+            else if (fallback !== undefined) {
+                out[name] = fallback;
+            }
+        }
+        if (pending.length > 0) {
+            return Promise.all(pending).then(() => out);
+        }
+        return out;
     }
 }
+/**
+ * A schema with no default rejects `undefined`, which is not a failure here —
+ * it is the answer that there is nothing to fall back to.
+ */
+const unwrapDefault = (result) => result.issues ? undefined : result.value;