Merge branch 'multi-role' of github.com:fosrl/pangolin into multi-role

thundering herd

license.py

@@ -0,0 +1,115 @@
+import os
+import sys
+
+# --- Configuration ---
+# The header text to be added to the files.
+HEADER_TEXT = """/*
+ * This file is part of a proprietary work.
+ *
+ * Copyright (c) 2025 Fossorial, Inc.
+ * All rights reserved.
+ *
+ * This file is licensed under the Fossorial Commercial License.
+ * You may not use this file except in compliance with the License.
+ * Unauthorized use, copying, modification, or distribution is strictly prohibited.
+ *
+ * This file is not licensed under the AGPLv3.
+ */
+"""
+
+def should_add_header(file_path):
+    """
+    Checks if a file should receive the commercial license header.
+    Returns True if 'private' is in the path or file content.
+    """
+    # Check if 'private' is in the file path (case-insensitive)
+    if 'server/private' in file_path.lower():
+        return True
+
+    # Check if 'private' is in the file content (case-insensitive)
+    # try:
+    #     with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
+    #         content = f.read()
+    #         if 'private' in content.lower():
+    #             return True
+    # except Exception as e:
+    #     print(f"Could not read file {file_path}: {e}")
+
+    return False
+
+def process_directory(root_dir):
+    """
+    Recursively scans a directory and adds headers to qualifying .ts or .tsx files,
+    skipping any 'node_modules' directories.
+    """
+    print(f"Scanning directory: {root_dir}")
+    files_processed = 0
+    headers_added = 0
+
+    for root, dirs, files in os.walk(root_dir):
+        # --- MODIFICATION ---
+        # Exclude 'node_modules' directories from the scan to improve performance.
+        if 'node_modules' in dirs:
+            dirs.remove('node_modules')
+
+        for file in files:
+            if file.endswith('.ts') or file.endswith('.tsx'):
+                file_path = os.path.join(root, file)
+                files_processed += 1
+
+                try:
+                    with open(file_path, 'r+', encoding='utf-8') as f:
+                        original_content = f.read()
+                        has_header = original_content.startswith(HEADER_TEXT.strip())
+                        
+                        if should_add_header(file_path):
+                            # Add header only if it's not already there
+                            if not has_header:
+                                f.seek(0, 0) # Go to the beginning of the file
+                                f.write(HEADER_TEXT.strip() + '\n\n' + original_content)
+                                print(f"Added header to: {file_path}")
+                                headers_added += 1
+                            else:
+                                print(f"Header already exists in: {file_path}")
+                        else:
+                            # Remove header if it exists but shouldn't be there
+                            if has_header:
+                                # Find the end of the header and remove it (including following newlines)
+                                header_with_newlines = HEADER_TEXT.strip() + '\n\n'
+                                if original_content.startswith(header_with_newlines):
+                                    content_without_header = original_content[len(header_with_newlines):]
+                                else:
+                                    # Handle case where there might be different newline patterns
+                                    header_end = len(HEADER_TEXT.strip())
+                                    # Skip any newlines after the header
+                                    while header_end < len(original_content) and original_content[header_end] in '\n\r':
+                                        header_end += 1
+                                    content_without_header = original_content[header_end:]
+                                
+                                f.seek(0)
+                                f.write(content_without_header)
+                                f.truncate()
+                                print(f"Removed header from: {file_path}")
+                                headers_added += 1  # Reusing counter for modifications
+
+                except Exception as e:
+                    print(f"Error processing file {file_path}: {e}")
+
+    print("\n--- Scan Complete ---")
+    print(f"Total .ts or .tsx files found: {files_processed}")
+    print(f"Files modified (headers added/removed): {headers_added}")
+
+
+if __name__ == "__main__":
+    # Get the target directory from the command line arguments.
+    # If no directory is provided, it uses the current directory ('.').
+    if len(sys.argv) > 1:
+        target_directory = sys.argv[1]
+    else:
+        target_directory = '.' # Default to current directory
+
+    if not os.path.isdir(target_directory):
+        print(f"Error: Directory '{target_directory}' not found.")
+        sys.exit(1)
+
+    process_directory(os.path.abspath(target_directory))

messages/en-US.json

@@ -512,6 +512,8 @@
     "autoProvisionedDescription": "Allow this user to be automatically managed by identity provider",
     "accessControlsDescription": "Manage what this user can access and do in the organization",
     "accessControlsSubmit": "Save Access Controls",
+    "singleRolePerUserPlanNotice": "Your plan only supports one role per user.",
+    "singleRolePerUserEditionNotice": "This edition only supports one role per user.",
     "roles": "Roles",
     "accessUsersRoles": "Manage Users & Roles",
     "accessUsersRolesDescription": "Invite users and add them to roles to manage access to the organization",

server/cleanup.ts

@@ -1,8 +1,10 @@
 import { flushBandwidthToDb } from "@server/routers/newt/handleReceiveBandwidthMessage";
 import { flushSiteBandwidthToDb } from "@server/routers/gerbil/receiveBandwidth";
