@portaidentity/server 1.7.0

package/dist/cli/output.d.ts

@@ -0,0 +1,94 @@
+/**
+ * CLI output helpers.
+ *
+ * Provides table and JSON formatters, color helpers, and common display
+ * utilities. All commands use these helpers for consistent output across
+ * the CLI.
+ *
+ * Table output uses cli-table3 with bold headers.
+ * JSON output uses formatted (2-space indent) JSON to stdout.
+ * Color helpers use chalk for success/warning/error messages.
+ *
+ * @module cli/output
+ */
+/**
+ * Format data as a table and print to stdout.
+ *
+ * Creates a cli-table3 instance with bold headers and prints each row.
+ * Used by list and show commands for human-readable output.
+ *
+ * @param headers - Column header labels (will be bold)
+ * @param rows - Array of row data (each row is an array of cell strings)
+ */
+export declare function printTable(headers: string[], rows: string[][]): void;
+/**
+ * Print data as formatted JSON to stdout.
+ *
+ * Outputs a 2-space-indented JSON representation. Used when the --json
+ * flag is provided for machine-readable output.
+ *
+ * @param data - Any JSON-serializable value
+ */
+export declare function printJson(data: unknown): void;
+/**
+ * Print a success message with green checkmark.
+ *
+ * @param message - The success message to display
+ */
+export declare function success(message: string): void;
+/**
+ * Print a warning message with yellow icon.
+ *
+ * @param message - The warning message to display
+ */
+export declare function warn(message: string): void;
+/**
+ * Print an error message with red X to stderr.
+ *
+ * Uses console.error so error messages go to stderr (fd 2),
+ * keeping stdout clean for piping and scripting.
+ *
+ * @param message - The error message to display
+ */
+export declare function error(message: string): void;
+/**
+ * Print a "total" summary line below a table.
+ *
+ * Standard pattern: "Total: N <label>" displayed after list output.
+ *
+ * @param label - Plural noun describing the items (e.g., "organizations")
+ * @param count - Number of items
+ */
+export declare function printTotal(label: string, count: number): void;
+/**
+ * Smart output: if --json, print JSON; otherwise, run the table renderer.
+ *
+ * Common pattern used by all list/show commands. The table renderer is
+ * a callback so we don't build table data when JSON mode is active.
+ *
+ * @param isJson - Whether JSON output is requested (from argv.json)
+ * @param tableRenderer - Function that renders table output when called
+ * @param jsonData - Data to output in JSON mode
+ */
+export declare function outputResult(isJson: boolean, tableRenderer: () => void, jsonData: unknown): void;
+/**
+ * Return an ID string for table display.
+ *
+ * Previously truncated UUIDs to 8 characters, but full IDs are needed
+ * for copy-paste into subsequent CLI commands. Now returns the full string.
+ *
+ * @param id - The string to display
+ * @returns The full ID string
+ */
+export declare function truncateId(id: string): string;
+/**
+ * Format a Date for display.
+ *
+ * Converts Date objects or ISO strings to YYYY-MM-DD format.
+ * Null/undefined values render as an em-dash for clean table display.
+ *
+ * @param date - Date object, ISO string, or null
+ * @returns Formatted date string or em-dash for null values
+ */
+export declare function formatDate(date: Date | string | null | undefined): string;
+//# sourceMappingURL=output.d.ts.map

package/dist/cli/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,CAIpE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,EACf,aAAa,EAAE,MAAM,IAAI,EACzB,QAAQ,EAAE,OAAO,GAChB,IAAI,CAMN;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAIzE"}

package/dist/cli/output.js

