@portaidentity/server 1.7.3 → 1.8.0

package/dist/lib/signing-keys.js

@@ -17,15 +17,18 @@
  */
 import { createPrivateKey, generateKeyPairSync, createHash } from 'node:crypto';
 import { config } from '../config/index.js';
-import { getPool } from './database.js';
+import { getPool, runDatabaseTransaction } from './database.js';
 import { logger } from './logger.js';
-import { encryptPrivateKey, decryptPrivateKey } from './signing-key-crypto.js';
+import { encryptPrivateKey, decryptPrivateKey, SigningKeyCryptoError, } from './signing-key-crypto.js';
 // ---------------------------------------------------------------------------
 // Cached JWKS for JWT verification (admin auth middleware, etc.)
 // ---------------------------------------------------------------------------
 /** In-memory cache for the active JWK set — avoids a DB round-trip per request */
 let cachedJwks = null;
+/** Millisecond timestamp of the currently installed cache entry. */
 let jwksCacheTimestamp = 0;
+/** Monotonic invalidation marker used to reject stale in-flight cache installations. */
+let jwksCacheGeneration = 0;
 /** Cache TTL for the active JWK set — 60 seconds matches system-config cache */
 const JWKS_CACHE_TTL_MS = 60_000;
 /**
@@ -42,15 +45,22 @@ export async function getActiveJwks() {
     if (cachedJwks && now - jwksCacheTimestamp < JWKS_CACHE_TTL_MS) {
         return cachedJwks;
     }
+    const loadGeneration = jwksCacheGeneration;
     const records = await loadSigningKeysFromDb();
-    cachedJwks = signingKeysToJwks(records);
-    jwksCacheTimestamp = now;
-    return cachedJwks;
+    const loadedJwks = signingKeysToJwks(records);
+    // A mutation may invalidate the cache while this database read is pending. The caller may use
+    // its completed snapshot, but installing it would make later callers observe stale key state.
+    if (loadGeneration === jwksCacheGeneration) {
+        cachedJwks = loadedJwks;
+        jwksCacheTimestamp = now;
+    }
+    return loadedJwks;
 }
 /**
  * Clear the cached JWK set — useful for testing and after key rotation.
  */
 export function clearJwksCache() {
+    jwksCacheGeneration += 1;
     cachedJwks = null;
     jwksCacheTimestamp = 0;
 }
