@hotmeshio/long-tail 0.5.11 → 0.6.0

package/build/services/user/crud.js

@@ -14,6 +14,7 @@ exports.listUsers = listUsers;
 const bcryptjs_1 = __importDefault(require("bcryptjs"));
 const db_1 = require("../../lib/db");
 const sql_1 = require("./sql");
+const scope_1 = require("./scope");
 // ─── Private helpers (exported for internal use by auth.ts) ──────────────────
 async function attachRoles(user) {
     const pool = (0, db_1.getPool)();
@@ -29,7 +30,13 @@ async function attachRolesToMany(users) {
     const roleMap = new Map();
     for (const row of rows) {
         const list = roleMap.get(row.user_id) || [];
-        list.push({ role: row.role, type: row.type, created_at: row.created_at });
+        list.push({
+            role: row.role,
+            type: row.type,
+            read_scope: row.read_scope,
+            write_scope: row.write_scope,
+            created_at: row.created_at,
+        });
         roleMap.set(row.user_id, list);
     }
     return users.map((u) => ({ ...u, roles: roleMap.get(u.id) || [] }));
@@ -40,7 +47,16 @@ async function createUser(input) {
     const passwordHash = input.password
         ? await bcryptjs_1.default.hash(input.password, 10)
         : null;
-    const { rows } = await pool.query(sql_1.INSERT_USER, [
+    // One atomic statement creates the user, ensures the role FK targets, and links
+    // the assignments — no partial-roles window, no per-role N+1. Roles + their
+    // effective scope travel as parallel text[] arrays. admin/superadmin normalize
+    // to ('all','all'); members store the requested scope.
+    const roleNames = (input.roles || []).map((r) => r.role);
+    const roleTypes = (input.roles || []).map((r) => r.type);
+    const effScopes = (input.roles || []).map((r) => (0, scope_1.effectiveScope)(r.type, r.read_scope ?? scope_1.DEFAULT_READ_SCOPE, r.write_scope ?? scope_1.DEFAULT_WRITE_SCOPE));
+    const roleReadScopes = effScopes.map((e) => e.read);
+    const roleWriteScopes = effScopes.map((e) => e.write);
+    const { rows } = await pool.query(sql_1.CREATE_USER_WITH_ROLES, [
         input.external_id,
         input.email || null,
         input.display_name || null,
@@ -49,16 +65,12 @@ async function createUser(input) {
         passwordHash,
         input.oauth_provider || null,
         input.oauth_provider_id || null,
+        roleNames,
+        roleTypes,
+        roleReadScopes,
+        roleWriteScopes,
     ]);
-    const user = rows[0];
-    if (input.roles && input.roles.length > 0) {
-        for (const r of input.roles) {
-            // Ensure the role exists in lt_roles (FK constraint)
-            await pool.query(sql_1.ENSURE_ROLE_EXISTS, [r.role]);
-            await pool.query(sql_1.INSERT_USER_ROLE_IGNORE, [user.id, r.role, r.type]);
-        }
-    }
-    return attachRoles(user);
+    return attachRoles(rows[0]);
 }
 async function getUser(id) {
     const pool = (0, db_1.getPool)();
@@ -140,6 +152,12 @@ async function listUsers(filters) {
         conditions.push(`u.status = $${idx++}`);
         values.push(filters.status);
     }
+    if (filters.search) {
+        // Server-side free-text over the user's display fields — one term, one param.
+        const i = idx++;
+        conditions.push(`(u.display_name ILIKE '%' || $${i} || '%' OR u.email ILIKE '%' || $${i} || '%' OR u.external_id ILIKE '%' || $${i} || '%')`);
+        values.push(filters.search);
+    }
     const join = needsJoin ? 'INNER JOIN lt_user_roles r ON r.user_id = u.id' : '';
     const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
     const limit = filters.limit || 50;

package/build/services/user/index.d.ts

@@ -1,6 +1,7 @@
 export { CreateUserInput, UpdateUserInput, VALID_ROLE_TYPES } from './types';
 export { createUser, getUser, getUserByExternalId, getUserByEmail, updateUser, deleteUser, listUsers, } from './crud';
 export { isValidRoleType, addUserRole, removeUserRole, getUserRoles, hasRole, hasRoleType, } from './roles';
-export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, hasRolesAsAdmin } from './rbac';
+export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, hasRolesAsAdmin, getRoleScope, getRoleWriteScope } from './rbac';
+export { READ_SCOPES, WRITE_SCOPES, DEFAULT_READ_SCOPE, DEFAULT_WRITE_SCOPE, isValidReadScope, isValidWriteScope, isValidScopePair, effectiveScope, } from './scope';
 export { verifyPassword } from './auth';
 export { seedAdmin } from './seed-admin';

package/build/services/user/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.seedAdmin = exports.verifyPassword = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
+exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "VALID_ROLE_TYPES", { enumerable: true, get: function () { return types_1.VALID_ROLE_TYPES; } });
 var crud_1 = require("./crud");
@@ -24,6 +24,17 @@ Object.defineProperty(exports, "isGroupAdmin", { enumerable: true, get: function
 Object.defineProperty(exports, "canManageRole", { enumerable: true, get: function () { return rbac_1.canManageRole; } });
 Object.defineProperty(exports, "hasGlobalEscalationAccess", { enumerable: true, get: function () { return rbac_1.hasGlobalEscalationAccess; } });
 Object.defineProperty(exports, "hasRolesAsAdmin", { enumerable: true, get: function () { return rbac_1.hasRolesAsAdmin; } });
+Object.defineProperty(exports, "getRoleScope", { enumerable: true, get: function () { return rbac_1.getRoleScope; } });
+Object.defineProperty(exports, "getRoleWriteScope", { enumerable: true, get: function () { return rbac_1.getRoleWriteScope; } });
+var scope_1 = require("./scope");
+Object.defineProperty(exports, "READ_SCOPES", { enumerable: true, get: function () { return scope_1.READ_SCOPES; } });
+Object.defineProperty(exports, "WRITE_SCOPES", { enumerable: true, get: function () { return scope_1.WRITE_SCOPES; } });
+Object.defineProperty(exports, "DEFAULT_READ_SCOPE", { enumerable: true, get: function () { return scope_1.DEFAULT_READ_SCOPE; } });
+Object.defineProperty(exports, "DEFAULT_WRITE_SCOPE", { enumerable: true, get: function () { return scope_1.DEFAULT_WRITE_SCOPE; } });
+Object.defineProperty(exports, "isValidReadScope", { enumerable: true, get: function () { return scope_1.isValidReadScope; } });
+Object.defineProperty(exports, "isValidWriteScope", { enumerable: true, get: function () { return scope_1.isValidWriteScope; } });
+Object.defineProperty(exports, "isValidScopePair", { enumerable: true, get: function () { return scope_1.isValidScopePair; } });
+Object.defineProperty(exports, "effectiveScope", { enumerable: true, get: function () { return scope_1.effectiveScope; } });
 var auth_1 = require("./auth");
 Object.defineProperty(exports, "verifyPassword", { enumerable: true, get: function () { return auth_1.verifyPassword; } });
 var seed_admin_1 = require("./seed-admin");

package/build/services/user/rbac.d.ts

@@ -1,3 +1,4 @@
+import type { LTReadScope, LTWriteScope } from '../../types';
 /**
  * Is the user a superadmin? (global — can manage all users and roles)
  */
@@ -24,6 +25,23 @@ export declare function canManageRole(actorId: string, role: string): Promise<bo
  * all roles, and can perform bulk actions.
  */
 export declare function hasGlobalEscalationAccess(userId: string): Promise<boolean>;
+/**
+ * Resolve the user's effective scope for a single role — the breadth at which
+ * they may SEARCH (read) and ACT (write). One indexed PK lookup on lt_user_roles.
+ * Returns `null` when the user is not a member of the role.
+ *
+ * The management tier (admin/superadmin) short-circuits both axes to `'all'` via
+ * effectiveScope. Callers that already hold global access should skip this.
+ */
+export declare function getRoleScope(userId: string, role: string): Promise<{
+    read: LTReadScope;
+    write: LTWriteScope;
+} | null>;
+/**
+ * Effective WRITE scope for a role: `'all'` (act on any item), `'self'` (only
+ * items assigned to the user), or `'none'` (read-only, or not a member).
+ */
+export declare function getRoleWriteScope(userId: string, role: string): Promise<LTWriteScope>;
 /**
  * Batch check: does the user have admin type for ALL specified roles?
  * Single query — replaces the N+1 loop in checkBulkPermission.

package/build/services/user/rbac.js

@@ -4,9 +4,12 @@ exports.isSuperAdmin = isSuperAdmin;
 exports.isGroupAdmin = isGroupAdmin;
 exports.canManageRole = canManageRole;
 exports.hasGlobalEscalationAccess = hasGlobalEscalationAccess;
+exports.getRoleScope = getRoleScope;
+exports.getRoleWriteScope = getRoleWriteScope;
 exports.hasRolesAsAdmin = hasRolesAsAdmin;
 const db_1 = require("../../lib/db");
 const roles_1 = require("./roles");
+const scope_1 = require("./scope");
 const sql_1 = require("./sql");
 // ─── RBAC helpers ─────────────────────────────────────────────────────────────
 /**
@@ -48,6 +51,30 @@ async function hasGlobalEscalationAccess(userId) {
     const roles = await (0, roles_1.getUserRoles)(userId);
     return roles.some((r) => r.role === 'admin' && r.type === 'admin');
 }
+/**
+ * Resolve the user's effective scope for a single role — the breadth at which
+ * they may SEARCH (read) and ACT (write). One indexed PK lookup on lt_user_roles.
+ * Returns `null` when the user is not a member of the role.
+ *
+ * The management tier (admin/superadmin) short-circuits both axes to `'all'` via
+ * effectiveScope. Callers that already hold global access should skip this.
+ */
+async function getRoleScope(userId, role) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_ROLE_SCOPE, [userId, role]);
+    if (rows.length === 0)
+        return null;
+    const { type, read_scope, write_scope } = rows[0];
+    return (0, scope_1.effectiveScope)(type, read_scope, write_scope);
+}
+/**
+ * Effective WRITE scope for a role: `'all'` (act on any item), `'self'` (only
+ * items assigned to the user), or `'none'` (read-only, or not a member).
+ */
+async function getRoleWriteScope(userId, role) {
+    const scope = await getRoleScope(userId, role);
+    return scope ? scope.write : 'none';
+}
 /**
  * Batch check: does the user have admin type for ALL specified roles?
  * Single query — replaces the N+1 loop in checkBulkPermission.

package/build/services/user/roles.d.ts

@@ -1,6 +1,11 @@
-import type { LTUserRole, LTRoleType } from '../../types';
+import type { LTReadScope, LTRoleType, LTUserRole, LTWriteScope } from '../../types';
 export declare function isValidRoleType(type: string): type is LTRoleType;
-export declare function addUserRole(userId: string, role: string, type: LTRoleType): Promise<LTUserRole>;
+/** Optional work-surface scope for a membership. Defaults to ('all','all') = full worker. */
+export interface RoleScopeInput {
+    read_scope?: LTReadScope;
+    write_scope?: LTWriteScope;
+}
+export declare function addUserRole(userId: string, role: string, type: LTRoleType, scope?: RoleScopeInput): Promise<LTUserRole>;
 export declare function removeUserRole(userId: string, role: string): Promise<boolean>;
 export declare function getUserRoles(userId: string): Promise<LTUserRole[]>;
 export declare function hasRole(userId: string, role: string): Promise<boolean>;

package/build/services/user/roles.js

@@ -8,17 +8,33 @@ exports.hasRole = hasRole;
 exports.hasRoleType = hasRoleType;
 const db_1 = require("../../lib/db");
 const sql_1 = require("./sql");
+const scope_1 = require("./scope");
 const types_1 = require("./types");
 // ─── Role management ──────────────────────────────────────────────────────────
 function isValidRoleType(type) {
     return types_1.VALID_ROLE_TYPES.includes(type);
 }
-async function addUserRole(userId, role, type) {
+async function addUserRole(userId, role, type, scope) {
+    // admin/superadmin always store ('all','all'); members store the requested scope.
+    const eff = (0, scope_1.effectiveScope)(type, scope?.read_scope ?? scope_1.DEFAULT_READ_SCOPE, scope?.write_scope ?? scope_1.DEFAULT_WRITE_SCOPE);
     const pool = (0, db_1.getPool)();
-    // Ensure the role exists in lt_roles (FK constraint)
-    await pool.query(sql_1.ENSURE_ROLE_EXISTS, [role]);
-    const { rows } = await pool.query(sql_1.UPSERT_USER_ROLE, [userId, role, type]);
-    return rows[0];
+    // Ensure-role (FK target) and the scoped user-role upsert commit together so a
+    // failure between them cannot leave the FK target without its assignment.
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        await client.query(sql_1.ENSURE_ROLE_EXISTS, [role]);
+        const { rows } = await client.query(sql_1.UPSERT_USER_ROLE, [userId, role, type, eff.read, eff.write]);
+        await client.query('COMMIT');
+        return rows[0];
+    }
+    catch (err) {
+        await client.query('ROLLBACK');
+        throw err;
+    }
+    finally {
+        client.release();
+    }
 }
 async function removeUserRole(userId, role) {
     const pool = (0, db_1.getPool)();

package/build/services/user/scope.d.ts

@@ -0,0 +1,22 @@
+import type { LTReadScope, LTRoleType, LTWriteScope } from '../../types';
+export declare const READ_SCOPES: LTReadScope[];
+export declare const WRITE_SCOPES: LTWriteScope[];
+/** Defaults preserve legacy `member` behavior (full role worker). */
+export declare const DEFAULT_READ_SCOPE: LTReadScope;
+export declare const DEFAULT_WRITE_SCOPE: LTWriteScope;
+export declare function isValidReadScope(scope: string): scope is LTReadScope;
+export declare function isValidWriteScope(scope: string): scope is LTWriteScope;
+/**
+ * Is (read, write) a valid point in the lattice? Enforces write ⊆ read:
+ * write='all' requires read='all'. (write='self'/'none' allowed under read='self'.)
+ */
+export declare function isValidScopePair(read: LTReadScope, write: LTWriteScope): boolean;
+/**
+ * Resolve the scope a membership actually grants. The management tier
+ * (admin/superadmin) short-circuits both axes to `all` — those users always
+ * search and act on the whole role queue regardless of stored scope columns.
+ */
+export declare function effectiveScope(type: LTRoleType, read: LTReadScope, write: LTWriteScope): {
+    read: LTReadScope;
+    write: LTWriteScope;
+};

package/build/services/user/scope.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = void 0;
+exports.isValidReadScope = isValidReadScope;
+exports.isValidWriteScope = isValidWriteScope;
+exports.isValidScopePair = isValidScopePair;
+exports.effectiveScope = effectiveScope;
+// ─── Role scope: the work-surface axes for an open-role membership ───────────
+//
+// A membership's `type` (member/admin/superadmin) is the management/global tier.
+// Orthogonal to it, a member also carries two scope axes that gate the four task
+// queue verbs:
+//
+//   read_scope  (self | all)        → governs SEARCH (which items appear)
+//   write_scope (none | self | all) → governs CLAIM / ACK / DELETE (which items
+//                                      the user may act on)
+//
+// `self` = items assigned to the user (`assigned_to = userId`). `all` = the whole
+// role queue. The only constraint is write ⊆ read: you cannot act on what you
+// cannot see (enforced in the DB by chk_lt_user_roles_scope). admin/superadmin
+// ignore scope and always operate on all.
+exports.READ_SCOPES = ['self', 'all'];
+exports.WRITE_SCOPES = ['none', 'self', 'all'];
+/** Defaults preserve legacy `member` behavior (full role worker). */
+exports.DEFAULT_READ_SCOPE = 'all';
+exports.DEFAULT_WRITE_SCOPE = 'all';
+function isValidReadScope(scope) {
+    return exports.READ_SCOPES.includes(scope);
+}
+function isValidWriteScope(scope) {
+    return exports.WRITE_SCOPES.includes(scope);
+}
+/**
+ * Is (read, write) a valid point in the lattice? Enforces write ⊆ read:
+ * write='all' requires read='all'. (write='self'/'none' allowed under read='self'.)
+ */
+function isValidScopePair(read, write) {
+    return !(write === 'all' && read === 'self');
+}
+/**
+ * Resolve the scope a membership actually grants. The management tier
+ * (admin/superadmin) short-circuits both axes to `all` — those users always
+ * search and act on the whole role queue regardless of stored scope columns.
+ */
+function effectiveScope(type, read, write) {
+    if (type === 'admin' || type === 'superadmin') {
+        return { read: 'all', write: 'all' };
+    }
+    return { read, write };
+}

package/build/services/user/seed-admin.js

@@ -20,23 +20,40 @@ async function seedAdmin(input) {
     catch { /* ON CONFLICT DO NOTHING */ }
     const existing = await (0, crud_1.getUserByExternalId)(externalId);
     if (existing) {
-        // Ensure existing user has the superadmin role
-        const roles = await (0, roles_1.getUserRoles)(existing.id);
-        const hasSuperadmin = roles.some((r) => r.role === 'superadmin' && r.type === 'superadmin');
-        if (!hasSuperadmin) {
-            await (0, roles_1.addUserRole)(existing.id, 'superadmin', 'superadmin');
-            logger_1.loggerRegistry.info(`[seed-admin] granted superadmin role to ${externalId}`);
+        return ensureSuperadmin(existing.id, externalId);
+    }
+    // Create. Concurrent container startups can both reach here; external_id UNIQUE
+    // is the arbiter — on the loser's 23505, adopt the winner's row instead of
+    // crashing the boot sequence.
+    try {
+        const user = await (0, crud_1.createUser)({
+            external_id: externalId,
+            email: email || undefined,
+            display_name: displayName || externalId,
+            password: password || undefined,
+            roles: [{ role: 'superadmin', type: 'superadmin' }],
+        });
+        logger_1.loggerRegistry.info(`[seed-admin] created superadmin user: ${externalId}`);
+        return user.id;
+    }
+    catch (err) {
+        if (err?.code === '23505') {
+            const winner = await (0, crud_1.getUserByExternalId)(externalId);
+            if (winner) {
+                return ensureSuperadmin(winner.id, externalId);
+            }
         }
-        logger_1.loggerRegistry.info(`[seed-admin] ${externalId} already exists, skipping creation`);
-        return existing.id;
+        throw err;
+    }
+}
+/** Ensure an existing user carries the superadmin role; returns its id. */
+async function ensureSuperadmin(userId, externalId) {
+    const roles = await (0, roles_1.getUserRoles)(userId);
+    const hasSuperadmin = roles.some((r) => r.role === 'superadmin' && r.type === 'superadmin');
+    if (!hasSuperadmin) {
+        await (0, roles_1.addUserRole)(userId, 'superadmin', 'superadmin');
+        logger_1.loggerRegistry.info(`[seed-admin] granted superadmin role to ${externalId}`);
     }
-    const user = await (0, crud_1.createUser)({
-        external_id: externalId,
-        email: email || undefined,
-        display_name: displayName || externalId,
-        password: password || undefined,
-        roles: [{ role: 'superadmin', type: 'superadmin' }],
-    });
-    logger_1.loggerRegistry.info(`[seed-admin] created superadmin user: ${externalId}`);
-    return user.id;
+    logger_1.loggerRegistry.info(`[seed-admin] ${externalId} already exists, skipping creation`);
+    return userId;
 }

package/build/services/user/sql.d.ts

@@ -1,24 +1,35 @@
 /** Ensure a role name exists in the lt_roles lookup table (FK target). */
 export declare const ENSURE_ROLE_EXISTS = "INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING";
 /** Fetch roles for a single user, ordered by creation time. */
-export declare const GET_ROLES_BY_USER_ID = "SELECT role, type, created_at FROM lt_user_roles WHERE user_id = $1 ORDER BY created_at";
+export declare const GET_ROLES_BY_USER_ID = "SELECT role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = $1 ORDER BY created_at";
 /** Fetch a user row by external_id. */
 export declare const GET_USER_BY_EXTERNAL_ID = "SELECT * FROM lt_users WHERE external_id = $1";
-export declare const INSERT_USER = "INSERT INTO lt_users (external_id, email, display_name, status, metadata, password_hash, oauth_provider, oauth_provider_id)\n   VALUES ($1, $2, $3, $4, $5, $6, $7, $8)\n   RETURNING *";
+/**
+ * Create a user and its role assignments in ONE atomic statement. The user row,
+ * the lt_roles FK targets ($9 = role names), and the lt_user_roles links
+ * ($9 names × $10 types × $11 read_scope × $12 write_scope) all commit together —
+ * a failure can never leave a half-provisioned user with a partial role set, and
+ * there is no per-role N+1. All four are passed as parallel text[] arrays (empty
+ * arrays → no roles). Postgres checks the lt_user_roles→lt_roles FK at statement
+ * end, after the sibling role-ensure CTE has run, so brand-new roles are valid
+ * FK targets.
+ */
+export declare const CREATE_USER_WITH_ROLES = "WITH new_user AS (\n     INSERT INTO lt_users (external_id, email, display_name, status, metadata, password_hash, oauth_provider, oauth_provider_id)\n     VALUES ($1, $2, $3, $4, $5, $6, $7, $8)\n     RETURNING *\n   ), ensured_roles AS (\n     INSERT INTO lt_roles (role)\n     SELECT DISTINCT unnest($9::text[])\n     ON CONFLICT DO NOTHING\n   ), assigned_roles AS (\n     INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope)\n     SELECT (SELECT id FROM new_user), x.role, x.type, x.read_scope, x.write_scope\n     FROM unnest($9::text[], $10::text[], $11::text[], $12::text[]) AS x(role, type, read_scope, write_scope)\n     ON CONFLICT DO NOTHING\n   )\n   SELECT * FROM new_user";
 export declare const GET_USER_BY_EMAIL = "SELECT * FROM lt_users WHERE email = $1 LIMIT 1";
-export declare const INSERT_USER_ROLE_IGNORE = "INSERT INTO lt_user_roles (user_id, role, type) VALUES ($1, $2, $3)\n   ON CONFLICT DO NOTHING";
 export declare const GET_USER_BY_ID = "SELECT * FROM lt_users WHERE id = $1";
 /** Check if a user exists by id. Lightweight — returns only the id column. */
 export declare const VERIFY_USER_BY_ID = "SELECT id FROM lt_users WHERE id = $1 LIMIT 1";
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */
-export declare const GET_USER_WITH_ROLES = "SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,\n          r.role, r.type AS role_type\n   FROM lt_users u\n   LEFT JOIN lt_user_roles r ON r.user_id = u.id\n   WHERE u.external_id = $1\n   ORDER BY r.created_at";
+export declare const GET_USER_WITH_ROLES = "SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,\n          r.role, r.type AS role_type, r.read_scope, r.write_scope\n   FROM lt_users u\n   LEFT JOIN lt_user_roles r ON r.user_id = u.id\n   WHERE u.external_id = $1\n   ORDER BY r.created_at";
 export declare const DELETE_USER_BY_ID = "DELETE FROM lt_users WHERE id = $1";
 /** Batch-load roles for many users (avoids N+1). */
-export declare const GET_ROLES_BY_USER_IDS = "SELECT user_id, role, type, created_at FROM lt_user_roles WHERE user_id = ANY($1) ORDER BY created_at";
-/** Upsert a user–role assignment, promoting the type if the row exists. */
-export declare const UPSERT_USER_ROLE = "INSERT INTO lt_user_roles (user_id, role, type) VALUES ($1, $2, $3)\n   ON CONFLICT (user_id, role) DO UPDATE SET type = EXCLUDED.type\n   RETURNING role, type, created_at";
+export declare const GET_ROLES_BY_USER_IDS = "SELECT user_id, role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = ANY($1) ORDER BY created_at";
+/** Upsert a user–role assignment, promoting the type/scope if the row exists. */
+export declare const UPSERT_USER_ROLE = "INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope) VALUES ($1, $2, $3, $4, $5)\n   ON CONFLICT (user_id, role) DO UPDATE SET\n     type = EXCLUDED.type,\n     read_scope = EXCLUDED.read_scope,\n     write_scope = EXCLUDED.write_scope\n   RETURNING role, type, read_scope, write_scope, created_at";
 export declare const DELETE_USER_ROLE = "DELETE FROM lt_user_roles WHERE user_id = $1 AND role = $2";
 export declare const HAS_ROLE = "SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND role = $2 LIMIT 1";
 export declare const HAS_ROLE_TYPE = "SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND type = $2 LIMIT 1";
+/** Fetch the management tier + scope for one (user, role) — used for write enforcement. */
+export declare const GET_ROLE_SCOPE = "SELECT type, read_scope, write_scope FROM lt_user_roles WHERE user_id = $1 AND role = $2 LIMIT 1";
 /** Check if a user is an admin (or superadmin) of a specific role group. */
 export declare const IS_GROUP_ADMIN = "SELECT 1 FROM lt_user_roles\n   WHERE user_id = $1\n     AND (\n       (role = $2 AND type IN ('admin', 'superadmin'))\n       OR type = 'superadmin'\n     )\n   LIMIT 1";

package/build/services/user/sql.js

@@ -1,26 +1,46 @@
 "use strict";
 // ─── Shared queries (used by multiple modules) ──────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IS_GROUP_ADMIN = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.VERIFY_USER_BY_ID = exports.GET_USER_BY_ID = exports.INSERT_USER_ROLE_IGNORE = exports.GET_USER_BY_EMAIL = exports.INSERT_USER = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = void 0;
+exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.VERIFY_USER_BY_ID = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = void 0;
 /** Ensure a role name exists in the lt_roles lookup table (FK target). */
 exports.ENSURE_ROLE_EXISTS = 'INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING';
 /** Fetch roles for a single user, ordered by creation time. */
-exports.GET_ROLES_BY_USER_ID = 'SELECT role, type, created_at FROM lt_user_roles WHERE user_id = $1 ORDER BY created_at';
+exports.GET_ROLES_BY_USER_ID = 'SELECT role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = $1 ORDER BY created_at';
 /** Fetch a user row by external_id. */
 exports.GET_USER_BY_EXTERNAL_ID = 'SELECT * FROM lt_users WHERE external_id = $1';
 // ─── User CRUD ───────────────────────────────────────────────────────────────
-exports.INSERT_USER = `INSERT INTO lt_users (external_id, email, display_name, status, metadata, password_hash, oauth_provider, oauth_provider_id)
-   VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
-   RETURNING *`;
+/**
+ * Create a user and its role assignments in ONE atomic statement. The user row,
+ * the lt_roles FK targets ($9 = role names), and the lt_user_roles links
+ * ($9 names × $10 types × $11 read_scope × $12 write_scope) all commit together —
+ * a failure can never leave a half-provisioned user with a partial role set, and
+ * there is no per-role N+1. All four are passed as parallel text[] arrays (empty
+ * arrays → no roles). Postgres checks the lt_user_roles→lt_roles FK at statement
+ * end, after the sibling role-ensure CTE has run, so brand-new roles are valid
+ * FK targets.
+ */
+exports.CREATE_USER_WITH_ROLES = `WITH new_user AS (
+     INSERT INTO lt_users (external_id, email, display_name, status, metadata, password_hash, oauth_provider, oauth_provider_id)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+     RETURNING *
+   ), ensured_roles AS (
+     INSERT INTO lt_roles (role)
+     SELECT DISTINCT unnest($9::text[])
+     ON CONFLICT DO NOTHING
+   ), assigned_roles AS (
+     INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope)
+     SELECT (SELECT id FROM new_user), x.role, x.type, x.read_scope, x.write_scope
+     FROM unnest($9::text[], $10::text[], $11::text[], $12::text[]) AS x(role, type, read_scope, write_scope)
+     ON CONFLICT DO NOTHING
+   )
+   SELECT * FROM new_user`;
 exports.GET_USER_BY_EMAIL = `SELECT * FROM lt_users WHERE email = $1 LIMIT 1`;
-exports.INSERT_USER_ROLE_IGNORE = `INSERT INTO lt_user_roles (user_id, role, type) VALUES ($1, $2, $3)
-   ON CONFLICT DO NOTHING`;
 exports.GET_USER_BY_ID = 'SELECT * FROM lt_users WHERE id = $1';
 /** Check if a user exists by id. Lightweight — returns only the id column. */
 exports.VERIFY_USER_BY_ID = 'SELECT id FROM lt_users WHERE id = $1 LIMIT 1';
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */
 exports.GET_USER_WITH_ROLES = `SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,
-          r.role, r.type AS role_type
+          r.role, r.type AS role_type, r.read_scope, r.write_scope
    FROM lt_users u
    LEFT JOIN lt_user_roles r ON r.user_id = u.id
    WHERE u.external_id = $1
@@ -28,14 +48,19 @@ exports.GET_USER_WITH_ROLES = `SELECT u.id, u.external_id, u.display_name, u.sta
 exports.DELETE_USER_BY_ID = 'DELETE FROM lt_users WHERE id = $1';
 // ─── Role management ─────────────────────────────────────────────────────────
 /** Batch-load roles for many users (avoids N+1). */
-exports.GET_ROLES_BY_USER_IDS = 'SELECT user_id, role, type, created_at FROM lt_user_roles WHERE user_id = ANY($1) ORDER BY created_at';
-/** Upsert a user–role assignment, promoting the type if the row exists. */
-exports.UPSERT_USER_ROLE = `INSERT INTO lt_user_roles (user_id, role, type) VALUES ($1, $2, $3)
-   ON CONFLICT (user_id, role) DO UPDATE SET type = EXCLUDED.type
-   RETURNING role, type, created_at`;
+exports.GET_ROLES_BY_USER_IDS = 'SELECT user_id, role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = ANY($1) ORDER BY created_at';
+/** Upsert a user–role assignment, promoting the type/scope if the row exists. */
+exports.UPSERT_USER_ROLE = `INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope) VALUES ($1, $2, $3, $4, $5)
+   ON CONFLICT (user_id, role) DO UPDATE SET
+     type = EXCLUDED.type,
+     read_scope = EXCLUDED.read_scope,
+     write_scope = EXCLUDED.write_scope
+   RETURNING role, type, read_scope, write_scope, created_at`;
 exports.DELETE_USER_ROLE = 'DELETE FROM lt_user_roles WHERE user_id = $1 AND role = $2';
 exports.HAS_ROLE = 'SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND role = $2 LIMIT 1';
 exports.HAS_ROLE_TYPE = 'SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND type = $2 LIMIT 1';
+/** Fetch the management tier + scope for one (user, role) — used for write enforcement. */
+exports.GET_ROLE_SCOPE = 'SELECT type, read_scope, write_scope FROM lt_user_roles WHERE user_id = $1 AND role = $2 LIMIT 1';
 // ─── RBAC ────────────────────────────────────────────────────────────────────
 /** Check if a user is an admin (or superadmin) of a specific role group. */
 exports.IS_GROUP_ADMIN = `SELECT 1 FROM lt_user_roles

package/build/services/user/sso-provision.js

@@ -18,34 +18,51 @@ async function ssoProvision(identity, ssoConfig) {
     const ltRoles = resolveRoles(identity.roles || [], defaultRoleType, ssoConfig.roleMap);
     const existing = await (0, crud_1.getUserByExternalId)(identity.externalId);
     if (existing) {
-        // Sync roles: ensure all resolved roles exist on the user
-        const currentRoles = await (0, roles_1.getUserRoles)(existing.id);
-        for (const lr of ltRoles) {
-            const has = currentRoles.some((r) => r.role === lr.role);
-            if (!has) {
-                await (0, roles_1.addUserRole)(existing.id, lr.role, lr.type);
-            }
-        }
-        const updatedRoles = await (0, roles_1.getUserRoles)(existing.id);
+        return syncExistingUser(existing.id, ltRoles);
+    }
+    // Create new user. Two concurrent first-logins for the same identity can both
+    // pass the existence check above; external_id UNIQUE is the arbiter. The loser's
+    // insert raises 23505 — adopt the winner's committed row and sync roles rather
+    // than failing the login.
+    try {
+        const user = await (0, crud_1.createUser)({
+            external_id: identity.externalId,
+            email: identity.email || undefined,
+            display_name: identity.displayName || identity.externalId,
+            roles: ltRoles.map((r) => ({ role: r.role, type: r.type })),
+            metadata: identity.metadata,
+        });
+        logger_1.loggerRegistry.info(`[lt-sso] provisioned user: ${identity.externalId} → ${user.id}`);
         return {
-            userId: existing.id,
-            roles: updatedRoles.map((r) => ({ role: r.role, type: r.type })),
-            created: false,
+            userId: user.id,
+            roles: (user.roles || []).map((r) => ({ role: r.role, type: r.type })),
+            created: true,
         };
     }
-    // Create new user
-    const user = await (0, crud_1.createUser)({
-        external_id: identity.externalId,
-        email: identity.email || undefined,
-        display_name: identity.displayName || identity.externalId,
-        roles: ltRoles.map((r) => ({ role: r.role, type: r.type })),
-        metadata: identity.metadata,
-    });
-    logger_1.loggerRegistry.info(`[lt-sso] provisioned user: ${identity.externalId} → ${user.id}`);
+    catch (err) {
+        if (err?.code === '23505') {
+            const winner = await (0, crud_1.getUserByExternalId)(identity.externalId);
+            if (winner) {
+                return syncExistingUser(winner.id, ltRoles);
+            }
+        }
+        throw err;
+    }
+}
+/** Ensure all resolved roles exist on an already-provisioned user. */
+async function syncExistingUser(userId, ltRoles) {
+    const currentRoles = await (0, roles_1.getUserRoles)(userId);
+    for (const lr of ltRoles) {
+        const has = currentRoles.some((r) => r.role === lr.role);
+        if (!has) {
+            await (0, roles_1.addUserRole)(userId, lr.role, lr.type);
+        }
+    }
+    const updatedRoles = await (0, roles_1.getUserRoles)(userId);
     return {
-        userId: user.id,
-        roles: (user.roles || []).map((r) => ({ role: r.role, type: r.type })),
-        created: true,
+        userId,
+        roles: updatedRoles.map((r) => ({ role: r.role, type: r.type })),
+        created: false,
     };
 }
 function resolveRoles(hostRoles, defaultRoleType, roleMap) {

package/build/services/user/types.d.ts

@@ -1,5 +1,12 @@
-import type { LTRoleType, LTUserStatus } from '../../types';
+import type { LTReadScope, LTRoleType, LTUserStatus, LTWriteScope } from '../../types';
 export declare const VALID_ROLE_TYPES: LTRoleType[];
+/** A role grant on user create: management tier + optional work-surface scope. */
+export interface RoleGrantInput {
+    role: string;
+    type: LTRoleType;
+    read_scope?: LTReadScope;
+    write_scope?: LTWriteScope;
+}
 export interface CreateUserInput {
     external_id: string;
     email?: string;
@@ -7,10 +14,7 @@ export interface CreateUserInput {
     password?: string;
     status?: LTUserStatus;
     metadata?: Record<string, any>;
-    roles?: {
-        role: string;
-        type: LTRoleType;
-    }[];
+    roles?: RoleGrantInput[];
     /** OAuth identity link (set during OAuth auto-provisioning). */
     oauth_provider?: string;
     oauth_provider_id?: string;

package/build/start/adapters.js

@@ -15,12 +15,15 @@ const adapter_1 = require("../services/mcp/adapter");
 const escalation_strategy_1 = require("../services/escalation-strategy");
 const default_1 = require("../services/escalation-strategy/default");
 const mcp_2 = require("../services/escalation-strategy/mcp");
+const features_1 = require("../modules/features");
 const socket_auth_1 = require("./socket-auth");
 /**
  * Register all adapters (logging, telemetry, events, maintenance,
  * escalation strategy, MCP) based on the startup config.
  */
 function registerAdapters(startConfig) {
+    // Dashboard feature flags (default permissive; deployment opts out).
+    (0, features_1.configureFeatureFlags)(startConfig.features);
     // Logging (register first so subsequent log calls use it)
     if (startConfig.logging?.adapter) {
         logger_1.loggerRegistry.register(startConfig.logging.adapter);