@@ -0,0 +1,124 @@
+/**
+ * CLI output helpers.
+ *
+ * Provides table and JSON formatters, color helpers, and common display
+ * utilities. All commands use these helpers for consistent output across
+ * the CLI.
+ *
+ * Table output uses cli-table3 with bold headers.
+ * JSON output uses formatted (2-space indent) JSON to stdout.
+ * Color helpers use chalk for success/warning/error messages.
+ *
+ * @module cli/output
+ */
+import Table from 'cli-table3';
+import chalk from 'chalk';
+/**
+ * Format data as a table and print to stdout.
+ *
+ * Creates a cli-table3 instance with bold headers and prints each row.
+ * Used by list and show commands for human-readable output.
+ *
+ * @param headers - Column header labels (will be bold)
+ * @param rows - Array of row data (each row is an array of cell strings)
+ */
+export function printTable(headers, rows) {
+    const table = new Table({ head: headers.map((h) => chalk.bold(h)) });
+    rows.forEach((row) => table.push(row));
+    console.log(table.toString());
+}
+/**
+ * Print data as formatted JSON to stdout.
+ *
+ * Outputs a 2-space-indented JSON representation. Used when the --json
+ * flag is provided for machine-readable output.
+ *
+ * @param data - Any JSON-serializable value
+ */
+export function printJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+/**
+ * Print a success message with green checkmark.
+ *
+ * @param message - The success message to display
+ */
+export function success(message) {
+    console.log(chalk.green('✅ ' + message));
+}
+/**
+ * Print a warning message with yellow icon.
+ *
+ * @param message - The warning message to display
+ */
+export function warn(message) {
+    console.log(chalk.yellow('⚠️  ' + message));
+}
+/**
+ * Print an error message with red X to stderr.
+ *
+ * Uses console.error so error messages go to stderr (fd 2),
+ * keeping stdout clean for piping and scripting.
+ *
+ * @param message - The error message to display
+ */
+export function error(message) {
+    console.error(chalk.red('❌ ' + message));
+}
+/**
+ * Print a "total" summary line below a table.
+ *
+ * Standard pattern: "Total: N <label>" displayed after list output.
+ *
+ * @param label - Plural noun describing the items (e.g., "organizations")
+ * @param count - Number of items
+ */
+export function printTotal(label, count) {
+    console.log(`\nTotal: ${count} ${label}`);
+}
+/**
+ * Smart output: if --json, print JSON; otherwise, run the table renderer.
+ *
+ * Common pattern used by all list/show commands. The table renderer is
+ * a callback so we don't build table data when JSON mode is active.
+ *
+ * @param isJson - Whether JSON output is requested (from argv.json)
+ * @param tableRenderer - Function that renders table output when called
+ * @param jsonData - Data to output in JSON mode
+ */
+export function outputResult(isJson, tableRenderer, jsonData) {
+    if (isJson) {
+        printJson(jsonData);
+    }
+    else {
+        tableRenderer();
+    }
+}
+/**
+ * Return an ID string for table display.
+ *
+ * Previously truncated UUIDs to 8 characters, but full IDs are needed
+ * for copy-paste into subsequent CLI commands. Now returns the full string.
+ *
+ * @param id - The string to display
+ * @returns The full ID string
+ */
+export function truncateId(id) {
+    return id;
+}
+/**
+ * Format a Date for display.
+ *
+ * Converts Date objects or ISO strings to YYYY-MM-DD format.
+ * Null/undefined values render as an em-dash for clean table display.
+ *
+ * @param date - Date object, ISO string, or null
+ * @returns Formatted date string or em-dash for null values
+ */
+export function formatDate(date) {
+    if (!date)
+        return '—';
+    const d = typeof date === 'string' ? new Date(date) : date;
+    return d.toISOString().split('T')[0];
+}
+//# sourceMappingURL=output.js.map

package/dist/cli/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,MAAM,YAAY,CAAC;AAC/B,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,OAAiB,EAAE,IAAgB;IAC5D,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACrE,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACvC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,IAAa;IACrC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,OAAe;IAClC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,KAAK,CAAC,OAAe;IACnC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,KAAa;IACrD,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,IAAI,KAAK,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAe,EACf,aAAyB,EACzB,QAAiB;IAEjB,IAAI,MAAM,EAAE,CAAC;QACX,SAAS,CAAC,QAAQ,CAAC,CAAC;IACtB,CAAC;SAAM,CAAC;QACN,aAAa,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,IAAsC;IAC/D,IAAI,CAAC,IAAI;QAAE,OAAO,GAAG,CAAC;IACtB,MAAM,CAAC,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3D,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC"}

package/dist/cli/prompt.d.ts

