@portaidentity/server 1.7.0

package/dist/two-factor/totp.js

@@ -0,0 +1,96 @@
+/**
+ * TOTP (Time-based One-Time Password) utilities.
+ *
+ * Implements RFC 6238 TOTP using the `otpauth` library. Provides secret
+ * generation, otpauth:// URI construction, QR code generation for
+ * authenticator app enrollment, and code verification with a ±1 step
+ * time window to accommodate clock drift.
+ *
+ * QR code generation uses the `qrcode` library to produce data URIs
+ * that can be displayed inline in Handlebars templates.
+ */
+import { TOTP, Secret } from 'otpauth';
+import QRCode from 'qrcode';
+/** Default TOTP parameters matching the user_totp table defaults. */
+const DEFAULT_ALGORITHM = 'SHA1';
+const DEFAULT_DIGITS = 6;
+const DEFAULT_PERIOD = 30;
+/**
+ * Generate a new TOTP secret.
+ *
+ * Creates a 20-byte (160-bit) random secret, which is the standard
+ * size for SHA-1-based TOTP as recommended by RFC 4226 §4.
+ * The secret is returned as a base32-encoded string suitable for
+ * storage (after encryption) and otpauth:// URI construction.
+ *
+ * @returns Base32-encoded TOTP secret
+ */
+export function generateTotpSecret() {
+    // Secret.fromRaw generates using crypto.randomBytes internally
+    const secret = new Secret({ size: 20 });
+    return secret.base32;
+}
+/**
+ * Generate an otpauth:// URI for authenticator app enrollment.
+ *
+ * The URI encodes the secret, issuer, account name, and TOTP parameters
+ * in a format understood by Google Authenticator, Authy, 1Password, etc.
+ *
+ * @param secret - Base32-encoded TOTP secret
+ * @param userEmail - User's email address (displayed as account name)
+ * @param issuer - Service name (e.g., "Porta" or org slug)
+ * @returns otpauth:// URI string
+ */
+export function generateTotpUri(secret, userEmail, issuer) {
+    const totp = new TOTP({
+        issuer,
+        label: userEmail,
+        algorithm: DEFAULT_ALGORITHM,
+        digits: DEFAULT_DIGITS,
+        period: DEFAULT_PERIOD,
+        secret: Secret.fromBase32(secret),
+    });
+    return totp.toString();
+}
+/**
+ * Generate a QR code data URI from an otpauth:// URI.
+ *
+ * The returned data URI can be used directly in an <img src="..."> tag
+ * in Handlebars templates. Uses SVG format for crisp rendering at any size.
+ *
+ * @param uri - otpauth:// URI to encode
+ * @returns Data URI string (data:image/svg+xml;base64,...)
+ */
+export async function generateQrCodeDataUri(uri) {
+    // QRCode.toDataURL generates a PNG data URI by default
+    // Using SVG would require toBuffer + manual base64, so PNG is simpler
+    return QRCode.toDataURL(uri, {
+        errorCorrectionLevel: 'M', // Medium error correction — good balance
+        margin: 2,
+        width: 256,
+    });
+}
+/**
+ * Verify a TOTP code against a secret.
+ *
+ * Allows a ±1 step time window (i.e., the current 30-second window
+ * plus one window before and one after) to accommodate minor clock
+ * drift between the server and the user's authenticator app.
+ *
+ * @param code - The 6-digit TOTP code entered by the user
+ * @param secret - Base32-encoded TOTP secret
+ * @returns True if the code is valid within the time window
+ */
+export function verifyTotpCode(code, secret) {
+    const totp = new TOTP({
+        algorithm: DEFAULT_ALGORITHM,
+        digits: DEFAULT_DIGITS,
+        period: DEFAULT_PERIOD,
+        secret: Secret.fromBase32(secret),
+    });
+    // validate() returns the time step delta (0 for exact match, ±1 for adjacent)
+    // or null if invalid. A window of 1 allows ±1 step.
+    const delta = totp.validate({ token: code, window: 1 });
+    return delta !== null;
+}
+//# sourceMappingURL=totp.js.map

