@portaidentity/server 1.7.2 → 1.8.0

package/dist/lib/system-config-catalog.js

@@ -0,0 +1,90 @@
+/** Closed operational policy. Database rows own values, never these definitions or defaults. */
+/** Locales for which Porta ships every authentication namespace. */
+export const SUPPORTED_LOCALES = Object.freeze(['en']);
+/** Build a frozen integer definition while preserving its literal key for typed callers. */
+function integerDefinition(key, group, label, description, unit, defaultValue, minimum, maximum, applicationMode = 'runtime') {
+    return Object.freeze({
+        key,
+        group,
+        label,
+        description,
+        valueType: 'integer',
+        unit,
+        defaultValue,
+        minimum,
+        maximum,
+        applicationMode,
+    });
+}
+/**
+ * Immutable public policy in administrative display order. Bootstrap settings and secrets are
+ * deliberately absent; adding a field requires an explicit application change and migration.
+ *
+ * @example
+ * const defaults = SYSTEM_CONFIG_CATALOG.map(({ key, defaultValue }) => [key, defaultValue]);
+ */
+export const SYSTEM_CONFIG_CATALOG = Object.freeze([
+    integerDefinition('access_token_ttl', 'lifetimes', 'Access token lifetime', 'How long newly issued access tokens remain valid.', 'seconds', 3600, 60, 86400, 'restart-required'),
+    integerDefinition('id_token_ttl', 'lifetimes', 'ID token lifetime', 'How long newly issued ID tokens remain valid.', 'seconds', 3600, 60, 86400, 'restart-required'),
+    integerDefinition('refresh_token_ttl', 'lifetimes', 'Refresh token lifetime', 'How long newly issued refresh tokens remain valid.', 'seconds', 2592000, 300, 31536000, 'restart-required'),
+    integerDefinition('authorization_code_ttl', 'lifetimes', 'Authorization code lifetime', 'How long a newly issued authorization code remains valid.', 'seconds', 600, 30, 3600, 'restart-required'),
+    integerDefinition('session_ttl', 'lifetimes', 'Session lifetime', 'How long newly created OIDC sessions remain valid.', 'seconds', 86400, 300, 2592000, 'restart-required'),
+    integerDefinition('magic_link_ttl', 'lifetimes', 'Magic-link lifetime', 'How long a newly created magic-link token remains valid.', 'seconds', 900, 60, 3600),
+    integerDefinition('password_reset_ttl', 'lifetimes', 'Password-reset lifetime', 'How long a newly created password-reset token remains valid.', 'seconds', 3600, 300, 86400),
+    integerDefinition('invitation_ttl', 'lifetimes', 'Invitation lifetime', 'How long a newly created user invitation remains valid.', 'seconds', 604800, 300, 2592000),
+    integerDefinition('rate_limit_login_max', 'rate-limits', 'Login attempt limit', 'Maximum login attempts allowed in one login window.', 'attempts', 10, 1, 100),
+    integerDefinition('rate_limit_login_window', 'rate-limits', 'Login window', 'Window used to count login attempts.', 'seconds', 900, 60, 86400),
+    integerDefinition('rate_limit_magic_link_max', 'rate-limits', 'Magic-link request limit', 'Maximum magic-link requests allowed in one window.', 'attempts', 5, 1, 100),
+    integerDefinition('rate_limit_magic_link_window', 'rate-limits', 'Magic-link request window', 'Window used to count magic-link requests.', 'seconds', 900, 60, 86400),
+    integerDefinition('rate_limit_password_reset_max', 'rate-limits', 'Password-reset request limit', 'Maximum password-reset requests allowed in one window.', 'attempts', 5, 1, 100),
+    integerDefinition('rate_limit_password_reset_window', 'rate-limits', 'Password-reset request window', 'Window used to count password-reset requests.', 'seconds', 900, 60, 86400),
+    integerDefinition('max_failed_logins', 'lockout', 'Failed login limit', 'Failed login count that activates automatic lockout.', 'attempts', 5, 1, 100),
+    integerDefinition('lockout_duration_seconds', 'lockout', 'Lockout duration', 'Duration applied when automatic lockout eligibility is checked.', 'seconds', 900, 60, 604800),
+    integerDefinition('audit_retention_days', 'general', 'Audit retention', 'Default number of days retained by audit cleanup.', 'days', 90, 1, 3650),
+    Object.freeze({
+        key: 'default_locale',
+        group: 'general',
+        label: 'Default locale',
+        description: 'Final locale fallback used by the authentication UI.',
+        valueType: 'string',
+        unit: 'locale',
+        defaultValue: 'en',
+        allowedValues: SUPPORTED_LOCALES,
+        applicationMode: 'runtime',
+    }),
+]);
+/**
+ * Resolve an untrusted name without querying whether an internal database row exists.
+ * @param key - Exact, case-sensitive name; no trimming or normalization is performed.
+ * @returns Public definition, or undefined for every non-catalog name.
+ * @example
+ * findSystemConfigDefinition('magic_link_ttl')?.defaultValue; // 900
+ */
+export function findSystemConfigDefinition(key) {
+    return SYSTEM_CONFIG_CATALOG.find((definition) => definition.key === key);
+}
+/**
+ * Validate submitted or stored policy without coercion. Numeric text and unsupported locales fail.
+ * @param definition - Application-owned public metadata.
+ * @param value - Untrusted native value from JSON or PostgreSQL.
+ * @returns The same valid scalar, or undefined when its type or bounds are wrong.
+ * @example
+ * const definition = findSystemConfigDefinition('magic_link_ttl');
+ * if (definition) validateSystemConfigValue(definition, 1200); // 1200
+ */
+export function validateSystemConfigValue(definition, value) {
+    if (definition.valueType === 'integer') {
+        if (typeof value !== 'number' ||
+            !Number.isInteger(value) ||
+            definition.minimum === undefined ||
+            definition.maximum === undefined ||
+            value < definition.minimum ||
+            value > definition.maximum)
+            return undefined;
+        return value;
+    }
+    if (typeof value !== 'string')
+        return undefined;
+    return definition.allowedValues?.find((locale) => locale === value);
+}
+//# sourceMappingURL=system-config-catalog.js.map

