@portaidentity/server 1.7.0

package/dist/custom-claims/validators.js

@@ -0,0 +1,136 @@
+/**
+ * Custom claim validators.
+ *
+ * Provides validation logic for claim names and values:
+ *   - Reserved claim name check (OIDC standard + Porta internal names)
+ *   - Claim name format validation (lowercase alphanumeric + underscores)
+ *   - Value type validation against claim definition type
+ *
+ * These validators are used by the service layer before any database
+ * operations to provide clear error messages.
+ */
+// ---------------------------------------------------------------------------
+// Reserved claim names
+// ---------------------------------------------------------------------------
+/**
+ * OIDC standard and Porta reserved claim names.
+ *
+ * Custom claims cannot use any of these names to prevent conflicts with
+ * standard OIDC claims (RFC 7519, OpenID Connect Core 1.0 §5.1) and
+ * Porta's own internal claims (roles, permissions, org context).
+ */
+export const RESERVED_CLAIM_NAMES = new Set([
+    // OIDC Core / JWT standard claims (RFC 7519)
+    'sub', 'iss', 'aud', 'exp', 'iat', 'nbf', 'jti', 'nonce', 'at_hash', 'c_hash',
+    // OpenID Connect Standard Claims (§5.1)
+    'name', 'given_name', 'family_name', 'middle_name', 'nickname',
+    'preferred_username', 'profile', 'picture', 'website',
+    'email', 'email_verified', 'gender', 'birthdate', 'zoneinfo', 'locale',
+    'phone_number', 'phone_number_verified', 'address', 'updated_at',
+    // Porta internal claims (used by RBAC and tenant context)
+    'roles', 'permissions', 'org_id', 'org_slug',
+]);
+/**
+ * Check if a claim name is reserved (cannot be used as a custom claim).
+ *
+ * @param name - Claim name to check
+ * @returns true if the name is reserved
+ */
+export function isReservedClaimName(name) {
+    return RESERVED_CLAIM_NAMES.has(name);
+}
+// ---------------------------------------------------------------------------
+// Claim name validation
+// ---------------------------------------------------------------------------
+/**
+ * Regex for valid claim names: lowercase letters, digits, and underscores.
+ * Must start with a letter, 1-100 characters.
+ * Examples: "department", "cost_center", "team_id"
+ */
+const CLAIM_NAME_REGEX = /^[a-z][a-z0-9_]{0,99}$/;
+/**
+ * Validate a custom claim name.
+ *
+ * Rules:
+ * 1. Must not be empty
+ * 2. Must match format: lowercase alphanumeric + underscores, starting with a letter
+ * 3. Must be 1-100 characters
+ * 4. Must not be a reserved OIDC/Porta claim name
+ *
+ * @param name - Claim name to validate
+ * @returns Object with valid=true or valid=false with reason
+ */
+export function validateClaimName(name) {
+    // Check for empty string
+    if (!name || name.length === 0) {
+        return { valid: false, reason: 'Claim name must not be empty' };
+    }
+    // Check length constraint (max 100 chars)
+    if (name.length > 100) {
+        return { valid: false, reason: 'Claim name must not exceed 100 characters' };
+    }
+    // Check format: lowercase alphanumeric + underscores, starting with a letter
+    if (!CLAIM_NAME_REGEX.test(name)) {
+        return {
+            valid: false,
+            reason: 'Claim name must start with a lowercase letter and contain only lowercase letters, digits, and underscores',
+        };
+    }
+    // Check against reserved names
+    if (isReservedClaimName(name)) {
+        return { valid: false, reason: `Claim name '${name}' is reserved` };
+    }
+    return { valid: true };
+}
+// ---------------------------------------------------------------------------
+// Claim value type validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate that a claim value matches the expected type from the definition.
+ *
+ * Type rules:
+ * - string: typeof value === 'string'
+ * - number: typeof value === 'number' && isFinite(value) (NaN and Infinity rejected)
+ * - boolean: typeof value === 'boolean'
+ * - json: value !== null && typeof value === 'object' (arrays and objects allowed)
+ *
+ * @param claimType - Expected type from the claim definition
+ * @param value - The value to validate
+ * @returns Object with valid=true or valid=false with reason
+ */
+export function validateClaimValue(claimType, value) {
+    // Null and undefined are never valid claim values
+    if (value === null || value === undefined) {
+        return { valid: false, reason: `Expected ${claimType} value, got null/undefined` };
+    }
+    switch (claimType) {
+        case 'string':
+            if (typeof value !== 'string') {
+                return { valid: false, reason: `Expected string, got ${typeof value}` };
+            }
+            return { valid: true };
+        case 'number':
+            if (typeof value !== 'number') {
+                return { valid: false, reason: `Expected number, got ${typeof value}` };
+            }
+            // Reject NaN and Infinity — these are not valid JSONB values
+            if (!Number.isFinite(value)) {
+                return { valid: false, reason: 'Number must be finite (NaN and Infinity are not allowed)' };
+            }
+            return { valid: true };
+        case 'boolean':
+            if (typeof value !== 'boolean') {
+                return { valid: false, reason: `Expected boolean, got ${typeof value}` };
+            }
+            return { valid: true };
+        case 'json':
+            // JSON type expects objects or arrays (not primitives)
+            if (typeof value !== 'object') {
+                return { valid: false, reason: `Expected JSON object/array, got ${typeof value}` };
+            }
+            return { valid: true };
+        default:
+            return { valid: false, reason: `Unknown claim type: ${claimType}` };
+    }
+}
+//# sourceMappingURL=validators.js.map

