@portaidentity/server 1.7.0

package/dist/clients/secret-repository.js

@@ -0,0 +1,166 @@
+/**
+ * Secret repository — PostgreSQL data access for client_secrets table.
+ *
+ * Manages the storage of hashed client secrets. The plaintext secret
+ * is NEVER stored — only the Argon2id hash. The secret_hash field
+ * is only accessible here in the repository layer; the mapRowToClientSecret
+ * function intentionally excludes it from the domain model.
+ *
+ * Key operations:
+ * - Insert hashed secret
+ * - List secrets (metadata only, no hashes)
+ * - Find active secrets with hashes (for verification only)
+ * - Revoke secrets
+ * - Update last_used_at timestamp
+ * - Cleanup expired secrets
+ */
+import { getPool } from '../lib/database.js';
+import { mapRowToClientSecret } from './types.js';
+/**
+ * Insert a new client secret.
+ *
+ * Stores the Argon2id hash — never the plaintext.
+ *
+ * @param data - Secret data including the hash
+ * @returns The created secret metadata (without hash)
+ */
+export async function insertSecret(data) {
+    const pool = getPool();
+    const result = await pool.query(`INSERT INTO client_secrets (client_id, secret_hash, secret_sha256, label, expires_at)
+     VALUES ($1, $2, $3, $4, $5)
+     RETURNING *`, [data.clientId, data.secretHash, data.secretSha256, data.label, data.expiresAt]);
+    return mapRowToClientSecret(result.rows[0]);
+}
+// ===========================================================================
+// Find / List
+// ===========================================================================
+/**
+ * List all secrets for a client (metadata only, no hashes).
+ *
+ * @param clientId - Client internal UUID
+ * @returns Array of secret metadata
+ */
+export async function listSecretsByClient(clientId) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT * FROM client_secrets WHERE client_id = $1 ORDER BY created_at DESC`, [clientId]);
+    return result.rows.map(mapRowToClientSecret);
+}
+/**
+ * Find a specific secret by ID.
+ *
+ * @param id - Secret UUID
+ * @returns Secret metadata or null
+ */
+export async function findSecretById(id) {
+    const pool = getPool();
+    const result = await pool.query('SELECT * FROM client_secrets WHERE id = $1', [id]);
+    if (result.rows.length === 0)
+        return null;
+    return mapRowToClientSecret(result.rows[0]);
+}
+/**
+ * Get active secret hashes for verification.
+ *
+ * This is the ONLY function that returns secret_hash values.
+ * Used exclusively by the secret service for Argon2id verification.
+ * Returns secrets that are active AND not expired.
+ *
+ * @param clientId - Client internal UUID
+ * @returns Array of {id, hash} pairs for active secrets
+ */
+export async function getActiveSecretHashes(clientId) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT id, secret_hash FROM client_secrets
+     WHERE client_id = $1
+       AND status = 'active'
+       AND (expires_at IS NULL OR expires_at > NOW())
+     ORDER BY created_at DESC`, [clientId]);
+    return result.rows.map((row) => ({ id: row.id, hash: row.secret_hash }));
+}
+// ===========================================================================
+// Update
+// ===========================================================================
+/**
+ * Revoke a secret (set status = 'revoked').
+ *
+ * This is a permanent operation — revoked secrets cannot be reactivated.
+ *
+ * @param id - Secret UUID
+ * @returns Updated secret metadata, or null if not found
+ */
+export async function revokeSecret(id) {
+    const pool = getPool();
+    const result = await pool.query(`UPDATE client_secrets SET status = 'revoked' WHERE id = $1 RETURNING *`, [id]);
+    if (result.rows.length === 0)
+        return null;
+    return mapRowToClientSecret(result.rows[0]);
+}
+/**
+ * Update the last_used_at timestamp for a secret.
+ *
+ * Called after successful secret verification to track usage.
+ *
+ * @param id - Secret UUID
+ */
+export async function updateLastUsedAt(id) {
+    const pool = getPool();
+    await pool.query(`UPDATE client_secrets SET last_used_at = NOW() WHERE id = $1`, [id]);
+}
+// ===========================================================================
+// Cleanup
+// ===========================================================================
+/**
+ * Delete expired secrets that have been expired for more than the given days.
+ *
+ * Only deletes secrets where expires_at is in the past by at least `retentionDays`.
+ * This prevents premature deletion of recently-expired secrets that might
+ * still appear in audit logs.
+ *
+ * @param retentionDays - Number of days to retain expired secrets (default: 30)
+ * @returns Number of deleted secrets
+ */
+export async function cleanupExpiredSecrets(retentionDays = 30) {
+    const pool = getPool();
+    const result = await pool.query(`DELETE FROM client_secrets
+     WHERE status = 'revoked'
+       OR (expires_at IS NOT NULL AND expires_at < NOW() - INTERVAL '1 day' * $1)`, [retentionDays]);
+    return result.rowCount ?? 0;
+}
+/**
+ * Get the SHA-256 hash of the most recent active, non-expired secret.
+ *
+ * Used by findForOidc() to include the SHA-256 hash as client_secret
+ * in oidc-provider metadata. Returns null if no active secret has a
+ * SHA-256 hash (e.g., secrets created before migration 013).
+ *
+ * @param clientId - Client internal UUID
+ * @returns SHA-256 hex hash string, or null if none available
+ */
+export async function getLatestActiveSha256(clientId) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT secret_sha256 FROM client_secrets
+     WHERE client_id = $1
+       AND status = 'active'
+       AND secret_sha256 IS NOT NULL
+       AND (expires_at IS NULL OR expires_at > NOW())
+     ORDER BY created_at DESC
+     LIMIT 1`, [clientId]);
+    if (result.rows.length === 0)
+        return null;
+    return result.rows[0].secret_sha256;
+}
+/**
+ * Count active secrets for a client.
+ *
+ * @param clientId - Client internal UUID
+ * @returns Number of active (non-revoked, non-expired) secrets
+ */
+export async function countActiveSecrets(clientId) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT COUNT(*) as count FROM client_secrets
+     WHERE client_id = $1
+       AND status = 'active'
+       AND (expires_at IS NULL OR expires_at > NOW())`, [clientId]);
+    return parseInt(result.rows[0].count, 10);
+}
+//# sourceMappingURL=secret-repository.js.map