+import { stopPingAccumulator } from "@server/routers/newt/pingAccumulator";
 import { cleanup as wsCleanup } from "#dynamic/routers/ws";
 
 async function cleanup() {
+    await stopPingAccumulator();
     await flushBandwidthToDb();
     await flushSiteBandwidthToDb();
     await wsCleanup();

server/db/pg/driver.ts

@@ -1,7 +1,7 @@
 import { drizzle as DrizzlePostgres } from "drizzle-orm/node-postgres";
-import { Pool } from "pg";
 import { readConfigFile } from "@server/lib/readConfigFile";
 import { withReplicas } from "drizzle-orm/pg-core";
+import { createPool } from "./poolConfig";
 
 function createDb() {
     const config = readConfigFile();
@@ -39,12 +39,17 @@ function createDb() {
 
     // Create connection pools instead of individual connections
     const poolConfig = config.postgres.pool;
-    const primaryPool = new Pool({
+    const maxConnections = poolConfig?.max_connections || 20;
+    const idleTimeoutMs = poolConfig?.idle_timeout_ms || 30000;
+    const connectionTimeoutMs = poolConfig?.connection_timeout_ms || 5000;
+
+    const primaryPool = createPool(
         connectionString,
-        max: poolConfig?.max_connections || 20,
-        idleTimeoutMillis: poolConfig?.idle_timeout_ms || 30000,
-        connectionTimeoutMillis: poolConfig?.connection_timeout_ms || 5000
-    });
+        maxConnections,
+        idleTimeoutMs,
+        connectionTimeoutMs,
+        "primary"
+    );
 
     const replicas = [];
 
@@ -55,14 +60,16 @@ function createDb() {
             })
         );
     } else {
+        const maxReplicaConnections =
+            poolConfig?.max_replica_connections || 20;
         for (const conn of replicaConnections) {
-            const replicaPool = new Pool({
-                connectionString: conn.connection_string,
-                max: poolConfig?.max_replica_connections || 20,
-                idleTimeoutMillis: poolConfig?.idle_timeout_ms || 30000,
-                connectionTimeoutMillis:
-                    poolConfig?.connection_timeout_ms || 5000
-            });
+            const replicaPool = createPool(
+                conn.connection_string,
+                maxReplicaConnections,
+                idleTimeoutMs,
+                connectionTimeoutMs,
+                "replica"
+            );
             replicas.push(
                 DrizzlePostgres(replicaPool, {
                     logger: process.env.QUERY_LOGGING == "true"
@@ -84,4 +91,4 @@ export default db;
 export const primaryDb = db.$primary;
 export type Transaction = Parameters<
     Parameters<(typeof db)["transaction"]>[0]
->[0];
+>[0];

server/db/pg/logsDriver.ts

@@ -1,9 +1,9 @@
 import { drizzle as DrizzlePostgres } from "drizzle-orm/node-postgres";
-import { Pool } from "pg";
 import { readConfigFile } from "@server/lib/readConfigFile";
 import { withReplicas } from "drizzle-orm/pg-core";
 import { build } from "@server/build";
 import { db as mainDb, primaryDb as mainPrimaryDb } from "./driver";
+import { createPool } from "./poolConfig";
 
 function createLogsDb() {
     // Only use separate logs database in SaaS builds
@@ -42,12 +42,17 @@ function createLogsDb() {
 
     // Create separate connection pool for logs database
     const poolConfig = logsConfig?.pool || config.postgres?.pool;
-    const primaryPool = new Pool({
+    const maxConnections = poolConfig?.max_connections || 20;
+    const idleTimeoutMs = poolConfig?.idle_timeout_ms || 30000;
+    const connectionTimeoutMs = poolConfig?.connection_timeout_ms || 5000;
+
+    const primaryPool = createPool(
         connectionString,
-        max: poolConfig?.max_connections || 20,
-        idleTimeoutMillis: poolConfig?.idle_timeout_ms || 30000,
-        connectionTimeoutMillis: poolConfig?.connection_timeout_ms || 5000
-    });
+        maxConnections,
+        idleTimeoutMs,
+        connectionTimeoutMs,
+        "logs-primary"
+    );
 
     const replicas = [];
 
@@ -58,14 +63,16 @@ function createLogsDb() {
             })
         );
     } else {
+        const maxReplicaConnections =
+            poolConfig?.max_replica_connections || 20;
         for (const conn of replicaConnections) {
-            const replicaPool = new Pool({
-                connectionString: conn.connection_string,
-                max: poolConfig?.max_replica_connections || 20,
-                idleTimeoutMillis: poolConfig?.idle_timeout_ms || 30000,
-                connectionTimeoutMillis:
-                    poolConfig?.connection_timeout_ms || 5000
-            });
+            const replicaPool = createPool(
+                conn.connection_string,
+                maxReplicaConnections,
+                idleTimeoutMs,
+                connectionTimeoutMs,
+                "logs-replica"
+            );
             replicas.push(
                 DrizzlePostgres(replicaPool, {
                     logger: process.env.QUERY_LOGGING == "true"
@@ -84,4 +91,4 @@ function createLogsDb() {
 
 export const logsDb = createLogsDb();
 export default logsDb;
-export const primaryLogsDb = logsDb.$primary;
+export const primaryLogsDb = logsDb.$primary;

server/db/pg/poolConfig.ts

@@ -0,0 +1,63 @@
+import { Pool, PoolConfig } from "pg";
+import logger from "@server/logger";
+
+export function createPoolConfig(
+    connectionString: string,
+    maxConnections: number,
+    idleTimeoutMs: number,
+    connectionTimeoutMs: number
+): PoolConfig {
+    return {
+        connectionString,
+        max: maxConnections,
+        idleTimeoutMillis: idleTimeoutMs,
+        connectionTimeoutMillis: connectionTimeoutMs,
+        // TCP keepalive to prevent silent connection drops by NAT gateways,
+        // load balancers, and other intermediate network devices (e.g. AWS
+        // NAT Gateway drops idle TCP connections after ~350s)
+        keepAlive: true,
+        keepAliveInitialDelayMillis: 10000, // send first keepalive after 10s of idle
+        // Allow connections to be released and recreated more aggressively
+        // to avoid stale connections building up
+        allowExitOnIdle: false
+    };
+}
+
+export function attachPoolErrorHandlers(pool: Pool, label: string): void {
+    pool.on("error", (err) => {
+        // This catches errors on idle clients in the pool. Without this
+        // handler an unexpected disconnect would crash the process.
+        logger.error(
+            `Unexpected error on idle ${label} database client: ${err.message}`
+        );
+    });
+
+    pool.on("connect", (client) => {
+        // Set a statement timeout on every new connection so a single slow
+        // query can't block the pool forever
+        client.query("SET statement_timeout = '30s'").catch((err: Error) => {
+            logger.warn(
+                `Failed to set statement_timeout on ${label} client: ${err.message}`
+            );
+        });
+    });
+}
+
+export function createPool(
+    connectionString: string,
+    maxConnections: number,
+    idleTimeoutMs: number,
+    connectionTimeoutMs: number,
+    label: string
+): Pool {
+    const pool = new Pool(
+        createPoolConfig(
+            connectionString,
+            maxConnections,
+            idleTimeoutMs,
+            connectionTimeoutMs
+        )
+    );
+    attachPoolErrorHandlers(pool, label);
+    return pool;
+}

server/lib/ip.ts

@@ -571,6 +571,129 @@ export function generateSubnetProxyTargets(
     return targets;
 }
 
+export type SubnetProxyTargetV2 = {
+    sourcePrefixes: string[]; // must be cidrs
+    destPrefix: string; // must be a cidr
+    disableIcmp?: boolean;
+    rewriteTo?: string; // must be a cidr
+    portRange?: {
+        min: number;
+        max: number;
+        protocol: "tcp" | "udp";
+    }[];
+};
+
+export function generateSubnetProxyTargetV2(
+    siteResource: SiteResource,
+    clients: {
+        clientId: number;
+        pubKey: string | null;
+        subnet: string | null;
+    }[]
+): SubnetProxyTargetV2 | undefined {
+    if (clients.length === 0) {
+        logger.debug(
+            `No clients have access to site resource ${siteResource.siteResourceId}, skipping target generation.`
+        );
+        return;
+    }
+
+    let target: SubnetProxyTargetV2 | null = null;
+
+    const portRange = [
+        ...parsePortRangeString(siteResource.tcpPortRangeString, "tcp"),
+        ...parsePortRangeString(siteResource.udpPortRangeString, "udp")
+    ];
+    const disableIcmp = siteResource.disableIcmp ?? false;
+
+    if (siteResource.mode == "host") {
+        let destination = siteResource.destination;
+        // check if this is a valid ip
+        const ipSchema = z.union([z.ipv4(), z.ipv6()]);
+        if (ipSchema.safeParse(destination).success) {
+            destination = `${destination}/32`;
+
+            target = {
+                sourcePrefixes: [],
+                destPrefix: destination,
+                portRange,
+                disableIcmp
+            };
+        }
+
+        if (siteResource.alias && siteResource.aliasAddress) {
+            // also push a match for the alias address
+            target = {
+                sourcePrefixes: [],
+                destPrefix: `${siteResource.aliasAddress}/32`,
+                rewriteTo: destination,
+                portRange,
+                disableIcmp
+            };
+        }
+    } else if (siteResource.mode == "cidr") {
+        target = {
+            sourcePrefixes: [],
+            destPrefix: siteResource.destination,
+            portRange,
+            disableIcmp
+        };
+    }
+
+    if (!target) {
+        return;
+    }
+
+    for (const clientSite of clients) {
+        if (!clientSite.subnet) {
+            logger.debug(
+                `Client ${clientSite.clientId} has no subnet, skipping for site resource ${siteResource.siteResourceId}.`
+            );
+            continue;
+        }
+
+        const clientPrefix = `${clientSite.subnet.split("/")[0]}/32`;
+
+        // add client prefix to source prefixes
+        target.sourcePrefixes.push(clientPrefix);
+    }
+
+    // print a nice representation of the targets
+    // logger.debug(
+    //     `Generated subnet proxy targets for: ${JSON.stringify(targets, null, 2)}`
+    // );
+
+    return target;
+}
+
+
+/**
+ * Converts a SubnetProxyTargetV2 to an array of SubnetProxyTarget (v1)
+ * by expanding each source prefix into its own target entry.
+ * @param targetV2 - The v2 target to convert
+ * @returns Array of v1 SubnetProxyTarget objects
+ */
+ export function convertSubnetProxyTargetsV2ToV1(
+     targetsV2: SubnetProxyTargetV2[]
+ ): SubnetProxyTarget[] {
+     return targetsV2.flatMap((targetV2) =>
+         targetV2.sourcePrefixes.map((sourcePrefix) => ({
+             sourcePrefix,
+             destPrefix: targetV2.destPrefix,
+             ...(targetV2.disableIcmp !== undefined && {
+                 disableIcmp: targetV2.disableIcmp
+             }),
+             ...(targetV2.rewriteTo !== undefined && {
+                 rewriteTo: targetV2.rewriteTo
+             }),
+             ...(targetV2.portRange !== undefined && {
+                 portRange: targetV2.portRange
+             })
+         }))
+     );
+ }
+
+
 // Custom schema for validating port range strings
 // Format: "80,443,8000-9000" or "*" for all ports, or empty string
 export const portRangeStringSchema = z

server/lib/readConfigFile.ts

@@ -302,8 +302,8 @@ export const configSchema = z
             .optional()
             .default({
                 block_size: 24,
-                subnet_group: "100.90.128.0/24",
-                utility_subnet_group: "100.96.128.0/24"
+                subnet_group: "100.90.128.0/20",
+                utility_subnet_group: "100.96.128.0/20"
             }),
         rate_limits: z
             .object({

server/lib/rebuildClientAssociations.ts

@@ -33,7 +33,7 @@ import logger from "@server/logger";
 import {
     generateAliasConfig,
     generateRemoteSubnets,
-    generateSubnetProxyTargets,
+    generateSubnetProxyTargetV2,
     parseEndpoint,
     formatEndpoint
 } from "@server/lib/ip";
@@ -661,19 +661,16 @@ async function handleSubnetProxyTargetUpdates(
         );
 
         if (addedClients.length > 0) {
-            const targetsToAdd = generateSubnetProxyTargets(
+            const targetToAdd = generateSubnetProxyTargetV2(
                 siteResource,
                 addedClients
             );
 
-            if (targetsToAdd.length > 0) {
-                logger.info(
-                    `Adding ${targetsToAdd.length} subnet proxy targets for siteResource ${siteResource.siteResourceId}`
-                );
+            if (targetToAdd) {
                 proxyJobs.push(
                     addSubnetProxyTargets(
                         newt.newtId,
-                        targetsToAdd,
+                        [targetToAdd],
                         newt.version
                     )
                 );
@@ -701,19 +698,16 @@ async function handleSubnetProxyTargetUpdates(
         );
 
         if (removedClients.length > 0) {
-            const targetsToRemove = generateSubnetProxyTargets(
+            const targetToRemove = generateSubnetProxyTargetV2(
                 siteResource,
                 removedClients
             );
 
-            if (targetsToRemove.length > 0) {
-                logger.info(
-                    `Removing ${targetsToRemove.length} subnet proxy targets for siteResource ${siteResource.siteResourceId}`
-                );
+            if (targetToRemove) {
                 proxyJobs.push(
                     removeSubnetProxyTargets(
                         newt.newtId,
-                        targetsToRemove,
+                        [targetToRemove],
                         newt.version
                     )
                 );
@@ -1170,7 +1164,7 @@ async function handleMessagesForClientResources(
             }
 
             for (const resource of resources) {
-                const targets = generateSubnetProxyTargets(resource, [
+                const target = generateSubnetProxyTargetV2(resource, [
                     {
                         clientId: client.clientId,
                         pubKey: client.pubKey,
@@ -1178,11 +1172,11 @@ async function handleMessagesForClientResources(
                     }
                 ]);
 
-                if (targets.length > 0) {
+                if (target) {
                     proxyJobs.push(
                         addSubnetProxyTargets(
                             newt.newtId,
-                            targets,
+                            [target],
                             newt.version
                         )
                     );
@@ -1247,7 +1241,7 @@ async function handleMessagesForClientResources(
             }
 
             for (const resource of resources) {
-                const targets = generateSubnetProxyTargets(resource, [
+                const target = generateSubnetProxyTargetV2(resource, [
                     {
                         clientId: client.clientId,
                         pubKey: client.pubKey,
@@ -1255,11 +1249,11 @@ async function handleMessagesForClientResources(
                     }
                 ]);
 
-                if (targets.length > 0) {
+                if (target) {
                     proxyJobs.push(
                         removeSubnetProxyTargets(
                             newt.newtId,
-                            targets,
+                            [target],
                             newt.version
                         )
                     );

server/lib/tokenCache.ts

@@ -0,0 +1,22 @@
+/**
+ * Returns a cached plaintext token from Redis if one exists and decrypts
+ * cleanly, otherwise calls `createSession` to mint a fresh token, stores the
+ * encrypted value in Redis with the given TTL, and returns it.
+ *
+ * Failures at the Redis layer are non-fatal – the function always falls
+ * through to session creation so the caller is never blocked by a Redis outage.
+ *
+ * @param cacheKey   Unique Redis key, e.g. `"newt:token_cache:abc123"`
+ * @param secret     Server secret used for AES encryption/decryption
+ * @param ttlSeconds Cache TTL in seconds (should match session expiry)
+ * @param createSession Factory that mints a new session and returns its raw token
+ */
+export async function getOrCreateCachedToken(
+    cacheKey: string,
+    secret: string,
+    ttlSeconds: number,
+    createSession: () => Promise<string>
+): Promise<string> {
+    const token = await createSession();
+    return token;
+}

server/private/cleanup.ts

@@ -15,8 +15,10 @@ import { rateLimitService } from "#private/lib/rateLimit";
 import { cleanup as wsCleanup } from "#private/routers/ws";
 import { flushBandwidthToDb } from "@server/routers/newt/handleReceiveBandwidthMessage";
 import { flushSiteBandwidthToDb } from "@server/routers/gerbil/receiveBandwidth";
+import { stopPingAccumulator } from "@server/routers/newt/pingAccumulator";
 
 async function cleanup() {
+    await stopPingAccumulator();
     await flushBandwidthToDb();
     await flushSiteBandwidthToDb();
     await rateLimitService.cleanup();

server/private/lib/cache.ts

@@ -1,3 +1,16 @@
+/*
+ * This file is part of a proprietary work.
+ *
+ * Copyright (c) 2025 Fossorial, Inc.
+ * All rights reserved.
+ *
+ * This file is licensed under the Fossorial Commercial License.
+ * You may not use this file except in compliance with the License.
+ * Unauthorized use, copying, modification, or distribution is strictly prohibited.
+ *
+ * This file is not licensed under the AGPLv3.
+ */
+
 import NodeCache from "node-cache";
 import logger from "@server/logger";
 import { redisManager } from "@server/private/lib/redis";

server/private/lib/readConfigFile.ts

@@ -57,7 +57,10 @@ export const privateConfigSchema = z.object({
         .object({
             host: z.string(),
             port: portSchema,
-            password: z.string().optional(),
+            password: z
+                .string()
+                .optional()
+                .transform(getEnvOrYaml("REDIS_PASSWORD")),
             db: z.int().nonnegative().optional().default(0),
             replicas: z
                 .array(

server/private/lib/tokenCache.ts

@@ -0,0 +1,77 @@
+/*
+ * This file is part of a proprietary work.
+ *
+ * Copyright (c) 2025 Fossorial, Inc.
+ * All rights reserved.
+ *
+ * This file is licensed under the Fossorial Commercial License.
+ * You may not use this file except in compliance with the License.
+ * Unauthorized use, copying, modification, or distribution is strictly prohibited.
+ *
+ * This file is not licensed under the AGPLv3.
+ */
+
+import redisManager from "#private/lib/redis";
+import { encrypt, decrypt } from "@server/lib/crypto";
+import logger from "@server/logger";
+
+/**
+ * Returns a cached plaintext token from Redis if one exists and decrypts
+ * cleanly, otherwise calls `createSession` to mint a fresh token, stores the
+ * encrypted value in Redis with the given TTL, and returns it.
+ *
+ * Failures at the Redis layer are non-fatal – the function always falls
+ * through to session creation so the caller is never blocked by a Redis outage.
+ *
+ * @param cacheKey   Unique Redis key, e.g. `"newt:token_cache:abc123"`
+ * @param secret     Server secret used for AES encryption/decryption
+ * @param ttlSeconds Cache TTL in seconds (should match session expiry)
+ * @param createSession Factory that mints a new session and returns its raw token
+ */
+export async function getOrCreateCachedToken(
+    cacheKey: string,
+    secret: string,
+    ttlSeconds: number,
+    createSession: () => Promise<string>
+): Promise<string> {
+    if (redisManager.isRedisEnabled()) {
+        try {
+            const cached = await redisManager.get(cacheKey);
+            if (cached) {
+                const token = decrypt(cached, secret);
+                if (token) {
+                    logger.debug(`Token cache hit for key: ${cacheKey}`);
+                    return token;
+                }
+                // Decryption produced an empty string – treat as a miss
+                logger.warn(
+                    `Token cache decryption returned empty string for key: ${cacheKey}, treating as miss`
+                );
+            }
+        } catch (e) {
+            logger.warn(
+                `Token cache read/decrypt failed for key ${cacheKey}, falling through to session creation:`,
+                e
+            );
+        }
+    }
+
+    const token = await createSession();
+
+    if (redisManager.isRedisEnabled()) {
+        try {
+            const encrypted = encrypt(token, secret);
+            await redisManager.set(cacheKey, encrypted, ttlSeconds);
+            logger.debug(
+                `Token cached in Redis for key: ${cacheKey} (TTL ${ttlSeconds}s)`
+            );
+        } catch (e) {
+            logger.warn(
+                `Token cache write failed for key ${cacheKey} (session was still created):`,
+                e
+            );
+        }
+    }
+
+    return token;
+}

server/private/routers/external.ts

@@ -26,6 +26,7 @@ import * as misc from "#private/routers/misc";
 import * as reKey from "#private/routers/re-key";
 import * as approval from "#private/routers/approvals";
 import * as ssh from "#private/routers/ssh";
+import * as user from "#private/routers/user";
 
 import {
     verifyOrgAccess,
@@ -33,7 +34,10 @@ import {
     verifyUserIsServerAdmin,
     verifySiteAccess,
     verifyClientAccess,
-    verifyLimits
+    verifyLimits,
+    verifyRoleAccess,
+    verifyUserAccess,
+    verifyUserCanSetUserOrgRoles
 } from "@server/middlewares";
 import { ActionsEnum } from "@server/auth/actions";
 import {
@@ -518,3 +522,33 @@ authenticated.post(
     // logActionAudit(ActionsEnum.signSshKey), // it is handled inside of the function below so we can include more metadata
     ssh.signSshKey
 );
+
+authenticated.post(
+    "/user/:userId/add-role/:roleId",
+    verifyRoleAccess,
+    verifyUserAccess,
+    verifyLimits,
+    verifyUserHasAction(ActionsEnum.addUserRole),
+    logActionAudit(ActionsEnum.addUserRole),
+    user.addUserRole
+);
+
+authenticated.delete(
+    "/user/:userId/remove-role/:roleId",
+    verifyRoleAccess,
+    verifyUserAccess,
+    verifyLimits,
+    verifyUserHasAction(ActionsEnum.removeUserRole),
+    logActionAudit(ActionsEnum.removeUserRole),
+    user.removeUserRole
+);
+
+authenticated.post(
+    "/user/:userId/org/:orgId/roles",
+    verifyOrgAccess,
+    verifyUserAccess,
+    verifyLimits,
+    verifyUserCanSetUserOrgRoles(),
+    logActionAudit(ActionsEnum.setUserOrgRoles),
+    user.setUserOrgRoles
+);

server/private/routers/integration.ts

@@ -20,8 +20,11 @@ import {
     verifyApiKeyIsRoot,
     verifyApiKeyOrgAccess,
     verifyApiKeyIdpAccess,
+    verifyApiKeyRoleAccess,
+    verifyApiKeyUserAccess,
     verifyLimits
 } from "@server/middlewares";
+import * as user from "#private/routers/user";
 import {
     verifyValidSubscription,
     verifyValidLicense
@@ -140,3 +143,23 @@ authenticated.get(
     verifyApiKeyHasAction(ActionsEnum.listIdps),
     orgIdp.listOrgIdps
 );
+
+authenticated.post(
+    "/user/:userId/add-role/:roleId",
+    verifyApiKeyRoleAccess,
+    verifyApiKeyUserAccess,
+    verifyLimits,
+    verifyApiKeyHasAction(ActionsEnum.addUserRole),
+    logActionAudit(ActionsEnum.addUserRole),
+    user.addUserRole
+);
+
+authenticated.delete(
+    "/user/:userId/remove-role/:roleId",
+    verifyApiKeyRoleAccess,
+    verifyApiKeyUserAccess,
+    verifyLimits,
+    verifyApiKeyHasAction(ActionsEnum.removeUserRole),
+    logActionAudit(ActionsEnum.removeUserRole),
+    user.removeUserRole
+);

server/private/routers/remoteExitNode/getRemoteExitNodeToken.ts

@@ -23,8 +23,10 @@ import { z } from "zod";
 import { fromError } from "zod-validation-error";
 import {
     createRemoteExitNodeSession,
-    validateRemoteExitNodeSessionToken
+    validateRemoteExitNodeSessionToken,
+    EXPIRES
 } from "#private/auth/sessions/remoteExitNode";
+import { getOrCreateCachedToken } from "@server/private/lib/tokenCache";
 import { verifyPassword } from "@server/auth/password";
 import logger from "@server/logger";
 import config from "@server/lib/config";
@@ -103,14 +105,23 @@ export async function getRemoteExitNodeToken(
             );
         }
 
-        const resToken = generateSessionToken();
-        await createRemoteExitNodeSession(
-            resToken,
-            existingRemoteExitNode.remoteExitNodeId
+        // Return a cached token if one exists to prevent thundering herd on
+        // simultaneous restarts; falls back to creating a fresh session when
+        // Redis is unavailable or the cache has expired.
+        const resToken = await getOrCreateCachedToken(
+            `remote_exit_node:token_cache:${existingRemoteExitNode.remoteExitNodeId}`,
+            config.getRawConfig().server.secret!,
+            Math.floor(EXPIRES / 1000),
+            async () => {
+                const token = generateSessionToken();
+                await createRemoteExitNodeSession(
+                    token,
+                    existingRemoteExitNode.remoteExitNodeId
+                );
+                return token;
+            }
         );
 
-        // logger.debug(`Created RemoteExitNode token response: ${JSON.stringify(resToken)}`);
-
         return response<{ token: string }>(res, {
             data: {
                 token: resToken

server/private/routers/ssh/signSshKey.ts

@@ -24,6 +24,7 @@ import {
     sites,
     userOrgs
 } from "@server/db";
+import { logAccessAudit } from "#private/lib/logAccessAudit";
 import { isLicensedOrSubscribed } from "#private/lib/isLicencedOrSubscribed";
 import { tierMatrix } from "@server/lib/billing/tierMatrix";
 import response from "@server/lib/response";
@@ -483,6 +484,24 @@ export async function signSshKey(
             })
         });
 
+        await logAccessAudit({
+            action: true,
+            type: "ssh",
+            orgId: orgId,
+            resourceId: resource.siteResourceId,
+            user: req.user
+                ? { username: req.user.username ?? "", userId: req.user.userId }
+                : undefined,
+            metadata: {
+                resourceName: resource.name,
+                siteId: resource.siteId,
+                sshUsername: usernameToUse,
+                sshHost: sshHost
+            },
+            userAgent: req.headers["user-agent"],
+            requestIp: req.ip
+        });
+
         return response<SignSshKeyResponse>(res, {
             data: {
                 certificate: cert.certificate,

server/private/routers/user/addUserRole.ts

@@ -1,5 +1,19 @@
+/*
+ * This file is part of a proprietary work.
+ *
+ * Copyright (c) 2025 Fossorial, Inc.
+ * All rights reserved.
+ *
+ * This file is licensed under the Fossorial Commercial License.
+ * You may not use this file except in compliance with the License.
+ * Unauthorized use, copying, modification, or distribution is strictly prohibited.
+ *
+ * This file is not licensed under the AGPLv3.
+ */
+
 import { Request, Response, NextFunction } from "express";
 import { z } from "zod";
+import stoi from "@server/lib/stoi";
 import { clients, db } from "@server/db";
 import { userOrgRoles, userOrgs, roles } from "@server/db";
 import { eq, and } from "drizzle-orm";
@@ -8,7 +22,6 @@ import HttpCode from "@server/types/HttpCode";
 import createHttpError from "http-errors";
 import logger from "@server/logger";
 import { fromError } from "zod-validation-error";
-import stoi from "@server/lib/stoi";
 import { OpenAPITags, registry } from "@server/openApi";
 import { rebuildClientAssociationsFromClient } from "@server/lib/rebuildClientAssociations";
 
@@ -17,11 +30,9 @@ const addUserRoleParamsSchema = z.strictObject({
     roleId: z.string().transform(stoi).pipe(z.number())
 });
 
-export type AddUserRoleResponse = z.infer<typeof addUserRoleParamsSchema>;
-
 registry.registerPath({
     method: "post",
-    path: "/role/{roleId}/add/{userId}",
+    path: "/user/{userId}/add-role/{roleId}",
     description: "Add a role to a user.",
     tags: [OpenAPITags.Role, OpenAPITags.User],
     request: {

server/private/routers/user/index.ts

@@ -0,0 +1,16 @@
+/*
+ * This file is part of a proprietary work.
+ *
+ * Copyright (c) 2025 Fossorial, Inc.
+ * All rights reserved.
+ *
+ * This file is licensed under the Fossorial Commercial License.
+ * You may not use this file except in compliance with the License.
+ * Unauthorized use, copying, modification, or distribution is strictly prohibited.
+ *
+ * This file is not licensed under the AGPLv3.
+ */
+
+export * from "./addUserRole";
+export * from "./removeUserRole";
+export * from "./setUserOrgRoles";

server/private/routers/user/removeUserRole.ts

@@ -1,5 +1,19 @@
+/*
+ * This file is part of a proprietary work.
+ *
+ * Copyright (c) 2025 Fossorial, Inc.
+ * All rights reserved.
+ *
+ * This file is licensed under the Fossorial Commercial License.
+ * You may not use this file except in compliance with the License.
+ * Unauthorized use, copying, modification, or distribution is strictly prohibited.
+ *
+ * This file is not licensed under the AGPLv3.
+ */
+
 import { Request, Response, NextFunction } from "express";
 import { z } from "zod";
+import stoi from "@server/lib/stoi";
 import { db } from "@server/db";
 import { userOrgRoles, userOrgs, roles, clients } from "@server/db";
 import { eq, and } from "drizzle-orm";
@@ -8,7 +22,6 @@ import HttpCode from "@server/types/HttpCode";
 import createHttpError from "http-errors";
 import logger from "@server/logger";
 import { fromError } from "zod-validation-error";
-import stoi from "@server/lib/stoi";
 import { OpenAPITags, registry } from "@server/openApi";
 import { rebuildClientAssociationsFromClient } from "@server/lib/rebuildClientAssociations";
 
@@ -19,8 +32,9 @@ const removeUserRoleParamsSchema = z.strictObject({
 
 registry.registerPath({
     method: "delete",
-    path: "/role/{roleId}/remove/{userId}",
-    description: "Remove a role from a user. User must have at least one role left in the org.",
+    path: "/user/{userId}/remove-role/{roleId}",
+    description:
+        "Remove a role from a user. User must have at least one role left in the org.",
     tags: [OpenAPITags.Role, OpenAPITags.User],
     request: {
         params: removeUserRoleParamsSchema

server/private/routers/user/setUserOrgRoles.ts

@@ -1,3 +1,16 @@
+/*
+ * This file is part of a proprietary work.
+ *
+ * Copyright (c) 2025 Fossorial, Inc.
+ * All rights reserved.
+ *
+ * This file is licensed under the Fossorial Commercial License.
+ * You may not use this file except in compliance with the License.
+ * Unauthorized use, copying, modification, or distribution is strictly prohibited.
+ *
+ * This file is not licensed under the AGPLv3.
+ */
+
 import { Request, Response, NextFunction } from "express";
 import { z } from "zod";
 import { clients, db } from "@server/db";
@@ -8,7 +21,6 @@ import HttpCode from "@server/types/HttpCode";
 import createHttpError from "http-errors";
 import logger from "@server/logger";
 import { fromError } from "zod-validation-error";
-import { OpenAPITags, registry } from "@server/openApi";
 import { rebuildClientAssociationsFromClient } from "@server/lib/rebuildClientAssociations";
 
 const setUserOrgRolesParamsSchema = z.strictObject({

server/private/routers/ws/ws.ts

@@ -19,17 +19,14 @@ import { Socket } from "net";
 import {
     Newt,
     newts,
-    NewtSession,
-    olms,
     Olm,
-    OlmSession,
+    olms,
     RemoteExitNode,
-    RemoteExitNodeSession,
     remoteExitNodes,
-    sites
 } from "@server/db";
 import { eq } from "drizzle-orm";
 import { db } from "@server/db";
+import { recordPing } from "@server/routers/newt/pingAccumulator";
 import { validateNewtSessionToken } from "@server/auth/sessions/newt";
 import { validateOlmSessionToken } from "@server/auth/sessions/olm";
 import logger from "@server/logger";
@@ -197,11 +194,7 @@ const connectedClients: Map<string, AuthenticatedWebSocket[]> = new Map();
 // Config version tracking map (local to this node, resets on server restart)
 const clientConfigVersions: Map<string, number> = new Map();
 
-// Tracks the last Unix timestamp (seconds) at which a ping was flushed to the
-// DB for a given siteId. Resets on server restart which is fine – the first
-// ping after startup will always write, re-establishing the online state.
-const lastPingDbWrite: Map<number, number> = new Map();
-const PING_DB_WRITE_INTERVAL = 45; // seconds
+
 
 // Recovery tracking
 let isRedisRecoveryInProgress = false;
@@ -853,32 +846,16 @@ const setupConnection = async (
         );
     });
 
-    // Handle WebSocket protocol-level pings from older newt clients that do
-    // not send application-level "newt/ping" messages. Update the site's
-    // online state and lastPing timestamp so the offline checker treats them
-    // the same as modern newt clients.
     if (clientType === "newt") {
         const newtClient = client as Newt;
-        ws.on("ping", async () => {
+        ws.on("ping", () => {
             if (!newtClient.siteId) return;
-            const now = Math.floor(Date.now() / 1000);
-            const lastWrite = lastPingDbWrite.get(newtClient.siteId) ?? 0;
-            if (now - lastWrite < PING_DB_WRITE_INTERVAL) return;
-            lastPingDbWrite.set(newtClient.siteId, now);
-            try {
-                await db
-                    .update(sites)
-                    .set({
-                        online: true,
-                        lastPing: now
-                    })
-                    .where(eq(sites.siteId, newtClient.siteId));
-            } catch (error) {
-                logger.error(
-                    "Error updating newt site online state on WS ping",
-                    { error }
-                );
-            }
+            // Record the ping in the accumulator instead of writing to the
+            // database on every WS ping frame. The accumulator flushes all
+            // pending pings in a single batched UPDATE every ~10s, which
+            // prevents connection pool exhaustion under load (especially
+            // with cross-region latency to the database).
+            recordPing(newtClient.siteId);
         });
     }
 

server/routers/client/targets.ts

@@ -1,15 +1,54 @@
 import { sendToClient } from "#dynamic/routers/ws";
-import { db, olms, Transaction } from "@server/db";
+import { db, newts, olms } from "@server/db";
+import {
+    Alias,
+    convertSubnetProxyTargetsV2ToV1,
+    SubnetProxyTarget,
+    SubnetProxyTargetV2
+} from "@server/lib/ip";
 import { canCompress } from "@server/lib/clientVersionChecks";
-import { Alias, SubnetProxyTarget } from "@server/lib/ip";
 import logger from "@server/logger";
 import { eq } from "drizzle-orm";
+import semver from "semver";
+
+const NEWT_V2_TARGETS_VERSION = ">=1.10.3";
+
+export async function convertTargetsIfNessicary(
+    newtId: string,
+    targets: SubnetProxyTarget[] | SubnetProxyTargetV2[]
+) {
+    // get the newt
+    const [newt] = await db
+        .select()
+        .from(newts)
+        .where(eq(newts.newtId, newtId));
+    if (!newt) {
+        throw new Error(`No newt found for id: ${newtId}`);
+    }
+
+    // check the semver
+    if (
+        newt.version &&
+        !semver.satisfies(newt.version, NEWT_V2_TARGETS_VERSION)
+    ) {
+        logger.debug(
+            `addTargets Newt version ${newt.version} does not support targets v2 falling back`
+        );
+        targets = convertSubnetProxyTargetsV2ToV1(
+            targets as SubnetProxyTargetV2[]
+        );
+    }
+
+    return targets;
+}
 
 export async function addTargets(
     newtId: string,
-    targets: SubnetProxyTarget[],
+    targets: SubnetProxyTarget[] | SubnetProxyTargetV2[],
     version?: string | null
 ) {
+    targets = await convertTargetsIfNessicary(newtId, targets);
+
     await sendToClient(
         newtId,
         {
@@ -22,9 +61,11 @@ export async function addTargets(
 
 export async function removeTargets(
     newtId: string,
-    targets: SubnetProxyTarget[],
+    targets: SubnetProxyTarget[] | SubnetProxyTargetV2[],
     version?: string | null
 ) {
+    targets = await convertTargetsIfNessicary(newtId, targets);
+
     await sendToClient(
         newtId,
         {
@@ -38,11 +79,39 @@ export async function removeTargets(
 export async function updateTargets(
     newtId: string,
     targets: {
-        oldTargets: SubnetProxyTarget[];
-        newTargets: SubnetProxyTarget[];
+        oldTargets: SubnetProxyTarget[] | SubnetProxyTargetV2[];
+        newTargets: SubnetProxyTarget[] | SubnetProxyTargetV2[];
     },
     version?: string | null
 ) {
+    // get the newt
+    const [newt] = await db
+        .select()
+        .from(newts)
+        .where(eq(newts.newtId, newtId));
+    if (!newt) {
+        logger.error(`addTargetsL No newt found for id: ${newtId}`);
+        return;
+    }
+
+    // check the semver
+    if (
+        newt.version &&
+        !semver.satisfies(newt.version, NEWT_V2_TARGETS_VERSION)
+    ) {
+        logger.debug(
+            `addTargets Newt version ${newt.version} does not support targets v2 falling back`
+        );
+        targets = {
+            oldTargets: convertSubnetProxyTargetsV2ToV1(
+                targets.oldTargets as SubnetProxyTargetV2[]
+            ),
+            newTargets: convertSubnetProxyTargetsV2ToV1(
+                targets.newTargets as SubnetProxyTargetV2[]
+            )
+        };
+    }
+
     await sendToClient(
         newtId,
         {

server/routers/external.ts

@@ -39,7 +39,6 @@ import {
     verifyApiKeyAccess,
     verifyDomainAccess,
     verifyUserHasAction,
-    verifyUserCanSetUserOrgRoles,
     verifyUserIsOrgOwner,
     verifySiteResourceAccess,
     verifyOlmAccess,
@@ -645,6 +644,7 @@ authenticated.delete(
     logActionAudit(ActionsEnum.deleteRole),
     role.deleteRole
 );
+
 authenticated.post(
     "/role/:roleId/add/:userId",
     verifyRoleAccess,
@@ -652,17 +652,7 @@ authenticated.post(
     verifyLimits,
     verifyUserHasAction(ActionsEnum.addUserRole),
     logActionAudit(ActionsEnum.addUserRole),
-    user.addUserRole
-);
-
-authenticated.delete(
-    "/role/:roleId/remove/:userId",
-    verifyRoleAccess,
-    verifyUserAccess,
-    verifyLimits,
-    verifyUserHasAction(ActionsEnum.removeUserRole),
-    logActionAudit(ActionsEnum.removeUserRole),
-    user.removeUserRole
+    user.addUserRoleLegacy
 );
 
 authenticated.post(
@@ -838,16 +828,6 @@ authenticated.post(
     user.updateOrgUser
 );
 
-authenticated.post(
-    "/org/:orgId/user/:userId/roles",
-    verifyOrgAccess,
-    verifyUserAccess,
-    verifyLimits,
-    verifyUserCanSetUserOrgRoles(),
-    logActionAudit(ActionsEnum.setUserOrgRoles),
-    user.setUserOrgRoles
-);
-
 authenticated.get("/org/:orgId/user/:userId", verifyOrgAccess, user.getOrgUser);
 authenticated.get("/org/:orgId/user/:userId/check", org.checkOrgUserAccess);
 

server/routers/gerbil/receiveBandwidth.ts

@@ -1,6 +1,5 @@
 import { Request, Response, NextFunction } from "express";
-import { eq, sql } from "drizzle-orm";
-import { sites } from "@server/db";
+import { sql } from "drizzle-orm";
 import { db } from "@server/db";
 import logger from "@server/logger";
 import createHttpError from "http-errors";
@@ -31,7 +30,10 @@ const MAX_RETRIES = 3;
 const BASE_DELAY_MS = 50;
 
 // How often to flush accumulated bandwidth data to the database
-const FLUSH_INTERVAL_MS = 30_000; // 30 seconds
+const FLUSH_INTERVAL_MS = 300_000; // 300 seconds
+
+// Maximum number of sites to include in a single batch UPDATE statement
+const BATCH_CHUNK_SIZE = 250;
 
 // In-memory accumulator: publicKey -> AccumulatorEntry
 let accumulator = new Map<string, AccumulatorEntry>();
@@ -75,13 +77,33 @@ async function withDeadlockRetry<T>(
     }
 }
 
+/**
+ * Execute a raw SQL query that returns rows, in a way that works across both
+ * the PostgreSQL driver (which exposes `execute`) and the SQLite driver (which
+ * exposes `all`).  Drizzle's typed query builder doesn't support bulk
+ * UPDATE … FROM (VALUES …) natively, so we drop to raw SQL here.
+ */
+async function dbQueryRows<T extends Record<string, unknown>>(
+    query: Parameters<(typeof sql)["join"]>[0][number]
+): Promise<T[]> {
+    const anyDb = db as any;
+    if (typeof anyDb.execute === "function") {
+        // PostgreSQL (node-postgres via Drizzle) — returns { rows: [...] } or an array
+        const result = await anyDb.execute(query);
+        return (Array.isArray(result) ? result : (result.rows ?? [])) as T[];
+    }
+    // SQLite (better-sqlite3 via Drizzle) — returns an array directly
+    return (await anyDb.all(query)) as T[];
+}
+
 /**
  * Flush all accumulated site bandwidth data to the database.
  *
  * Swaps out the accumulator before writing so that any bandwidth messages
  * received during the flush are captured in the new accumulator rather than
- * being lost or causing contention. Entries that fail to write are re-queued
- * back into the accumulator so they will be retried on the next flush.
+ * being lost or causing contention. Sites are updated in chunks via a single
+ * batch UPDATE per chunk. Failed chunks are discarded — exact per-flush
+ * accuracy is not critical and re-queuing is not worth the added complexity.
  *
  * This function is exported so that the application's graceful-shutdown
  * cleanup handler can call it before the process exits.
@@ -108,76 +130,76 @@ export async function flushSiteBandwidthToDb(): Promise<void> {
         `Flushing accumulated bandwidth data for ${sortedEntries.length} site(s) to the database`
     );
 
-    // Aggregate billing usage by org, collected during the DB update loop.
+    // Build a lookup so post-processing can reach each entry by publicKey.
+    const snapshotMap = new Map(sortedEntries);
+
+    // Aggregate billing usage by org across all chunks.
     const orgUsageMap = new Map<string, number>();
 
-    for (const [publicKey, { bytesIn, bytesOut, exitNodeId, calcUsage }] of sortedEntries) {
+    // Process in chunks so individual queries stay at a reasonable size.
+    for (let i = 0; i < sortedEntries.length; i += BATCH_CHUNK_SIZE) {
+        const chunk = sortedEntries.slice(i, i + BATCH_CHUNK_SIZE);
+        const chunkEnd = i + chunk.length - 1;
+
+        // Build a parameterised VALUES list: (pubKey, bytesIn, bytesOut), ...
+        // Both PostgreSQL and SQLite (≥ 3.33.0, which better-sqlite3 bundles)
+        // support UPDATE … FROM (VALUES …), letting us update the whole chunk
+        // in a single query instead of N individual round-trips.
+        const valuesList = chunk.map(([publicKey, { bytesIn, bytesOut }]) =>
+            sql`(${publicKey}, ${bytesIn}, ${bytesOut})`
+        );
+        const valuesClause = sql.join(valuesList, sql`, `);
+
+        let rows: { orgId: string; pubKey: string }[] = [];
+
         try {
-            const updatedSite = await withDeadlockRetry(async () => {
-                const [result] = await db
-                    .update(sites)
-                    .set({
-                        megabytesOut: sql`COALESCE(${sites.megabytesOut}, 0) + ${bytesIn}`,
-                        megabytesIn: sql`COALESCE(${sites.megabytesIn}, 0) + ${bytesOut}`,
-                        lastBandwidthUpdate: currentTime,
-                    })
-                    .where(eq(sites.pubKey, publicKey))
-                    .returning({
-                        orgId: sites.orgId,
-                        siteId: sites.siteId
-                    });
-                return result;
-            }, `flush bandwidth for site ${publicKey}`);
-
-            if (updatedSite) {
-                if (exitNodeId) {
-                    const notAllowed = await checkExitNodeOrg(
-                        exitNodeId,
-                        updatedSite.orgId
-                    );
-                    if (notAllowed) {
-                        logger.warn(
-                            `Exit node ${exitNodeId} is not allowed for org ${updatedSite.orgId}`
-                        );
-                        // Skip usage tracking for this site but continue
-                        // processing the rest.
-                        continue;
-                    }
-                }
-
-                if (calcUsage) {
-                    const totalBandwidth = bytesIn + bytesOut;
-                    const current = orgUsageMap.get(updatedSite.orgId) ?? 0;
-                    orgUsageMap.set(updatedSite.orgId, current + totalBandwidth);
-                }
-            }
+            rows = await withDeadlockRetry(async () => {
+                return dbQueryRows<{ orgId: string; pubKey: string }>(sql`
+                    UPDATE sites
+                    SET
+                        "bytesOut"            = COALESCE("bytesOut", 0) + v.bytes_in,
+                        "bytesIn"             = COALESCE("bytesIn", 0)  + v.bytes_out,
+                        "lastBandwidthUpdate" = ${currentTime}
+                    FROM (VALUES ${valuesClause}) AS v(pub_key, bytes_in, bytes_out)
+                    WHERE sites."pubKey" = v.pub_key
+                    RETURNING sites."orgId" AS "orgId", sites."pubKey" AS "pubKey"
+                `);
+            }, `flush bandwidth chunk [${i}–${chunkEnd}]`);
         } catch (error) {
             logger.error(
-                `Failed to flush bandwidth for site ${publicKey}:`,
+                `Failed to flush bandwidth chunk [${i}–${chunkEnd}], discarding ${chunk.length} site(s):`,
                 error
             );
+            // Discard the chunk — exact per-flush accuracy is not critical.
+            continue;
+        }
 
-            // Re-queue the failed entry so it is retried on the next flush
-            // rather than silently dropped.
-            const existing = accumulator.get(publicKey);
-            if (existing) {
-                existing.bytesIn += bytesIn;
-                existing.bytesOut += bytesOut;
-            } else {
-                accumulator.set(publicKey, {
-                    bytesIn,
-                    bytesOut,
-                    exitNodeId,
-                    calcUsage
-                });
+        // Collect billing usage from the returned rows.
+        for (const { orgId, pubKey } of rows) {
+            const entry = snapshotMap.get(pubKey);
+            if (!entry) continue;
+
+            const { bytesIn, bytesOut, exitNodeId, calcUsage } = entry;
+
+            if (exitNodeId) {
+                const notAllowed = await checkExitNodeOrg(exitNodeId, orgId);
+                if (notAllowed) {
+                    logger.warn(
+                        `Exit node ${exitNodeId} is not allowed for org ${orgId}`
+                    );
+                    continue;
+                }
+            }
+
+            if (calcUsage) {
+                const current = orgUsageMap.get(orgId) ?? 0;
+                orgUsageMap.set(orgId, current + bytesIn + bytesOut);
             }
         }
     }
 
-    // Process billing usage updates outside the site-update loop to keep
-    // lock scope small and concerns separated.
+    // Process billing usage updates after all chunks are written.
     if (orgUsageMap.size > 0) {
-        // Sort org IDs for consistent lock ordering.
         const sortedOrgIds = [...orgUsageMap.keys()].sort();
 
         for (const orgId of sortedOrgIds) {

server/routers/idp/validateOidcCallback.ts

@@ -41,6 +41,7 @@ import {
     assignUserToOrg,
     removeUserFromOrg
 } from "@server/lib/userOrg";
+import { unwrapRoleMapping } from "@app/lib/idpRoleMapping";
 
 const ensureTrailingSlash = (url: string): string => {
     return url;
@@ -367,7 +368,7 @@ export async function validateOidcCallback(
             const defaultRoleMapping = existingIdp.idp.defaultRoleMapping;
             const defaultOrgMapping = existingIdp.idp.defaultOrgMapping;
 
-            const userOrgInfo: { orgId: string; roleId: number }[] = [];
+            const userOrgInfo: { orgId: string; roleIds: number[] }[] = [];
             for (const org of allOrgs) {
                 const [idpOrgRes] = await db
                     .select()
@@ -379,8 +380,6 @@ export async function validateOidcCallback(
                         )
                     );
 
-                let roleId: number | undefined = undefined;
-
                 const orgMapping = idpOrgRes?.orgMapping || defaultOrgMapping;
                 const hydratedOrgMapping = hydrateOrgMapping(
                     orgMapping,
@@ -405,38 +404,47 @@ export async function validateOidcCallback(
                     idpOrgRes?.roleMapping || defaultRoleMapping;
                 if (roleMapping) {
                     logger.debug("Role Mapping", { roleMapping });
-                    const roleName = jmespath.search(claims, roleMapping);
+                    const roleMappingJmes = unwrapRoleMapping(
+                        roleMapping
+                    ).evaluationExpression;
+                    const roleMappingResult = jmespath.search(
+                        claims,
+                        roleMappingJmes
+                    );
+                    const roleNames = normalizeRoleMappingResult(
+                        roleMappingResult
+                    );
 
-                    if (!roleName) {
-                        logger.error("Role name not found in the ID token", {
-                            roleName
+                    if (!roleNames.length) {
+                        logger.error("Role mapping returned no valid roles", {
+                            roleMappingResult
                         });
                         continue;
                     }
 
-                    const [roleRes] = await db
+                    const roleRes = await db
                         .select()
                         .from(roles)
                         .where(
                             and(
                                 eq(roles.orgId, org.orgId),
-                                eq(roles.name, roleName)
+                                inArray(roles.name, roleNames)
                             )
                         );
 
-                    if (!roleRes) {
-                        logger.error("Role not found", {
+                    if (!roleRes.length) {
+                        logger.error("No mapped roles found in organization", {
                             orgId: org.orgId,
-                            roleName
+                            roleNames
                         });
                         continue;
                     }
 
-                    roleId = roleRes.roleId;
+                    const roleIds = [...new Set(roleRes.map((r) => r.roleId))];
 
                     userOrgInfo.push({
                         orgId: org.orgId,
-                        roleId
+                        roleIds
                     });
                 }
             }
@@ -584,15 +592,17 @@ export async function validateOidcCallback(
                     const currentRolesInOrg = userRolesInOrgs.filter(
                         (r) => r.orgId === currentOrg.orgId
                     );
-                    const hasIdpRole = currentRolesInOrg.some(
-                        (r) => r.roleId === newRole.roleId
-                    );
-                    if (!hasIdpRole) {
-                        await trx.insert(userOrgRoles).values({
-                            userId: userId!,
-                            orgId: currentOrg.orgId,
-                            roleId: newRole.roleId
-                        });
+                    for (const roleId of newRole.roleIds) {
+                        const hasIdpRole = currentRolesInOrg.some(
+                            (r) => r.roleId === roleId
+                        );
+                        if (!hasIdpRole) {
+                            await trx.insert(userOrgRoles).values({
+                                userId: userId!,
+                                orgId: currentOrg.orgId,
+                                roleId
+                            });
+                        }
                     }
                 }
 
@@ -606,6 +616,12 @@ export async function validateOidcCallback(
 
                 if (orgsToAdd.length > 0) {
                     for (const org of orgsToAdd) {
+                        const [initialRoleId, ...additionalRoleIds] =
+                            org.roleIds;
+                        if (!initialRoleId) {
+                            continue;
+                        }
+
                         const [fullOrg] = await trx
                             .select()
                             .from(orgs)
@@ -618,9 +634,17 @@ export async function validateOidcCallback(
                                     userId: userId!,
                                     autoProvisioned: true,
                                 },
-                                org.roleId,
+                                initialRoleId,
                                 trx
                             );
+
+                            for (const roleId of additionalRoleIds) {
+                                await trx.insert(userOrgRoles).values({
+                                    userId: userId!,
+                                    orgId: org.orgId,
+                                    roleId
+                                });
+                            }
                         }
                     }
                 }
@@ -745,3 +769,25 @@ function hydrateOrgMapping(
     }
     return orgMapping.split("{{orgId}}").join(orgId);
 }
+
+function normalizeRoleMappingResult(
+    result: unknown
+): string[] {
+    if (typeof result === "string") {
+        const role = result.trim();
+        return role ? [role] : [];
+    }
+
+    if (Array.isArray(result)) {
+        return [
+            ...new Set(
+                result
+                    .filter((value): value is string => typeof value === "string")
+                    .map((value) => value.trim())
+                    .filter(Boolean)
+            )
+        ];
+    }
+
+    return [];
+}

server/routers/integration.ts

@@ -596,17 +596,7 @@ authenticated.post(
     verifyLimits,
     verifyApiKeyHasAction(ActionsEnum.addUserRole),
     logActionAudit(ActionsEnum.addUserRole),
-    user.addUserRole
-);
-
-authenticated.delete(
-    "/role/:roleId/remove/:userId",
-    verifyApiKeyRoleAccess,
-    verifyApiKeyUserAccess,
-    verifyLimits,
-    verifyApiKeyHasAction(ActionsEnum.removeUserRole),
-    logActionAudit(ActionsEnum.removeUserRole),
-    user.removeUserRole
+    user.addUserRoleLegacy
 );
 
 authenticated.post(
@@ -815,16 +805,6 @@ authenticated.post(
     user.updateOrgUser
 );
 
-authenticated.post(
-    "/org/:orgId/user/:userId/roles",
-    verifyApiKeyOrgAccess,
-    verifyApiKeyUserAccess,
-    verifyLimits,
-    verifyApiKeyCanSetUserOrgRoles(),
-    logActionAudit(ActionsEnum.setUserOrgRoles),
-    user.setUserOrgRoles
-);
-
 authenticated.delete(
     "/org/:orgId/user/:userId",
     verifyApiKeyOrgAccess,

server/routers/newt/buildConfiguration.ts

@@ -16,8 +16,8 @@ import { eq, and } from "drizzle-orm";
 import config from "@server/lib/config";
 import {
     formatEndpoint,
-    generateSubnetProxyTargets,
-    SubnetProxyTarget
+    generateSubnetProxyTargetV2,
+    SubnetProxyTargetV2
 } from "@server/lib/ip";
 
 export async function buildClientConfigurationForNewtClient(
@@ -143,7 +143,7 @@ export async function buildClientConfigurationForNewtClient(
         .from(siteResources)
         .where(eq(siteResources.siteId, siteId));
 
-    const targetsToSend: SubnetProxyTarget[] = [];
+    const targetsToSend: SubnetProxyTargetV2[] = [];
 
     for (const resource of allSiteResources) {
         // Get clients associated with this specific resource
@@ -168,12 +168,14 @@ export async function buildClientConfigurationForNewtClient(
                 )
             );
 
-        const resourceTargets = generateSubnetProxyTargets(
+        const resourceTarget = generateSubnetProxyTargetV2(
             resource,
             resourceClients
         );
 
-        targetsToSend.push(...resourceTargets);
+        if (resourceTarget) {
+            targetsToSend.push(resourceTarget);
+        }
     }
 
     return {

server/routers/newt/getNewtToken.ts

@@ -1,6 +1,8 @@
 import { generateSessionToken } from "@server/auth/sessions/app";
-import { db } from "@server/db";
+import { db, newtSessions } from "@server/db";
 import { newts } from "@server/db";
+import { getOrCreateCachedToken } from "#dynamic/lib/tokenCache";
+import { EXPIRES } from "@server/auth/sessions/newt";
 import HttpCode from "@server/types/HttpCode";
 import response from "@server/lib/response";
 import { eq } from "drizzle-orm";
@@ -92,8 +94,19 @@ export async function getNewtToken(
             );
         }
 
-        const resToken = generateSessionToken();
-        await createNewtSession(resToken, existingNewt.newtId);
+        // Return a cached token if one exists to prevent thundering herd on
+        // simultaneous restarts; falls back to creating a fresh session when
+        // Redis is unavailable or the cache has expired.
+        const resToken = await getOrCreateCachedToken(
+            `newt:token_cache:${existingNewt.newtId}`,
+            config.getRawConfig().server.secret!,
+            Math.floor(EXPIRES / 1000),
+            async () => {
+                const token = generateSessionToken();
+                await createNewtSession(token, existingNewt.newtId);
+                return token;
+            }
+        );
 
         return response<{ token: string; serverVersion: string }>(res, {
             data: {

server/routers/newt/handleGetConfigMessage.ts

@@ -6,6 +6,7 @@ import { db, ExitNode, exitNodes, Newt, sites } from "@server/db";
 import { eq } from "drizzle-orm";
 import { sendToExitNode } from "#dynamic/lib/exitNodes";
 import { buildClientConfigurationForNewtClient } from "./buildConfiguration";
+import { convertTargetsIfNessicary } from "../client/targets";
 import { canCompress } from "@server/lib/clientVersionChecks";
 
 const inputSchema = z.object({
@@ -127,13 +128,15 @@ export const handleGetConfigMessage: MessageHandler = async (context) => {
         exitNode
     );
 
+    const targetsToSend = await convertTargetsIfNessicary(newt.newtId, targets);
+
     return {
         message: {
             type: "newt/wg/receive-config",
             data: {
                 ipAddress: site.address,
                 peers,
-                targets
+                targets: targetsToSend
             }
         },
         options: {

server/routers/newt/handleNewtPingMessage.ts

@@ -5,6 +5,7 @@ import { Newt } from "@server/db";
 import { eq, lt, isNull, and, or } from "drizzle-orm";
 import logger from "@server/logger";
 import { sendNewtSyncMessage } from "./sync";
+import { recordPing } from "./pingAccumulator";
 
 // Track if the offline checker interval is running
 let offlineCheckerInterval: NodeJS.Timeout | null = null;
@@ -114,18 +115,12 @@ export const handleNewtPingMessage: MessageHandler = async (context) => {
         return;
     }
 
-    try {
-        // Mark the site as online and record the ping timestamp.
-        await db
-            .update(sites)
-            .set({
-                online: true,
-                lastPing: Math.floor(Date.now() / 1000)
-            })
-            .where(eq(sites.siteId, newt.siteId));
-    } catch (error) {
-        logger.error("Error updating online state on newt ping", { error });
-    }
+    // Record the ping in memory; it will be flushed to the database
+    // periodically by the ping accumulator (every ~10s) in a single
+    // batched UPDATE instead of one query per ping. This prevents
+    // connection pool exhaustion under load, especially with
+    // cross-region latency to the database.
+    recordPing(newt.siteId);
 
     // Check config version and sync if stale.
     const configVersion = await getClientConfigVersion(newt.newtId);

server/routers/newt/pingAccumulator.ts

@@ -0,0 +1,382 @@
+import { db } from "@server/db";
+import { sites, clients, olms } from "@server/db";
+import { eq, inArray } from "drizzle-orm";
+import logger from "@server/logger";
+
+/**
+ * Ping Accumulator
+ *
+ * Instead of writing to the database on every single newt/olm ping (which
+ * causes pool exhaustion under load, especially with cross-region latency),
+ * we accumulate pings in memory and flush them to the database periodically
+ * in a single batch.
+ *
+ * This is the same pattern used for bandwidth flushing in
+ * receiveBandwidth.ts and handleReceiveBandwidthMessage.ts.
+ *
+ * Supports two kinds of pings:
+ *   - **Site pings** (from newts): update `sites.online` and `sites.lastPing`
+ *   - **Client pings** (from OLMs): update `clients.online`, `clients.lastPing`,
+ *     `clients.archived`, and optionally reset `olms.archived`
+ */
+
+const FLUSH_INTERVAL_MS = 10_000; // Flush every 10 seconds
+const MAX_RETRIES = 2;
+const BASE_DELAY_MS = 50;
+
+// ── Site (newt) pings ──────────────────────────────────────────────────
+// Map of siteId -> latest ping timestamp (unix seconds)
+const pendingSitePings: Map<number, number> = new Map();
+
+// ── Client (OLM) pings ────────────────────────────────────────────────
+// Map of clientId -> latest ping timestamp (unix seconds)
+const pendingClientPings: Map<number, number> = new Map();
+// Set of olmIds whose `archived` flag should be reset to false
+const pendingOlmArchiveResets: Set<string> = new Set();
+
+let flushTimer: NodeJS.Timeout | null = null;
+
+// ── Public API ─────────────────────────────────────────────────────────
+
+/**
+ * Record a ping for a newt site. This does NOT write to the database
+ * immediately. Instead it stores the latest ping timestamp in memory,
+ * to be flushed periodically by the background timer.
+ */
+export function recordSitePing(siteId: number): void {
+    const now = Math.floor(Date.now() / 1000);
+    pendingSitePings.set(siteId, now);
+}
+
+/** @deprecated Use `recordSitePing` instead. Alias kept for existing call-sites. */
+export const recordPing = recordSitePing;
+
+/**
+ * Record a ping for an OLM client. Batches the `clients` table update
+ * (`online`, `lastPing`, `archived`) and, when `olmArchived` is true,
+ * also queues an `olms` table update to clear the archived flag.
+ */
+export function recordClientPing(
+    clientId: number,
+    olmId: string,
+    olmArchived: boolean
+): void {
+    const now = Math.floor(Date.now() / 1000);
+    pendingClientPings.set(clientId, now);
+    if (olmArchived) {
+        pendingOlmArchiveResets.add(olmId);
+    }
+}
+
+// ── Flush Logic ────────────────────────────────────────────────────────
+
+/**
+ * Flush all accumulated site pings to the database.
+ */
+async function flushSitePingsToDb(): Promise<void> {
+    if (pendingSitePings.size === 0) {
+        return;
+    }
+
+    // Snapshot and clear so new pings arriving during the flush go into a
+    // fresh map for the next cycle.
+    const pingsToFlush = new Map(pendingSitePings);
+    pendingSitePings.clear();
+
+    // Sort by siteId for consistent lock ordering (prevents deadlocks)
+    const sortedEntries = Array.from(pingsToFlush.entries()).sort(
+        ([a], [b]) => a - b
+    );
+
+    const BATCH_SIZE = 50;
+    for (let i = 0; i < sortedEntries.length; i += BATCH_SIZE) {
+        const batch = sortedEntries.slice(i, i + BATCH_SIZE);
+
+        try {
+            await withRetry(async () => {
+                // Group by timestamp for efficient bulk updates
+                const byTimestamp = new Map<number, number[]>();
+                for (const [siteId, timestamp] of batch) {
+                    const group = byTimestamp.get(timestamp) || [];
+                    group.push(siteId);
+                    byTimestamp.set(timestamp, group);
+                }
+
+                if (byTimestamp.size === 1) {
+                    const [timestamp, siteIds] = Array.from(
+                        byTimestamp.entries()
+                    )[0];
+                    await db
+                        .update(sites)
+                        .set({
+                            online: true,
+                            lastPing: timestamp
+                        })
+                        .where(inArray(sites.siteId, siteIds));
+                } else {
+                    await db.transaction(async (tx) => {
+                        for (const [timestamp, siteIds] of byTimestamp) {
+                            await tx
+                                .update(sites)
+                                .set({
+                                    online: true,
+                                    lastPing: timestamp
+                                })
+                                .where(inArray(sites.siteId, siteIds));
+                        }
+                    });
+                }
+            }, "flushSitePingsToDb");
+        } catch (error) {
+            logger.error(
+                `Failed to flush site ping batch (${batch.length} sites), re-queuing for next cycle`,
+                { error }
+            );
+            for (const [siteId, timestamp] of batch) {
+                const existing = pendingSitePings.get(siteId);
+                if (!existing || existing < timestamp) {
+                    pendingSitePings.set(siteId, timestamp);
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Flush all accumulated client (OLM) pings to the database.
+ */
+async function flushClientPingsToDb(): Promise<void> {
+    if (pendingClientPings.size === 0 && pendingOlmArchiveResets.size === 0) {
+        return;
+    }
+
+    // Snapshot and clear
+    const pingsToFlush = new Map(pendingClientPings);
+    pendingClientPings.clear();
+
+    const olmResetsToFlush = new Set(pendingOlmArchiveResets);
+    pendingOlmArchiveResets.clear();
+
+    // ── Flush client pings ─────────────────────────────────────────────
+    if (pingsToFlush.size > 0) {
+        const sortedEntries = Array.from(pingsToFlush.entries()).sort(
+            ([a], [b]) => a - b
+        );
+
+        const BATCH_SIZE = 50;
+        for (let i = 0; i < sortedEntries.length; i += BATCH_SIZE) {
+            const batch = sortedEntries.slice(i, i + BATCH_SIZE);
+
+            try {
+                await withRetry(async () => {
+                    const byTimestamp = new Map<number, number[]>();
+                    for (const [clientId, timestamp] of batch) {
+                        const group = byTimestamp.get(timestamp) || [];
+                        group.push(clientId);
+                        byTimestamp.set(timestamp, group);
+                    }
+
+                    if (byTimestamp.size === 1) {
+                        const [timestamp, clientIds] = Array.from(
+                            byTimestamp.entries()
+                        )[0];
+                        await db
+                            .update(clients)
+                            .set({
+                                lastPing: timestamp,
+                                online: true,
+                                archived: false
+                            })
+                            .where(inArray(clients.clientId, clientIds));
+                    } else {
+                        await db.transaction(async (tx) => {
+                            for (const [timestamp, clientIds] of byTimestamp) {
+                                await tx
+                                    .update(clients)
+                                    .set({
+                                        lastPing: timestamp,
+                                        online: true,
+                                        archived: false
+                                    })
+                                    .where(
+                                        inArray(clients.clientId, clientIds)
+                                    );
+                            }
+                        });
+                    }
+                }, "flushClientPingsToDb");
+            } catch (error) {
+                logger.error(
+                    `Failed to flush client ping batch (${batch.length} clients), re-queuing for next cycle`,
+                    { error }
+                );
+                for (const [clientId, timestamp] of batch) {
+                    const existing = pendingClientPings.get(clientId);
+                    if (!existing || existing < timestamp) {
+                        pendingClientPings.set(clientId, timestamp);
+                    }
+                }
+            }
+        }
+    }
+
+    // ── Flush OLM archive resets ───────────────────────────────────────
+    if (olmResetsToFlush.size > 0) {
+        const olmIds = Array.from(olmResetsToFlush).sort();
+
+        const BATCH_SIZE = 50;
+        for (let i = 0; i < olmIds.length; i += BATCH_SIZE) {
+            const batch = olmIds.slice(i, i + BATCH_SIZE);
+
+            try {
+                await withRetry(async () => {
+                    await db
+                        .update(olms)
+                        .set({ archived: false })
+                        .where(inArray(olms.olmId, batch));
+                }, "flushOlmArchiveResets");
+            } catch (error) {
+                logger.error(
+                    `Failed to flush OLM archive reset batch (${batch.length} olms), re-queuing for next cycle`,
+                    { error }
+                );
+                for (const olmId of batch) {
+                    pendingOlmArchiveResets.add(olmId);
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Flush everything — called by the interval timer and during shutdown.
+ */
+export async function flushPingsToDb(): Promise<void> {
+    await flushSitePingsToDb();
+    await flushClientPingsToDb();
+}
+
+// ── Retry / Error Helpers ──────────────────────────────────────────────
+
+/**
+ * Simple retry wrapper with exponential backoff for transient errors
+ * (connection timeouts, unexpected disconnects).
+ */
+async function withRetry<T>(
+    operation: () => Promise<T>,
+    context: string
+): Promise<T> {
+    let attempt = 0;
+    while (true) {
+        try {
+            return await operation();
+        } catch (error: any) {
+            if (isTransientError(error) && attempt < MAX_RETRIES) {
+                attempt++;
+                const baseDelay = Math.pow(2, attempt - 1) * BASE_DELAY_MS;
+                const jitter = Math.random() * baseDelay;
+                const delay = baseDelay + jitter;
+                logger.warn(
+                    `Transient DB error in ${context}, retrying attempt ${attempt}/${MAX_RETRIES} after ${delay.toFixed(0)}ms`
+                );
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+
+/**
+ * Detect transient connection errors that are safe to retry.
+ */
+function isTransientError(error: any): boolean {
+    if (!error) return false;
+
+    const message = (error.message || "").toLowerCase();
+    const causeMessage = (error.cause?.message || "").toLowerCase();
+    const code = error.code || "";
+
+    // Connection timeout / terminated
+    if (
+        message.includes("connection timeout") ||
+        message.includes("connection terminated") ||
+        message.includes("timeout exceeded when trying to connect") ||
+        causeMessage.includes("connection terminated unexpectedly") ||
+        causeMessage.includes("connection timeout")
+    ) {
+        return true;
+    }
+
+    // PostgreSQL deadlock
+    if (code === "40P01" || message.includes("deadlock")) {
+        return true;
+    }
+
+    // ECONNRESET, ECONNREFUSED, EPIPE
+    if (
+        code === "ECONNRESET" ||
+        code === "ECONNREFUSED" ||
+        code === "EPIPE" ||
+        code === "ETIMEDOUT"
+    ) {
+        return true;
+    }
+
+    return false;
+}
+
+// ── Lifecycle ──────────────────────────────────────────────────────────
+
+/**
+ * Start the background flush timer. Call this once at server startup.
+ */
+export function startPingAccumulator(): void {
+    if (flushTimer) {
+        return; // Already running
+    }
+
+    flushTimer = setInterval(async () => {
+        try {
+            await flushPingsToDb();
+        } catch (error) {
+            logger.error("Unhandled error in ping accumulator flush", {
+                error
+            });
+        }
+    }, FLUSH_INTERVAL_MS);
+
+    // Don't prevent the process from exiting
+    flushTimer.unref();
+
+    logger.info(
+        `Ping accumulator started (flush interval: ${FLUSH_INTERVAL_MS}ms)`
+    );
+}
+
+/**
+ * Stop the background flush timer and perform a final flush.
+ * Call this during graceful shutdown.
+ */
+export async function stopPingAccumulator(): Promise<void> {
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
+
+    // Final flush to persist any remaining pings
+    try {
+        await flushPingsToDb();
+    } catch (error) {
+        logger.error("Error during final ping accumulator flush", { error });
+    }
+
+    logger.info("Ping accumulator stopped");
+}
+
+/**
+ * Get the number of pending (unflushed) pings. Useful for monitoring.
+ */
+export function getPendingPingCount(): number {
+    return pendingSitePings.size + pendingClientPings.size;
+}

server/routers/olm/getOlmToken.ts

@@ -8,7 +8,7 @@ import {
     ExitNode,
     exitNodes,
     sites,
-    clientSitesAssociationsCache
+    clientSitesAssociationsCache,
 } from "@server/db";
 import { olms } from "@server/db";
 import HttpCode from "@server/types/HttpCode";
@@ -20,8 +20,10 @@ import { z } from "zod";
 import { fromError } from "zod-validation-error";
 import {
     createOlmSession,
-    validateOlmSessionToken
+    validateOlmSessionToken,
+    EXPIRES
 } from "@server/auth/sessions/olm";
+import { getOrCreateCachedToken } from "#dynamic/lib/tokenCache";
 import { verifyPassword } from "@server/auth/password";
 import logger from "@server/logger";
 import config from "@server/lib/config";
@@ -132,8 +134,19 @@ export async function getOlmToken(
 
         logger.debug("Creating new olm session token");
 
-        const resToken = generateSessionToken();
-        await createOlmSession(resToken, existingOlm.olmId);
+        // Return a cached token if one exists to prevent thundering herd on
+        // simultaneous restarts; falls back to creating a fresh session when
+        // Redis is unavailable or the cache has expired.
+        const resToken = await getOrCreateCachedToken(
+            `olm:token_cache:${existingOlm.olmId}`,
+            config.getRawConfig().server.secret!,
+            Math.floor(EXPIRES / 1000),
+            async () => {
+                const token = generateSessionToken();
+                await createOlmSession(token, existingOlm.olmId);
+                return token;
+            }
+        );
 
         let clientIdToUse;
         if (orgId) {

server/routers/olm/handleOlmPingMessage.ts

@@ -3,6 +3,7 @@ import { db } from "@server/db";
 import { MessageHandler } from "@server/routers/ws";
 import { clients, olms, Olm } from "@server/db";
 import { eq, lt, isNull, and, or } from "drizzle-orm";
+import { recordClientPing } from "@server/routers/newt/pingAccumulator";
 import logger from "@server/logger";
 import { validateSessionToken } from "@server/auth/sessions/app";
 import { checkOrgAccessPolicy } from "#dynamic/lib/checkOrgAccessPolicy";
@@ -201,22 +202,12 @@ export const handleOlmPingMessage: MessageHandler = async (context) => {
             await sendOlmSyncMessage(olm, client);
         }
 
-        // Update the client's last ping timestamp
-        await db
-            .update(clients)
-            .set({
-                lastPing: Math.floor(Date.now() / 1000),
-                online: true,
-                archived: false
-            })
-            .where(eq(clients.clientId, olm.clientId));
-
-        if (olm.archived) {
-            await db
-                .update(olms)
-                .set({ archived: false })
-                .where(eq(olms.olmId, olm.olmId));
-        }
+        // Record the ping in memory; it will be flushed to the database
+        // periodically by the ping accumulator (every ~10s) in a single
+        // batched UPDATE instead of one query per ping. This prevents
+        // connection pool exhaustion under load, especially with
+        // cross-region latency to the database.
+        recordClientPing(olm.clientId, olm.olmId, !!olm.archived);
     } catch (error) {
         logger.error("Error handling ping message", { error });
     }

server/routers/siteResource/createSiteResource.ts

@@ -88,7 +88,7 @@ const createSiteResourceSchema = z
         },
         {
             message:
-                "Destination must be a valid IP address or valid domain AND alias is required"
+                "Destination must be a valid IPV4 address or valid domain AND alias is required"
         }
     )
     .refine(

server/routers/siteResource/updateSiteResource.ts

@@ -24,7 +24,7 @@ import { updatePeerData, updateTargets } from "@server/routers/client/targets";
 import {
     generateAliasConfig,
     generateRemoteSubnets,
-    generateSubnetProxyTargets,
+    generateSubnetProxyTargetV2,
     isIpInCidr,
     portRangeStringSchema
 } from "@server/lib/ip";
@@ -608,18 +608,18 @@ export async function handleMessagingForUpdatedSiteResource(
 
         // Only update targets on newt if destination changed
         if (destinationChanged || portRangesChanged) {
-            const oldTargets = generateSubnetProxyTargets(
+            const oldTarget = generateSubnetProxyTargetV2(
                 existingSiteResource,
                 mergedAllClients
             );
-            const newTargets = generateSubnetProxyTargets(
+            const newTarget = generateSubnetProxyTargetV2(
                 updatedSiteResource,
                 mergedAllClients
             );
 
             await updateTargets(newt.newtId, {
-                oldTargets: oldTargets,
-                newTargets: newTargets
+                oldTargets: oldTarget ? [oldTarget] : [],
+                newTargets: newTarget ? [newTarget] : []
             }, newt.version);
         }
 

server/routers/user/addUserRoleLegacy.ts

@@ -0,0 +1,159 @@
+import { Request, Response, NextFunction } from "express";
+import { z } from "zod";
+import stoi from "@server/lib/stoi";
+import { clients, db } from "@server/db";
+import { userOrgRoles, userOrgs, roles } from "@server/db";
+import { eq, and } from "drizzle-orm";
+import response from "@server/lib/response";
+import HttpCode from "@server/types/HttpCode";
+import createHttpError from "http-errors";
+import logger from "@server/logger";
+import { fromError } from "zod-validation-error";
+import { OpenAPITags, registry } from "@server/openApi";
+import { rebuildClientAssociationsFromClient } from "@server/lib/rebuildClientAssociations";
+
+/** Legacy path param order: /role/:roleId/add/:userId */
+const addUserRoleLegacyParamsSchema = z.strictObject({
+    roleId: z.string().transform(stoi).pipe(z.number()),
+    userId: z.string()
+});
+
+registry.registerPath({
+    method: "post",
+    path: "/role/{roleId}/add/{userId}",
+    description:
+        "Legacy: set exactly one role for the user (replaces any other roles the user has in the org).",
+    tags: [OpenAPITags.Role, OpenAPITags.User],
+    request: {
+        params: addUserRoleLegacyParamsSchema
+    },
+    responses: {}
+});
+
+export async function addUserRoleLegacy(
+    req: Request,
+    res: Response,
+    next: NextFunction
+): Promise<any> {
+    try {
+        const parsedParams = addUserRoleLegacyParamsSchema.safeParse(
+            req.params
+        );
+        if (!parsedParams.success) {
+            return next(
+                createHttpError(
+                    HttpCode.BAD_REQUEST,
+                    fromError(parsedParams.error).toString()
+                )
+            );
+        }
+
+        const { userId, roleId } = parsedParams.data;
+
+        if (req.user && !req.userOrg) {
+            return next(
+                createHttpError(
+                    HttpCode.FORBIDDEN,
+                    "You do not have access to this organization"
+                )
+            );
+        }
+
+        const [role] = await db
+            .select()
+            .from(roles)
+            .where(eq(roles.roleId, roleId))
+            .limit(1);
+
+        if (!role) {
+            return next(
+                createHttpError(HttpCode.BAD_REQUEST, "Invalid role ID")
+            );
+        }
+
+        const [existingUser] = await db
+            .select()
+            .from(userOrgs)
+            .where(
+                and(eq(userOrgs.userId, userId), eq(userOrgs.orgId, role.orgId))
+            )
+            .limit(1);
+
+        if (!existingUser) {
+            return next(
+                createHttpError(
+                    HttpCode.NOT_FOUND,
+                    "User not found or does not belong to the specified organization"
+                )
+            );
+        }
+
+        if (existingUser.isOwner) {
+            return next(
+                createHttpError(
+                    HttpCode.FORBIDDEN,
+                    "Cannot change the role of the owner of the organization"
+                )
+            );
+        }
+
+        const [roleInOrg] = await db
+            .select()
+            .from(roles)
+            .where(and(eq(roles.roleId, roleId), eq(roles.orgId, role.orgId)))
+            .limit(1);
+
+        if (!roleInOrg) {
+            return next(
+                createHttpError(
+                    HttpCode.NOT_FOUND,
+                    "Role not found or does not belong to the specified organization"
+                )
+            );
+        }
+
+        await db.transaction(async (trx) => {
+            await trx
+                .delete(userOrgRoles)
+                .where(
+                    and(
+                        eq(userOrgRoles.userId, userId),
+                        eq(userOrgRoles.orgId, role.orgId)
+                    )
+                );
+
+            await trx.insert(userOrgRoles).values({
+                userId,
+                orgId: role.orgId,
+                roleId
+            });
+
+            const orgClients = await trx
+                .select()
+                .from(clients)
+                .where(
+                    and(
+                        eq(clients.userId, userId),
+                        eq(clients.orgId, role.orgId)
+                    )
+                );
+
+            for (const orgClient of orgClients) {
+                await rebuildClientAssociationsFromClient(orgClient, trx);
+            }
+        });
+
+        return response(res, {
+            data: { ...existingUser, roleId },
+            success: true,
+            error: false,
+            message: "Role added to user successfully",
+            status: HttpCode.OK
+        });
+    } catch (error) {
+        logger.error(error);
+        return next(
+            createHttpError(HttpCode.INTERNAL_SERVER_ERROR, "An error occurred")
+        );
+    }
+}

server/routers/user/index.ts

@@ -1,9 +1,8 @@
 export * from "./getUser";
 export * from "./removeUserOrg";
 export * from "./listUsers";
-export * from "./addUserRole";
-export * from "./removeUserRole";
-export * from "./setUserOrgRoles";
+export * from "./types";
+export * from "./addUserRoleLegacy";
 export * from "./inviteUser";
 export * from "./acceptInvite";
 export * from "./getOrgUser";

server/routers/user/types.ts

@@ -0,0 +1,18 @@
+import type { UserOrg } from "@server/db";
+
+export type AddUserRoleResponse = {
+    userId: string;
+    roleId: number;
+};
+
+/** Legacy POST /role/:roleId/add/:userId response shape (membership + effective role). */
+export type AddUserRoleLegacyResponse = UserOrg & { roleId: number };
+
+export type SetUserOrgRolesParams = {
+    orgId: string;
+    userId: string;
+};
+
+export type SetUserOrgRolesBody = {
+    roleIds: number[];
+};

server/routers/ws/messageHandlers.ts

@@ -11,6 +11,7 @@ import {
     startNewtOfflineChecker,
     handleNewtDisconnectingMessage
 } from "../newt";
+import { startPingAccumulator } from "../newt/pingAccumulator";
 import {
     handleOlmRegisterMessage,
     handleOlmRelayMessage,
@@ -46,6 +47,10 @@ export const messageHandlers: Record<string, MessageHandler> = {
     "ws/round-trip/complete": handleRoundTripMessage
 };
 
+// Start the ping accumulator for all builds — it batches per-site online/lastPing
+// updates into periodic bulk writes, preventing connection pool exhaustion.
+startPingAccumulator();
+
 if (build != "saas") {
     startOlmOfflineChecker(); // this is to handle the offline check for olms
     startNewtOfflineChecker(); // this is to handle the offline check for newts

server/routers/ws/ws.ts

@@ -6,6 +6,7 @@ import { Socket } from "net";
 import { Newt, newts, NewtSession, olms, Olm, OlmSession, sites } from "@server/db";
 import { eq } from "drizzle-orm";
 import { db } from "@server/db";
+import { recordPing } from "@server/routers/newt/pingAccumulator";
 import { validateNewtSessionToken } from "@server/auth/sessions/newt";
 import { validateOlmSessionToken } from "@server/auth/sessions/olm";
 import { messageHandlers } from "./messageHandlers";
@@ -386,22 +387,14 @@ const setupConnection = async (
     // the same as modern newt clients.
     if (clientType === "newt") {
         const newtClient = client as Newt;
-        ws.on("ping", async () => {
+        ws.on("ping", () => {
             if (!newtClient.siteId) return;
-            try {
-                await db
-                    .update(sites)
-                    .set({
-                        online: true,
-                        lastPing: Math.floor(Date.now() / 1000)
-                    })
-                    .where(eq(sites.siteId, newtClient.siteId));
-            } catch (error) {
-                logger.error(
-                    "Error updating newt site online state on WS ping",
-                    { error }
-                );
-            }
+            // Record the ping in the accumulator instead of writing to the
+            // database on every WS ping frame. The accumulator flushes all
+            // pending pings in a single batched UPDATE every ~10s, which
+            // prevents connection pool exhaustion under load (especially
+            // with cross-region latency to the database).
+            recordPing(newtClient.siteId);
         });
     }
 

src/app/[orgId]/settings/(private)/idp/[idpId]/general/page.tsx

@@ -47,6 +47,14 @@ import { ListRolesResponse } from "@server/routers/role";
 import AutoProvisionConfigWidget from "@app/components/AutoProvisionConfigWidget";
 import { PaidFeaturesAlert } from "@app/components/PaidFeaturesAlert";
 import { tierMatrix } from "@server/lib/billing/tierMatrix";
+import {
+    compileRoleMappingExpression,
+    createMappingBuilderRule,
+    detectRoleMappingConfig,
+    ensureMappingBuilderRuleIds,
+    MappingBuilderRule,
+    RoleMappingMode
+} from "@app/lib/idpRoleMapping";
 
 export default function GeneralPage() {
     const { env } = useEnvContext();
@@ -56,9 +64,15 @@ export default function GeneralPage() {
     const [loading, setLoading] = useState(false);
     const [initialLoading, setInitialLoading] = useState(true);
     const [roles, setRoles] = useState<{ roleId: number; name: string }[]>([]);
-    const [roleMappingMode, setRoleMappingMode] = useState<
-        "role" | "expression"
-    >("role");
+    const [roleMappingMode, setRoleMappingMode] =
+        useState<RoleMappingMode>("fixedRoles");
+    const [fixedRoleNames, setFixedRoleNames] = useState<string[]>([]);
+    const [mappingBuilderClaimPath, setMappingBuilderClaimPath] =
+        useState("groups");
+    const [mappingBuilderRules, setMappingBuilderRules] = useState<
+        MappingBuilderRule[]
+    >([createMappingBuilderRule()]);
+    const [rawRoleExpression, setRawRoleExpression] = useState("");
     const [variant, setVariant] = useState<"oidc" | "google" | "azure">("oidc");
 
     const dashboardRedirectUrl = `${env.app.dashboardUrl}/auth/idp/${idpId}/oidc/callback`;
@@ -190,34 +204,8 @@ export default function GeneralPage() {
                     // Set the variant
                     setVariant(idpVariant as "oidc" | "google" | "azure");
 
-                    // Check if roleMapping matches the basic pattern '{role name}' (simple single role)
-                    // This should NOT match complex expressions like 'Admin' || 'Member'
-                    const isBasicRolePattern =
-                        roleMapping &&
-                        typeof roleMapping === "string" &&
-                        /^'[^']+'$/.test(roleMapping);
-
-                    // Determine if roleMapping is a number (roleId) or matches basic pattern
-                    const isRoleId =
-                        !isNaN(Number(roleMapping)) && roleMapping !== "";
-                    const isRoleName = isBasicRolePattern;
-
-                    // Extract role name from basic pattern for matching
-                    let extractedRoleName = null;
-                    if (isRoleName) {
-                        extractedRoleName = roleMapping.slice(1, -1); // Remove quotes
-                    }
-
-                    // Try to find matching role by name if we have a basic pattern
-                    let matchingRoleId = undefined;
-                    if (extractedRoleName && availableRoles.length > 0) {
-                        const matchingRole = availableRoles.find(
-                            (role) => role.name === extractedRoleName
-                        );
-                        if (matchingRole) {
-                            matchingRoleId = matchingRole.roleId;
-                        }
-                    }
+                    const detectedRoleMappingConfig =
+                        detectRoleMappingConfig(roleMapping);
 
                     // Extract tenant ID from Azure URLs if present
                     let tenantId = "";
@@ -238,9 +226,7 @@ export default function GeneralPage() {
                         clientSecret: data.idpOidcConfig.clientSecret,
                         autoProvision: data.idp.autoProvision,
                         roleMapping: roleMapping || null,
-                        roleId: isRoleId
-                            ? Number(roleMapping)
-                            : matchingRoleId || null
+                        roleId: null
                     };
 
                     // Add variant-specific fields
@@ -259,10 +245,18 @@ export default function GeneralPage() {
 
                     form.reset(formData);
 
-                    // Set the role mapping mode based on the data
-                    // Default to "expression" unless it's a simple roleId or basic '{role name}' pattern
-                    setRoleMappingMode(
-                        matchingRoleId && isRoleName ? "role" : "expression"
+                    setRoleMappingMode(detectedRoleMappingConfig.mode);
+                    setFixedRoleNames(detectedRoleMappingConfig.fixedRoleNames);
+                    setMappingBuilderClaimPath(
+                        detectedRoleMappingConfig.mappingBuilder.claimPath
+                    );
+                    setMappingBuilderRules(
+                        ensureMappingBuilderRuleIds(
+                            detectedRoleMappingConfig.mappingBuilder.rules
+                        )
+                    );
+                    setRawRoleExpression(
+                        detectedRoleMappingConfig.rawExpression
                     );
                 }
             } catch (e) {
@@ -327,7 +321,26 @@ export default function GeneralPage() {
                 return;
             }
 
-            const roleName = roles.find((r) => r.roleId === data.roleId)?.name;
+            const roleMappingExpression = compileRoleMappingExpression({
+                mode: roleMappingMode,
+                fixedRoleNames,
+                mappingBuilder: {
+                    claimPath: mappingBuilderClaimPath,
+                    rules: mappingBuilderRules
+                },
+                rawExpression: rawRoleExpression
+            });
+
+            if (data.autoProvision && !roleMappingExpression) {
+                toast({
+                    title: t("error"),
+                    description:
+                        "A role mapping is required when auto-provisioning is enabled.",
+                    variant: "destructive"
+                });
+                setLoading(false);
+                return;
+            }
 
             // Build payload based on variant
             let payload: any = {
@@ -335,10 +348,7 @@ export default function GeneralPage() {
                 clientId: data.clientId,
                 clientSecret: data.clientSecret,
                 autoProvision: data.autoProvision,
-                roleMapping:
-                    roleMappingMode === "role"
-                        ? `'${roleName}'`
-                        : data.roleMapping || ""
+                roleMapping: roleMappingExpression
             };
 
             // Add variant-specific fields
@@ -497,42 +507,43 @@ export default function GeneralPage() {
                         </SettingsSectionDescription>
                     </SettingsSectionHeader>
                     <SettingsSectionBody>
-                        <SettingsSectionForm>
-                            <PaidFeaturesAlert
-                                tiers={tierMatrix.autoProvisioning}
-                            />
+                        <PaidFeaturesAlert
+                            tiers={tierMatrix.autoProvisioning}
+                        />
 
-                            <Form {...form}>
-                                <form
-                                    onSubmit={form.handleSubmit(onSubmit)}
-                                    className="space-y-4"
-                                    id="general-settings-form"
-                                >
-                                    <AutoProvisionConfigWidget
-                                        control={form.control}
-                                        autoProvision={form.watch(
-                                            "autoProvision"
-                                        )}
-                                        onAutoProvisionChange={(checked) => {
-                                            form.setValue(
-                                                "autoProvision",
-                                                checked
-                                            );
-                                        }}
-                                        roleMappingMode={roleMappingMode}
-                                        onRoleMappingModeChange={(data) => {
-                                            setRoleMappingMode(data);
-                                            // Clear roleId and roleMapping when mode changes
-                                            form.setValue("roleId", null);
-                                            form.setValue("roleMapping", null);
-                                        }}
-                                        roles={roles}
-                                        roleIdFieldName="roleId"
-                                        roleMappingFieldName="roleMapping"
-                                    />
-                                </form>
-                            </Form>
-                        </SettingsSectionForm>
+                        <Form {...form}>
+                            <form
+                                onSubmit={form.handleSubmit(onSubmit)}
+                                className="space-y-4"
+                                id="general-settings-form"
+                            >
+                                <AutoProvisionConfigWidget
+                                    autoProvision={form.watch("autoProvision")}
+                                    onAutoProvisionChange={(checked) => {
+                                        form.setValue("autoProvision", checked);
+                                    }}
+                                    roleMappingMode={roleMappingMode}
+                                    onRoleMappingModeChange={(data) => {
+                                        setRoleMappingMode(data);
+                                    }}
+                                    roles={roles}
+                                    fixedRoleNames={fixedRoleNames}
+                                    onFixedRoleNamesChange={setFixedRoleNames}
+                                    mappingBuilderClaimPath={
+                                        mappingBuilderClaimPath
+                                    }
+                                    onMappingBuilderClaimPathChange={
+                                        setMappingBuilderClaimPath
+                                    }
+                                    mappingBuilderRules={mappingBuilderRules}
+                                    onMappingBuilderRulesChange={
+                                        setMappingBuilderRules
+                                    }
+                                    rawExpression={rawRoleExpression}
+                                    onRawExpressionChange={setRawRoleExpression}
+                                />
+                            </form>
+                        </Form>
                     </SettingsSectionBody>
                 </SettingsSection>
 

src/app/[orgId]/settings/(private)/idp/create/page.tsx

@@ -42,6 +42,12 @@ import { useParams, useRouter } from "next/navigation";
 import { useEffect, useState } from "react";
 import { useForm } from "react-hook-form";
 import { z } from "zod";
+import {
+    compileRoleMappingExpression,
+    createMappingBuilderRule,
+    MappingBuilderRule,
+    RoleMappingMode
+} from "@app/lib/idpRoleMapping";
 
 export default function Page() {
     const { env } = useEnvContext();
@@ -49,9 +55,15 @@ export default function Page() {
     const router = useRouter();
     const [createLoading, setCreateLoading] = useState(false);
     const [roles, setRoles] = useState<{ roleId: number; name: string }[]>([]);
-    const [roleMappingMode, setRoleMappingMode] = useState<
-        "role" | "expression"
-    >("role");
+    const [roleMappingMode, setRoleMappingMode] =
+        useState<RoleMappingMode>("fixedRoles");
+    const [fixedRoleNames, setFixedRoleNames] = useState<string[]>([]);
+    const [mappingBuilderClaimPath, setMappingBuilderClaimPath] =
+        useState("groups");
+    const [mappingBuilderRules, setMappingBuilderRules] = useState<
+        MappingBuilderRule[]
+    >([createMappingBuilderRule()]);
+    const [rawRoleExpression, setRawRoleExpression] = useState("");
     const t = useTranslations();
     const { isPaidUser } = usePaidStatus();
 
@@ -228,7 +240,26 @@ export default function Page() {
                 tokenUrl = tokenUrl?.replace("{{TENANT_ID}}", data.tenantId);
             }
 
-            const roleName = roles.find((r) => r.roleId === data.roleId)?.name;
+            const roleMappingExpression = compileRoleMappingExpression({
+                mode: roleMappingMode,
+                fixedRoleNames,
+                mappingBuilder: {
+                    claimPath: mappingBuilderClaimPath,
+                    rules: mappingBuilderRules
+                },
+                rawExpression: rawRoleExpression
+            });
+
+            if (data.autoProvision && !roleMappingExpression) {
+                toast({
+                    title: t("error"),
+                    description:
+                        "A role mapping is required when auto-provisioning is enabled.",
+                    variant: "destructive"
+                });
+                setCreateLoading(false);
+                return;
+            }
 
             const payload = {
                 name: data.name,
@@ -240,10 +271,7 @@ export default function Page() {
                 emailPath: data.emailPath,
                 namePath: data.namePath,
                 autoProvision: data.autoProvision,
-                roleMapping:
-                    roleMappingMode === "role"
-                        ? `'${roleName}'`
-                        : data.roleMapping || "",
+                roleMapping: roleMappingExpression,
                 scopes: data.scopes,
                 variant: data.type
             };
@@ -275,6 +303,8 @@ export default function Page() {
         }
     }
 
+    const disabled = !isPaidUser(tierMatrix.orgOidc);
+
     return (
         <>
             <div className="flex justify-between">
@@ -292,6 +322,9 @@ export default function Page() {
                 </Button>
             </div>
 
+            <PaidFeaturesAlert tiers={tierMatrix.orgOidc} />
+
+            <fieldset disabled={disabled} className={disabled ? "opacity-50 pointer-events-none" : ""}>
             <SettingsContainer>
                 <SettingsSection>
                     <SettingsSectionHeader>
@@ -363,43 +396,44 @@ export default function Page() {
                         </SettingsSectionDescription>
                     </SettingsSectionHeader>
                     <SettingsSectionBody>
-                        <SettingsSectionForm>
-                            <PaidFeaturesAlert
-                                tiers={tierMatrix.autoProvisioning}
-                            />
-                            <Form {...form}>
-                                <form
-                                    className="space-y-4"
-                                    id="create-idp-form"
-                                    onSubmit={form.handleSubmit(onSubmit)}
-                                >
-                                    <AutoProvisionConfigWidget
-                                        control={form.control}
-                                        autoProvision={
-                                            form.watch(
-                                                "autoProvision"
-                                            ) as boolean
-                                        } // is this right?
-                                        onAutoProvisionChange={(checked) => {
-                                            form.setValue(
-                                                "autoProvision",
-                                                checked
-                                            );
-                                        }}
-                                        roleMappingMode={roleMappingMode}
-                                        onRoleMappingModeChange={(data) => {
-                                            setRoleMappingMode(data);
-                                            // Clear roleId and roleMapping when mode changes
-                                            form.setValue("roleId", null);
-                                            form.setValue("roleMapping", null);
-                                        }}
-                                        roles={roles}
-                                        roleIdFieldName="roleId"
-                                        roleMappingFieldName="roleMapping"
-                                    />
-                                </form>
-                            </Form>
-                        </SettingsSectionForm>
+                        <PaidFeaturesAlert
+                            tiers={tierMatrix.autoProvisioning}
+                        />
+                        <Form {...form}>
+                            <form
+                                className="space-y-4"
+                                id="create-idp-form"
+                                onSubmit={form.handleSubmit(onSubmit)}
+                            >
+                                <AutoProvisionConfigWidget
+                                    autoProvision={
+                                        form.watch("autoProvision") as boolean
+                                    } // is this right?
+                                    onAutoProvisionChange={(checked) => {
+                                        form.setValue("autoProvision", checked);
+                                    }}
+                                    roleMappingMode={roleMappingMode}
+                                    onRoleMappingModeChange={(data) => {
+                                        setRoleMappingMode(data);
+                                    }}
+                                    roles={roles}
+                                    fixedRoleNames={fixedRoleNames}
+                                    onFixedRoleNamesChange={setFixedRoleNames}
+                                    mappingBuilderClaimPath={
+                                        mappingBuilderClaimPath
+                                    }
+                                    onMappingBuilderClaimPathChange={
+                                        setMappingBuilderClaimPath
+                                    }
+                                    mappingBuilderRules={mappingBuilderRules}
+                                    onMappingBuilderRulesChange={
+                                        setMappingBuilderRules
+                                    }
+                                    rawExpression={rawRoleExpression}
+                                    onRawExpressionChange={setRawRoleExpression}
+                                />
+                            </form>
+                        </Form>
                     </SettingsSectionBody>
                 </SettingsSection>
 
@@ -812,9 +846,10 @@ export default function Page() {
                 </Button>
                 <Button
                     type="submit"
-                    disabled={createLoading || !isPaidUser(tierMatrix.orgOidc)}
+                    disabled={createLoading || disabled}
                     loading={createLoading}
                     onClick={() => {
+                        if (disabled) return;
                         // log any issues with the form
                         console.log(form.formState.errors);
                         form.handleSubmit(onSubmit)();
@@ -823,6 +858,7 @@ export default function Page() {
                     {t("idpSubmit")}
                 </Button>
             </div>
+            </fieldset>
         </>
     );
 }

src/app/[orgId]/settings/access/users/[userId]/access-controls/page.tsx

@@ -37,6 +37,9 @@ import { useEnvContext } from "@app/hooks/useEnvContext";
 import { useTranslations } from "next-intl";
 import IdpTypeBadge from "@app/components/IdpTypeBadge";
 import { UserType } from "@server/types/UserTypes";
+import { usePaidStatus } from "@app/hooks/usePaidStatus";
+import { tierMatrix } from "@server/lib/billing/tierMatrix";
+import { build } from "@server/build";
 
 const accessControlsFormSchema = z.object({
     username: z.string(),
@@ -51,8 +54,9 @@ const accessControlsFormSchema = z.object({
 
 export default function AccessControlsPage() {
     const { orgUser: user, updateOrgUser } = userOrgUserContext();
+    const { env } = useEnvContext();
 
-    const api = createApiClient(useEnvContext());
+    const api = createApiClient({ env });
 
     const { orgId } = useParams();
 
@@ -63,6 +67,18 @@ export default function AccessControlsPage() {
     );
 
     const t = useTranslations();
+    const { isPaidUser, hasSaasSubscription, hasEnterpriseLicense } =
+        usePaidStatus();
+    const multiRoleFeatureTiers = Array.from(
+        new Set([...tierMatrix.sshPam, ...tierMatrix.orgOidc])
+    );
+    const isPaid = isPaidUser(multiRoleFeatureTiers);
+    const supportsMultipleRolesPerUser = isPaid;
+    const showMultiRolePaywallMessage =
+        !env.flags.disableEnterpriseFeatures &&
+        ((build === "saas" && !isPaid) ||
+            (build === "enterprise" && !isPaid) ||
+            (build === "oss" && !isPaid));
 
     const form = useForm({
         resolver: zodResolver(accessControlsFormSchema),
@@ -124,11 +140,28 @@ export default function AccessControlsPage() {
         [roles]
     );
 
-    function setRoleTags(
-        updater: Tag[] | ((prev: Tag[]) => Tag[])
-    ) {
+    function setRoleTags(updater: Tag[] | ((prev: Tag[]) => Tag[])) {
         const prev = form.getValues("roles");
-        const next = typeof updater === "function" ? updater(prev) : updater;
+        const nextValue =
+            typeof updater === "function" ? updater(prev) : updater;
+        const next = supportsMultipleRolesPerUser
+            ? nextValue
+            : nextValue.length > 1
+              ? [nextValue[nextValue.length - 1]]
+              : nextValue;
+
+        // In single-role mode, selecting the currently selected role can transiently
+        // emit an empty tag list from TagInput; keep the prior selection.
+        if (
+            !supportsMultipleRolesPerUser &&
+            next.length === 0 &&
+            prev.length > 0
+        ) {
+            form.setValue("roles", [prev[prev.length - 1]], {
+                shouldDirty: true
+            });
+            return;
+        }
 
         if (next.length === 0) {
             toast({
@@ -155,11 +188,14 @@ export default function AccessControlsPage() {
         setLoading(true);
         try {
             const roleIds = values.roles.map((r) => parseInt(r.id, 10));
+            const updateRoleRequest = supportsMultipleRolesPerUser
+                ? api.post(`/user/${user.userId}/org/${orgId}/roles`, {
+                      roleIds
+                  })
+                : api.post(`/role/${roleIds[0]}/add/${user.userId}`);
 
             await Promise.all([
-                api.post(`/org/${orgId}/user/${user.userId}/roles`, {
-                    roleIds
-                }),
+                updateRoleRequest,
                 api.post(`/org/${orgId}/user/${user.userId}`, {
                     autoProvisioned: values.autoProvisioned
                 })
@@ -233,7 +269,7 @@ export default function AccessControlsPage() {
                                     name="roles"
                                     render={({ field }) => (
                                         <FormItem className="flex flex-col items-start">
-                                            <FormLabel>{t("role")}</FormLabel>
+                                            <FormLabel>{t("roles")}</FormLabel>
                                             <FormControl>
                                                 <TagInput
                                                     {...field}
@@ -261,6 +297,17 @@ export default function AccessControlsPage() {
                                                     disabled={loading}
                                                 />
                                             </FormControl>
+                                            {showMultiRolePaywallMessage && (
+                                                <FormDescription>
+                                                    {build === "saas"
+                                                        ? t(
+                                                              "singleRolePerUserPlanNotice"
+                                                          )
+                                                        : t(
+                                                              "singleRolePerUserEditionNotice"
+                                                          )}
+                                                </FormDescription>
+                                            )}
                                             <FormMessage />
                                         </FormItem>
                                     )}

src/app/[orgId]/settings/logs/access/page.tsx

@@ -493,7 +493,8 @@ export default function GeneralPage() {
                                 {
                                     value: "whitelistedEmail",
                                     label: "Whitelisted Email"
-                                }
+                                },
+                                { value: "ssh", label: "SSH" }
                             ]}
                             selectedValue={filters.type}
                             onValueChange={(value) =>
@@ -507,13 +508,12 @@ export default function GeneralPage() {
                 );
             },
             cell: ({ row }) => {
-                // should be capitalized first letter
-                return (
-                    <span>
-                        {row.original.type.charAt(0).toUpperCase() +
-                            row.original.type.slice(1) || "-"}
-                    </span>
-                );
+                const typeLabel =
+                    row.original.type === "ssh"
+                        ? "SSH"
+                        : row.original.type.charAt(0).toUpperCase() +
+                          row.original.type.slice(1);
+                return <span>{typeLabel || "-"}</span>;
             }
         },
         {

src/components/AutoProvisionConfigWidget.tsx

@@ -1,57 +1,74 @@
 "use client";
 
 import {
-    FormField,
-    FormItem,
     FormLabel,
-    FormControl,
-    FormDescription,
-    FormMessage
+    FormDescription
 } from "@app/components/ui/form";
 import { SwitchInput } from "@app/components/SwitchInput";
 import { RadioGroup, RadioGroupItem } from "@app/components/ui/radio-group";
-import {
-    Select,
-    SelectContent,
-    SelectItem,
-    SelectTrigger,
-    SelectValue
-} from "@app/components/ui/select";
+import { Button } from "@app/components/ui/button";
 import { Input } from "@app/components/ui/input";
 import { useTranslations } from "next-intl";
-import { Control, FieldValues, Path } from "react-hook-form";
+import { useMemo, useState } from "react";
 import { usePaidStatus } from "@app/hooks/usePaidStatus";
 import { tierMatrix } from "@server/lib/billing/tierMatrix";
+import { Tag, TagInput } from "@app/components/tags/tag-input";
+import {
+    createMappingBuilderRule,
+    MappingBuilderRule,
+    RoleMappingMode
+} from "@app/lib/idpRoleMapping";
 
 type Role = {
     roleId: number;
     name: string;
 };
 
-type AutoProvisionConfigWidgetProps<T extends FieldValues> = {
-    control: Control<T>;
+type AutoProvisionConfigWidgetProps = {
     autoProvision: boolean;
     onAutoProvisionChange: (checked: boolean) => void;
-    roleMappingMode: "role" | "expression";
-    onRoleMappingModeChange: (mode: "role" | "expression") => void;
+    roleMappingMode: RoleMappingMode;
+    onRoleMappingModeChange: (mode: RoleMappingMode) => void;
     roles: Role[];
-    roleIdFieldName: Path<T>;
-    roleMappingFieldName: Path<T>;
+    fixedRoleNames: string[];
+    onFixedRoleNamesChange: (roleNames: string[]) => void;
+    mappingBuilderClaimPath: string;
+    onMappingBuilderClaimPathChange: (claimPath: string) => void;
+    mappingBuilderRules: MappingBuilderRule[];
+    onMappingBuilderRulesChange: (rules: MappingBuilderRule[]) => void;
+    rawExpression: string;
+    onRawExpressionChange: (expression: string) => void;
 };
 
-export default function AutoProvisionConfigWidget<T extends FieldValues>({
-    control,
+export default function AutoProvisionConfigWidget({
     autoProvision,
     onAutoProvisionChange,
     roleMappingMode,
     onRoleMappingModeChange,
     roles,
-    roleIdFieldName,
-    roleMappingFieldName
-}: AutoProvisionConfigWidgetProps<T>) {
+    fixedRoleNames,
+    onFixedRoleNamesChange,
+    mappingBuilderClaimPath,
+    onMappingBuilderClaimPathChange,
+    mappingBuilderRules,
+    onMappingBuilderRulesChange,
+    rawExpression,
+    onRawExpressionChange
+}: AutoProvisionConfigWidgetProps) {
     const t = useTranslations();
-
     const { isPaidUser } = usePaidStatus();
+    const [activeFixedRoleTagIndex, setActiveFixedRoleTagIndex] = useState<
+        number | null
+    >(null);
+
+    const roleOptions = useMemo(
+        () =>
+            roles.map((role) => ({
+                id: role.name,
+                text: role.name
+            })),
+        [roles]
+    );
 
     return (
         <div className="space-y-4">
@@ -81,97 +98,243 @@ export default function AutoProvisionConfigWidget<T extends FieldValues>({
                         <RadioGroup
                             value={roleMappingMode}
                             onValueChange={onRoleMappingModeChange}
-                            className="flex space-x-6"
+                            className="flex flex-wrap gap-x-6 gap-y-2"
                         >
                             <div className="flex items-center space-x-2">
-                                <RadioGroupItem value="role" id="role-mode" />
+                                <RadioGroupItem
+                                    value="fixedRoles"
+                                    id="fixed-roles-mode"
+                                />
                                 <label
-                                    htmlFor="role-mode"
+                                    htmlFor="fixed-roles-mode"
                                     className="text-sm font-medium"
                                 >
-                                    {t("selectRole")}
+                                    Fixed roles
                                 </label>
                             </div>
                             <div className="flex items-center space-x-2">
                                 <RadioGroupItem
-                                    value="expression"
+                                    value="mappingBuilder"
+                                    id="mapping-builder-mode"
+                                />
+                                <label
+                                    htmlFor="mapping-builder-mode"
+                                    className="text-sm font-medium"
+                                >
+                                    Mapping builder
+                                </label>
+                            </div>
+                            <div className="flex items-center space-x-2">
+                                <RadioGroupItem
+                                    value="rawExpression"
                                     id="expression-mode"
                                 />
                                 <label
                                     htmlFor="expression-mode"
                                     className="text-sm font-medium"
                                 >
-                                    {t("roleMappingExpression")}
+                                    Raw expression
                                 </label>
                             </div>
                         </RadioGroup>
                     </div>
 
-                    {roleMappingMode === "role" ? (
-                        <FormField
-                            control={control}
-                            name={roleIdFieldName}
-                            render={({ field }) => (
-                                <FormItem>
-                                    <Select
-                                        onValueChange={(value) =>
-                                            field.onChange(Number(value))
-                                        }
-                                        value={field.value?.toString()}
-                                    >
-                                        <FormControl>
-                                            <SelectTrigger>
-                                                <SelectValue
-                                                    placeholder={t(
-                                                        "selectRolePlaceholder"
-                                                    )}
-                                                />
-                                            </SelectTrigger>
-                                        </FormControl>
-                                        <SelectContent>
-                                            {roles.map((role) => (
-                                                <SelectItem
-                                                    key={role.roleId}
-                                                    value={role.roleId.toString()}
-                                                >
-                                                    {role.name}
-                                                </SelectItem>
-                                            ))}
-                                        </SelectContent>
-                                    </Select>
-                                    <FormDescription>
-                                        {t("selectRoleDescription")}
-                                    </FormDescription>
-                                    <FormMessage />
-                                </FormItem>
-                            )}
-                        />
-                    ) : (
-                        <FormField
-                            control={control}
-                            name={roleMappingFieldName}
-                            render={({ field }) => (
-                                <FormItem>
-                                    <FormControl>
-                                        <Input
-                                            {...field}
-                                            defaultValue={field.value || ""}
-                                            value={field.value || ""}
-                                            placeholder={t(
-                                                "roleMappingExpressionPlaceholder"
-                                            )}
-                                        />
-                                    </FormControl>
-                                    <FormDescription>
-                                        {t("roleMappingExpressionDescription")}
-                                    </FormDescription>
-                                    <FormMessage />
-                                </FormItem>
-                            )}
-                        />
+                    {roleMappingMode === "fixedRoles" && (
+                        <div className="space-y-2">
+                            <TagInput
+                                tags={fixedRoleNames.map((name) => ({
+                                    id: name,
+                                    text: name
+                                }))}
+                                setTags={(nextTags) => {
+                                    const next =
+                                        typeof nextTags === "function"
+                                            ? nextTags(
+                                                  fixedRoleNames.map((name) => ({
+                                                      id: name,
+                                                      text: name
+                                                  }))
+                                              )
+                                            : nextTags;
+
+                                    onFixedRoleNamesChange(
+                                        [...new Set(next.map((tag) => tag.text))]
+                                    );
+                                }}
+                                activeTagIndex={activeFixedRoleTagIndex}
+                                setActiveTagIndex={setActiveFixedRoleTagIndex}
+                                placeholder="Select one or more roles"
+                                enableAutocomplete={true}
+                                autocompleteOptions={roleOptions}
+                                restrictTagsToAutocompleteOptions={true}
+                                allowDuplicates={false}
+                                sortTags={true}
+                                size="sm"
+                            />
+                            <FormDescription>
+                                Assign the same role set to every auto-provisioned
+                                user.
+                            </FormDescription>
+                        </div>
+                    )}
+
+                    {roleMappingMode === "mappingBuilder" && (
+                        <div className="space-y-4 rounded-md border p-3">
+                            <div className="space-y-2">
+                                <FormLabel>Claim path</FormLabel>
+                                <Input
+                                    value={mappingBuilderClaimPath}
+                                    onChange={(e) =>
+                                        onMappingBuilderClaimPathChange(
+                                            e.target.value
+                                        )
+                                    }
+                                    placeholder="groups"
+                                />
+                                <FormDescription>
+                                    Path in the token payload that contains source
+                                    values (for example, groups).
+                                </FormDescription>
+                            </div>
+
+                            <div className="space-y-3">
+                                <div className="hidden md:grid md:grid-cols-[minmax(220px,1fr)_minmax(340px,2fr)_auto] md:gap-3">
+                                    <FormLabel>Match value</FormLabel>
+                                    <FormLabel>Assign roles</FormLabel>
+                                    <span />
+                                </div>
+
+                                {mappingBuilderRules.map((rule, index) => (
+                                    <BuilderRuleRow
+                                        key={rule.id ?? `mapping-rule-${index}`}
+                                        roleOptions={roleOptions}
+                                        rule={rule}
+                                        onChange={(nextRule) => {
+                                            const nextRules =
+                                                mappingBuilderRules.map(
+                                                    (row, i) =>
+                                                        i === index
+                                                            ? nextRule
+                                                            : row
+                                                );
+                                            onMappingBuilderRulesChange(
+                                                nextRules
+                                            );
+                                        }}
+                                        onRemove={() => {
+                                            const nextRules =
+                                                mappingBuilderRules.filter(
+                                                    (_, i) => i !== index
+                                                );
+                                            onMappingBuilderRulesChange(
+                                                nextRules.length
+                                                    ? nextRules
+                                                    : [createMappingBuilderRule()]
+                                            );
+                                        }}
+                                    />
+                                ))}
+                            </div>
+
+                            <Button
+                                type="button"
+                                variant="outline"
+                                onClick={() => {
+                                    onMappingBuilderRulesChange([
+                                        ...mappingBuilderRules,
+                                        createMappingBuilderRule()
+                                    ]);
+                                }}
+                            >
+                                Add mapping rule
+                            </Button>
+                        </div>
+                    )}
+
+                    {roleMappingMode === "rawExpression" && (
+                        <div className="space-y-2">
+                            <Input
+                                value={rawExpression}
+                                onChange={(e) =>
+                                    onRawExpressionChange(e.target.value)
+                                }
+                                placeholder={t("roleMappingExpressionPlaceholder")}
+                            />
+                            <FormDescription>
+                                Expression must evaluate to a string or string
+                                array.
+                            </FormDescription>
+                        </div>
                     )}
                 </div>
             )}
         </div>
     );
 }
+
+function BuilderRuleRow({
+    rule,
+    roleOptions,
+    onChange,
+    onRemove
+}: {
+    rule: MappingBuilderRule;
+    roleOptions: Tag[];
+    onChange: (rule: MappingBuilderRule) => void;
+    onRemove: () => void;
+}) {
+    const [activeTagIndex, setActiveTagIndex] = useState<number | null>(null);
+
+    return (
+        <div className="grid gap-3 rounded-md border p-3 md:grid-cols-[minmax(220px,1fr)_minmax(340px,2fr)_auto] md:items-start">
+            <div className="space-y-1">
+                <FormLabel className="text-xs md:hidden">Match value</FormLabel>
+                <Input
+                    value={rule.matchValue}
+                    onChange={(e) =>
+                        onChange({
+                            ...rule,
+                            matchValue: e.target.value
+                        })
+                    }
+                    placeholder="Match value (for example: admin)"
+                />
+            </div>
+            <div className="space-y-1 min-w-0">
+                <FormLabel className="text-xs md:hidden">Assign roles</FormLabel>
+                <TagInput
+                    tags={rule.roleNames.map((name) => ({ id: name, text: name }))}
+                    setTags={(nextTags) => {
+                        const next =
+                            typeof nextTags === "function"
+                                ? nextTags(
+                                      rule.roleNames.map((name) => ({
+                                          id: name,
+                                          text: name
+                                      }))
+                                  )
+                                : nextTags;
+                        onChange({
+                            ...rule,
+                            roleNames: [...new Set(next.map((tag) => tag.text))]
+                        });
+                    }}
+                    activeTagIndex={activeTagIndex}
+                    setActiveTagIndex={setActiveTagIndex}
+                    placeholder="Assign roles"
+                    enableAutocomplete={true}
+                    autocompleteOptions={roleOptions}
+                    restrictTagsToAutocompleteOptions={true}
+                    allowDuplicates={false}
+                    sortTags={true}
+                    size="sm"
+                />
+            </div>
+            <div className="flex justify-end md:justify-start">
+                <Button type="button" variant="ghost" onClick={onRemove}>
+                    Remove
+                </Button>
+            </div>
+        </div>
+    );
+}

src/components/PermissionsSelectBox.tsx

@@ -96,7 +96,7 @@ function getActionsCategories(root: boolean) {
             [t("actionUpdateRole")]: "updateRole",
             [t("actionListAllowedRoleResources")]: "listRoleResources",
             [t("actionAddUserRole")]: "addUserRole",
-            [t("actionSetUserOrgRoles")]: "setUserOrgRoles"
+            [t("actionRemoveUserRole")]: "removeUserRole"
         },
         "Access Token": {
             [t("actionGenerateAccessToken")]: "generateAccessToken",

src/lib/idpRoleMapping.ts

@@ -0,0 +1,266 @@
+export type RoleMappingMode = "fixedRoles" | "mappingBuilder" | "rawExpression";
+
+export type MappingBuilderRule = {
+    /** Stable React list key; not used when compiling JMESPath. */
+    id?: string;
+    matchValue: string;
+    roleNames: string[];
+};
+
+function newMappingBuilderRuleId(): string {
+    if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+        return crypto.randomUUID();
+    }
+    return `rule-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+export function createMappingBuilderRule(): MappingBuilderRule {
+    return {
+        id: newMappingBuilderRuleId(),
+        matchValue: "",
+        roleNames: []
+    };
+}
+
+/** Ensures every rule has a stable id (e.g. after loading from the API). */
+export function ensureMappingBuilderRuleIds(
+    rules: MappingBuilderRule[]
+): MappingBuilderRule[] {
+    return rules.map((rule) =>
+        rule.id ? rule : { ...rule, id: newMappingBuilderRuleId() }
+    );
+}
+
+export type MappingBuilderConfig = {
+    claimPath: string;
+    rules: MappingBuilderRule[];
+};
+
+export type RoleMappingConfig = {
+    mode: RoleMappingMode;
+    fixedRoleNames: string[];
+    mappingBuilder: MappingBuilderConfig;
+    rawExpression: string;
+};
+
+const SINGLE_QUOTED_ROLE_REGEX = /^'([^']+)'$/;
+const QUOTED_ROLE_ARRAY_REGEX = /^\[(.*)\]$/;
+
+/** Stored role mappings created by the mapping builder are prefixed so the UI can restore the builder. */
+export const PANGOLIN_ROLE_MAP_BUILDER_PREFIX = "__PANGOLIN_ROLE_MAP_BUILDER_V1__";
+
+const BUILDER_METADATA_SEPARATOR = "\n---\n";
+
+export type UnwrappedRoleMapping = {
+    /** Expression passed to JMESPath (no builder wrapper). */
+    evaluationExpression: string;
+    /** Present when the stored value was saved from the mapping builder. */
+    builderState: { claimPath: string; rules: MappingBuilderRule[] } | null;
+};
+
+/**
+ * Split stored DB value into evaluation expression and optional builder metadata.
+ * Legacy values (no prefix) are returned as-is for evaluation.
+ */
+export function unwrapRoleMapping(
+    stored: string | null | undefined
+): UnwrappedRoleMapping {
+    const trimmed = stored?.trim() ?? "";
+    if (!trimmed.startsWith(PANGOLIN_ROLE_MAP_BUILDER_PREFIX)) {
+        return {
+            evaluationExpression: trimmed,
+            builderState: null
+        };
+    }
+
+    let rest = trimmed.slice(PANGOLIN_ROLE_MAP_BUILDER_PREFIX.length);
+    if (rest.startsWith("\n")) {
+        rest = rest.slice(1);
+    }
+
+    const sepIdx = rest.indexOf(BUILDER_METADATA_SEPARATOR);
+    if (sepIdx === -1) {
+        return {
+            evaluationExpression: trimmed,
+            builderState: null
+        };
+    }
+
+    const jsonPart = rest.slice(0, sepIdx).trim();
+    const inner = rest.slice(sepIdx + BUILDER_METADATA_SEPARATOR.length).trim();
+
+    try {
+        const meta = JSON.parse(jsonPart) as {
+            claimPath?: unknown;
+            rules?: unknown;
+        };
+        if (
+            typeof meta.claimPath === "string" &&
+            Array.isArray(meta.rules)
+        ) {
+            const rules: MappingBuilderRule[] = meta.rules.map(
+                (r: unknown) => {
+                    const row = r as {
+                        matchValue?: unknown;
+                        roleNames?: unknown;
+                    };
+                    return {
+                        matchValue:
+                            typeof row.matchValue === "string"
+                                ? row.matchValue
+                                : "",
+                        roleNames: Array.isArray(row.roleNames)
+                            ? row.roleNames.filter(
+                                  (n): n is string => typeof n === "string"
+                              )
+                            : []
+                    };
+                }
+            );
+            return {
+                evaluationExpression: inner,
+                builderState: {
+                    claimPath: meta.claimPath,
+                    rules: ensureMappingBuilderRuleIds(rules)
+                }
+            };
+        }
+    } catch {
+        /* fall through */
+    }
+
+    return {
+        evaluationExpression: inner.length ? inner : trimmed,
+        builderState: null
+    };
+}
+
+function escapeSingleQuotes(value: string): string {
+    return value.replace(/'/g, "\\'");
+}
+
+export function compileRoleMappingExpression(config: RoleMappingConfig): string {
+    if (config.mode === "rawExpression") {
+        return config.rawExpression.trim();
+    }
+
+    if (config.mode === "fixedRoles") {
+        const roleNames = dedupeNonEmpty(config.fixedRoleNames);
+        if (!roleNames.length) {
+            return "";
+        }
+
+        if (roleNames.length === 1) {
+            return `'${escapeSingleQuotes(roleNames[0])}'`;
+        }
+
+        return `[${roleNames.map((name) => `'${escapeSingleQuotes(name)}'`).join(", ")}]`;
+    }
+
+    const claimPath = config.mappingBuilder.claimPath.trim();
+    const rules = config.mappingBuilder.rules
+        .map((rule) => ({
+            matchValue: rule.matchValue.trim(),
+            roleNames: dedupeNonEmpty(rule.roleNames)
+        }))
+        .filter((rule) => Boolean(rule.matchValue) && rule.roleNames.length > 0);
+
+    if (!claimPath || !rules.length) {
+        return "";
+    }
+
+    const compiledRules = rules.map((rule) => {
+        const mappedRoles = `[${rule.roleNames
+            .map((name) => `'${escapeSingleQuotes(name)}'`)
+            .join(", ")}]`;
+        return `contains(${claimPath}, '${escapeSingleQuotes(rule.matchValue)}') && ${mappedRoles} || []`;
+    });
+
+    const inner = `[${compiledRules.join(", ")}][]`;
+    const metadata = {
+        claimPath,
+        rules: rules.map((r) => ({
+            matchValue: r.matchValue,
+            roleNames: r.roleNames
+        }))
+    };
+
+    return `${PANGOLIN_ROLE_MAP_BUILDER_PREFIX}\n${JSON.stringify(metadata)}${BUILDER_METADATA_SEPARATOR}${inner}`;
+}
+
+export function detectRoleMappingConfig(
+    expression: string | null | undefined
+): RoleMappingConfig {
+    const stored = expression?.trim() || "";
+
+    if (!stored) {
+        return defaultRoleMappingConfig();
+    }
+
+    const { evaluationExpression, builderState } = unwrapRoleMapping(stored);
+
+    if (builderState) {
+        return {
+            mode: "mappingBuilder",
+            fixedRoleNames: [],
+            mappingBuilder: {
+                claimPath: builderState.claimPath,
+                rules: builderState.rules
+            },
+            rawExpression: evaluationExpression
+        };
+    }
+
+    const tail = evaluationExpression.trim();
+
+    const singleMatch = tail.match(SINGLE_QUOTED_ROLE_REGEX);
+    if (singleMatch?.[1]) {
+        return {
+            mode: "fixedRoles",
+            fixedRoleNames: [singleMatch[1]],
+            mappingBuilder: defaultRoleMappingConfig().mappingBuilder,
+            rawExpression: tail
+        };
+    }
+
+    const arrayMatch = tail.match(QUOTED_ROLE_ARRAY_REGEX);
+    if (arrayMatch?.[1]) {
+        const roleNames = arrayMatch[1]
+            .split(",")
+            .map((entry) => entry.trim())
+            .map((entry) => entry.match(SINGLE_QUOTED_ROLE_REGEX)?.[1] || "")
+            .filter(Boolean);
+
+        if (roleNames.length > 0) {
+            return {
+                mode: "fixedRoles",
+                fixedRoleNames: roleNames,
+                mappingBuilder: defaultRoleMappingConfig().mappingBuilder,
+                rawExpression: tail
+            };
+        }
+    }
+
+    return {
+        mode: "rawExpression",
+        fixedRoleNames: [],
+        mappingBuilder: defaultRoleMappingConfig().mappingBuilder,
+        rawExpression: tail
+    };
+}
+
+export function defaultRoleMappingConfig(): RoleMappingConfig {
+    return {
+        mode: "fixedRoles",
+        fixedRoleNames: [],
+        mappingBuilder: {
+            claimPath: "groups",
+            rules: [createMappingBuilderRule()]
+        },
+        rawExpression: ""
+    };
+}
+
+function dedupeNonEmpty(values: string[]): string[] {
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}