@@ -0,0 +1,48 @@
+/**
+ * CLI prompt utilities.
+ *
+ * Provides confirmation, text input, and password (hidden) prompts
+ * for interactive CLI commands. Uses Node.js built-in readline.
+ *
+ * - `confirm()` — y/N confirmation, respects --force flag
+ * - `promptInput()` — reads a line of text (echoed)
+ * - `promptPassword()` — reads a line with hidden input (no echo)
+ *
+ * @module cli/prompt
+ */
+/**
+ * Ask a y/N confirmation question.
+ *
+ * Returns true if user types "y" or "Y", false for anything else.
+ * If force is true, skips the prompt entirely and returns true —
+ * this allows `--force` to bypass confirmations in scripts/automation.
+ *
+ * @param message - The question to display (e.g., "Delete organization?")
+ * @param force - If true, skip the prompt and return true (from argv.force)
+ * @returns true if confirmed, false otherwise
+ */
+export declare function confirm(message: string, force?: boolean): Promise<boolean>;
+/**
+ * Prompt the user for a line of text input.
+ *
+ * Displays the message and waits for the user to type a response.
+ * Returns the trimmed input string. Used for non-sensitive fields
+ * like email, name, etc.
+ *
+ * @param message - The prompt message to display (e.g., "Admin email: ")
+ * @returns The user's trimmed input
+ */
+export declare function promptInput(message: string): Promise<string>;
+/**
+ * Prompt the user for a password (hidden input).
+ *
+ * Displays the message but suppresses character echo so the password
+ * is not visible on screen. Uses a muted Writable stream as the
+ * readline output to prevent echo while still allowing the prompt
+ * message to be displayed via direct stdout write.
+ *
+ * @param message - The prompt message to display (e.g., "Password: ")
+ * @returns The user's password input (trimmed)
+ */
+export declare function promptPassword(message: string): Promise<string>;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/cli/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/cli/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;;;;;;;;;GAUG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,EACf,KAAK,UAAQ,GACZ,OAAO,CAAC,OAAO,CAAC,CAalB;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQlE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBrE"}

package/dist/cli/prompt.js