package/dist/clients/secret-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-repository.js","sourceRoot":"","sources":["../../src/clients/secret-repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAelD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAsB;IACvD,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B;;iBAEa,EACb,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAChF,CAAC;IAEF,OAAO,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAAgB;IACxD,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,4EAA4E,EAC5E,CAAC,QAAQ,CAAC,CACX,CAAC;IAEF,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,EAAU;IAC7C,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,4CAA4C,EAC5C,CAAC,EAAE,CAAC,CACL,CAAC;IAEF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,QAAgB;IAEhB,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B;;;;8BAI0B,EAC1B,CAAC,QAAQ,CAAC,CACX,CAAC;IAEF,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EAAU;IAC3C,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B,wEAAwE,EACxE,CAAC,EAAE,CAAC,CACL,CAAC;IAEF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,EAAU;IAC/C,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,IAAI,CAAC,KAAK,CACd,8DAA8D,EAC9D,CAAC,EAAE,CAAC,CACL,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,aAAa,GAAW,EAAE;IACpE,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B;;kFAE8E,EAC9E,CAAC,aAAa,CAAC,CAChB,CAAC;IAEF,OAAO,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,QAAgB;IAC1D,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B;;;;;;aAMS,EACT,CAAC,QAAQ,CAAC,CACX,CAAC;IAEF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,QAAgB;IACvD,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAC7B;;;sDAGkD,EAClD,CAAC,QAAQ,CAAC,CACX,CAAC;IAEF,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC5C,CAAC"}