package/dist/two-factor/totp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp.js","sourceRoot":"","sources":["../../src/two-factor/totp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,qEAAqE;AACrE,MAAM,iBAAiB,GAAG,MAAM,CAAC;AACjC,MAAM,cAAc,GAAG,CAAC,CAAC;AACzB,MAAM,cAAc,GAAG,EAAE,CAAC;AAE1B;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB;IAChC,+DAA+D;IAC/D,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACxC,OAAO,MAAM,CAAC,MAAM,CAAC;AACvB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,SAAiB,EACjB,MAAc;IAEd,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC;QACpB,MAAM;QACN,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,iBAAiB;QAC5B,MAAM,EAAE,cAAc;QACtB,MAAM,EAAE,cAAc;QACtB,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;KAClC,CAAC,CAAC;IAEH,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,GAAW;IACrD,uDAAuD;IACvD,sEAAsE;IACtE,OAAO,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE;QAC3B,oBAAoB,EAAE,GAAG,EAAE,yCAAyC;QACpE,MAAM,EAAE,CAAC;QACT,KAAK,EAAE,GAAG;KACX,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,MAAc;IACzD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC;QACpB,SAAS,EAAE,iBAAiB;QAC5B,MAAM,EAAE,cAAc;QACtB,MAAM,EAAE,cAAc;QACtB,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;KAClC,CAAC,CAAC;IAEH,8EAA8E;IAC9E,oDAAoD;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IACxD,OAAO,KAAK,KAAK,IAAI,CAAC;AACxB,CAAC"}