@@ -0,0 +1,96 @@
+/**
+ * CLI prompt utilities.
+ *
+ * Provides confirmation, text input, and password (hidden) prompts
+ * for interactive CLI commands. Uses Node.js built-in readline.
+ *
+ * - `confirm()` — y/N confirmation, respects --force flag
+ * - `promptInput()` — reads a line of text (echoed)
+ * - `promptPassword()` — reads a line with hidden input (no echo)
+ *
+ * @module cli/prompt
+ */
+import * as readline from 'node:readline/promises';
+import { Writable } from 'node:stream';
+import { stdin as input, stdout as output } from 'node:process';
+/**
+ * Ask a y/N confirmation question.
+ *
+ * Returns true if user types "y" or "Y", false for anything else.
+ * If force is true, skips the prompt entirely and returns true —
+ * this allows `--force` to bypass confirmations in scripts/automation.
+ *
+ * @param message - The question to display (e.g., "Delete organization?")
+ * @param force - If true, skip the prompt and return true (from argv.force)
+ * @returns true if confirmed, false otherwise
+ */
+export async function confirm(message, force = false) {
+    // --force flag bypasses all confirmation prompts
+    if (force)
+        return true;
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question(`${message} (y/N): `);
+        // Only explicit "y" or "Y" confirms — empty input or anything else is "no"
+        return answer.trim().toLowerCase() === 'y';
+    }
+    finally {
+        // Always close the readline interface to release stdin
+        rl.close();
+    }
+}
+/**
+ * Prompt the user for a line of text input.
+ *
+ * Displays the message and waits for the user to type a response.
+ * Returns the trimmed input string. Used for non-sensitive fields
+ * like email, name, etc.
+ *
+ * @param message - The prompt message to display (e.g., "Admin email: ")
+ * @returns The user's trimmed input
+ */
+export async function promptInput(message) {
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question(message);
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Prompt the user for a password (hidden input).
+ *
+ * Displays the message but suppresses character echo so the password
+ * is not visible on screen. Uses a muted Writable stream as the
+ * readline output to prevent echo while still allowing the prompt
+ * message to be displayed via direct stdout write.
+ *
+ * @param message - The prompt message to display (e.g., "Password: ")
+ * @returns The user's password input (trimmed)
+ */
+export async function promptPassword(message) {
+    // Write the prompt message directly to stdout before creating the
+    // muted readline — this ensures the user sees the prompt label
+    output.write(message);
+    // Create a Writable that discards all output — this suppresses
+    // character echo while readline is active
+    const muted = new Writable({
+        write(_chunk, _encoding, callback) {
+            callback();
+        },
+    });
+    const rl = readline.createInterface({ input, output: muted, terminal: true });
+    try {
+        // Empty string prompt since we already wrote the label above
+        const answer = await rl.question('');
+        // Move to the next line since echo was suppressed (no newline from Enter)
+        output.write('\n');
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=prompt.js.map

package/dist/cli/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/cli/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,QAAQ,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,KAAK,IAAI,KAAK,EAAE,MAAM,IAAI,MAAM,EAAE,MAAM,cAAc,CAAC;AAEhE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,OAAe,EACf,KAAK,GAAG,KAAK;IAEb,iDAAiD;IACjD,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC;IAEvB,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,GAAG,OAAO,UAAU,CAAC,CAAC;QACvD,2EAA2E;QAC3E,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,GAAG,CAAC;IAC7C,CAAC;YAAS,CAAC;QACT,uDAAuD;QACvD,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAe;IAC/C,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC1C,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAe;IAClD,kEAAkE;IAClE,+DAA+D;IAC/D,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAEtB,+DAA+D;IAC/D,0CAA0C;IAC1C,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC;QACzB,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ;YAC/B,QAAQ,EAAE,CAAC;QACb,CAAC;KACF,CAAC,CAAC;IAEH,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9E,IAAI,CAAC;QACH,6DAA6D;QAC7D,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACrC,0EAA0E;QAC1E,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/clients/cache.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Client cache — Redis-backed fast lookup layer.
+ *
+ * Provides get/set/invalidate operations for Client objects stored in Redis.
+ * Each client is cached under two keys:
+ *   - `client:cid:{clientId}` — for lookups by OIDC client_id (public identifier)
+ *   - `client:id:{id}`        — for lookups by internal UUID
+ *
+ * Both keys store the same JSON-serialized Client object with a 5-minute TTL.
+ * Date fields (createdAt, updatedAt) are serialized as ISO 8601 strings and
+ * deserialized back to Date objects on read.
+ *
+ * IMPORTANT: Secret data is NEVER cached. Secret lookups always hit the
+ * database directly to ensure revoked/expired secrets are immediately
+ * ineffective. Only client metadata is cached here.
+ *
+ * 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 { Client } from './types.js';
+/**
+ * Get a client from cache by OIDC client_id.
+ *
+ * Returns null on cache miss, invalid JSON, or Redis error.
+ * Callers should fall back to the database on null.
+ *
+ * @param clientId - OIDC client_id (public identifier)
+ * @returns Cached client or null
+ */
+export declare function getCachedClientByClientId(clientId: string): Promise<Client | null>;
+/**
+ * Get a client from cache by internal UUID.
+ *
+ * Returns null on cache miss, invalid JSON, or Redis error.
+ * Callers should fall back to the database on null.
+ *
+ * @param id - Client internal UUID
+ * @returns Cached client or null
+ */
+export declare function getCachedClientById(id: string): Promise<Client | null>;
+/**
+ * Store a client in cache under both client_id and internal ID keys.
+ *
+ * Both keys get the same TTL so they expire together.
+ * Date fields are serialized to ISO 8601 strings automatically
+ * by JSON.stringify().
+ *
+ * @param client - Client to cache
+ */
+export declare function cacheClient(client: Client): Promise<void>;
+/**
+ * Invalidate all cache entries for a client.
+ *
+ * Deletes both the client_id-keyed and ID-keyed cache entries.
+ * Should be called after any write operation (create, update,
+ * status change) to ensure stale data is not served.
+ *
+ * @param clientId - OIDC client_id (public identifier)
+ * @param id - Client internal UUID
+ */
+export declare function invalidateClientCache(clientId: string, id: string): Promise<void>;
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/clients/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAmBzC;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWxF;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW5E;AAMD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAc/D;AAMD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAavF"}

package/dist/clients/cache.js

@@ -0,0 +1,160 @@
+/**
+ * Client cache — Redis-backed fast lookup layer.
+ *
+ * Provides get/set/invalidate operations for Client objects stored in Redis.
+ * Each client is cached under two keys:
+ *   - `client:cid:{clientId}` — for lookups by OIDC client_id (public identifier)
+ *   - `client:id:{id}`        — for lookups by internal UUID
+ *
+ * Both keys store the same JSON-serialized Client object with a 5-minute TTL.
+ * Date fields (createdAt, updatedAt) are serialized as ISO 8601 strings and
+ * deserialized back to Date objects on read.
+ *
+ * IMPORTANT: Secret data is NEVER cached. Secret lookups always hit the
+ * database directly to ensure revoked/expired secrets are immediately
+ * ineffective. Only client metadata is cached here.
+ *
+ * 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) */
+const CACHE_TTL = 300;
+/** Key prefix for OIDC client_id lookups */
+const CLIENT_ID_PREFIX = 'client:cid:';
+/** Key prefix for internal UUID lookups */
+const ID_PREFIX = 'client:id:';
+// ---------------------------------------------------------------------------
+// Cache retrieval
+// ---------------------------------------------------------------------------
+/**
+ * Get a client from cache by OIDC client_id.
+ *
+ * Returns null on cache miss, invalid JSON, or Redis error.
+ * Callers should fall back to the database on null.
+ *
+ * @param clientId - OIDC client_id (public identifier)
+ * @returns Cached client or null
+ */
+export async function getCachedClientByClientId(clientId) {
+    try {
+        const redis = getRedis();
+        const data = await redis.get(`${CLIENT_ID_PREFIX}${clientId}`);
+        if (!data)
+            return null;
+        return deserializeClient(data);
+    }
+    catch {
+        // Graceful degradation — log and return null so caller falls back to DB
+        logger.warn({ event: 'client-cache-read-failed' }, 'Client cache read failed');
+        return null;
+    }
+}
+/**
+ * Get a client from cache by internal UUID.
+ *
+ * Returns null on cache miss, invalid JSON, or Redis error.
+ * Callers should fall back to the database on null.
+ *
+ * @param id - Client internal UUID
+ * @returns Cached client or null
+ */
+export async function getCachedClientById(id) {
+    try {
+        const redis = getRedis();
+        const data = await redis.get(`${ID_PREFIX}${id}`);
+        if (!data)
+            return null;
+        return deserializeClient(data);
+    }
+    catch {
+        // Graceful degradation — log and return null so caller falls back to DB
+        logger.warn({ event: 'client-cache-read-failed' }, 'Client cache read failed');
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Cache storage
+// ---------------------------------------------------------------------------
+/**
+ * Store a client in cache under both client_id and internal ID keys.
+ *
+ * Both keys get the same TTL so they expire together.
+ * Date fields are serialized to ISO 8601 strings automatically
+ * by JSON.stringify().
+ *
+ * @param client - Client to cache
+ */
+export async function cacheClient(client) {
+    await afterDatabaseCommit(async () => {
+        try {
+            const redis = getRedis();
+            const data = JSON.stringify(client);
+            // Store under both keys with the same TTL
+            await redis.set(`${CLIENT_ID_PREFIX}${client.clientId}`, data, 'EX', CACHE_TTL);
+            await redis.set(`${ID_PREFIX}${client.id}`, data, 'EX', CACHE_TTL);
+        }
+        catch {
+            // Graceful degradation — cache write failure is non-fatal
+            logger.warn({ event: 'client-cache-write-failed' }, 'Client cache write failed');
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Cache invalidation
+// ---------------------------------------------------------------------------
+/**
+ * Invalidate all cache entries for a client.
+ *
+ * Deletes both the client_id-keyed and ID-keyed cache entries.
+ * Should be called after any write operation (create, update,
+ * status change) to ensure stale data is not served.
+ *
+ * @param clientId - OIDC client_id (public identifier)
+ * @param id - Client internal UUID
+ */
+export async function invalidateClientCache(clientId, id) {
+    await afterDatabaseCommit(async () => {
+        try {
+            const redis = getRedis();
+            await redis.del(`${CLIENT_ID_PREFIX}${clientId}`, `${ID_PREFIX}${id}`);
+        }
+        catch {
+            // Graceful degradation — cache invalidation failure is non-fatal
+            logger.warn({ event: 'client-cache-invalidation-failed' }, 'Client cache invalidation failed');
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Serialization helpers
+// ---------------------------------------------------------------------------
+/**
+ * Deserialize a JSON string from Redis into a Client object.
+ *
+ * Converts ISO 8601 date strings back to Date objects for the
+ * createdAt and updatedAt fields, which JSON.stringify() serializes
+ * as strings rather than Date instances.
+ *
+ * @param data - JSON string from Redis
+ * @returns Client object with proper Date instances, or null if parse fails
+ */
+function deserializeClient(data) {
+    try {
+        const parsed = JSON.parse(data);
+        // Restore Date objects from ISO string serialization
+        parsed.createdAt = new Date(parsed.createdAt);
+        parsed.updatedAt = new Date(parsed.updatedAt);
+        return parsed;
+    }
+    catch {
+        logger.warn('Failed to parse cached client JSON');
+        return null;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/clients/cache.js.map

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