package/dist/clients/secret-service.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Secret service — client secret lifecycle management.
+ *
+ * Handles the full lifecycle of OIDC client secrets:
+ *   - Generate and store new secrets (Argon2id hashed)
+ *   - Verify secrets during token endpoint authentication
+ *   - Revoke secrets permanently
+ *   - List secrets (metadata only, never hashes)
+ *   - Cleanup expired secrets
+ *
+ * Security model:
+ *   - Plaintext is returned ONCE at generation, never stored
+ *   - Only Argon2id hashes are persisted in the database
+ *   - Verification iterates ALL active secrets (no short-circuit)
+ *   - Failed verifications are logged as security events
+ *   - All operations use fire-and-forget audit logging
+ *
+ * This service is consumed by:
+ *   - The client service (initial secret on confidential client creation)
+ *   - The API routes (secret rotation, revocation)
+ *   - The OIDC token endpoint (secret verification via admin API)
+ */
+import type { ClientSecret, SecretWithPlaintext, CreateSecretInput } from './types.js';
+/**
+ * Generate a new client secret, hash it, and store it.
+ *
+ * Flow:
+ * 1. Generate cryptographically random plaintext (48 bytes, base64url)
+ * 2. Hash with Argon2id (OWASP-recommended parameters)
+ * 3. Insert hashed secret into database
+ * 4. Write audit log entry
+ * 5. Return SecretWithPlaintext (plaintext shown once, then discarded)
+ *
+ * @param clientDbId - Client internal UUID (FK to clients.id)
+ * @param input - Optional label and expiration
+ * @param actorId - UUID of the user performing the action
+ * @returns Secret metadata with plaintext (shown once)
+ */
+export declare function generateAndStore(clientDbId: string, input?: CreateSecretInput, actorId?: string): Promise<SecretWithPlaintext>;
+/**
+ * Verify a plaintext secret against all active secrets for a client.
+ *
+ * Called during OIDC token endpoint authentication. Iterates through
+ * ALL active (non-revoked, non-expired) secrets and checks each one.
+ *
+ * Security notes:
+ * - Iterates all secrets to prevent timing-based enumeration
+ * - Updates last_used_at on successful match
+ * - Logs failed verification as a security event
+ * - Returns false on any error (fail closed)
+ *
+ * @param clientDbId - Client internal UUID
+ * @param plaintext - The secret to verify
+ * @returns true if the secret matches any active secret
+ */
+export declare function verify(clientDbId: string, plaintext: string): Promise<boolean>;
+/**
+ * Revoke a client secret permanently.
+ *
+ * Revocation is irreversible — once revoked, a secret cannot be
+ * reactivated. The revoked secret remains in the database for
+ * audit trail purposes until cleanup removes it.
+ *
+ * @param secretId - Secret UUID
+ * @param actorId - UUID of the user performing the action
+ * @throws ClientNotFoundError if secret not found
+ * @throws ClientValidationError if secret already revoked
+ */
+export declare function revoke(secretId: string, actorId?: string): Promise<void>;
+/**
+ * List all secrets for a client (metadata only, never hashes).
+ *
+ * @param clientDbId - Client internal UUID
+ * @returns Array of secret metadata
+ */
+export declare function listByClient(clientDbId: string): Promise<ClientSecret[]>;
+/**
+ * Delete expired and revoked secrets older than the retention period.
+ *
+ * This is a maintenance operation that should be run periodically
+ * (e.g., via cron) to clean up old secrets that are no longer needed.
+ *
+ * @param retentionDays - Days to retain expired secrets (default: 30)
+ * @returns Number of deleted secrets
+ */
+export declare function cleanupExpired(retentionDays?: number): Promise<number>;
+//# sourceMappingURL=secret-service.d.ts.map

package/dist/clients/secret-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-service.d.ts","sourceRoot":"","sources":["../../src/clients/secret-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAmBvF;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,iBAAsB,EAC7B,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,mBAAmB,CAAC,CAyC9B;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,MAAM,CAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAyClB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,MAAM,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAMD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAE9E;AAMD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE5E"}

package/dist/clients/secret-service.js