package/dist/custom-claims/validators.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Application entry point.
+ *
+ * Orchestrates startup in the correct order:
+ * 1. Connect to PostgreSQL and Redis
+ * 2. Initialize i18n and template engine for auth workflows
+ * 3. Load/generate signing keys from the database
+ * 4. Load OIDC TTL configuration from system_config table
+ * 5. Create the OIDC provider with all configuration wired together
+ * 6. Create and start the Koa HTTP server with the provider mounted
+ * 7. Register graceful shutdown handlers (SIGTERM/SIGINT)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/index.js

@@ -0,0 +1,91 @@
+/**
+ * Application entry point.
+ *
+ * Orchestrates startup in the correct order:
+ * 1. Connect to PostgreSQL and Redis
+ * 2. Initialize i18n and template engine for auth workflows
+ * 3. Load/generate signing keys from the database
+ * 4. Load OIDC TTL configuration from system_config table
+ * 5. Create the OIDC provider with all configuration wired together
+ * 6. Create and start the Koa HTTP server with the provider mounted
+ * 7. Register graceful shutdown handlers (SIGTERM/SIGINT)
+ */
+import { createApp } from './server.js';
+import { config } from './config/index.js';
+import { logger } from './lib/logger.js';
+import { connectDatabase, disconnectDatabase } from './lib/database.js';
+import { connectRedis, disconnectRedis } from './lib/redis.js';
+import { ensureSigningKeys } from './lib/signing-keys.js';
+import { loadOidcTtlConfig } from './lib/system-config.js';
+import { createOidcProvider } from './oidc/provider.js';
+import { initI18n, registerHandlebarsI18nHelper } from './auth/i18n.js';
+import { initTemplateEngine } from './auth/template-engine.js';
+import { startAccountRecoveryWorker, stopAccountRecoveryWorker } from './auth/recovery-service.js';
+import { initializeDummyPasswordHash } from './users/password.js';
+import { attachTransportDecisionHandler } from './security/transport-decision.js';
+async function main() {
+    // Step 1: Connect to infrastructure services
+    await connectDatabase();
+    await connectRedis();
+    // Step 2: Initialize i18n and template engine for auth workflow pages.
+    // Must happen before any route handlers are invoked.
+    await initI18n();
+    registerHandlebarsI18nHelper();
+    await initTemplateEngine();
+    // Build the process-owned Argon2id fallback before accepting authentication requests. Startup
+    // fails closed if the production-strength hash cannot be initialized.
+    await initializeDummyPasswordHash();
+    // Step 3: Load or auto-generate signing keys from the database.
+    // If no active keys exist (e.g., fresh database), a new ES256 key pair
+    // is generated and inserted automatically.
+    const jwks = await ensureSigningKeys();
+    // Step 4: Load OIDC TTL configuration from the system_config table.
+    // Falls back to hardcoded defaults if config keys are missing.
+    const ttl = await loadOidcTtlConfig();
+    // Step 5: Create the OIDC provider with all config wired together
+    const oidcProvider = await createOidcProvider({ jwks, ttl });
+    // Step 6: Create and start the HTTP server with OIDC provider mounted
+    const app = createApp(oidcProvider);
+    const server = app.listen(config.port, config.host, () => {
+        startAccountRecoveryWorker(oidcProvider);
+        logger.info({ port: config.port, host: config.host }, 'Server started');
+    });
+    attachTransportDecisionHandler(server);
+    // Step 7: Graceful shutdown — close connections in reverse order
+    let shutdownStarted = false;
+    const shutdown = async (signal) => {
+        if (shutdownStarted)
+            return;
+        shutdownStarted = true;
+        logger.info({ signal }, 'Shutdown signal received');
+        const forcedExit = setTimeout(() => {
+            logger.error('Forced shutdown after timeout');
+            process.exit(1);
+        }, 60_000);
+        forcedExit.unref();
+        try {
+            await new Promise((resolve, reject) => {
+                server.close((error) => (error ? reject(error) : resolve()));
+            });
+            const workerSettled = await stopAccountRecoveryWorker();
+            if (!workerSettled)
+                throw new Error('Recovery worker did not settle before shutdown');
+            await disconnectDatabase();
+            await disconnectRedis();
+            clearTimeout(forcedExit);
+            logger.info('Server shut down gracefully');
+            process.exit(0);
+        }
+        catch {
+            logger.error({ event: 'graceful_shutdown_failed' }, 'Graceful shutdown failed');
+            process.exit(1);
+        }
+    };
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+}
+main().catch((err) => {
+    logger.fatal(err, 'Failed to start server');
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/lib/admin-permissions.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Admin permission constants and role definitions for granular admin access control.
+ *
+ * Replaces the single porta-admin role with a permission-based model where
+ * each admin endpoint requires specific permissions. Five predefined admin
+ * roles group permissions by responsibility area.
+ *
+ * @module admin-permissions
+ * @see 03-granular-admin-roles.md
+ */
+/**
+ * Admin permission slugs following the `module:resource:action` pattern.
+ * Used by admin-auth middleware's `requirePermission()` factory
+ * and route handlers for endpoint-level authorization.
+ *
+ * The `admin` module prefix satisfies the RBAC permission slug validation
+ * requirement of at least 3 colon-separated segments.
+ *
+ * Permissions are seeded into the admin application during `porta init`
+ * and resolved at runtime from the user's assigned admin roles.
+ */
+export declare const ADMIN_PERMISSIONS: {
+    readonly ORG_CREATE: 'admin:org:create';
+    readonly ORG_READ: 'admin:org:read';
+    readonly ORG_UPDATE: 'admin:org:update';
+    readonly ORG_SUSPEND: 'admin:org:suspend';
+    readonly ORG_ARCHIVE: 'admin:org:archive';
+    readonly APP_CREATE: 'admin:app:create';
+    readonly APP_READ: 'admin:app:read';
+    readonly APP_UPDATE: 'admin:app:update';
+    readonly APP_ARCHIVE: 'admin:app:archive';
+    readonly CLIENT_CREATE: 'admin:client:create';
+    readonly CLIENT_READ: 'admin:client:read';
+    readonly CLIENT_UPDATE: 'admin:client:update';
+    readonly CLIENT_REVOKE: 'admin:client:revoke';
+    readonly USER_CREATE: 'admin:user:create';
+    readonly USER_READ: 'admin:user:read';
+    readonly USER_UPDATE: 'admin:user:update';
+    readonly USER_SUSPEND: 'admin:user:suspend';
+    readonly USER_ARCHIVE: 'admin:user:archive';
+    readonly USER_INVITE: 'admin:user:invite';
+    readonly USER_2FA: 'admin:user:2fa';
+    readonly ROLE_CREATE: 'admin:role:create';
+    readonly ROLE_READ: 'admin:role:read';
+    readonly ROLE_UPDATE: 'admin:role:update';
+    readonly ROLE_ARCHIVE: 'admin:role:archive';
+    readonly ROLE_ASSIGN: 'admin:role:assign';
+    readonly PERMISSION_CREATE: 'admin:permission:create';
+    readonly PERMISSION_READ: 'admin:permission:read';
+    readonly PERMISSION_ARCHIVE: 'admin:permission:archive';
+    readonly CLAIM_CREATE: 'admin:claim:create';
+    readonly CLAIM_READ: 'admin:claim:read';
+    readonly CLAIM_UPDATE: 'admin:claim:update';
+    readonly CLAIM_ARCHIVE: 'admin:claim:archive';
+    readonly CONFIG_READ: 'admin:config:read';
+    readonly CONFIG_UPDATE: 'admin:config:update';
+    readonly KEY_READ: 'admin:key:read';
+    readonly KEY_GENERATE: 'admin:key:generate';
+    readonly KEY_ROTATE: 'admin:key:rotate';
+    readonly AUDIT_READ: 'admin:audit:read';
+    readonly SESSION_READ: 'admin:session:read';
+    readonly SESSION_REVOKE: 'admin:session:revoke';
+    readonly STATS_READ: 'admin:stats:read';
+    readonly EXPORT_READ: 'admin:export:read';
+    readonly IMPORT_WRITE: 'admin:import:write';
+};
+/** Union type of all valid admin permission slug values */
+export type AdminPermission = (typeof ADMIN_PERMISSIONS)[keyof typeof ADMIN_PERMISSIONS];
+/** Array of all admin permission slug values (useful for iteration/validation) */
+export declare const ALL_ADMIN_PERMISSIONS: readonly AdminPermission[];
+/**
+ * Shape of a predefined admin role definition.
+ * Used during `porta init` to seed RBAC for the admin application.
+ */
+export interface AdminRoleDefinition {
+    /** Unique role slug (e.g., 'porta-super-admin') */
+    readonly slug: string;
+    /** Human-readable role name */
+    readonly name: string;
+    /** Brief description of the role's purpose */
+    readonly description: string;
+    /** Permission slugs granted to this role */
+    readonly permissions: readonly string[];
+}
+/**
+ * Predefined admin role definitions with their permission sets.
+ *
+ * These roles are seeded during `porta init` into the admin application's
+ * RBAC system. Each role groups permissions by administrative responsibility:
+ *
+ * - **Super Admin** — Full access to all admin operations (all permissions)
+ * - **Org Admin** — Organization lifecycle management and statistics
+ * - **User Admin** — User management, invitations, role assignment, sessions
+ * - **App Admin** — Application/client/RBAC/claims management
+ * - **Auditor** — Read-only access across all resources plus audit log
+ */
+export declare const ADMIN_ROLE_DEFINITIONS: Record<string, AdminRoleDefinition>;
+/** All admin role definition values as an array (for iteration) */
+export declare const ALL_ADMIN_ROLES: readonly AdminRoleDefinition[];
+/**
+ * Legacy admin role slug from pre-granular auth.
+ * Users with this role are automatically treated as super-admins
+ * for backward compatibility during the transition period.
+ */
+export declare const LEGACY_ADMIN_ROLE = "porta-admin";
+/**
+ * Check if a role slug represents a super-admin role.
+ * Recognizes both the new `porta-super-admin` and legacy `porta-admin` slugs.
+ *
+ * @param roleSlug - The role slug to check
+ * @returns true if the role grants super-admin level access
+ */
+export declare function isSuperAdminRole(roleSlug: string): boolean;
+/**
+ * Resolve the effective admin role slug, mapping legacy roles to their
+ * modern equivalents.
+ *
+ * @param roleSlug - The role slug to resolve
+ * @returns The effective role slug (legacy porta-admin → porta-super-admin)
+ */
+export declare function resolveAdminRoleSlug(roleSlug: string): string;
+/**
+ * Get the permission set for an admin role slug.
+ * Returns all permissions for super-admin roles (including legacy).
+ * Returns an empty array for unrecognized role slugs.
+ *
+ * @param roleSlug - The admin role slug to look up
+ * @returns Array of permission slugs granted by this role
+ */
+export declare function getPermissionsForAdminRole(roleSlug: string): readonly string[];
+/**
+ * Resolve the union of all permissions from multiple admin role slugs.
+ * Deduplicates the result. Handles legacy role mapping automatically.
+ *
+ * @param roleSlugs - Array of admin role slugs assigned to a user
+ * @returns Deduplicated array of all permission slugs
+ */
+export declare function resolvePermissionsFromRoles(roleSlugs: readonly string[]): string[];
+/**
+ * Check if a set of permissions includes all required permissions.
+ *
+ * @param userPermissions - The user's resolved permission set
+ * @param requiredPermissions - The permissions required for an operation
+ * @returns true if all required permissions are present
+ */
+export declare function hasPermissions(userPermissions: readonly string[], requiredPermissions: readonly string[]): boolean;
+//# sourceMappingURL=admin-permissions.d.ts.map

package/dist/lib/admin-permissions.d.ts.map

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