@fuzdev/fuz_app 0.65.0 → 0.67.0

package/dist/auth/signup_routes.d.ts

@@ -13,6 +13,27 @@ import { type RateLimiter } from '../rate_limiter.js';
 import type { RouteFactoryDeps } from './deps.js';
 import type { AppSettings } from './app_settings_schema.js';
 import type { AuthSessionRouteOptions } from './account_routes.js';
+/**
+ * Default minimum wall-clock time (ms) for a signup denial (403 / 409) response.
+ *
+ * Parallel to login's `DEFAULT_LOGIN_FAIL_FLOOR_MS`. Without a floor, an
+ * attacker can distinguish `ERROR_NO_MATCHING_INVITE` (cheap — bails before
+ * Argon2 + tx) from `ERROR_SIGNUP_CONFLICT` (Argon2 + tx + rollback) via
+ * response time and use the gap as a username-enumeration oracle. Picked
+ * to exceed the p99 of every denial code path (Argon2id dominates at
+ * ~100ms, plus DB + overhead). 429 stays fast by design (same precedent
+ * as login) so rate-limit DoS handling stays cheap.
+ */
+export declare const DEFAULT_SIGNUP_FAIL_FLOOR_MS = 250;
+/**
+ * Default uniform jitter window (±ms) layered on the floor.
+ *
+ * Random jitter prevents a stable clamp point from leaking whenever a
+ * path occasionally exceeds the floor. `Math.random` is sufficient —
+ * we only need unpredictability of the exact delay, not cryptographic
+ * guarantees.
+ */
+export declare const DEFAULT_SIGNUP_FAIL_JITTER_MS = 25;
 /**
  * Per-factory configuration for signup route specs.
  */
@@ -21,6 +42,18 @@ export interface SignupRouteOptions extends AuthSessionRouteOptions {
     signup_account_rate_limiter: RateLimiter | null;
     /** Mutable ref to app settings — when `open_signup` is true, invite check is skipped. */
     app_settings: AppSettings;
+    /**
+     * Minimum wall-clock time (ms) for signup denial responses (403 / 409).
+     * Set to `0` or a negative number to disable (e.g., in tests). Default
+     * `DEFAULT_SIGNUP_FAIL_FLOOR_MS`. 429 responses are not floored.
+     */
+    signup_fail_floor_ms?: number;
+    /**
+     * Uniform jitter window (±ms) layered on the floor. Set to `0` to
+     * disable jitter while keeping the floor. Default
+     * `DEFAULT_SIGNUP_FAIL_JITTER_MS`.
+     */
+    signup_fail_jitter_ms?: number;
 }
 /** Input for `POST /signup`. `email` is optional and must match any referenced invite. */
 export declare const SignupInput: z.ZodObject<{
@@ -29,9 +62,22 @@ export declare const SignupInput: z.ZodObject<{
     email: z.ZodOptional<z.ZodEmail>;
 }, z.core.$strict>;
 export type SignupInput = z.infer<typeof SignupInput>;
-/** Output for `POST /signup`. Session cookie is the operative side effect. */
+/**
+ * Output for `POST /signup`.
+ *
+ * Session cookie is the operative side effect. The returned `account` and
+ * `actor` mirror `BootstrapOutput` so cross-process per-test setup can read
+ * the per-test identity straight off the signup response.
+ */
 export declare const SignupOutput: z.ZodObject<{
     ok: z.ZodLiteral<true>;
+    account: z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+        username: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    }, z.core.$strict>;
+    actor: z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodUUID, "Uuid", "out">;
+    }, z.core.$strict>;
 }, z.core.$strict>;
 export type SignupOutput = z.infer<typeof SignupOutput>;
 /**

package/dist/auth/signup_routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signup_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAStB,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAOhD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,qBAAqB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAClE,6FAA6F;IAC7F,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,yFAAyF;IACzF,YAAY,EAAE,WAAW,CAAC;CAC1B;AAID,0FAA0F;AAC1F,eAAO,MAAM,WAAW;;;;kBAItB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,8EAA8E;AAC9E,eAAO,MAAM,YAAY;;kBAEvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,gBAAgB,EACtB,SAAS,kBAAkB,KACzB,KAAK,CAAC,SAAS,CAmJjB,CAAC"}
+{"version":3,"file":"signup_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/signup_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAatB,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAA+B,KAAK,WAAW,EAAC,MAAM,oBAAoB,CAAC;AAClF,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,WAAW,CAAC;AAOhD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,qBAAqB,CAAC;AAEjE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAQhD;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAClE,6FAA6F;IAC7F,2BAA2B,EAAE,WAAW,GAAG,IAAI,CAAC;IAChD,yFAAyF;IACzF,YAAY,EAAE,WAAW,CAAC;IAC1B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID,0FAA0F;AAC1F,eAAO,MAAM,WAAW;;;;kBAItB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;;;;;;;kBAIvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,gBAAgB,EACtB,SAAS,kBAAkB,KACzB,KAAK,CAAC,SAAS,CAmLjB,CAAC"}

package/dist/auth/signup_routes.js

@@ -8,9 +8,10 @@
  * @module
  */
 import { z } from 'zod';