@@ -120,10 +130,8 @@ export function signingKeysToJwks(records) {
         try {
             keys.push(pemToJwk(record.privateKey, record.kid));
         }
-        catch (error) {
-            // Skip invalid PEM keys rather than crashing — log error and continue
-            // with remaining keys so the provider can still start
-            logger.error({ kid: record.kid, error }, 'Failed to convert signing key PEM to JWK, skipping');
+        catch {
+            throw invalidSigningKeyRecord(record.kid);
         }
     }
     return { keys };
@@ -146,38 +154,51 @@ export async function loadSigningKeysFromDb() {
      WHERE status IN ('active', 'retired')
        AND (expires_at IS NULL OR expires_at > NOW())
      ORDER BY activated_at DESC`);
-    // Map snake_case DB columns to camelCase TypeScript interface.
-    // Decrypt private keys that are stored encrypted; pass through plaintext legacy keys.
+    // Map snake_case DB columns to camelCase TypeScript interface. Every private key must use the
+    // authenticated encrypted representation; accepting a partial or plaintext row would weaken
+    // the storage guarantee and could expose key material through later error handling.
     return result.rows.map((row) => {
-        let privateKey;
-        if (row.encrypted && row.private_key_iv && row.private_key_tag) {
-            // Encrypted key — decrypt with AES-256-GCM
-            privateKey = decryptPrivateKey(row.private_key, row.private_key_iv, row.private_key_tag, config.signingKeyEncryptionKey);
+        if (!row.encrypted || !row.private_key_iv || !row.private_key_tag) {
+            throw invalidSigningKeyRecord(row.kid);
+        }
+        try {
+            const privateKey = decryptPrivateKey(row.private_key, row.private_key_iv, row.private_key_tag, config.signingKeyEncryptionKey);
+            return {
+                id: row.id,
+                kid: row.kid,
+                algorithm: row.algorithm,
+                publicKey: row.public_key,
+                privateKey,
+                status: row.status,
+                activatedAt: row.activated_at,
+                retiredAt: row.retired_at,
+                expiresAt: row.expires_at,
+            };
         }
-        else {
-            // Legacy plaintext key — use as-is
-            privateKey = row.private_key;
+        catch {
+            throw invalidSigningKeyRecord(row.kid);
         }
-        return {
-            id: row.id,
-            kid: row.kid,
-            algorithm: row.algorithm,
-            publicKey: row.public_key,
-            privateKey,
-            status: row.status,
-            activatedAt: row.activated_at,
-            retiredAt: row.retired_at,
-            expiresAt: row.expires_at,
-        };
     });
 }
+/**
+ * Creates and records the fixed failure used for any unusable stored signing key.
+ *
+ * Only the public key identifier is logged. Ciphertext, metadata, parser errors, and stack traces
+ * are deliberately omitted because they can reveal secrets or internal deployment details.
+ *
+ * @param kid - Public identifier of the unusable database row.
+ * @returns A safe domain error suitable for propagation to startup and CLI boundaries.
+ */
+function invalidSigningKeyRecord(kid) {
+    logger.error({ event: 'signing-key-record-invalid', kid }, 'Signing key record is invalid');
+    return new SigningKeyCryptoError('Signing key record is invalid');
+}
 /**
  * Ensure at least one active signing key exists in the database.
  *
- * Called at application startup. If no active keys are found:
- * 1. Generate a new ES256 key pair
- * 2. Insert it into the signing_keys table with status='active'
- * 3. Log a warning that a key was auto-generated
+ * Called at application startup. A transaction-scoped table lock serializes the active-key
+ * recheck and optional encrypted insert, so simultaneous new processes cannot each create a
+ * bootstrap key. Every caller reloads the committed rows after releasing the lock.
  *
  * This guarantees the OIDC provider can always start, even on a fresh database
  * that has no signing keys yet (e.g., first run after migrations).
@@ -185,22 +206,26 @@ export async function loadSigningKeysFromDb() {
  * @returns The JWK key set containing all active and retired keys
  */
 export async function ensureSigningKeys() {
-    let records = await loadSigningKeysFromDb();
-    // Check if there are any active keys
-    const hasActiveKey = records.some((r) => r.status === 'active');
-    if (!hasActiveKey) {
+    await runDatabaseTransaction(async () => {
+        const pool = getPool();
+        await pool.query('LOCK TABLE signing_keys IN SHARE ROW EXCLUSIVE MODE');
+        // Recheck under the lock because another process may have inserted the first key while this
+        // process was waiting. Only the lock holder that still sees no active key may create one.
+        const lockedRecords = await loadSigningKeysFromDb();
+        if (lockedRecords.some((record) => record.status === 'active'))
+            return;
         logger.warn('No active signing keys found — auto-generating a new ES256 key pair');
         const keyPair = generateES256KeyPair();
-        const pool = getPool();
         // Encrypt the private key before storage (AES-256-GCM)
         const { encrypted, iv, tag } = encryptPrivateKey(keyPair.privateKeyPem, config.signingKeyEncryptionKey);
         // Insert the new key with encrypted private key
         await pool.query(`INSERT INTO signing_keys (kid, algorithm, public_key, private_key, private_key_iv, private_key_tag, encrypted, status, activated_at)
        VALUES ($1, $2, $3, $4, $5, $6, true, 'active', NOW())`, [keyPair.kid, keyPair.algorithm, keyPair.publicKeyPem, encrypted, iv, tag]);
         logger.info({ kid: keyPair.kid }, 'Auto-generated signing key inserted into database');
-        // Reload keys from DB to get the full record including generated UUID
-        records = await loadSigningKeysFromDb();
-    }
+    });
+    // Every caller reloads after the lock transaction commits. This gives both the inserting caller
+    // and any waiter the same authoritative winner, including its database-generated identifier.
+    const records = await loadSigningKeysFromDb();
     return signingKeysToJwks(records);
 }
 //# sourceMappingURL=signing-keys.js.map

package/dist/lib/signing-keys.js.map

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

package/dist/lib/super-admin-protection.d.ts

@@ -11,8 +11,6 @@
  *
  * Protected operations (all throw 403 Forbidden):
  *   - Delete
- *   - Suspend
- *   - Lock
  *   - Deactivate
  *   - Remove porta-super-admin role
  *   - Manage 2FA (disable, reset, regenerate recovery codes)
@@ -25,7 +23,8 @@ export declare const SUPER_ADMIN_USER_ID_KEY = "super_admin_user_id";
  * Operations that are forbidden on the super-admin user.
  * Used in error messages to clearly communicate what was attempted.
  */
-export declare const PROTECTED_OPERATIONS: readonly ['delete', 'suspend', 'lock', 'deactivate', 'remove-super-admin-role', 'manage-2fa'];
+export declare const PROTECTED_OPERATIONS: readonly ['delete', 'deactivate', 'remove-super-admin-role', 'manage-2fa'];
+/** Destructive operations that cannot target the bootstrap administrator. */
 export type ProtectedOperation = (typeof PROTECTED_OPERATIONS)[number];
 /**
  * Check if a user is the protected super-admin user.
@@ -47,6 +46,7 @@ export declare class SuperAdminProtectionError extends Error {
     readonly status = 403;
     /** The operation that was attempted */
     readonly operation: ProtectedOperation;
+    /** Create the public rejection for an attempted protected operation. */
     constructor(operation: ProtectedOperation);
 }
 /**
@@ -54,8 +54,8 @@ export declare class SuperAdminProtectionError extends Error {
  *
  * Call this before executing any destructive operation on a user:
  * ```typescript
- * await guardSuperAdmin(userId, 'suspend');
- * // ... proceed with suspend logic
+ * await guardSuperAdmin(userId, 'deactivate');
+ * // ... proceed with deactivation
  * ```
  *
  * If the user is not the super-admin, this function is a no-op.

package/dist/lib/super-admin-protection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"super-admin-protection.d.ts","sourceRoot":"","sources":["../../src/lib/super-admin-protection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAQH,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,YAC/B,QAAQ,EACR,SAAS,EACT,MAAM,EACN,YAAY,EACZ,yBAAyB,EACzB,YAAY,CACJ,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAMvE;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvE;AAMD;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,oCAAoC;IACpC,QAAQ,CAAC,MAAM,OAAO;IACtB,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IAEvC,YAAY,SAAS,EAAE,kBAAkB,EAIxC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,kBAAkB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAKf"}
+{"version":3,"file":"super-admin-protection.d.ts","sourceRoot":"","sources":["../../src/lib/super-admin-protection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,YAC/B,QAAQ,EACR,YAAY,EACZ,yBAAyB,EACzB,YAAY,CACJ,CAAC;AAEX,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAMvE;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvE;AAMD;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,oCAAoC;IACpC,QAAQ,CAAC,MAAM,OAAO;IACtB,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IAEvC,wEAAwE;IACxE,YAAY,SAAS,EAAE,kBAAkB,EAIxC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,kBAAkB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/lib/super-admin-protection.js

@@ -11,15 +11,13 @@
  *
  * Protected operations (all throw 403 Forbidden):
  *   - Delete
- *   - Suspend
- *   - Lock
  *   - Deactivate
  *   - Remove porta-super-admin role
  *   - Manage 2FA (disable, reset, regenerate recovery codes)
  *
  * @module lib/super-admin-protection
  */
-import { getSystemConfigString } from './system-config.js';
+import { getInternalSystemConfigString } from './system-config.js';
 // ============================================================================
 // Constants
 // ============================================================================
@@ -31,8 +29,6 @@ export const SUPER_ADMIN_USER_ID_KEY = 'super_admin_user_id';
  */
 export const PROTECTED_OPERATIONS = [
     'delete',
-    'suspend',
-    'lock',
     'deactivate',
     'remove-super-admin-role',
     'manage-2fa',
@@ -51,9 +47,9 @@ export const PROTECTED_OPERATIONS = [
  * @returns true if the user is the super-admin
  */
 export async function isSuperAdminUser(userId) {
-    // getSystemConfigString returns the fallback when the key doesn't exist.
+    // The internal reader returns the fallback when the key doesn't exist.
     // Empty string fallback means: if no super-admin is configured, nobody matches.
-    const superAdminUserId = await getSystemConfigString(SUPER_ADMIN_USER_ID_KEY, '');
+    const superAdminUserId = await getInternalSystemConfigString(SUPER_ADMIN_USER_ID_KEY, '');
     if (!superAdminUserId) {
         return false;
     }
@@ -71,6 +67,7 @@ export class SuperAdminProtectionError extends Error {
     status = 403;
     /** The operation that was attempted */
     operation;
+    /** Create the public rejection for an attempted protected operation. */
     constructor(operation) {
         super(`Cannot ${operation} the super-admin user`);
         this.name = 'SuperAdminProtectionError';
@@ -82,8 +79,8 @@ export class SuperAdminProtectionError extends Error {
  *
  * Call this before executing any destructive operation on a user:
  * ```typescript
- * await guardSuperAdmin(userId, 'suspend');
- * // ... proceed with suspend logic
+ * await guardSuperAdmin(userId, 'deactivate');
+ * // ... proceed with deactivation
  * ```
  *
  * If the user is not the super-admin, this function is a no-op.

package/dist/lib/super-admin-protection.js.map

@@ -1 +1 @@
-{"version":3,"file":"super-admin-protection.js","sourceRoot":"","sources":["../../src/lib/super-admin-protection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E,gEAAgE;AAChE,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAE7D;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,QAAQ;IACR,SAAS;IACT,MAAM;IACN,YAAY;IACZ,yBAAyB;IACzB,YAAY;CACJ,CAAC;AAIX,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAc;IACnD,yEAAyE;IACzE,gFAAgF;IAChF,MAAM,gBAAgB,GAAG,MAAM,qBAAqB,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;IAClF,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,gBAAgB,KAAK,MAAM,CAAC;AACrC,CAAC;AAED,+EAA+E;AAC/E,QAAQ;AACR,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,oCAAoC;IAC3B,MAAM,GAAG,GAAG,CAAC;IACtB,uCAAuC;IAC9B,SAAS,CAAqB;IAEvC,YAAY,SAA6B;QACvC,KAAK,CAAC,UAAU,SAAS,uBAAuB,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAc,EACd,SAA6B;IAE7B,MAAM,WAAW,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACnD,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,IAAI,yBAAyB,CAAC,SAAS,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}
+{"version":3,"file":"super-admin-protection.js","sourceRoot":"","sources":["../../src/lib/super-admin-protection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,oBAAoB,CAAC;AAEnE,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E,gEAAgE;AAChE,MAAM,CAAC,MAAM,uBAAuB,GAAG,qBAAqB,CAAC;AAE7D;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,QAAQ;IACR,YAAY;IACZ,yBAAyB;IACzB,YAAY;CACJ,CAAC;AAKX,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAc;IACnD,uEAAuE;IACvE,gFAAgF;IAChF,MAAM,gBAAgB,GAAG,MAAM,6BAA6B,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;IAC1F,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,gBAAgB,KAAK,MAAM,CAAC;AACrC,CAAC;AAED,+EAA+E;AAC/E,QAAQ;AACR,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,oCAAoC;IAC3B,MAAM,GAAG,GAAG,CAAC;IACtB,uCAAuC;IAC9B,SAAS,CAAqB;IAEvC,wEAAwE;IACxE,YAAY,SAA6B;QACvC,KAAK,CAAC,UAAU,SAAS,uBAAuB,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAc,EACd,SAA6B;IAE7B,MAAM,WAAW,GAAG,MAAM,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACnD,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,IAAI,yBAAyB,CAAC,SAAS,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,268 @@
+/** Closed operational policy. Database rows own values, never these definitions or defaults. */
+/** Locales for which Porta ships every authentication namespace. */
+export declare const SUPPORTED_LOCALES: readonly ["en"];
+/** A completely packaged authentication locale. */
+export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
+/** Administrative tab containing a policy field. */
+export type SystemConfigGroup = 'lifetimes' | 'rate-limits' | 'lockout' | 'general';
+/** Whether a saved value is read at runtime or only during provider construction. */
+export type SystemConfigApplicationMode = 'runtime' | 'restart-required';
+/** Native JSON scalar kind accepted by a policy field. */
+export type SystemConfigValueType = 'integer' | 'string';
+/** Unit used to explain a native policy value without changing its representation. */
+export type SystemConfigUnit = 'seconds' | 'attempts' | 'days' | 'locale';
+/** Valid native operational policy; locale strings must be completely packaged. */
+export type SystemConfigValue = number | SupportedLocale;
+/**
+ * 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 declare const SYSTEM_CONFIG_CATALOG: readonly [Readonly<{
+    key: "access_token_ttl";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "id_token_ttl";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "refresh_token_ttl";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "authorization_code_ttl";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "session_ttl";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "magic_link_ttl";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "password_reset_ttl";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "invitation_ttl";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "rate_limit_login_max";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "rate_limit_login_window";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "rate_limit_magic_link_max";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "rate_limit_magic_link_window";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "rate_limit_password_reset_max";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "rate_limit_password_reset_window";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "max_failed_logins";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "lockout_duration_seconds";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    key: "audit_retention_days";
+    group: SystemConfigGroup;
+    label: string;
+    description: string;
+    valueType: 'integer';
+    unit: "attempts" | "days" | "seconds";
+    defaultValue: number;
+    minimum: number;
+    maximum: number;
+    applicationMode: SystemConfigApplicationMode;
+}>, Readonly<{
+    readonly key: 'default_locale';
+    readonly group: 'general';
+    readonly label: 'Default locale';
+    readonly description: 'Final locale fallback used by the authentication UI.';
+    readonly valueType: 'string';
+    readonly unit: 'locale';
+    readonly defaultValue: 'en';
+    readonly allowedValues: readonly ["en"];
+    readonly applicationMode: 'runtime';
+}>];
+/** Exact public keys, derived from the same catalog used by runtime and administrative readers. */
+export type SystemConfigKey = (typeof SYSTEM_CONFIG_CATALOG)[number]['key'];
+/** Public keys whose native values are integers. */
+export type NumericSystemConfigKey = Exclude<SystemConfigKey, 'default_locale'>;
+/** Application-owned metadata for one editable operational-policy field. */
+export interface SystemConfigDefinition {
+    /** Closed identifier used in storage and requests. */
+    readonly key: SystemConfigKey;
+    /** Administrative tab to which this field belongs. */
+    readonly group: SystemConfigGroup;
+    /** Human-readable field caption. */
+    readonly label: string;
+    /** Operational effect explained without infrastructure details. */
+    readonly description: string;
+    /** Accepted native JSON scalar kind. */
+    readonly valueType: SystemConfigValueType;
+    /** Unit of the stored value. */
+    readonly unit: SystemConfigUnit;
+    /** Safe runtime fallback when storage is missing, invalid or unavailable. */
+    readonly defaultValue: SystemConfigValue;
+    /** Inclusive lower bound for integer fields. */
+    readonly minimum?: number;
+    /** Inclusive upper bound for integer fields. */
+    readonly maximum?: number;
+    /** Completely supported values for a locale field. */
+    readonly allowedValues?: readonly SupportedLocale[];
+    /** Whether every provider instance must restart after saving this field. */
+    readonly applicationMode: SystemConfigApplicationMode;
+}
+/**
+ * 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 declare function findSystemConfigDefinition(key: string): SystemConfigDefinition | undefined;
+/**
+ * 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 declare function validateSystemConfigValue(definition: SystemConfigDefinition, value: unknown): SystemConfigValue | undefined;
+//# sourceMappingURL=system-config-catalog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"system-config-catalog.d.ts","sourceRoot":"","sources":["../../src/lib/system-config-catalog.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAEhG,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,iBAAiC,CAAC;AAEhE,mDAAmD;AACnD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,oDAAoD;AACpD,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC;AAEpF,qFAAqF;AACrF,MAAM,MAAM,2BAA2B,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAEzE,0DAA0D;AAC1D,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzD,sFAAsF;AACtF,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE1E,mFAAmF;AACnF,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,eAAe,CAAC;AA4BzD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;eAhBnB,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;;;;;eAAT,SAAS;;;;;;;kBAiMf,gBAAgB;oBACd,SAAS;oBACT,gBAAgB;0BACV,sDAAsD;wBACxD,QAAQ;mBACb,QAAQ;2BACA,IAAI;;8BAED,SAAS;GAEnB,CAAC;AAEZ,mGAAmG;AACnG,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;AAE5E,oDAAoD;AACpD,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAAC;AAEhF,4EAA4E;AAC5E,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;IAC1C,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;IACzC,gDAAgD;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACpD,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,EAAE,2BAA2B,CAAC;CACvD;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAE1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,sBAAsB,EAClC,KAAK,EAAE,OAAO,GACb,iBAAiB,GAAG,SAAS,CAe/B"}