@portaidentity/server 1.7.0

package/migrations/003_applications.sql

@@ -0,0 +1,50 @@
+-- Up Migration
+
+-- Applications represent SaaS products managed by Porta
+CREATE TABLE applications (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name            VARCHAR(255) NOT NULL,               -- e.g., "BusinessSuite"
+    slug            VARCHAR(100) NOT NULL UNIQUE,         -- e.g., "business-suite"
+    description     TEXT,
+    status          VARCHAR(20) NOT NULL DEFAULT 'active'
+                    CHECK (status IN ('active', 'inactive', 'archived')),
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TRIGGER set_updated_at
+    BEFORE UPDATE ON applications
+    FOR EACH ROW
+    EXECUTE FUNCTION trigger_set_updated_at();
+
+COMMENT ON TABLE applications IS 'SaaS application definitions — each org uses the same app but with their own users/roles';
+
+-- Application modules are logical groupings (e.g., CRM, Invoicing, HR)
+-- Permissions are namespaced by module
+CREATE TABLE application_modules (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    application_id  UUID NOT NULL REFERENCES applications(id) ON DELETE CASCADE,
+    name            VARCHAR(255) NOT NULL,               -- e.g., "CRM"
+    slug            VARCHAR(100) NOT NULL,               -- e.g., "crm"
+    description     TEXT,
+    status          VARCHAR(20) NOT NULL DEFAULT 'active'
+                    CHECK (status IN ('active', 'inactive')),
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    UNIQUE (application_id, slug)
+);
+
+CREATE INDEX idx_app_modules_application ON application_modules(application_id);
+
+CREATE TRIGGER set_updated_at
+    BEFORE UPDATE ON application_modules
+    FOR EACH ROW
+    EXECUTE FUNCTION trigger_set_updated_at();
+
+COMMENT ON TABLE application_modules IS 'Logical groupings within an application (e.g., CRM, Invoicing) — permissions are namespaced by module';
+
+-- Down Migration
+
+DROP TABLE IF EXISTS application_modules CASCADE;
+DROP TABLE IF EXISTS applications CASCADE;

package/migrations/004_clients.sql

@@ -0,0 +1,74 @@
+-- Up Migration
+
+-- OIDC clients — each represents a deployment type (web, mobile, SPA) of an app for an org
+CREATE TABLE clients (
+    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    organization_id     UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+    application_id      UUID NOT NULL REFERENCES applications(id) ON DELETE CASCADE,
+    client_id           VARCHAR(255) NOT NULL UNIQUE,     -- OIDC client_id (public identifier)
+    client_name         VARCHAR(255) NOT NULL,
+    client_type         VARCHAR(20) NOT NULL
+                        CHECK (client_type IN ('confidential', 'public')),
+    application_type    VARCHAR(20) NOT NULL DEFAULT 'web'
+                        CHECK (application_type IN ('web', 'native', 'spa')),
+
+    -- OIDC Configuration
+    redirect_uris       TEXT[] NOT NULL DEFAULT '{}',     -- Array of allowed redirect URIs
+    post_logout_redirect_uris TEXT[] DEFAULT '{}',
+    grant_types         TEXT[] NOT NULL DEFAULT '{authorization_code}',
+    response_types      TEXT[] NOT NULL DEFAULT '{code}',
+    scope               TEXT NOT NULL DEFAULT 'openid profile email',
+    token_endpoint_auth_method VARCHAR(50) NOT NULL DEFAULT 'client_secret_basic',
+
+    -- CORS
+    allowed_origins     TEXT[] DEFAULT '{}',               -- Allowed CORS origins
+
+    -- PKCE
+    require_pkce        BOOLEAN NOT NULL DEFAULT TRUE,
+
+    -- Status
+    status              VARCHAR(20) NOT NULL DEFAULT 'active'
+                        CHECK (status IN ('active', 'inactive', 'revoked')),
+
+    -- Metadata
+    created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_clients_org ON clients(organization_id);
+CREATE INDEX idx_clients_app ON clients(application_id);
+CREATE INDEX idx_clients_client_id ON clients(client_id);
+
+CREATE TRIGGER set_updated_at
+    BEFORE UPDATE ON clients
+    FOR EACH ROW
+    EXECUTE FUNCTION trigger_set_updated_at();
+
+COMMENT ON TABLE clients IS 'OIDC clients — each represents a deployment (web/mobile/SPA) of an application for an organization';
+COMMENT ON COLUMN clients.client_id IS 'Public OIDC client_id — used in authorization requests';
+COMMENT ON COLUMN clients.require_pkce IS 'Whether PKCE is required for this client (recommended: always true)';
+
+-- Client secrets — stored as Argon2id hashes
+-- Multiple active secrets support zero-downtime rotation
+CREATE TABLE client_secrets (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    client_id       UUID NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
+    secret_hash     TEXT NOT NULL,                        -- Argon2id hash of the secret
+    label           VARCHAR(255),                         -- Human-readable label
+    expires_at      TIMESTAMPTZ,                          -- NULL = never expires
+    status          VARCHAR(20) NOT NULL DEFAULT 'active'
+                    CHECK (status IN ('active', 'revoked')),
+    last_used_at    TIMESTAMPTZ,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_client_secrets_client ON client_secrets(client_id);
+CREATE INDEX idx_client_secrets_active ON client_secrets(client_id) WHERE status = 'active';
+
+COMMENT ON TABLE client_secrets IS 'Hashed client secrets — multiple active secrets allow zero-downtime rotation';
+COMMENT ON COLUMN client_secrets.secret_hash IS 'Argon2id hash of the client secret (plaintext is never stored)';
+
+-- Down Migration
+
+DROP TABLE IF EXISTS client_secrets CASCADE;
+DROP TABLE IF EXISTS clients CASCADE;

package/migrations/005_users.sql

@@ -0,0 +1,119 @@
+-- Up Migration
+
+-- Users belong to exactly one organization
+-- Profile fields follow OIDC Standard Claims (OpenID Connect Core 1.0, §5.1)
+CREATE TABLE users (
+    id                      UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    organization_id         UUID NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+
+    -- Authentication
+    email                   CITEXT NOT NULL,              -- Case-insensitive via citext extension
+    email_verified          BOOLEAN NOT NULL DEFAULT FALSE,
+    password_hash           TEXT,                          -- NULL for passwordless-only users
+    password_changed_at     TIMESTAMPTZ,
+
+    -- OIDC Standard Claims (OpenID Connect Core 1.0, §5.1)
+    given_name              VARCHAR(255),
+    family_name             VARCHAR(255),
+    middle_name             VARCHAR(255),
+    nickname                VARCHAR(255),
+    preferred_username      VARCHAR(255),
+    profile_url             TEXT,                          -- "profile" claim
+    picture_url             TEXT,                          -- "picture" claim
+    website_url             TEXT,                          -- "website" claim
+    gender                  VARCHAR(50),
+    birthdate               DATE,                         -- ISO 8601 (YYYY-MM-DD)
+    zoneinfo                VARCHAR(50),                  -- e.g., "Europe/Amsterdam"
+    locale                  VARCHAR(10),                  -- e.g., "nl-NL"
+    phone_number            VARCHAR(50),
+    phone_number_verified   BOOLEAN NOT NULL DEFAULT FALSE,
+
+    -- Address (structured, OIDC §5.1.1)
+    address_street          TEXT,
+    address_locality        VARCHAR(255),                 -- City
+    address_region          VARCHAR(255),                 -- State/Province
+    address_postal_code     VARCHAR(20),
+    address_country         VARCHAR(2),                   -- ISO 3166-1 alpha-2
+
+    -- Status & Lifecycle
+    status                  VARCHAR(20) NOT NULL DEFAULT 'active'
+                            CHECK (status IN ('active', 'inactive', 'suspended', 'locked')),
+    locked_at               TIMESTAMPTZ,
+    locked_reason           TEXT,
+    last_login_at           TIMESTAMPTZ,
+    login_count             INTEGER NOT NULL DEFAULT 0,
+
+    -- Metadata
+    created_at              TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at              TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    -- Constraints: email is unique per organization (case-insensitive via CITEXT)
+    UNIQUE (organization_id, email)
+);
+
+CREATE INDEX idx_users_org ON users(organization_id);
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_status ON users(organization_id, status);
+
+CREATE TRIGGER set_updated_at
+    BEFORE UPDATE ON users
+    FOR EACH ROW
+    EXECUTE FUNCTION trigger_set_updated_at();
+
+COMMENT ON TABLE users IS 'User accounts — each user belongs to exactly one organization';
+COMMENT ON COLUMN users.email IS 'Case-insensitive email (CITEXT) — unique per organization';
+COMMENT ON COLUMN users.password_hash IS 'Argon2id hash — NULL for passwordless-only users';
+COMMENT ON COLUMN users.status IS 'User lifecycle: active → inactive/suspended/locked';
+
+-- Magic link tokens for passwordless authentication
+CREATE TABLE magic_link_tokens (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id         UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    token_hash      TEXT NOT NULL UNIQUE,                 -- SHA-256 hash of the token
+    expires_at      TIMESTAMPTZ NOT NULL,
+    used_at         TIMESTAMPTZ,                          -- NULL = not yet used
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_magic_link_user ON magic_link_tokens(user_id);
+CREATE INDEX idx_magic_link_token ON magic_link_tokens(token_hash) WHERE used_at IS NULL;
+
+COMMENT ON TABLE magic_link_tokens IS 'Passwordless login tokens — SHA-256 hashed, single-use with expiry';
+
+-- Password reset tokens
+CREATE TABLE password_reset_tokens (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id         UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    token_hash      TEXT NOT NULL UNIQUE,                 -- SHA-256 hash of the token
+    expires_at      TIMESTAMPTZ NOT NULL,
+    used_at         TIMESTAMPTZ,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_pwd_reset_user ON password_reset_tokens(user_id);
+CREATE INDEX idx_pwd_reset_token ON password_reset_tokens(token_hash) WHERE used_at IS NULL;
+
+COMMENT ON TABLE password_reset_tokens IS 'Password reset tokens — SHA-256 hashed, single-use with expiry';
+
+-- Invitation tokens — sent when admin creates a user account
+-- User clicks link to set their initial password
+CREATE TABLE invitation_tokens (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id         UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    token_hash      TEXT NOT NULL UNIQUE,                 -- SHA-256 hash of the token
+    expires_at      TIMESTAMPTZ NOT NULL,                 -- Default: 7 days from creation
+    used_at         TIMESTAMPTZ,                          -- NULL = not yet accepted
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_invitation_user ON invitation_tokens(user_id);
+CREATE INDEX idx_invitation_token ON invitation_tokens(token_hash) WHERE used_at IS NULL;
+
+COMMENT ON TABLE invitation_tokens IS 'User invitation tokens — sent by admin, user clicks to set initial password';
+
+-- Down Migration
+
+DROP TABLE IF EXISTS invitation_tokens CASCADE;
+DROP TABLE IF EXISTS password_reset_tokens CASCADE;
+DROP TABLE IF EXISTS magic_link_tokens CASCADE;
+DROP TABLE IF EXISTS users CASCADE;

package/migrations/006_roles_permissions.sql

@@ -0,0 +1,80 @@
+-- Up Migration
+
+-- Roles are defined globally per application
+-- Role assignments to users are per-organization (since users belong to one org)
+CREATE TABLE roles (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    application_id  UUID NOT NULL REFERENCES applications(id) ON DELETE CASCADE,
+    name            VARCHAR(255) NOT NULL,               -- e.g., "CRM Editor"
+    slug            VARCHAR(100) NOT NULL,               -- e.g., "crm-editor"
+    description     TEXT,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    UNIQUE (application_id, slug)
+);
+
+CREATE INDEX idx_roles_application ON roles(application_id);
+
+CREATE TRIGGER set_updated_at
+    BEFORE UPDATE ON roles
+    FOR EACH ROW
+    EXECUTE FUNCTION trigger_set_updated_at();
+
+COMMENT ON TABLE roles IS 'Global role definitions per application — assigned to users via user_roles';
+
+-- Permissions are defined globally per application, optionally scoped to a module
+CREATE TABLE permissions (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    application_id  UUID NOT NULL REFERENCES applications(id) ON DELETE CASCADE,
+    module_id       UUID REFERENCES application_modules(id) ON DELETE SET NULL,
+    name            VARCHAR(255) NOT NULL,               -- e.g., "Read CRM Contacts"
+    slug            VARCHAR(150) NOT NULL,               -- e.g., "crm:contacts:read"
+    description     TEXT,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    UNIQUE (application_id, slug)
+);
+
+CREATE INDEX idx_permissions_application ON permissions(application_id);
+CREATE INDEX idx_permissions_module ON permissions(module_id);
+
+COMMENT ON TABLE permissions IS 'Global permission definitions per application — optionally scoped to a module';
+COMMENT ON COLUMN permissions.slug IS 'Namespaced permission slug (e.g., "crm:contacts:read")';
+
+-- Many-to-many: which permissions does each role grant?
+CREATE TABLE role_permissions (
+    role_id         UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
+    permission_id   UUID NOT NULL REFERENCES permissions(id) ON DELETE CASCADE,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    PRIMARY KEY (role_id, permission_id)
+);
+
+CREATE INDEX idx_role_permissions_role ON role_permissions(role_id);
+CREATE INDEX idx_role_permissions_permission ON role_permissions(permission_id);
+
+COMMENT ON TABLE role_permissions IS 'Maps roles to permissions — many-to-many join table';
+
+-- Many-to-many: which roles are assigned to each user?
+CREATE TABLE user_roles (
+    user_id         UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    role_id         UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
+    assigned_by     UUID REFERENCES users(id) ON DELETE SET NULL,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    PRIMARY KEY (user_id, role_id)
+);
+
+CREATE INDEX idx_user_roles_user ON user_roles(user_id);
+CREATE INDEX idx_user_roles_role ON user_roles(role_id);
+
+COMMENT ON TABLE user_roles IS 'Maps users to roles — includes who assigned the role';
+COMMENT ON COLUMN user_roles.assigned_by IS 'The admin user who assigned this role (NULL if system-assigned)';
+
+-- Down Migration
+
+DROP TABLE IF EXISTS user_roles CASCADE;
+DROP TABLE IF EXISTS role_permissions CASCADE;
+DROP TABLE IF EXISTS permissions CASCADE;
+DROP TABLE IF EXISTS roles CASCADE;

package/migrations/007_custom_claims.sql

@@ -0,0 +1,55 @@
+-- Up Migration
+
+-- Custom claim definitions — per application
+-- Controls which tokens include the claim (id_token, access_token, userinfo)
+CREATE TABLE custom_claim_definitions (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    application_id  UUID NOT NULL REFERENCES applications(id) ON DELETE CASCADE,
+    claim_name      VARCHAR(255) NOT NULL,               -- e.g., "department"
+    claim_type      VARCHAR(20) NOT NULL DEFAULT 'string'
+                    CHECK (claim_type IN ('string', 'number', 'boolean', 'json')),
+    description     TEXT,
+    include_in_id_token     BOOLEAN NOT NULL DEFAULT FALSE,
+    include_in_access_token BOOLEAN NOT NULL DEFAULT TRUE,
+    include_in_userinfo     BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    UNIQUE (application_id, claim_name)
+);
+
+CREATE INDEX idx_custom_claims_app ON custom_claim_definitions(application_id);
+
+CREATE TRIGGER set_updated_at
+    BEFORE UPDATE ON custom_claim_definitions
+    FOR EACH ROW
+    EXECUTE FUNCTION trigger_set_updated_at();
+
+COMMENT ON TABLE custom_claim_definitions IS 'Per-application custom claim definitions — controls token inclusion';
+
+-- Custom claim values — per user
+-- Stores the actual value as JSONB (supports any type: string, number, boolean, object)
+CREATE TABLE custom_claim_values (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id         UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    claim_id        UUID NOT NULL REFERENCES custom_claim_definitions(id) ON DELETE CASCADE,
+    value           JSONB NOT NULL,                      -- Stores any type as JSONB
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    UNIQUE (user_id, claim_id)
+);
+
+CREATE INDEX idx_custom_claim_values_user ON custom_claim_values(user_id);
+
+CREATE TRIGGER set_updated_at
+    BEFORE UPDATE ON custom_claim_values
+    FOR EACH ROW
+    EXECUTE FUNCTION trigger_set_updated_at();
+
+COMMENT ON TABLE custom_claim_values IS 'Per-user custom claim values — JSONB supports any claim type';
+
+-- Down Migration
+
+DROP TABLE IF EXISTS custom_claim_values CASCADE;
+DROP TABLE IF EXISTS custom_claim_definitions CASCADE;

package/migrations/008_config.sql

@@ -0,0 +1,51 @@
+-- Up Migration
+
+-- System configuration — key-value store with typed JSONB values
+-- All configurable settings (token lifetimes, rate limits, etc.) are stored here
+CREATE TABLE system_config (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    key             VARCHAR(255) NOT NULL UNIQUE,        -- e.g., "access_token_ttl"
+    value           JSONB NOT NULL,                      -- Typed value as JSON
+    value_type      VARCHAR(20) NOT NULL DEFAULT 'string'
+                    CHECK (value_type IN ('string', 'number', 'boolean', 'duration', 'json')),
+    description     TEXT,
+    is_sensitive    BOOLEAN NOT NULL DEFAULT FALSE,      -- Hide from non-super-admin
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TRIGGER set_updated_at
+    BEFORE UPDATE ON system_config
+    FOR EACH ROW
+    EXECUTE FUNCTION trigger_set_updated_at();
+
+COMMENT ON TABLE system_config IS 'System-wide configuration — key-value store with typed JSONB values';
+COMMENT ON COLUMN system_config.is_sensitive IS 'If true, value is hidden from non-super-admin users';
+
+-- Signing keys for JWKS (JSON Web Key Sets)
+-- Stores PEM-encoded key pairs with lifecycle management
+CREATE TABLE signing_keys (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    kid             VARCHAR(255) NOT NULL UNIQUE,         -- Key ID (for JWKS)
+    algorithm       VARCHAR(10) NOT NULL DEFAULT 'ES256',
+    public_key      TEXT NOT NULL,                        -- PEM-encoded public key
+    private_key     TEXT NOT NULL,                        -- PEM-encoded private key (encrypted at rest)
+    status          VARCHAR(20) NOT NULL DEFAULT 'active'
+                    CHECK (status IN ('active', 'retired', 'revoked')),
+    activated_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    retired_at      TIMESTAMPTZ,                          -- When marked as retired
+    expires_at      TIMESTAMPTZ,                          -- Grace period expiry
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_signing_keys_status ON signing_keys(status);
+CREATE INDEX idx_signing_keys_active ON signing_keys(status) WHERE status = 'active';
+
+COMMENT ON TABLE signing_keys IS 'JWKS signing key pairs — supports key rotation with active/retired/revoked lifecycle';
+COMMENT ON COLUMN signing_keys.kid IS 'Key ID published in JWKS endpoint for token verification';
+COMMENT ON COLUMN signing_keys.private_key IS 'PEM-encoded private key — should be encrypted at rest in production';
+
+-- Down Migration
+
+DROP TABLE IF EXISTS signing_keys CASCADE;
+DROP TABLE IF EXISTS system_config CASCADE;

package/migrations/009_audit_log.sql

@@ -0,0 +1,31 @@
+-- Up Migration
+
+-- Audit log for security events
+-- Uses SET NULL on delete to preserve audit entries when users/orgs are removed
+CREATE TABLE audit_log (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    organization_id UUID REFERENCES organizations(id) ON DELETE SET NULL,
+    user_id         UUID REFERENCES users(id) ON DELETE SET NULL,
+    actor_id        UUID REFERENCES users(id) ON DELETE SET NULL, -- Who performed the action
+    event_type      VARCHAR(100) NOT NULL,                -- e.g., "user.login.success"
+    event_category  VARCHAR(50) NOT NULL,                 -- e.g., "authentication", "admin", "security"
+    description     TEXT,
+    metadata        JSONB DEFAULT '{}',                   -- Additional context (IP, user-agent, etc.)
+    ip_address      INET,
+    user_agent      TEXT,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Composite indexes for common query patterns (org+time, user+time, event+time)
+CREATE INDEX idx_audit_log_org ON audit_log(organization_id, created_at DESC);
+CREATE INDEX idx_audit_log_user ON audit_log(user_id, created_at DESC);
+CREATE INDEX idx_audit_log_event ON audit_log(event_type, created_at DESC);
+CREATE INDEX idx_audit_log_category ON audit_log(event_category, created_at DESC);
+
+COMMENT ON TABLE audit_log IS 'Security event audit log — append-only, preserved on user/org deletion';
+COMMENT ON COLUMN audit_log.actor_id IS 'The user who performed the action (may differ from user_id for admin actions)';
+COMMENT ON COLUMN audit_log.metadata IS 'Structured additional context (e.g., IP address, user-agent, request details)';
+
+-- Down Migration
+
+DROP TABLE IF EXISTS audit_log CASCADE;

package/migrations/010_oidc_adapter.sql

@@ -0,0 +1,34 @@
+-- Up Migration
+
+-- Generic OIDC adapter storage table for node-oidc-provider
+-- Stores: AccessToken, AuthorizationCode, RefreshToken, DeviceCode,
+-- ClientCredentials, InitialAccessToken, RegistrationAccessToken,
+-- Interaction, ReplayDetection, PushedAuthorizationRequest, Grant,
+-- Session, BackchannelAuthenticationRequest
+CREATE TABLE oidc_payloads (
+    id              VARCHAR(255) NOT NULL,
+    type            VARCHAR(50) NOT NULL,                 -- Model name (e.g., "AccessToken")
+    payload         JSONB NOT NULL,
+    grant_id        VARCHAR(255),
+    user_code       VARCHAR(255),
+    uid             VARCHAR(255),
+    expires_at      TIMESTAMPTZ,
+    consumed_at     TIMESTAMPTZ,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    PRIMARY KEY (id, type)
+);
+
+-- Partial indexes for efficient lookups on non-null columns
+CREATE INDEX idx_oidc_payloads_grant ON oidc_payloads(grant_id) WHERE grant_id IS NOT NULL;
+CREATE INDEX idx_oidc_payloads_user_code ON oidc_payloads(user_code) WHERE user_code IS NOT NULL;
+CREATE INDEX idx_oidc_payloads_uid ON oidc_payloads(uid) WHERE uid IS NOT NULL;
+CREATE INDEX idx_oidc_payloads_expires ON oidc_payloads(expires_at) WHERE expires_at IS NOT NULL;
+
+COMMENT ON TABLE oidc_payloads IS 'Generic storage for node-oidc-provider — all OIDC artifact types share this table';
+COMMENT ON COLUMN oidc_payloads.type IS 'OIDC model type (e.g., AccessToken, AuthorizationCode, Session)';
+COMMENT ON COLUMN oidc_payloads.payload IS 'Full OIDC artifact payload as JSONB';
+
+-- Down Migration
+
+DROP TABLE IF EXISTS oidc_payloads CASCADE;

package/migrations/011_seed.sql

@@ -0,0 +1,53 @@
+-- Up Migration
+
+-- Seed data for development: super-admin organization and default system config values.
+-- NOTE: Super-admin user is NOT created here (deferred to RD-06, requires password hashing).
+-- NOTE: Signing keys are NOT created here (deferred to RD-03, requires crypto key generation).
+
+-- Super-admin organization
+-- The is_super_admin partial unique index ensures only one row can have is_super_admin = TRUE
+INSERT INTO organizations (name, slug, status, is_super_admin, branding_company_name, default_locale)
+VALUES ('Porta Admin', 'porta-admin', 'active', TRUE, 'Porta', 'en');
+
+-- Default system configuration values
+-- These control global OIDC/auth behavior and can be changed at runtime via admin UI
+INSERT INTO system_config (key, value, value_type, description, is_sensitive) VALUES
+    -- Token lifetimes
+    ('access_token_ttl',    '"3600"',           'duration',  'Access token TTL in seconds (default: 1 hour)',              FALSE),
+    ('id_token_ttl',        '"3600"',           'duration',  'ID token TTL in seconds (default: 1 hour)',                  FALSE),
+    ('refresh_token_ttl',   '"2592000"',        'duration',  'Refresh token TTL in seconds (default: 30 days)',            FALSE),
+    ('authorization_code_ttl', '"600"',         'duration',  'Authorization code TTL in seconds (default: 10 minutes)',    FALSE),
+
+    -- Session settings
+    ('session_ttl',         '"86400"',          'duration',  'Session TTL in seconds (default: 24 hours)',                 FALSE),
+    ('cookie_secure',       'true',             'boolean',   'Require HTTPS for cookies (disable for local dev only)',     FALSE),
+
+    -- Magic link / passwordless
+    ('magic_link_ttl',      '"900"',            'duration',  'Magic link token TTL in seconds (default: 15 minutes)',      FALSE),
+    ('magic_link_length',   '48',               'number',    'Magic link token length in bytes',                           FALSE),
+
+    -- Password reset
+    ('password_reset_ttl',  '"3600"',           'duration',  'Password reset token TTL in seconds (default: 1 hour)',      FALSE),
+
+    -- Invitation
+    ('invitation_ttl',      '"604800"',         'duration',  'Invitation token TTL in seconds (default: 7 days)',          FALSE),
+
+    -- Rate limiting
+    ('login_rate_limit',    '10',               'number',    'Max login attempts per user per 15 minutes',                 FALSE),
+    ('api_rate_limit',      '100',              'number',    'Max API requests per client per minute',                     FALSE),
+
+    -- Account lockout
+    ('max_failed_logins',   '5',                'number',    'Max failed logins before account lockout',                   FALSE),
+    ('lockout_duration',    '"900"',            'duration',  'Account lockout duration in seconds (default: 15 minutes)',   FALSE),
+
+    -- PKCE
+    ('require_pkce',        'true',             'boolean',   'Require PKCE for all authorization code flows',              FALSE),
+
+    -- CORS
+    ('cors_max_age',        '86400',            'number',    'CORS preflight cache duration in seconds (default: 24h)',    FALSE);
+
+-- Down Migration
+
+-- Remove seed data in reverse order
+DELETE FROM system_config;
+DELETE FROM organizations WHERE slug = 'porta-admin';

package/migrations/012_two_factor.sql

@@ -0,0 +1,88 @@
+-- Up Migration
+
+-- Two-Factor Authentication (RD-12)
+-- Adds per-org 2FA policy, per-user 2FA state, and tables for TOTP config,
+-- email OTP codes, and recovery codes.
+
+-- Add 2FA policy to organizations — controls whether 2FA is required for org members.
+-- Values: 'optional' (default), 'required_email', 'required_totp', 'required_any'
+ALTER TABLE organizations
+  ADD COLUMN two_factor_policy VARCHAR(20) NOT NULL DEFAULT 'optional'
+  CHECK (two_factor_policy IN ('optional', 'required_email', 'required_totp', 'required_any'));
+
+-- Add 2FA state columns to users — tracks whether 2FA is enabled and which method.
+ALTER TABLE users
+  ADD COLUMN two_factor_enabled BOOLEAN NOT NULL DEFAULT false,
+  ADD COLUMN two_factor_method VARCHAR(10) DEFAULT NULL
+  CHECK (two_factor_method IN ('email', 'totp') OR two_factor_method IS NULL);
+
+-- TOTP configuration per user (encrypted secrets)
+-- Stores AES-256-GCM encrypted TOTP secret, one row per user.
+CREATE TABLE user_totp (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  encrypted_secret TEXT NOT NULL,          -- AES-256-GCM encrypted TOTP secret
+  encryption_iv TEXT NOT NULL,             -- Initialization vector (hex)
+  encryption_tag TEXT NOT NULL,            -- Authentication tag (hex)
+  algorithm VARCHAR(10) NOT NULL DEFAULT 'SHA1',
+  digits INTEGER NOT NULL DEFAULT 6,
+  period INTEGER NOT NULL DEFAULT 30,
+  verified BOOLEAN NOT NULL DEFAULT false, -- true after first successful TOTP verification
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  UNIQUE (user_id)                         -- one TOTP config per user
+);
+
+-- Email OTP codes (SHA-256 hashed, short-lived)
+-- Stores hashed 6-digit codes sent via email for 2FA verification.
+CREATE TABLE two_factor_otp_codes (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  code_hash VARCHAR(64) NOT NULL,          -- SHA-256 hex hash of 6-digit code
+  expires_at TIMESTAMPTZ NOT NULL,         -- 10 minute expiry
+  used_at TIMESTAMPTZ DEFAULT NULL,        -- NULL = unused, set on successful verification
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Index for fast lookup of active (unused, not expired) OTP codes per user
+CREATE INDEX idx_otp_codes_user_active
+  ON two_factor_otp_codes(user_id, expires_at)
+  WHERE used_at IS NULL;
+
+-- Recovery codes (Argon2id hashed, single-use)
+-- 10 codes generated during 2FA setup, each usable once as a backup.
+CREATE TABLE two_factor_recovery_codes (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  code_hash TEXT NOT NULL,                 -- Argon2id hash of recovery code
+  used_at TIMESTAMPTZ DEFAULT NULL,        -- NULL = unused
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Index for fast lookup of unused recovery codes per user
+CREATE INDEX idx_recovery_codes_user
+  ON two_factor_recovery_codes(user_id)
+  WHERE used_at IS NULL;
+
+-- Auto-update trigger for user_totp.updated_at
+-- Uses the reusable trigger function defined in 001_extensions.sql
+CREATE TRIGGER set_user_totp_updated_at
+  BEFORE UPDATE ON user_totp
+  FOR EACH ROW EXECUTE FUNCTION trigger_set_updated_at();
+
+-- Down Migration
+
+-- Drop tables and indexes (indexes are dropped automatically with tables)
+DROP TRIGGER IF EXISTS set_user_totp_updated_at ON user_totp;
+DROP TABLE IF EXISTS two_factor_recovery_codes;
+DROP TABLE IF EXISTS two_factor_otp_codes;
+DROP TABLE IF EXISTS user_totp;
+
+-- Remove 2FA columns from users
+ALTER TABLE users
+  DROP COLUMN IF EXISTS two_factor_method,
+  DROP COLUMN IF EXISTS two_factor_enabled;
+
+-- Remove 2FA policy from organizations
+ALTER TABLE organizations
+  DROP COLUMN IF EXISTS two_factor_policy;

package/migrations/013_client_secret_sha256.sql

@@ -0,0 +1,22 @@
+-- Migration 013: Add SHA-256 hash column to client_secrets
+--
+-- Adds a SHA-256 hex hash column used for oidc-provider client authentication.
+-- SHA-256 is appropriate for machine-generated, high-entropy client secrets
+-- (48 bytes / 384 bits). Argon2id hashes are retained for admin API verification.
+--
+-- Existing secrets cannot be backfilled (we don't have plaintexts).
+-- New secrets will have both Argon2id hash and SHA-256 hash.
+
+-- Up Migration
+ALTER TABLE client_secrets ADD COLUMN secret_sha256 VARCHAR(64);
+
+CREATE INDEX idx_client_secrets_sha256
+  ON client_secrets(secret_sha256)
+  WHERE secret_sha256 IS NOT NULL;
+
+COMMENT ON COLUMN client_secrets.secret_sha256
+  IS 'SHA-256 hex hash of the secret — used for oidc-provider client authentication';
+
+-- Down Migration (in comments for reference)
+-- DROP INDEX IF EXISTS idx_client_secrets_sha256;
+-- ALTER TABLE client_secrets DROP COLUMN IF EXISTS secret_sha256;