+import { Uuid } from '@fuzdev/fuz_util/id.js';
 import { create_session_and_set_cookie } from './session_middleware.js';
 import { query_create_account_with_actor } from './account_queries.js';
-import { query_invite_find_unclaimed_match, query_invite_claim_unscoped } from './invite_queries.js';
+import { query_invite_find_unclaimed_match_for_update, query_invite_claim_unscoped, } from './invite_queries.js';
 import { Username, Email } from '../primitive_schemas.js';
 import { Password } from './password.js';
 import { get_route_input } from '../http/route_spec.js';
@@ -18,6 +19,33 @@ import { get_client_ip } from '../http/proxy.js';
 import { rate_limit_exceeded_response } from '../rate_limiter.js';
 import { ERROR_NO_MATCHING_INVITE, ERROR_SIGNUP_CONFLICT, ERROR_INVALID_JSON_BODY, ERROR_INVALID_REQUEST_BODY, } from '../http/error_schemas.js';
 import { is_pg_unique_violation } from '../db/pg_error.js';
+/**
+ * Default minimum wall-clock time (ms) for a signup denial (403 / 409) response.
+ *
+ * Parallel to login's `DEFAULT_LOGIN_FAIL_FLOOR_MS`. Without a floor, an
+ * attacker can distinguish `ERROR_NO_MATCHING_INVITE` (cheap — bails before
+ * Argon2 + tx) from `ERROR_SIGNUP_CONFLICT` (Argon2 + tx + rollback) via
+ * response time and use the gap as a username-enumeration oracle. Picked
+ * to exceed the p99 of every denial code path (Argon2id dominates at
+ * ~100ms, plus DB + overhead). 429 stays fast by design (same precedent
+ * as login) so rate-limit DoS handling stays cheap.
+ */
+export const DEFAULT_SIGNUP_FAIL_FLOOR_MS = 250;
+/**
+ * Default uniform jitter window (±ms) layered on the floor.
+ *
+ * Random jitter prevents a stable clamp point from leaking whenever a
+ * path occasionally exceeds the floor. `Math.random` is sufficient —
+ * we only need unpredictability of the exact delay, not cryptographic
+ * guarantees.
+ */
+export const DEFAULT_SIGNUP_FAIL_JITTER_MS = 25;
+const signup_fail_delay = (floor_ms, jitter_ms) => {
+    if (floor_ms <= 0)
+        return Promise.resolve();
+    const jitter = jitter_ms > 0 ? Math.floor(Math.random() * (jitter_ms * 2 + 1)) - jitter_ms : 0;
+    return new Promise((resolve) => setTimeout(resolve, floor_ms + jitter));
+};
 // -- Input/output schemas ---------------------------------------------------
 /** Input for `POST /signup`. `email` is optional and must match any referenced invite. */
 export const SignupInput = z.strictObject({
@@ -25,9 +53,17 @@ export const SignupInput = z.strictObject({
     password: Password,
     email: Email.optional(),
 });
-/** Output for `POST /signup`. Session cookie is the operative side effect. */
+/**
+ * Output for `POST /signup`.
+ *
+ * Session cookie is the operative side effect. The returned `account` and
+ * `actor` mirror `BootstrapOutput` so cross-process per-test setup can read
+ * the per-test identity straight off the signup response.
+ */
 export const SignupOutput = z.strictObject({
     ok: z.literal(true),
+    account: z.strictObject({ id: Uuid, username: Username }),
+    actor: z.strictObject({ id: Uuid }),
 });
 /**
  * Create signup route specs for account creation.
@@ -38,7 +74,7 @@ export const SignupOutput = z.strictObject({
  */
 export const create_signup_route_specs = (deps, options) => {
     const { keyring, password } = deps;
-    const { session_options, ip_rate_limiter, signup_account_rate_limiter, app_settings } = options;
+    const { session_options, ip_rate_limiter, signup_account_rate_limiter, app_settings, signup_fail_floor_ms = DEFAULT_SIGNUP_FAIL_FLOOR_MS, signup_fail_jitter_ms = DEFAULT_SIGNUP_FAIL_JITTER_MS, } = options;
     return [
         {
             method: 'POST',
@@ -57,7 +93,7 @@ export const create_signup_route_specs = (deps, options) => {
                 409: z.looseObject({ error: z.literal(ERROR_SIGNUP_CONFLICT) }),
             },
             handler: async (c, route) => {
-                // Per-IP rate limit check (before any work)
+                // Per-IP rate limit check (before any work). 429 stays fast.
                 const ip = ip_rate_limiter ? get_client_ip(c) : null;
                 if (ip_rate_limiter && ip) {
                     const check = ip_rate_limiter.check(ip);
@@ -66,7 +102,8 @@ export const create_signup_route_specs = (deps, options) => {
                     }
                 }
                 const { username, password: pw, email } = get_route_input(c);
-                // Per-account rate limit check (after input parsing, before DB work)
+                // Per-account rate limit check (after input parsing, before DB work).
+                // 429 stays fast — same precedent as login.
                 const account_key = username.toLowerCase();
                 if (signup_account_rate_limiter) {
                     const check = signup_account_rate_limiter.check(account_key);
@@ -74,13 +111,23 @@ export const create_signup_route_specs = (deps, options) => {
                         return rate_limit_exceeded_response(c, check.retry_after);
                     }
                 }
-                // Check for matching invite (unless open signup is enabled).
-                // `transaction: false` makes `route.db` the pool, which is
-                // what the pre-tx invite lookup wants.
+                // Start the denial-time floor concurrently with failure work.
+                // Observed response time for 403 / 409 is `max(work, delay)`
+                // so the cheap `no_match` path (no Argon2, find returns
+                // nothing) and the expensive `signup_conflict` path (Argon2
+                // + tx + rollback) converge — closes the username-enumeration
+                // timing oracle. Mirrors login's `login_fail_delay`. Started
+                // after rate-limit checks so 429 stays fast.
+                const delay = signup_fail_delay(signup_fail_floor_ms, signup_fail_jitter_ms);
+                // Hash before the transaction so the connection isn't held
+                // across the ~100ms Argon2id. Paid unconditionally — bounded
+                // by the per-IP + per-account rate limiters above.
+                const password_hash = await password.hash_password(pw);
+                // `invite` is assigned inside the tx by the FOR UPDATE find;
+                // captured at the outer scope so the failure-audit catch
+                // branch can still reference `invite.id` after the tx rolls
+                // back on PG unique violation.
                 let invite;
-                if (!app_settings.open_signup) {
-                    invite = await query_invite_find_unclaimed_match({ db: route.db }, email ?? null, username);
-                }
                 const emit_failure_audit = (reason) => {
                     deps.audit.emit(route, {
                         event_type: 'signup',
@@ -95,43 +142,34 @@ export const create_signup_route_specs = (deps, options) => {
                         },
                     });
                 };
-                if (!app_settings.open_signup && !invite) {
-                    if (ip_rate_limiter && ip)
-                        ip_rate_limiter.record(ip);
-                    if (signup_account_rate_limiter)
-                        signup_account_rate_limiter.record(account_key);
-                    emit_failure_audit('no_match');
-                    return c.json({ error: ERROR_NO_MATCHING_INVITE }, 403);
-                }
-                // Create account, optionally claim invite, and create session atomically.
-                // Username/email uniqueness enforced by DB unique constraints.
-                const password_hash = await password.hash_password(pw);
                 let result;
                 try {
                     result = await route.db.transaction(async (tx) => {
                         const tx_deps = { db: tx };
-                        const { account } = await query_create_account_with_actor(tx_deps, {
+                        // Find + claim run inside the same transaction so the
+                        // row lock makes them atomic. Concurrent signups for
+                        // the same (username, email) tuple block on the lock
+                        // and observe the post-commit state on retry — the
+                        // loser's `find_for_update` returns no row (winner
+                        // flipped `claimed_at`) and falls through to
+                        // `ERROR_NO_MATCHING_INVITE`. No race window.
+                        if (!app_settings.open_signup) {
+                            invite = await query_invite_find_unclaimed_match_for_update(tx_deps, email ?? null, username);
+                            if (!invite) {
+                                throw new NoMatchingInviteError();
+                            }
+                        }
+                        const { account, actor } = await query_create_account_with_actor(tx_deps, {
                             username,
                             password_hash,
                             email,
                         });
                         if (invite) {
-                            const claimed = await query_invite_claim_unscoped(tx_deps, invite.id, account.id);
-                            if (!claimed) {
-                                // Race: invite was claimed between the find and this claim.
-                                //
-                                // SECURITY NOTE: this branch is largely shadowed by the account
-                                // unique constraints. Because `query_invite_find_unclaimed_match`
-                                // returns at most one invite for the (username, email) tuple, two
-                                // concurrent signups satisfying the same find share the same
-                                // username and/or email — and the case-insensitive partial uniques
-                                // on `account.username` / `account.email` (`ACCOUNT_USERNAME_CI_INDEX`
-                                // / `ACCOUNT_EMAIL_INDEX`) fire on the second `query_create_account_with_actor`
-                                // before the claim runs. The audit emit is kept for defense-in-depth
-                                // in case those constraints are loosened or the find query starts
-                                // returning multiple invites for a single signup tuple.
-                                throw new SignupConflictError(ERROR_NO_MATCHING_INVITE);
-                            }
+                            // Guaranteed to succeed: FOR UPDATE held the row
+                            // for the duration of the tx, so no concurrent
+                            // claim could flip `claimed_at` between the find
+                            // and this UPDATE.
+                            await query_invite_claim_unscoped(tx_deps, invite.id, account.id);
                         }
                         await create_session_and_set_cookie({
                             keyring,
@@ -140,17 +178,18 @@ export const create_signup_route_specs = (deps, options) => {
                             account_id: account.id,
                             session_options,
                         });
-                        return account;
+                        return { account, actor };
                     });
                 }
                 catch (e) {
-                    if (e instanceof SignupConflictError) {
+                    if (e instanceof NoMatchingInviteError) {
                         if (ip_rate_limiter && ip)
                             ip_rate_limiter.record(ip);
                         if (signup_account_rate_limiter)
                             signup_account_rate_limiter.record(account_key);
-                        emit_failure_audit('race_lost');
-                        return c.json({ error: e.error }, 403);
+                        emit_failure_audit('no_match');
+                        await delay;
+                        return c.json({ error: ERROR_NO_MATCHING_INVITE }, 403);
                     }
                     // Unique constraint violation: username or email already exists.
                     if (is_pg_unique_violation(e)) {
@@ -159,8 +198,17 @@ export const create_signup_route_specs = (deps, options) => {
                         if (signup_account_rate_limiter)
                             signup_account_rate_limiter.record(account_key);
                         emit_failure_audit('signup_conflict');
+                        await delay;
                         return c.json({ error: ERROR_SIGNUP_CONFLICT }, 409);
                     }
+                    // Unclassified failure (e.g. session create error, Argon2
+                    // fault on hash, DB outage mid-tx). Tx is rolled back so
+                    // no account persists, but the *attempt* should leave a
+                    // forensic trail — emit `outcome: 'failure'` with reason
+                    // `internal_error` before rethrowing. 5xx responses are
+                    // not floored: they aren't response-time-controlled
+                    // enumeration oracles.
+                    emit_failure_audit('internal_error');
                     throw e;
                 }
                 // Reset rate limiters on success
@@ -170,20 +218,23 @@ export const create_signup_route_specs = (deps, options) => {
                     signup_account_rate_limiter.reset(account_key);
                 deps.audit.emit(route, {
                     event_type: 'signup',
-                    account_id: result.id,
+                    account_id: result.account.id,
                     ip: get_client_ip(c),
                     metadata: invite ? { invite_id: invite.id, username } : { open_signup: true, username },
                 });
-                return c.json({ ok: true });
+                return c.json({
+                    ok: true,
+                    account: { id: result.account.id, username: result.account.username },
+                    actor: { id: result.actor.id },
+                });
             },
         },
     ];
 };
-/** Thrown inside the signup transaction to signal a conflict that should roll back. */
-class SignupConflictError extends Error {
-    error;
-    constructor(error) {
-        super(error);
-        this.error = error;
-    }
+/**
+ * Thrown inside the signup transaction to signal `ERROR_NO_MATCHING_INVITE`
+ * when the FOR UPDATE find returns no row (and `open_signup` is off).
+ * Caught by the handler to roll back the tx and emit the failure audit.
+ */
+class NoMatchingInviteError extends Error {
 }

package/dist/env/resolve.d.ts

@@ -10,15 +10,32 @@
  * - Easy to grep: `grep '\$\$'`
  * - Fails loud if accidentally shell-processed (`$$`=PID in shell)
  *
+ * # Syntax
+ *
+ * - `$$VAR$$` — required reference. Missing or empty fails validation
+ *   (see `validate_env_vars`).
+ * - `$$?VAR$$` — optional reference. Missing or empty resolves to the
+ *   empty string and passes validation. Use for vars that exist in the
+ *   contract but may be intentionally blank (e.g. `SMTP_PASSWORD=` on
+ *   a deployment that hasn't configured SMTP yet).
+ * - `\$$VAR$$` — escape. The leading backslash is dropped at resolution
+ *   time and the rest is emitted literally. Use this when documenting
+ *   the syntax inside a string literal (comments in env-file templates,
+ *   for example) where a regex scan would otherwise treat the mention
+ *   as a real reference. Combines with `?` as `\$$?VAR$$`.
+ *
  * @module
  */
 import type { EnvDeps } from '../runtime/deps.js';
 /**
  * Resolve environment variable references in a string.
  *
- * Uses `$$VAR$$` syntax (bookended double-dollar signs).
- * Only resolves variables that are actually set in the environment.
- * Unset variables are left as-is for clear error messages.
+ * - `$$VAR$$` resolves from the runtime env; missing values are left as-is
+ *   for the validation phase to report.
+ * - `$$?VAR$$` is the optional form — missing or empty resolves to the empty
+ *   string. Required validation skips refs marked optional.
+ * - `\$$VAR$$` / `\$$?VAR$$` are escapes — the leading backslash is dropped
+ *   and the body is emitted literally (no resolution attempted).
  *
  * @param runtime - runtime with `env_get` capability
  * @param value - string that may contain `$$VAR$$` references
@@ -28,13 +45,20 @@ export declare const resolve_env_vars: (runtime: Pick<EnvDeps, "env_get">, value
 /**
  * Check if a string contains unresolved env var references.
  *
+ * Escaped references (`\$$VAR$$`) do not count — they're literal text once
+ * resolved.
+ *
  * @param value - string to check
- * @returns `true` if string contains `$$VAR$$` patterns
+ * @returns `true` if string contains unescaped `$$VAR$$` patterns
  */
 export declare const has_env_vars: (value: string) => boolean;
 /**
  * Get list of env var names referenced in a string.
  *
+ * Escaped references are skipped; optional and required references are both
+ * included (callers that care about the distinction should use `scan_env_vars`
+ * which preserves the `optional` flag per ref).
+ *
  * @param value - string to scan
  * @returns array of variable names (without `$$` delimiters)
  */
@@ -50,7 +74,9 @@ export declare const resolve_env_vars_in_object: <T extends Record<string, unkno
 /**
  * Resolve env vars and throw if any are missing/empty.
  *
- * Use this for values that must be present.
+ * Use this for values that must be present. `$$?VAR$$` (optional) refs
+ * resolve to the empty string on miss without contributing to the error.
+ * Escaped references (`\$$VAR$$`) emit literally and never check the env.
  *
  * @param runtime - runtime with `env_get` capability
  * @param value - string with `$$VAR$$` references
@@ -67,15 +93,24 @@ export interface EnvVarRef {
     name: string;
     /** Path where the reference was found (e.g., `"target.host"`, `"resources[3].path"`). */
     path: string;
+    /**
+     * Whether the reference is optional (`$$?VAR$$`). Optional refs resolve
+     * to the empty string when unset and are skipped by `validate_env_vars` —
+     * a var that's intentionally blank doesn't count as missing.
+     */
+    optional: boolean;
 }
 /**
  * Recursively scan an object for `$$VAR$$` env var references.
  *
  * Walks all string values in the object tree and extracts env var names
- * with their path context for error reporting.
+ * with their path context for error reporting. Escaped references
+ * (`\$$VAR$$`) are skipped — they're literal text, not references.
+ * The `optional` flag on each ref distinguishes `$$VAR$$` (required) from
+ * `$$?VAR$$` (optional) for downstream validation.
  *
  * @param obj - object to scan (typically a config)
- * @returns array of env var references with paths
+ * @returns array of env var references with paths and optional flags
  */
 export declare const scan_env_vars: (obj: unknown) => Array<EnvVarRef>;
 /**
@@ -97,6 +132,8 @@ export type EnvValidationResult = {
  *
  * Returns all missing refs (including duplicates by name). Grouping
  * and deduplication is handled by `format_missing_env_vars` at display time.
+ * Refs marked `optional: true` (from `$$?VAR$$` syntax) are skipped — a
+ * deliberately-blank var is contract, not a missing dependency.
  *
  * @param runtime - runtime with `env_get` capability
  * @param refs - env var references from `scan_env_vars`

package/dist/env/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAOhD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,MAAM,KAAG,MAMnF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,OAG5C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,KAAK,CAAC,MAAM,CAS7D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3E,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,KAAK,CAAC,KACJ,CAQF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GACrC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,OAAO,MAAM,EACb,SAAS,MAAM,KACb,MAmBF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,KAAG,KAAK,CAAC,SAAS,CAI3D,CAAC;AAwBF;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAC5B;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAC,GACzB;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;CAAC,CAAC;AAE1C;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,KAAK,CAAC,SAAS,CAAC,KACpB,mBAWF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC3C,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GACnC,SAAS,KAAK,CAAC,SAAS,CAAC,EACzB,UAAU,2BAA2B,KACnC,MA+BF,CAAC"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAiBhD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,MAAM,KAAG,MAYnF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,OAQ5C,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,KAAK,CAAC,MAAM,CAS7D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3E,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,KAAK,CAAC,KACJ,CAQF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,GACrC,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,OAAO,MAAM,EACb,SAAS,MAAM,KACb,MAyBF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,KAAK,OAAO,KAAG,KAAK,CAAC,SAAS,CAI3D,CAAC;AA2BF;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAC5B;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAC,GACzB;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;CAAC,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,GAC7B,SAAS,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,EACjC,MAAM,KAAK,CAAC,SAAS,CAAC,KACpB,mBAYF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC3C,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GACnC,SAAS,KAAK,CAAC,SAAS,CAAC,EACzB,UAAU,2BAA2B,KACnC,MA+BF,CAAC"}

package/dist/env/resolve.js

@@ -10,53 +10,102 @@
  * - Easy to grep: `grep '\$\$'`
  * - Fails loud if accidentally shell-processed (`$$`=PID in shell)
  *
+ * # Syntax
+ *
+ * - `$$VAR$$` — required reference. Missing or empty fails validation
+ *   (see `validate_env_vars`).
+ * - `$$?VAR$$` — optional reference. Missing or empty resolves to the
+ *   empty string and passes validation. Use for vars that exist in the
+ *   contract but may be intentionally blank (e.g. `SMTP_PASSWORD=` on
+ *   a deployment that hasn't configured SMTP yet).
+ * - `\$$VAR$$` — escape. The leading backslash is dropped at resolution
+ *   time and the rest is emitted literally. Use this when documenting
+ *   the syntax inside a string literal (comments in env-file templates,
+ *   for example) where a regex scan would otherwise treat the mention
+ *   as a real reference. Combines with `?` as `\$$?VAR$$`.
+ *
  * @module
  */
 /**
- * Pattern for environment variable references: `$$VAR$$`.
+ * Pattern matching `$$VAR$$`, `$$?VAR$$`, and their escaped forms
+ * `\$$VAR$$` / `\$$?VAR$$`. Capture groups:
+ *
+ * - 1: the `$$...$$` body (without any leading escape char) — what to
+ *   emit when the match is escaped.
+ * - 2: `?` if the reference is optional, empty otherwise.
+ * - 3: the variable name (without `$$` delimiters).
+ *
+ * The leading `\\?` (optional backslash) is the escape signal — its
+ * presence in `match[0]` (vs. `match[1]`) drives the literal-emission
+ * branch in the resolver.
  */
-const ENV_VAR_PATTERN = /\$\$([A-Za-z_][A-Za-z0-9_]*)\$\$/g;
+const ENV_VAR_PATTERN = /\\?(\$\$(\??)([A-Za-z_][A-Za-z0-9_]*)\$\$)/g;
 /**
  * Resolve environment variable references in a string.
  *
- * Uses `$$VAR$$` syntax (bookended double-dollar signs).
- * Only resolves variables that are actually set in the environment.
- * Unset variables are left as-is for clear error messages.
+ * - `$$VAR$$` resolves from the runtime env; missing values are left as-is
+ *   for the validation phase to report.
+ * - `$$?VAR$$` is the optional form — missing or empty resolves to the empty
+ *   string. Required validation skips refs marked optional.
+ * - `\$$VAR$$` / `\$$?VAR$$` are escapes — the leading backslash is dropped
+ *   and the body is emitted literally (no resolution attempted).
  *
  * @param runtime - runtime with `env_get` capability
  * @param value - string that may contain `$$VAR$$` references
  * @returns string with env vars resolved
  */
 export const resolve_env_vars = (runtime, value) => {
-    return value.replace(ENV_VAR_PATTERN, (match, name) => {
+    return value.replace(ENV_VAR_PATTERN, (match, body, modifier, name) => {
+        if (match.startsWith('\\')) {
+            // Escaped: drop the leading backslash, emit the body literally.
+            return body;
+        }
         const resolved = runtime.env_get(name);
-        // leave unresolved for the validation phase to report
-        return resolved !== undefined ? resolved : match;
+        if (resolved !== undefined && resolved !== '')
+            return resolved;
+        // Optional: empty-on-miss. Required: leave unresolved for validation.
+        if (modifier === '?')
+            return '';
+        return match;
     });
 };
 /**
  * Check if a string contains unresolved env var references.
  *
+ * Escaped references (`\$$VAR$$`) do not count — they're literal text once
+ * resolved.
+ *
  * @param value - string to check
- * @returns `true` if string contains `$$VAR$$` patterns
+ * @returns `true` if string contains unescaped `$$VAR$$` patterns
  */
 export const has_env_vars = (value) => {
-    // use a fresh regex to avoid global regex lastIndex state issues
-    return /\$\$[A-Za-z_][A-Za-z0-9_]*\$\$/.test(value);
+    // Iterate the shared pattern (fresh regex; lastIndex is fine on construct).
+    const pattern = new RegExp(ENV_VAR_PATTERN.source, 'g');
+    let match;
+    while ((match = pattern.exec(value)) !== null) {
+        if (!match[0].startsWith('\\'))
+            return true;
+    }
+    return false;
 };
 /**
  * Get list of env var names referenced in a string.
  *
+ * Escaped references are skipped; optional and required references are both
+ * included (callers that care about the distinction should use `scan_env_vars`
+ * which preserves the `optional` flag per ref).
+ *
  * @param value - string to scan
  * @returns array of variable names (without `$$` delimiters)
  */
 export const get_env_var_names = (value) => {
     const names = [];
-    let match;
-    // reset regex lastIndex since it's global
     const pattern = new RegExp(ENV_VAR_PATTERN.source, 'g');
+    let match;
     while ((match = pattern.exec(value)) !== null) {
-        names.push(match[1]);
+        if (match[0].startsWith('\\'))
+            continue;
+        names.push(match[3]);
     }
     return names;
 };
@@ -79,7 +128,9 @@ export const resolve_env_vars_in_object = (runtime, obj) => {
 /**
  * Resolve env vars and throw if any are missing/empty.
  *
- * Use this for values that must be present.
+ * Use this for values that must be present. `$$?VAR$$` (optional) refs
+ * resolve to the empty string on miss without contributing to the error.
+ * Escaped references (`\$$VAR$$`) emit literally and never check the env.
  *
  * @param runtime - runtime with `env_get` capability
  * @param value - string with `$$VAR$$` references
@@ -89,13 +140,18 @@ export const resolve_env_vars_in_object = (runtime, obj) => {
  */
 export const resolve_env_vars_required = (runtime, value, context) => {
     const missing = [];
-    const result = value.replace(ENV_VAR_PATTERN, (match, name) => {
-        const resolved = runtime.env_get(name);
-        if (resolved === undefined || resolved === '') {
-            missing.push(name);
-            return match; // keep original for error message
+    const result = value.replace(ENV_VAR_PATTERN, (match, body, modifier, name) => {
+        if (match.startsWith('\\')) {
+            // Escaped — emit body, no env lookup.
+            return body;
         }
-        return resolved;
+        const resolved = runtime.env_get(name);
+        if (resolved !== undefined && resolved !== '')
+            return resolved;
+        if (modifier === '?')
+            return '';
+        missing.push(name);
+        return match; // keep original for error message
     });
     if (missing.length > 0) {
         throw new Error(`Missing required environment variable(s) for ${context}: ${missing.join(', ')}`);
@@ -106,10 +162,13 @@ export const resolve_env_vars_required = (runtime, value, context) => {
  * Recursively scan an object for `$$VAR$$` env var references.
  *
  * Walks all string values in the object tree and extracts env var names
- * with their path context for error reporting.
+ * with their path context for error reporting. Escaped references
+ * (`\$$VAR$$`) are skipped — they're literal text, not references.
+ * The `optional` flag on each ref distinguishes `$$VAR$$` (required) from
+ * `$$?VAR$$` (optional) for downstream validation.
  *
  * @param obj - object to scan (typically a config)
- * @returns array of env var references with paths
+ * @returns array of env var references with paths and optional flags
  */
 export const scan_env_vars = (obj) => {
     const refs = [];
@@ -117,13 +176,17 @@ export const scan_env_vars = (obj) => {
     return refs;
 };
 /**
- * Recursive helper for `scan_env_vars`.
+ * Recursive helper for `scan_env_vars`. Uses the full pattern (not
+ * `get_env_var_names`) to preserve the `optional` modifier on each ref.
  */
 const scan_recursive = (value, path, refs) => {
     if (typeof value === 'string') {
-        const names = get_env_var_names(value);
-        for (const name of names) {
-            refs.push({ name, path });
+        const pattern = new RegExp(ENV_VAR_PATTERN.source, 'g');
+        let match;
+        while ((match = pattern.exec(value)) !== null) {
+            if (match[0].startsWith('\\'))
+                continue; // escaped — literal text
+            refs.push({ name: match[3], path, optional: match[2] === '?' });
         }
     }
     else if (Array.isArray(value)) {
@@ -144,6 +207,8 @@ const scan_recursive = (value, path, refs) => {
  *
  * Returns all missing refs (including duplicates by name). Grouping
  * and deduplication is handled by `format_missing_env_vars` at display time.
+ * Refs marked `optional: true` (from `$$?VAR$$` syntax) are skipped — a
+ * deliberately-blank var is contract, not a missing dependency.
  *
  * @param runtime - runtime with `env_get` capability
  * @param refs - env var references from `scan_env_vars`
@@ -152,6 +217,8 @@ const scan_recursive = (value, path, refs) => {
 export const validate_env_vars = (runtime, refs) => {
     let missing = null;
     for (const ref of refs) {
+        if (ref.optional)
+            continue;
         const value = runtime.env_get(ref.name);
         if (value === undefined || value === '') {
             (missing ??= []).push(ref);