package/dist/lib/system-config-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-config-catalog.js","sourceRoot":"","sources":["../../src/lib/system-config-catalog.ts"],"names":[],"mappings":"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"}

package/dist/lib/system-config.d.ts

@@ -1,18 +1,17 @@
 /**
  * System configuration service — reads runtime settings from the system_config table.
  *
- * Values are cached in-memory with a configurable TTL to minimize database queries.
+ * Found values are cached in-memory for 60 seconds to minimize database queries.
  * The cache is shared across all requests within the process.
  *
- * The system_config table stores values as JSONB. Duration-type values are stored
- * as JSONB strings (e.g., '"3600"'), while booleans and numbers are stored as
- * native JSONB types. The typed getters handle parsing and coercion for each type.
+ * Public values use native JSONB scalars and the immutable catalog's validation and defaults.
+ * No coercion is performed. Missing, invalid or unavailable policy uses a bounded safe warning.
  *
  * @example
- *   const ttl = await getSystemConfigNumber('access_token_ttl', 3600);
- *   const secure = await getSystemConfigBoolean('cookie_secure', true);
+ *   const ttl = await getSystemConfigNumber('access_token_ttl');
  *   const allTtls = await loadOidcTtlConfig();
  */
+import type { NumericSystemConfigKey, SupportedLocale } from './system-config-catalog.js';
 /** OIDC TTL configuration loaded from system_config table */
 export interface OidcTtlConfig {
     /** Access token lifetime in seconds (default: 3600 = 1 hour) */
@@ -31,40 +30,37 @@ export interface OidcTtlConfig {
     grant: number;
 }
 /**
- * Get a string config value from the system_config table.
- *
- * @param key - Config key (e.g., 'magic_link_length')
- * @param fallback - Default value returned if key not found or value is not a string
- * @returns The config value as a string, or the fallback
+ * Read a native, bounded integer or its exact catalog default, without caller-owned fallbacks.
+ * @param key - Public integer policy key.
+ * @returns Valid stored integer or the same catalog's safe default.
+ * @throws Error when JavaScript callers supply a non-numeric or non-catalog key.
+ * @example
+ * await getSystemConfigNumber('magic_link_ttl'); // seconds
  */
-export declare function getSystemConfigString(key: string, fallback: string): Promise<string>;
+export declare function getSystemConfigNumber(key: NumericSystemConfigKey): Promise<number>;
 /**
- * Get a numeric config value from the system_config table.
- *
- * Handles two storage patterns:
- * - Duration-type values stored as JSONB strings (e.g., '"3600"') → parsed to number
- * - Number-type values stored as native JSONB numbers (e.g., 10) → returned directly
- *
- * @param key - Config key (e.g., 'access_token_ttl')
- * @param fallback - Default value returned if key not found or not a valid number
- * @returns The config value as a number, or the fallback
+ * Read the final authentication locale fallback without coercing arbitrary database content.
+ * @param key - The closed public locale key.
+ * @returns Completely supported stored locale or its catalog default.
+ * @throws Error when JavaScript callers supply a non-locale or non-catalog key.
+ * @example
+ * await getSystemConfigString('default_locale'); // 'en'
  */
-export declare function getSystemConfigNumber(key: string, fallback: number): Promise<number>;
+export declare function getSystemConfigString(key: 'default_locale'): Promise<SupportedLocale>;
 /**
- * Get a boolean config value from the system_config table.
- *
- * Handles native JSONB booleans (true/false) and string representations
- * ('true'/'false') for maximum flexibility.
- *
- * @param key - Config key (e.g., 'cookie_secure')
- * @param fallback - Default value returned if key not found or not a valid boolean
- * @returns The config value as a boolean, or the fallback
+ * Read trusted internal string rows independently of public operational policy. Internal rows
+ * never enter administrative projections, and raw exceptions or stored content are not logged.
+ * @param key - Internal name supplied by Porta code, not by an administrative request.
+ * @param fallback - Safe result when storage is absent, unavailable or not a native string.
+ * @returns Native internal string, or the supplied fallback.
+ * @example
+ * await getInternalSystemConfigString('super_admin_user_id', '');
  */
-export declare function getSystemConfigBoolean(key: string, fallback: boolean): Promise<boolean>;
+export declare function getInternalSystemConfigString(key: string, fallback: string): Promise<string>;
 /**
  * Load all TTL config values needed by the OIDC provider.
  *
- * Reads each TTL key from system_config with hardcoded fallback defaults.
+ * Reads each native TTL through the same catalog used by administrative policy.
  * Called once at provider initialization to build the TTL configuration.
  * The interaction TTL is hardcoded (not stored in system_config).
  *
@@ -73,7 +69,8 @@ export declare function getSystemConfigBoolean(key: string, fallback: boolean):
 export declare function loadOidcTtlConfig(): Promise<OidcTtlConfig>;
 /**
  * Clear the in-memory config cache.
- * Useful for testing to ensure fresh reads from the database.
+ * Successful administrative saves call this after commit. Replacing the map also isolates
+ * reads already awaiting PostgreSQL, so their later completion cannot restore stale policy.
  */
 export declare function clearSystemConfigCache(): void;
 //# sourceMappingURL=system-config.d.ts.map

package/dist/lib/system-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-config.d.ts","sourceRoot":"","sources":["../../src/lib/system-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAWH,6DAA6D;AAC7D,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,WAAW,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;CACf;AA8CD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM1F;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB1F;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAe7F;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,aAAa,CAAC,CAoBhE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}
+{"version":3,"file":"system-config.d.ts","sourceRoot":"","sources":["../../src/lib/system-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EACV,sBAAsB,EACtB,eAAe,EAGhB,MAAM,4BAA4B,CAAC;AAUpC,6DAA6D;AAC7D,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,WAAW,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;CACf;AA+DD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAIxF;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAI3F;AAED;;;;;;;;GAQG;AACH,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,aAAa,CAAC,CAoBhE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/lib/system-config.js

@@ -1,129 +1,113 @@
 /**
  * System configuration service — reads runtime settings from the system_config table.
  *
- * Values are cached in-memory with a configurable TTL to minimize database queries.
+ * Found values are cached in-memory for 60 seconds to minimize database queries.
  * The cache is shared across all requests within the process.
  *
- * The system_config table stores values as JSONB. Duration-type values are stored
- * as JSONB strings (e.g., '"3600"'), while booleans and numbers are stored as
- * native JSONB types. The typed getters handle parsing and coercion for each type.
+ * Public values use native JSONB scalars and the immutable catalog's validation and defaults.
+ * No coercion is performed. Missing, invalid or unavailable policy uses a bounded safe warning.
  *
  * @example
- *   const ttl = await getSystemConfigNumber('access_token_ttl', 3600);
- *   const secure = await getSystemConfigBoolean('cookie_secure', true);
+ *   const ttl = await getSystemConfigNumber('access_token_ttl');
  *   const allTtls = await loadOidcTtlConfig();
  */
 import { getPool } from './database.js';
 import { logger } from './logger.js';
-// In-memory cache with TTL (default: 60 seconds)
-const cache = new Map();
+import { findSystemConfigDefinition, validateSystemConfigValue } from './system-config-catalog.js';
+/** Active local cache; old queries retain their original map after explicit invalidation. */
+let cache = new Map();
+/** Maximum time another healthy process may retain a previously read policy value. */
 const CACHE_TTL_MS = 60_000;
 /**
  * Fetch a raw config value from the database by key.
- * Returns undefined if the key does not exist.
- * Results are cached for CACHE_TTL_MS milliseconds.
+ * Only found rows are cached. Each query captures its cache map before awaiting PostgreSQL,
+ * so a completion from before invalidation cannot refill the replacement cache with stale policy.
  *
  * @param key - Config key to look up (e.g., 'access_token_ttl')
- * @returns The JSONB value from the database, or undefined if not found
+ * @returns Found JSONB content, missing, or unavailable; raw errors never escape this boundary.
  */
 async function getRawConfigValue(key) {
     const now = Date.now();
+    const startingCache = cache;
     // Check cache first
-    const cached = cache.get(key);
+    const cached = startingCache.get(key);
     if (cached && cached.expiresAt > now) {
-        return cached.value;
+        return { status: 'found', value: cached.value };
     }
     try {
         const pool = getPool();
         const result = await pool.query('SELECT value FROM system_config WHERE key = $1', [key]);
-        if (result.rows.length === 0) {
-            // Cache the miss to avoid repeated DB queries for unknown keys
-            cache.set(key, { value: undefined, expiresAt: now + CACHE_TTL_MS });
-            return undefined;
-        }
-        const value = result.rows[0].value;
-        cache.set(key, { value, expiresAt: now + CACHE_TTL_MS });
-        return value;
+        const row = result.rows[0];
+        if (!row)
+            return { status: 'missing' };
+        startingCache.set(key, { value: row.value, expiresAt: now + CACHE_TTL_MS });
+        return { status: 'found', value: row.value };
     }
-    catch (error) {
-        // Log warning but don't fail — callers always provide fallback defaults
-        logger.warn({ key, error }, 'Failed to read system_config value, using fallback');
-        return undefined;
+    catch {
+        return { status: 'unavailable' };
     }
 }
 /**
- * Get a string config value from the system_config table.
- *
- * @param key - Config key (e.g., 'magic_link_length')
- * @param fallback - Default value returned if key not found or value is not a string
- * @returns The config value as a string, or the fallback
+ * Read public policy through application-owned validation and defaults. Warning fields contain
+ * only a catalog key and closed reason; neither stored content nor infrastructure exceptions leak.
  */
-export async function getSystemConfigString(key, fallback) {
-    const raw = await getRawConfigValue(key);
-    if (raw === undefined || raw === null)
-        return fallback;
-    // JSONB values may be strings, numbers, or booleans — coerce to string
-    return String(raw);
+async function readCatalogValue(key) {
+    const definition = findSystemConfigDefinition(key);
+    if (!definition)
+        throw new Error('Unsupported system configuration key');
+    const result = await getRawConfigValue(key);
+    const value = result.status === 'found' ? validateSystemConfigValue(definition, result.value) : undefined;
+    if (value !== undefined)
+        return value;
+    const reason = result.status === 'found' ? 'invalid' : result.status;
+    logger.warn({ event: 'system-config-fallback', key, reason }, 'Using default system configuration value');
+    return definition.defaultValue;
 }
 /**
- * Get a numeric config value from the system_config table.
- *
- * Handles two storage patterns:
- * - Duration-type values stored as JSONB strings (e.g., '"3600"') → parsed to number
- * - Number-type values stored as native JSONB numbers (e.g., 10) → returned directly
- *
- * @param key - Config key (e.g., 'access_token_ttl')
- * @param fallback - Default value returned if key not found or not a valid number
- * @returns The config value as a number, or the fallback
+ * Read a native, bounded integer or its exact catalog default, without caller-owned fallbacks.
+ * @param key - Public integer policy key.
+ * @returns Valid stored integer or the same catalog's safe default.
+ * @throws Error when JavaScript callers supply a non-numeric or non-catalog key.
+ * @example
+ * await getSystemConfigNumber('magic_link_ttl'); // seconds
  */
-export async function getSystemConfigNumber(key, fallback) {
-    const raw = await getRawConfigValue(key);
-    if (raw === undefined || raw === null)
-        return fallback;
-    // If already a number (native JSONB number), return directly
-    if (typeof raw === 'number' && !Number.isNaN(raw))
-        return raw;
-    // If it's a string (duration values stored as JSONB strings like '"3600"'),
-    // parse as number
-    if (typeof raw === 'string') {
-        const parsed = Number(raw);
-        if (!Number.isNaN(parsed))
-            return parsed;
-    }
-    logger.warn({ key, raw }, 'system_config value is not a valid number, using fallback');
-    return fallback;
+export async function getSystemConfigNumber(key) {
+    const value = await readCatalogValue(key);
+    if (typeof value !== 'number')
+        throw new Error('Expected numeric system configuration key');
+    return value;
 }
 /**
- * Get a boolean config value from the system_config table.
- *
- * Handles native JSONB booleans (true/false) and string representations
- * ('true'/'false') for maximum flexibility.
- *
- * @param key - Config key (e.g., 'cookie_secure')
- * @param fallback - Default value returned if key not found or not a valid boolean
- * @returns The config value as a boolean, or the fallback
+ * Read the final authentication locale fallback without coercing arbitrary database content.
+ * @param key - The closed public locale key.
+ * @returns Completely supported stored locale or its catalog default.
+ * @throws Error when JavaScript callers supply a non-locale or non-catalog key.
+ * @example
+ * await getSystemConfigString('default_locale'); // 'en'
  */
-export async function getSystemConfigBoolean(key, fallback) {
-    const raw = await getRawConfigValue(key);
-    if (raw === undefined || raw === null)
-        return fallback;
-    // Native JSONB boolean
-    if (typeof raw === 'boolean')
-        return raw;
-    // String representation (from some JSONB encodings)
-    if (typeof raw === 'string') {
-        if (raw === 'true')
-            return true;
-        if (raw === 'false')
-            return false;
-    }
-    logger.warn({ key, raw }, 'system_config value is not a valid boolean, using fallback');
-    return fallback;
+export async function getSystemConfigString(key) {
+    const value = await readCatalogValue(key);
+    if (typeof value !== 'string')
+        throw new Error('Expected locale system configuration key');
+    return value;
+}
+/**
+ * Read trusted internal string rows independently of public operational policy. Internal rows
+ * never enter administrative projections, and raw exceptions or stored content are not logged.
+ * @param key - Internal name supplied by Porta code, not by an administrative request.
+ * @param fallback - Safe result when storage is absent, unavailable or not a native string.
+ * @returns Native internal string, or the supplied fallback.
+ * @example
+ * await getInternalSystemConfigString('super_admin_user_id', '');
+ */
+export async function getInternalSystemConfigString(key, fallback) {
+    const result = await getRawConfigValue(key);
+    return result.status === 'found' && typeof result.value === 'string' ? result.value : fallback;
 }
 /**
  * Load all TTL config values needed by the OIDC provider.
  *
- * Reads each TTL key from system_config with hardcoded fallback defaults.
+ * Reads each native TTL through the same catalog used by administrative policy.
  * Called once at provider initialization to build the TTL configuration.
  * The interaction TTL is hardcoded (not stored in system_config).
  *
@@ -131,11 +115,11 @@ export async function getSystemConfigBoolean(key, fallback) {
  */
 export async function loadOidcTtlConfig() {
     const [accessToken, idToken, refreshToken, authorizationCode, session] = await Promise.all([
-        getSystemConfigNumber('access_token_ttl', 3600),
-        getSystemConfigNumber('id_token_ttl', 3600),
-        getSystemConfigNumber('refresh_token_ttl', 2592000),
-        getSystemConfigNumber('authorization_code_ttl', 600),
-        getSystemConfigNumber('session_ttl', 86400),
+        getSystemConfigNumber('access_token_ttl'),
+        getSystemConfigNumber('id_token_ttl'),
+        getSystemConfigNumber('refresh_token_ttl'),
+        getSystemConfigNumber('authorization_code_ttl'),
+        getSystemConfigNumber('session_ttl'),
     ]);
     return {
         accessToken,
@@ -151,9 +135,10 @@ export async function loadOidcTtlConfig() {
 }
 /**
  * Clear the in-memory config cache.
- * Useful for testing to ensure fresh reads from the database.
+ * Successful administrative saves call this after commit. Replacing the map also isolates
+ * reads already awaiting PostgreSQL, so their later completion cannot restore stale policy.
  */
 export function clearSystemConfigCache() {
-    cache.clear();
+    cache = new Map();
 }
 //# sourceMappingURL=system-config.js.map

package/dist/lib/system-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-config.js","sourceRoot":"","sources":["../../src/lib/system-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"system-config.js","sourceRoot":"","sources":["../../src/lib/system-config.ts"],"names":[],"mappings":"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"}

package/dist/lib/with-timeout.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Bounded dependency probing.
+ *
+ * Health and readiness probes must never wait indefinitely for a dependency
+ * that has stopped responding. An unbounded probe lets a degraded dependency
+ * hang an orchestrator check, so every check is raced against a short timeout
+ * and the timer is cleared as soon as the probe settles.
+ *
+ * @module lib/with-timeout
+ */
+/** Default budget (milliseconds) for a single dependency probe. */
+export declare const DEPENDENCY_PROBE_TIMEOUT_MS = 2000;
+/**
+ * Resolve with `promise`, or reject with a labeled timeout error when the
+ * promise does not settle within `timeoutMs`.
+ *
+ * The timeout only bounds how long a probe may hold a health response; it does
+ * not cancel the underlying operation, which the owning client bounds itself.
+ *
+ * @param promise - Probe promise to bound.
+ * @param label - Short dependency name used in the timeout error message.
+ * @param timeoutMs - Maximum wait; defaults to {@link DEPENDENCY_PROBE_TIMEOUT_MS}.
+ * @returns The probe result when it settles in time.
+ * @throws {Error} When the probe exceeds `timeoutMs`.
+ *
+ * @example
+ * ```ts
+ * await withTimeout(getPool().query('SELECT 1'), 'db');
+ * ```
+ */
+export declare function withTimeout<T>(promise: Promise<T>, label: string, timeoutMs?: number): Promise<T>;
+//# sourceMappingURL=with-timeout.d.ts.map

package/dist/lib/with-timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-timeout.d.ts","sourceRoot":"","sources":["../../src/lib/with-timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,mEAAmE;AACnE,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,MAAoC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAmBZ"}

package/dist/lib/with-timeout.js

@@ -0,0 +1,45 @@
+/**
+ * Bounded dependency probing.
+ *
+ * Health and readiness probes must never wait indefinitely for a dependency
+ * that has stopped responding. An unbounded probe lets a degraded dependency
+ * hang an orchestrator check, so every check is raced against a short timeout
+ * and the timer is cleared as soon as the probe settles.
+ *
+ * @module lib/with-timeout
+ */
+/** Default budget (milliseconds) for a single dependency probe. */
+export const DEPENDENCY_PROBE_TIMEOUT_MS = 2000;
+/**
+ * Resolve with `promise`, or reject with a labeled timeout error when the
+ * promise does not settle within `timeoutMs`.
+ *
+ * The timeout only bounds how long a probe may hold a health response; it does
+ * not cancel the underlying operation, which the owning client bounds itself.
+ *
+ * @param promise - Probe promise to bound.
+ * @param label - Short dependency name used in the timeout error message.
+ * @param timeoutMs - Maximum wait; defaults to {@link DEPENDENCY_PROBE_TIMEOUT_MS}.
+ * @returns The probe result when it settles in time.
+ * @throws {Error} When the probe exceeds `timeoutMs`.
+ *
+ * @example
+ * ```ts
+ * await withTimeout(getPool().query('SELECT 1'), 'db');
+ * ```
+ */
+export function withTimeout(promise, label, timeoutMs = DEPENDENCY_PROBE_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${label} timeout after ${timeoutMs}ms`)), timeoutMs);
+        // Never keep the process alive solely for a pending probe timeout.
+        timer.unref?.();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+//# sourceMappingURL=with-timeout.js.map

package/dist/lib/with-timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-timeout.js","sourceRoot":"","sources":["../../src/lib/with-timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,mEAAmE;AACnE,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CACzB,OAAmB,EACnB,KAAa,EACb,SAAS,GAAW,2BAA2B;IAE/C,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,MAAM,KAAK,GAAG,UAAU,CACtB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,KAAK,kBAAkB,SAAS,IAAI,CAAC,CAAC,EAChE,SAAS,CACV,CAAC;QACF,mEAAmE;QACnE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE;YACR,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/middleware/admin-auth.d.ts

@@ -3,9 +3,9 @@
  *
  * Validates Bearer access tokens against Porta's own OIDC provider
  * using opaque token lookup (provider.AccessToken.find()). Verifies
- * the user belongs to the super-admin organization and has the
- * porta-admin role. Sets ctx.state.adminUser for downstream handlers
- * and audit logging.
+ * the user belongs to the super-admin organization and has a recognized
+ * built-in role owned by the canonical Porta Admin application. Sets
+ * ctx.state.adminUser for downstream handlers and audit logging.
  *
  * This middleware replaces the old requireSuperAdmin() that checked
  * ctx.state.organization.isSuperAdmin (which required tenant-resolver
@@ -17,7 +17,7 @@
  *   3. Resolve super-admin organization
  *   4. Look up user — must be active
  *   5. Verify user belongs to the super-admin organization
- *   6. Verify user has the porta-admin role
+ *   6. Verify the user has a recognized role from the canonical Admin application
  *   7. Set ctx.state.adminUser and proceed
  *
  * Response codes:
@@ -89,7 +89,8 @@ declare module 'koa' {
  *
  * Validates the Bearer access token in the Authorization header by looking
  * it up via the OIDC provider's opaque token store, then verifies the user
- * is an active member of the super-admin organization with the porta-admin role.
+ * is an active member of the super-admin organization with a recognized role
+ * owned by the canonical Porta Admin application.
  *
  * On success, sets ctx.state.adminUser with the authenticated identity.
  * On failure, responds with 401 (unauthenticated) or 403 (unauthorized).

package/dist/middleware/admin-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"admin-auth.d.ts","sourceRoot":"","sources":["../../src/middleware/admin-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAY9D,4EAA4E;AAC5E,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE;QACpB,4EAA4E;QAC5E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;YAAE,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS,CAAC,CAAC;KAClE,CAAC;CACH;AAID;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI,CAE7E;AAED,gFAAgF;AAChF,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAChD,GAAG,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAC9B,kBAAkB,EAAE,MAAM,EAC1B,mBAAmB,EAAE,MAAM,GAC1B,OAAO,CAaT;AAMD;;;GAGG;AACH,OAAO,QAAQ,KAAK,CAAC;IACnB,UAAU,YAAY;QACpB,oFAAoF;QACpF,YAAY,CAAC,EAAE,YAAY,CAAC;QAC5B,+FAA+F;QAC/F,SAAS,CAAC,EAAE,SAAS,CAAC;KACvB;CACF;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CA+J7C"}
+{"version":3,"file":"admin-auth.d.ts","sourceRoot":"","sources":["../../src/middleware/admin-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAgB9D,4EAA4E;AAC5E,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE;QACpB,4EAA4E;QAC5E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;YAAE,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS,CAAC,CAAC;KAClE,CAAC;CACH;AAID;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI,CAE7E;AAED,gFAAgF;AAChF,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yDAAyD;IACzD,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAChD,GAAG,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAC9B,kBAAkB,EAAE,MAAM,EAC1B,mBAAmB,EAAE,MAAM,GAC1B,OAAO,CAaT;AAMD;;;GAGG;AACH,OAAO,QAAQ,KAAK,CAAC;IACnB,UAAU,YAAY;QACpB,oFAAoF;QACpF,YAAY,CAAC,EAAE,YAAY,CAAC;QAC5B,+FAA+F;QAC/F,SAAS,CAAC,EAAE,SAAS,CAAC;KACvB;CACF;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CA+K7C"}