package/dist/two-factor/types.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Two-factor authentication types and interfaces.
+ *
+ * Defines data structures for the 2FA module: method and policy enums,
+ * TOTP configuration, email OTP codes, recovery codes, setup results,
+ * and status tracking. Also provides row mapping functions for
+ * converting snake_case PostgreSQL rows to camelCase TypeScript objects.
+ *
+ * These types are the foundation for all other two-factor modules
+ * (repository, cache, service, routes, CLI).
+ */
+/** The 2FA method a user has configured. */
+export type TwoFactorMethod = 'email' | 'totp';
+/**
+ * Organization-level 2FA policy — controls whether 2FA is required for members.
+ * - 'optional': users may enable 2FA but it's not required
+ * - 'required_email': all users must use email OTP
+ * - 'required_totp': all users must use authenticator app (TOTP)
+ * - 'required_any': all users must use any supported 2FA method
+ */
+export type TwoFactorPolicy = 'optional' | 'required_email' | 'required_totp' | 'required_any';
+/**
+ * TOTP configuration record for a user.
+ * Secrets are stored encrypted with AES-256-GCM; the IV and auth tag
+ * are needed alongside the encryption key to decrypt.
+ */
+export interface UserTotp {
+    id: string;
+    userId: string;
+    encryptedSecret: string;
+    encryptionIv: string;
+    encryptionTag: string;
+    algorithm: string;
+    digits: number;
+    period: number;
+    /** True after the user has verified their first TOTP code. */
+    verified: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Email OTP code record.
+ * The actual 6-digit code is stored as a SHA-256 hash; the plaintext
+ * is only ever sent via email and never stored.
+ */
+export interface OtpCode {
+    id: string;
+    userId: string;
+    codeHash: string;
+    expiresAt: Date;
+    /** Null if unused; set to a timestamp upon successful verification. */
+    usedAt: Date | null;
+    createdAt: Date;
+}
+/**
+ * Recovery code record.
+ * Each code is hashed with Argon2id and can only be used once.
+ * Users receive 10 codes at 2FA setup time as a backup.
+ */
+export interface RecoveryCode {
+    id: string;
+    userId: string;
+    codeHash: string;
+    /** Null if unused; set to a timestamp upon successful verification. */
+    usedAt: Date | null;
+    createdAt: Date;
+}
+/**
+ * Result returned after 2FA setup — contains everything the user needs
+ * to complete enrollment. Recovery codes are shown only once.
+ */
+export interface TwoFactorSetupResult {
+    method: TwoFactorMethod;
+    /** Plaintext recovery codes — displayed once to the user. */
+    recoveryCodes: string[];
+    /** otpauth:// URI for authenticator app enrollment (TOTP only). */
+    totpUri?: string;
+    /** Data URI of QR code image for scanning (TOTP only). */
+    qrCodeDataUri?: string;
+}
+/**
+ * Current 2FA status for a user — used by the service layer and CLI.
+ */
+export interface TwoFactorStatus {
+    enabled: boolean;
+    method: TwoFactorMethod | null;
+    totpConfigured: boolean;
+    recoveryCodesRemaining: number;
+}
+/** Input data for inserting a new TOTP configuration. */
+export interface InsertTotpData {
+    userId: string;
+    encryptedSecret: string;
+    encryptionIv: string;
+    encryptionTag: string;
+    algorithm?: string;
+    digits?: number;
+    period?: number;
+}
+/** Raw database row from the user_totp table (snake_case columns). */
+export interface UserTotpRow {
+    id: string;
+    user_id: string;
+    encrypted_secret: string;
+    encryption_iv: string;
+    encryption_tag: string;
+    algorithm: string;
+    digits: number;
+    period: number;
+    verified: boolean;
+    created_at: Date;
+    updated_at: Date;
+}
+/** Raw database row from the two_factor_otp_codes table. */
+export interface OtpCodeRow {
+    id: string;
+    user_id: string;
+    code_hash: string;
+    expires_at: Date;
+    used_at: Date | null;
+    created_at: Date;
+}
+/** Raw database row from the two_factor_recovery_codes table. */
+export interface RecoveryCodeRow {
+    id: string;
+    user_id: string;
+    code_hash: string;
+    used_at: Date | null;
+    created_at: Date;
+}
+/**
+ * Map a user_totp database row to a UserTotp object.
+ *
+ * @param row - Raw database row from the user_totp table
+ * @returns Mapped UserTotp object with camelCase properties
+ */
+export declare function mapRowToUserTotp(row: UserTotpRow): UserTotp;
+/**
+ * Map a two_factor_otp_codes database row to an OtpCode object.
+ *
+ * @param row - Raw database row from the two_factor_otp_codes table
+ * @returns Mapped OtpCode object with camelCase properties
+ */
+export declare function mapRowToOtpCode(row: OtpCodeRow): OtpCode;
+/**
+ * Map a two_factor_recovery_codes database row to a RecoveryCode object.
+ *
+ * @param row - Raw database row from the two_factor_recovery_codes table
+ * @returns Mapped RecoveryCode object with camelCase properties
+ */
+export declare function mapRowToRecoveryCode(row: RecoveryCodeRow): RecoveryCode;
+//# sourceMappingURL=types.d.ts.map

package/dist/two-factor/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/two-factor/types.ts"],"names":[],"mappings":"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"}

package/dist/two-factor/types.js

@@ -0,0 +1,64 @@
+/**
+ * Two-factor authentication types and interfaces.
+ *
+ * Defines data structures for the 2FA module: method and policy enums,
+ * TOTP configuration, email OTP codes, recovery codes, setup results,
+ * and status tracking. Also provides row mapping functions for
+ * converting snake_case PostgreSQL rows to camelCase TypeScript objects.
+ *
+ * These types are the foundation for all other two-factor modules
+ * (repository, cache, service, routes, CLI).
+ */
+/**
+ * Map a user_totp database row to a UserTotp object.
+ *
+ * @param row - Raw database row from the user_totp table
+ * @returns Mapped UserTotp object with camelCase properties
+ */
+export function mapRowToUserTotp(row) {
+    return {
+        id: row.id,
+        userId: row.user_id,
+        encryptedSecret: row.encrypted_secret,
+        encryptionIv: row.encryption_iv,
+        encryptionTag: row.encryption_tag,
+        algorithm: row.algorithm,
+        digits: row.digits,
+        period: row.period,
+        verified: row.verified,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+/**
+ * Map a two_factor_otp_codes database row to an OtpCode object.
+ *
+ * @param row - Raw database row from the two_factor_otp_codes table
+ * @returns Mapped OtpCode object with camelCase properties
+ */
+export function mapRowToOtpCode(row) {
+    return {
+        id: row.id,
+        userId: row.user_id,
+        codeHash: row.code_hash,
+        expiresAt: row.expires_at,
+        usedAt: row.used_at,
+        createdAt: row.created_at,
+    };
+}
+/**
+ * Map a two_factor_recovery_codes database row to a RecoveryCode object.
+ *
+ * @param row - Raw database row from the two_factor_recovery_codes table
+ * @returns Mapped RecoveryCode object with camelCase properties
+ */
+export function mapRowToRecoveryCode(row) {
+    return {
+        id: row.id,
+        userId: row.user_id,
+        codeHash: row.code_hash,
+        usedAt: row.used_at,
+        createdAt: row.created_at,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/two-factor/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/two-factor/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgKH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAgB;IAC/C,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,eAAe,EAAE,GAAG,CAAC,gBAAgB;QACrC,YAAY,EAAE,GAAG,CAAC,aAAa;QAC/B,aAAa,EAAE,GAAG,CAAC,cAAc;QACjC,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAAe;IAC7C,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAoB;IACvD,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC"}

package/dist/users/cache.d.ts

@@ -0,0 +1,49 @@
+/**
+ * User cache — Redis-backed fast lookup layer.
+ *
+ * Provides get/set/invalidate operations for User objects stored in
+ * Redis. Users are cached by ID only (not by email) because:
+ *   - Email lookups happen during login (which hits DB for password_hash anyway)
+ *   - ID lookups happen during token validation, userinfo, etc. (cacheable)
+ *   - Simpler invalidation — one key per user instead of two
+ *
+ * Date fields are serialized as ISO 8601 strings by JSON.stringify()
+ * and restored to Date objects on read. The user cache has 5 nullable
+ * date fields: passwordChangedAt, lockedAt, lastLoginAt, createdAt,
+ * updatedAt.
+ *
+ * All Redis errors are caught and logged — cache failures never
+ * propagate to callers. The system gracefully degrades to direct
+ * database lookups when Redis is unavailable.
+ */
+import type { User } from './types.js';
+/**
+ * Get a user from cache by ID.
+ *
+ * Returns null on cache miss, invalid JSON, or Redis error.
+ * Callers should fall back to the database on null.
+ *
+ * @param id - User UUID
+ * @returns Cached user or null
+ */
+export declare function getCachedUserById(id: string): Promise<User | null>;
+/**
+ * Store a user in cache under the ID key.
+ *
+ * Date fields are serialized to ISO 8601 strings automatically
+ * by JSON.stringify(). Silent failure — cache write errors are
+ * logged but never propagated.
+ *
+ * @param user - User to cache
+ */
+export declare function cacheUser(user: User): Promise<void>;
+/**
+ * Invalidate the cache entry for a user.
+ *
+ * Should be called after any write operation (create, update, status
+ * change, password change) to ensure stale data is not served.
+ *
+ * @param id - User UUID
+ */
+export declare function invalidateUserCache(id: string): Promise<void>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/users/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/users/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAgBvC;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAWxE;AAMD;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAWzD;AAMD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUnE"}

package/dist/users/cache.js

@@ -0,0 +1,140 @@
+/**
+ * User cache — Redis-backed fast lookup layer.
+ *
+ * Provides get/set/invalidate operations for User objects stored in
+ * Redis. Users are cached by ID only (not by email) because:
+ *   - Email lookups happen during login (which hits DB for password_hash anyway)
+ *   - ID lookups happen during token validation, userinfo, etc. (cacheable)
+ *   - Simpler invalidation — one key per user instead of two
+ *
+ * Date fields are serialized as ISO 8601 strings by JSON.stringify()
+ * and restored to Date objects on read. The user cache has 5 nullable
+ * date fields: passwordChangedAt, lockedAt, lastLoginAt, createdAt,
+ * updatedAt.
+ *
+ * All Redis errors are caught and logged — cache failures never
+ * propagate to callers. The system gracefully degrades to direct
+ * database lookups when Redis is unavailable.
+ */
+import { getRedis } from '../lib/redis.js';
+import { logger } from '../lib/logger.js';
+import { afterDatabaseCommit } from '../lib/database.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Cache TTL in seconds (5 minutes — matches organizations) */
+const CACHE_TTL = 300;
+/** Key prefix for ID-based lookups */
+const USER_PREFIX = 'user:id:';
+// ---------------------------------------------------------------------------
+// Cache retrieval
+// ---------------------------------------------------------------------------
+/**
+ * Get a user from cache by ID.
+ *
+ * Returns null on cache miss, invalid JSON, or Redis error.
+ * Callers should fall back to the database on null.
+ *
+ * @param id - User UUID
+ * @returns Cached user or null
+ */
+export async function getCachedUserById(id) {
+    try {
+        const redis = getRedis();
+        const data = await redis.get(`${USER_PREFIX}${id}`);
+        if (!data)
+            return null;
+        return deserializeUser(data);
+    }
+    catch {
+        // Graceful degradation — log and return null so caller falls back to DB
+        logger.warn({ event: 'user-cache-read-failed' }, 'User cache read failed');
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Cache storage
+// ---------------------------------------------------------------------------
+/**
+ * Store a user in cache under the ID key.
+ *
+ * Date fields are serialized to ISO 8601 strings automatically
+ * by JSON.stringify(). Silent failure — cache write errors are
+ * logged but never propagated.
+ *
+ * @param user - User to cache
+ */
+export async function cacheUser(user) {
+    await afterDatabaseCommit(async () => {
+        try {
+            const redis = getRedis();
+            const data = JSON.stringify(user);
+            await redis.set(`${USER_PREFIX}${user.id}`, data, 'EX', CACHE_TTL);
+        }
+        catch {
+            // Graceful degradation — cache write failure is non-fatal
+            logger.warn({ event: 'user-cache-write-failed' }, 'User cache write failed');
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Cache invalidation
+// ---------------------------------------------------------------------------
+/**
+ * Invalidate the cache entry for a user.
+ *
+ * Should be called after any write operation (create, update, status
+ * change, password change) to ensure stale data is not served.
+ *
+ * @param id - User UUID
+ */
+export async function invalidateUserCache(id) {
+    await afterDatabaseCommit(async () => {
+        try {
+            const redis = getRedis();
+            await redis.del(`${USER_PREFIX}${id}`);
+        }
+        catch {
+            // Graceful degradation — cache invalidation failure is non-fatal
+            logger.warn({ event: 'user-cache-invalidation-failed' }, 'User cache invalidation failed');
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Serialization helpers
+// ---------------------------------------------------------------------------
+/**
+ * Deserialize a JSON string from Redis into a User object.
+ *
+ * Converts ISO 8601 date strings back to Date objects for all date
+ * fields. The User interface has 5 date fields: createdAt, updatedAt
+ * (always present), and passwordChangedAt, lockedAt, lastLoginAt
+ * (nullable — only converted when non-null).
+ *
+ * @param data - JSON string from Redis
+ * @returns User object with proper Date instances, or null if parse fails
+ */
+function deserializeUser(data) {
+    try {
+        const parsed = JSON.parse(data);
+        // Restore required Date objects from ISO string serialization
+        parsed.createdAt = new Date(parsed.createdAt);
+        parsed.updatedAt = new Date(parsed.updatedAt);
+        // Restore nullable Date objects (only convert when non-null)
+        if (parsed.passwordChangedAt !== null) {
+            parsed.passwordChangedAt = new Date(parsed.passwordChangedAt);
+        }
+        if (parsed.lockedAt !== null) {
+            parsed.lockedAt = new Date(parsed.lockedAt);
+        }
+        if (parsed.lastLoginAt !== null) {
+            parsed.lastLoginAt = new Date(parsed.lastLoginAt);
+        }
+        return parsed;
+    }
+    catch {
+        logger.warn('Failed to parse cached user JSON');
+        return null;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/users/cache.js.map

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

package/dist/users/claims.d.ts

@@ -0,0 +1,67 @@
+/**
+ * OIDC Standard Claims builder.
+ *
+ * Builds OIDC Standard Claims from a User profile based on the granted
+ * OAuth2 scopes. Follows the scope-to-claims mapping defined in
+ * OpenID Connect Core 1.0, §5.4:
+ *
+ *   - openid  → sub (always included)
+ *   - profile → name, given_name, family_name, middle_name, nickname,
+ *               preferred_username, profile, picture, website, gender,
+ *               birthdate, zoneinfo, locale, updated_at
+ *   - email   → email, email_verified
+ *   - phone   → phone_number, phone_number_verified
+ *   - address → address (structured object per §5.1.1)
+ *
+ * Custom claims (org_id, org_slug, roles) are handled in RD-08, not here.
+ * This module only handles the OIDC Standard Claims specification.
+ */
+import type { User } from './types.js';
+/**
+ * OIDC claims object — flexible key-value with required `sub` field.
+ * Uses index signature for the wide variety of standard claim names.
+ */
+export interface OidcClaims {
+    sub: string;
+    [key: string]: unknown;
+}
+/**
+ * Structured address per OIDC §5.1.1.
+ * All fields are optional/nullable — the address object is only
+ * included when at least one field has a value.
+ */
+export interface OidcAddress {
+    street_address?: string | null;
+    locality?: string | null;
+    region?: string | null;
+    postal_code?: string | null;
+    country?: string | null;
+}
+/**
+ * Build OIDC Standard Claims from a user profile based on granted scopes.
+ *
+ * The `sub` claim is always included. Additional claims are added based
+ * on which scopes are present in the `scopes` array. Null profile fields
+ * are included as null (not omitted) — per the OIDC spec, null indicates
+ * "no value" which is different from "not requested".
+ *
+ * The `updated_at` claim is a Unix timestamp (seconds since epoch) per
+ * the OIDC specification, not an ISO 8601 string.
+ *
+ * @param user - User whose profile claims to build
+ * @param scopes - Array of granted OAuth2 scope strings
+ * @returns Claims object with `sub` and scope-dependent fields
+ */
+export declare function buildUserClaims(user: User, scopes: string[]): OidcClaims;
+/**
+ * Check if a user has any address fields populated.
+ *
+ * Returns true if at least one address field is non-null/non-empty.
+ * Used to decide whether to include the address claim object —
+ * per the spec, the address claim should not be an empty object.
+ *
+ * @param user - User to check
+ * @returns true if any address field has a value
+ */
+export declare function hasAddress(user: User): boolean;
+//# sourceMappingURL=claims.d.ts.map

package/dist/users/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/users/claims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAMvC;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAoDxE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAQ9C"}