@@ -0,0 +1,204 @@
+/**
+ * Secret service — client secret lifecycle management.
+ *
+ * Handles the full lifecycle of OIDC client secrets:
+ *   - Generate and store new secrets (Argon2id hashed)
+ *   - Verify secrets during token endpoint authentication
+ *   - Revoke secrets permanently
+ *   - List secrets (metadata only, never hashes)
+ *   - Cleanup expired secrets
+ *
+ * Security model:
+ *   - Plaintext is returned ONCE at generation, never stored
+ *   - Only Argon2id hashes are persisted in the database
+ *   - Verification iterates ALL active secrets (no short-circuit)
+ *   - Failed verifications are logged as security events
+ *   - All operations use fire-and-forget audit logging
+ *
+ * This service is consumed by:
+ *   - The client service (initial secret on confidential client creation)
+ *   - The API routes (secret rotation, revocation)
+ *   - The OIDC token endpoint (secret verification via admin API)
+ */
+import { insertSecret, listSecretsByClient, findSecretById, getActiveSecretHashes, revokeSecret as repoRevokeSecret, updateLastUsedAt, cleanupExpiredSecrets, } from './secret-repository.js';
+import { generateSecret, hashSecret, sha256Secret, verifySecretHash } from './crypto.js';
+import { writeAuditLog } from '../lib/audit-log.js';
+import { logger } from '../lib/logger.js';
+import { ClientNotFoundError, ClientValidationError } from './errors.js';
+// ===========================================================================
+// Secret generation
+// ===========================================================================
+/**
+ * Generate a new client secret, hash it, and store it.
+ *
+ * Flow:
+ * 1. Generate cryptographically random plaintext (48 bytes, base64url)
+ * 2. Hash with Argon2id (OWASP-recommended parameters)
+ * 3. Insert hashed secret into database
+ * 4. Write audit log entry
+ * 5. Return SecretWithPlaintext (plaintext shown once, then discarded)
+ *
+ * @param clientDbId - Client internal UUID (FK to clients.id)
+ * @param input - Optional label and expiration
+ * @param actorId - UUID of the user performing the action
+ * @returns Secret metadata with plaintext (shown once)
+ */
+export async function generateAndStore(clientDbId, input = {}, actorId) {
+    // Generate plaintext secret
+    const plaintext = generateSecret();
+    // Hash with Argon2id — only the hash is stored
+    const secretHash = await hashSecret(plaintext);
+    // Compute SHA-256 for oidc-provider client authentication
+    const secretSha256 = sha256Secret(plaintext);
+    // Insert into database
+    const secret = await insertSecret({
+        clientId: clientDbId,
+        secretHash,
+        secretSha256,
+        label: input.label ?? null,
+        expiresAt: input.expiresAt ?? null,
+    });
+    // Audit log (fire-and-forget)
+    await writeAuditLog({
+        eventType: 'client.secret.generated',
+        eventCategory: 'admin',
+        actorId,
+        metadata: {
+            clientId: clientDbId,
+            secretId: secret.id,
+            label: secret.label,
+            expiresAt: secret.expiresAt?.toISOString() ?? null,
+        },
+    });
+    // Return with plaintext — this is the ONLY time it's available
+    return {
+        id: secret.id,
+        clientId: secret.clientId,
+        label: secret.label,
+        plaintext,
+        expiresAt: secret.expiresAt,
+        createdAt: secret.createdAt,
+    };
+}
+// ===========================================================================
+// Secret verification
+// ===========================================================================
+/**
+ * Verify a plaintext secret against all active secrets for a client.
+ *
+ * Called during OIDC token endpoint authentication. Iterates through
+ * ALL active (non-revoked, non-expired) secrets and checks each one.
+ *
+ * Security notes:
+ * - Iterates all secrets to prevent timing-based enumeration
+ * - Updates last_used_at on successful match
+ * - Logs failed verification as a security event
+ * - Returns false on any error (fail closed)
+ *
+ * @param clientDbId - Client internal UUID
+ * @param plaintext - The secret to verify
+ * @returns true if the secret matches any active secret
+ */
+export async function verify(clientDbId, plaintext) {
+    try {
+        // Load all active, non-expired secret hashes
+        const activeSecrets = await getActiveSecretHashes(clientDbId);
+        if (activeSecrets.length === 0) {
+            return false;
+        }
+        // Try each active secret — Argon2id verify is async and non-blocking
+        for (const secret of activeSecrets) {
+            const matches = await verifySecretHash(secret.hash, plaintext);
+            if (matches) {
+                // Update last_used_at timestamp (fire-and-forget)
+                await updateLastUsedAt(secret.id);
+                // Audit log: successful verification
+                await writeAuditLog({
+                    eventType: 'client.secret.verified',
+                    eventCategory: 'authentication',
+                    metadata: { clientId: clientDbId, secretId: secret.id },
+                });
+                return true;
+            }
+        }
+        // No match found — log as security event
+        await writeAuditLog({
+            eventType: 'client.secret.failed',
+            eventCategory: 'security',
+            metadata: { clientId: clientDbId, activeSecretCount: activeSecrets.length },
+        });
+        return false;
+    }
+    catch (err) {
+        // Fail closed — any error during verification results in rejection
+        logger.error({ err, clientDbId }, 'Error during secret verification');
+        return false;
+    }
+}
+// ===========================================================================
+// Secret revocation
+// ===========================================================================
+/**
+ * Revoke a client secret permanently.
+ *
+ * Revocation is irreversible — once revoked, a secret cannot be
+ * reactivated. The revoked secret remains in the database for
+ * audit trail purposes until cleanup removes it.
+ *
+ * @param secretId - Secret UUID
+ * @param actorId - UUID of the user performing the action
+ * @throws ClientNotFoundError if secret not found
+ * @throws ClientValidationError if secret already revoked
+ */
+export async function revoke(secretId, actorId) {
+    // Validate secret exists
+    const secret = await findSecretById(secretId);
+    if (!secret) {
+        throw new ClientNotFoundError(secretId);
+    }
+    // Validate secret is not already revoked
+    if (secret.status === 'revoked') {
+        throw new ClientValidationError('Secret is already revoked');
+    }
+    // Revoke in database
+    await repoRevokeSecret(secretId);
+    // Audit log (fire-and-forget)
+    await writeAuditLog({
+        eventType: 'client.secret.revoked',
+        eventCategory: 'admin',
+        actorId,
+        metadata: {
+            clientId: secret.clientId,
+            secretId: secret.id,
+            label: secret.label,
+        },
+    });
+}
+// ===========================================================================
+// Secret listing
+// ===========================================================================
+/**
+ * List all secrets for a client (metadata only, never hashes).
+ *
+ * @param clientDbId - Client internal UUID
+ * @returns Array of secret metadata
+ */
+export async function listByClient(clientDbId) {
+    return listSecretsByClient(clientDbId);
+}
+// ===========================================================================
+// Secret cleanup
+// ===========================================================================
+/**
+ * Delete expired and revoked secrets older than the retention period.
+ *
+ * This is a maintenance operation that should be run periodically
+ * (e.g., via cron) to clean up old secrets that are no longer needed.
+ *
+ * @param retentionDays - Days to retain expired secrets (default: 30)
+ * @returns Number of deleted secrets
+ */
+export async function cleanupExpired(retentionDays) {
+    return cleanupExpiredSecrets(retentionDays);
+}
+//# sourceMappingURL=secret-service.js.map

package/dist/clients/secret-service.js.map

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

package/dist/clients/service.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Client service — business logic orchestrator.
+ *
+ * Composes the repository, cache, validators, crypto utilities, and audit log
+ * to provide the complete client management API. All write operations follow:
+ *   1. Validate inputs (org, app, URIs)
+ *   2. Perform DB operation (via repository)
+ *   3. Invalidate + re-cache (via cache)
+ *   4. Write audit log (fire-and-forget)
+ *
+ * Read operations check cache first, fall back to DB on miss.
+ *
+ * Status lifecycle:
+ *   - activate:   inactive → active
+ *   - deactivate: active → inactive
+ *   - revoke:     active|inactive → revoked (permanent, cannot be undone)
+ *
+ * The findForOidc() function maps internal Client objects to oidc-provider
+ * metadata format, used by the adapter factory during OIDC operations.
+ */
+import type { Client, ClientWithSecret, CreateClientInput, UpdateClientInput, ListClientsOptions, PaginatedResult } from './types.js';
+import type { ListClientsCursorOptions } from './repository.js';
+import type { CursorPaginatedResult } from '../lib/cursor.js';
+/**
+ * Create a new OIDC client.
+ *
+ * Flow:
+ * 1. Validate organization exists and is active
+ * 2. Validate application exists and is active
+ * 3. Validate redirect URIs
+ * 4. Apply defaults (grant types, response types, scope, auth method, PKCE)
+ * 5. Generate cryptographically random client_id
+ * 6. Insert client row
+ * 7. Cache the client
+ * 8. Write audit log
+ * 9. Return ClientWithSecret (secret is null for public clients;
+ *    for confidential clients, the caller must generate the initial
+ *    secret separately via the secret service)
+ *
+ * @param input - Client creation data
+ * @param actorId - UUID of the user performing the action (for audit)
+ * @returns Created client wrapped in ClientWithSecret (secret always null here)
+ * @throws ClientValidationError if org/app invalid or URIs fail validation
+ */
+export declare function createClient(input: CreateClientInput, actorId?: string): Promise<ClientWithSecret>;
+/**
+ * Find a client by internal UUID.
+ * Checks Redis cache first, falls back to database on miss.
+ *
+ * @param id - Client internal UUID
+ * @returns Client or null if not found
+ */
+export declare function getClientById(id: string): Promise<Client | null>;
+/**
+ * Find a client by OIDC client_id.
+ * Checks Redis cache first, falls back to database on miss.
+ *
+ * @param clientId - OIDC client_id (public identifier)
+ * @returns Client or null if not found
+ */
+export declare function getClientByClientId(clientId: string): Promise<Client | null>;
+/**
+ * Update a client's configurable fields.
+ *
+ * Validates redirect URIs if they are being changed.
+ *
+ * @param id - Client internal UUID
+ * @param input - Fields to update
+ * @param actorId - UUID of the user performing the action
+ * @returns Updated client
+ * @throws ClientNotFoundError if client not found
+ * @throws ClientValidationError if redirect URIs are invalid
+ */
+export declare function updateClient(id: string, input: UpdateClientInput, actorId?: string): Promise<Client>;
+/**
+ * List clients by organization with pagination.
+ *
+ * @param organizationId - Organization UUID
+ * @param options - Pagination and sort options
+ * @returns Paginated result
+ */
+export declare function listClientsByOrganization(organizationId: string, options: Omit<ListClientsOptions, 'organizationId'>): Promise<PaginatedResult<Client>>;
+/**
+ * List clients by application with pagination.
+ *
+ * @param applicationId - Application UUID
+ * @param options - Pagination and sort options
+ * @returns Paginated result
+ */
+export declare function listClientsByApplication(applicationId: string, options: Omit<ListClientsOptions, 'applicationId'>): Promise<PaginatedResult<Client>>;
+/**
+ * List clients with cursor-based keyset pagination.
+ * Supports all existing filters (org, app, status, search).
+ *
+ * @param options - Cursor, limit, filter, and sort options
+ * @returns Cursor-paginated result with nextCursor/hasMore
+ */
+export declare function listClientsCursor(options: ListClientsCursorOptions): Promise<CursorPaginatedResult<Client>>;
+/**
+ * Deactivate a client (active → inactive).
+ *
+ * @param id - Client internal UUID
+ * @param actorId - UUID of the user performing the action
+ * @throws ClientNotFoundError if not found
+ * @throws ClientValidationError if not currently active
+ */
+export declare function deactivateClient(id: string, actorId?: string): Promise<void>;
+/**
+ * Activate a client (inactive → active).
+ *
+ * @param id - Client internal UUID
+ * @param actorId - UUID of the user performing the action
+ * @throws ClientNotFoundError if not found
+ * @throws ClientValidationError if not currently inactive
+ */
+export declare function activateClient(id: string, actorId?: string): Promise<void>;
+/**
+ * Revoke a client (active or inactive → revoked).
+ *
+ * Revocation is permanent — revoked clients cannot be reactivated.
+ * This effectively disables the client for all OIDC operations.
+ *
+ * @param id - Client internal UUID
+ * @param actorId - UUID of the user performing the action
+ * @throws ClientNotFoundError if not found
+ * @throws ClientValidationError if already revoked
+ */
+export declare function revokeClient(id: string, actorId?: string): Promise<void>;
+/**
+ * Find a client by OIDC client_id and return oidc-provider metadata format.
+ *
+ * This function is the bridge between Porta's internal client model and
+ * the metadata shape expected by node-oidc-provider. It's called by the
+ * adapter factory during OIDC flows (authorization, token exchange, etc.).
+ *
+ * Returns undefined (not null) for compatibility with oidc-provider which
+ * expects undefined for "client not found".
+ *
+ * @param clientId - OIDC client_id
+ * @returns OIDC client metadata object, or undefined if not found/inactive
+ */
+export declare function findForOidc(clientId: string): Promise<Record<string, unknown> | undefined>;
+/**
+ * Verify a client secret for OIDC authentication.
+ *
+ * Convenience wrapper around secret-service.verify() that resolves the
+ * internal DB id from the OIDC client_id and performs guard checks:
+ * - Client must exist and be active
+ * - Client must be confidential (public clients have no secrets)
+ *
+ * Used during token endpoint authentication via the admin API.
+ *
+ * @param clientId - The OIDC client_id (external identifier)
+ * @param plaintext - The presented secret to verify
+ * @returns true if secret matches any active hash, false otherwise
+ */
+export declare function verifyClientSecret(clientId: string, plaintext: string): Promise<boolean>;
+//# sourceMappingURL=service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/clients/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,gBAAgB,EAChB,iBAAiB,EAEjB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EAChB,MAAM,YAAY,CAAC;AAUpB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AA4E9D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,EACxB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,CAAC,CA2F3B;AAOD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWtE;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWlF;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,iBAAiB,EACxB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CA6EjB;AAOD;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,IAAI,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,GAClD,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAElC;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,IAAI,CAAC,kBAAkB,EAAE,eAAe,CAAC,GACjD,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAElC;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAExC;AAgBD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAqBf;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAoD9C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAWlB"}