@hotmeshio/long-tail 0.1.0

package/build/services/user/crud.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachRoles = attachRoles;
+exports.createUser = createUser;
+exports.getUser = getUser;
+exports.getUserByExternalId = getUserByExternalId;
+exports.getUserByEmail = getUserByEmail;
+exports.updateUser = updateUser;
+exports.deleteUser = deleteUser;
+exports.listUsers = listUsers;
+const bcryptjs_1 = __importDefault(require("bcryptjs"));
+const db_1 = require("../db");
+const sql_1 = require("./sql");
+// ─── Private helpers (exported for internal use by auth.ts) ──────────────────
+async function attachRoles(user) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_ROLES_BY_USER_ID, [user.id]);
+    return { ...user, roles: rows };
+}
+async function attachRolesToMany(users) {
+    if (users.length === 0)
+        return [];
+    const pool = (0, db_1.getPool)();
+    const ids = users.map((u) => u.id);
+    const { rows } = await pool.query(sql_1.GET_ROLES_BY_USER_IDS, [ids]);
+    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 });
+        roleMap.set(row.user_id, list);
+    }
+    return users.map((u) => ({ ...u, roles: roleMap.get(u.id) || [] }));
+}
+// ─── CRUD ─────────────────────────────────────────────────────────────────────
+async function createUser(input) {
+    const pool = (0, db_1.getPool)();
+    const passwordHash = input.password
+        ? await bcryptjs_1.default.hash(input.password, 10)
+        : null;
+    const { rows } = await pool.query(sql_1.INSERT_USER, [
+        input.external_id,
+        input.email || null,
+        input.display_name || null,
+        input.status || 'active',
+        input.metadata ? JSON.stringify(input.metadata) : null,
+        passwordHash,
+        input.oauth_provider || null,
+        input.oauth_provider_id || null,
+    ]);
+    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);
+}
+async function getUser(id) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_USER_BY_ID, [id]);
+    if (!rows[0])
+        return null;
+    return attachRoles(rows[0]);
+}
+async function getUserByExternalId(externalId) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_USER_BY_EXTERNAL_ID, [externalId]);
+    if (!rows[0])
+        return null;
+    return attachRoles(rows[0]);
+}
+async function getUserByEmail(email) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_USER_BY_EMAIL, [email]);
+    if (!rows[0])
+        return null;
+    return attachRoles(rows[0]);
+}
+async function updateUser(id, input) {
+    const pool = (0, db_1.getPool)();
+    const sets = [];
+    const values = [];
+    let idx = 1;
+    if (input.email !== undefined) {
+        sets.push(`email = $${idx++}`);
+        values.push(input.email);
+    }
+    if (input.display_name !== undefined) {
+        sets.push(`display_name = $${idx++}`);
+        values.push(input.display_name);
+    }
+    if (input.status !== undefined) {
+        sets.push(`status = $${idx++}`);
+        values.push(input.status);
+    }
+    if (input.metadata !== undefined) {
+        sets.push(`metadata = $${idx++}`);
+        values.push(JSON.stringify(input.metadata));
+    }
+    if (sets.length === 0) {
+        return getUser(id);
+    }
+    values.push(id);
+    const { rows } = await pool.query(`UPDATE lt_users SET ${sets.join(', ')} WHERE id = $${idx} RETURNING *`, values);
+    if (!rows[0])
+        return null;
+    return attachRoles(rows[0]);
+}
+async function deleteUser(id) {
+    const pool = (0, db_1.getPool)();
+    const { rowCount } = await pool.query(sql_1.DELETE_USER_BY_ID, [id]);
+    return (rowCount ?? 0) > 0;
+}
+async function listUsers(filters) {
+    const pool = (0, db_1.getPool)();
+    const conditions = [];
+    const values = [];
+    let idx = 1;
+    let needsJoin = false;
+    if (filters.role) {
+        needsJoin = true;
+        conditions.push(`r.role = $${idx++}`);
+        values.push(filters.role);
+    }
+    if (filters.roleType) {
+        needsJoin = true;
+        conditions.push(`r.type = $${idx++}`);
+        values.push(filters.roleType);
+    }
+    if (filters.status) {
+        conditions.push(`u.status = $${idx++}`);
+        values.push(filters.status);
+    }
+    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;
+    const offset = filters.offset || 0;
+    const [countResult, dataResult] = await Promise.all([
+        pool.query(`SELECT COUNT(DISTINCT u.id) FROM lt_users u ${join} ${where}`, values),
+        pool.query(`SELECT DISTINCT u.* FROM lt_users u ${join} ${where} ORDER BY u.created_at DESC LIMIT $${idx++} OFFSET $${idx++}`, [...values, limit, offset]),
+    ]);
+    return {
+        users: await attachRolesToMany(dataResult.rows),
+        total: parseInt(countResult.rows[0].count, 10),
+    };
+}

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

@@ -0,0 +1,5 @@
+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 } from './rbac';
+export { verifyPassword } from './auth';

package/build/services/user/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyPassword = 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");
+Object.defineProperty(exports, "createUser", { enumerable: true, get: function () { return crud_1.createUser; } });
+Object.defineProperty(exports, "getUser", { enumerable: true, get: function () { return crud_1.getUser; } });
+Object.defineProperty(exports, "getUserByExternalId", { enumerable: true, get: function () { return crud_1.getUserByExternalId; } });
+Object.defineProperty(exports, "getUserByEmail", { enumerable: true, get: function () { return crud_1.getUserByEmail; } });
+Object.defineProperty(exports, "updateUser", { enumerable: true, get: function () { return crud_1.updateUser; } });
+Object.defineProperty(exports, "deleteUser", { enumerable: true, get: function () { return crud_1.deleteUser; } });
+Object.defineProperty(exports, "listUsers", { enumerable: true, get: function () { return crud_1.listUsers; } });
+var roles_1 = require("./roles");
+Object.defineProperty(exports, "isValidRoleType", { enumerable: true, get: function () { return roles_1.isValidRoleType; } });
+Object.defineProperty(exports, "addUserRole", { enumerable: true, get: function () { return roles_1.addUserRole; } });
+Object.defineProperty(exports, "removeUserRole", { enumerable: true, get: function () { return roles_1.removeUserRole; } });
+Object.defineProperty(exports, "getUserRoles", { enumerable: true, get: function () { return roles_1.getUserRoles; } });
+Object.defineProperty(exports, "hasRole", { enumerable: true, get: function () { return roles_1.hasRole; } });
+Object.defineProperty(exports, "hasRoleType", { enumerable: true, get: function () { return roles_1.hasRoleType; } });
+var rbac_1 = require("./rbac");
+Object.defineProperty(exports, "isSuperAdmin", { enumerable: true, get: function () { return rbac_1.isSuperAdmin; } });
+Object.defineProperty(exports, "isGroupAdmin", { enumerable: true, get: function () { return rbac_1.isGroupAdmin; } });
+Object.defineProperty(exports, "canManageRole", { enumerable: true, get: function () { return rbac_1.canManageRole; } });
+var auth_1 = require("./auth");
+Object.defineProperty(exports, "verifyPassword", { enumerable: true, get: function () { return auth_1.verifyPassword; } });

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

@@ -0,0 +1,15 @@
+/**
+ * Is the user a superadmin? (global — can manage all users and roles)
+ */
+export declare function isSuperAdmin(userId: string): Promise<boolean>;
+/**
+ * Is the user an admin of a specific role group?
+ * Returns true if the user has `type = 'admin'` or `type = 'superadmin'` for that role,
+ * OR if the user is a global superadmin (superadmin on any role).
+ */
+export declare function isGroupAdmin(userId: string, role: string): Promise<boolean>;
+/**
+ * Can the actor manage members of the given role?
+ * Superadmins can manage any role. Admins can manage roles they belong to.
+ */
+export declare function canManageRole(actorId: string, role: string): Promise<boolean>;

package/build/services/user/rbac.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSuperAdmin = isSuperAdmin;
+exports.isGroupAdmin = isGroupAdmin;
+exports.canManageRole = canManageRole;
+const db_1 = require("../db");
+const roles_1 = require("./roles");
+const sql_1 = require("./sql");
+// ─── RBAC helpers ─────────────────────────────────────────────────────────────
+/**
+ * Is the user a superadmin? (global — can manage all users and roles)
+ */
+async function isSuperAdmin(userId) {
+    return (0, roles_1.hasRoleType)(userId, 'superadmin');
+}
+/**
+ * Is the user an admin of a specific role group?
+ * Returns true if the user has `type = 'admin'` or `type = 'superadmin'` for that role,
+ * OR if the user is a global superadmin (superadmin on any role).
+ */
+async function isGroupAdmin(userId, role) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.IS_GROUP_ADMIN, [userId, role]);
+    return rows.length > 0;
+}
+/**
+ * Can the actor manage members of the given role?
+ * Superadmins can manage any role. Admins can manage roles they belong to.
+ */
+async function canManageRole(actorId, role) {
+    return isGroupAdmin(actorId, role);
+}

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

@@ -0,0 +1,7 @@
+import type { LTUserRole, LTRoleType } from '../../types';
+export declare function isValidRoleType(type: string): type is LTRoleType;
+export declare function addUserRole(userId: string, role: string, type: LTRoleType): 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>;
+export declare function hasRoleType(userId: string, type: LTRoleType): Promise<boolean>;

package/build/services/user/roles.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidRoleType = isValidRoleType;
+exports.addUserRole = addUserRole;
+exports.removeUserRole = removeUserRole;
+exports.getUserRoles = getUserRoles;
+exports.hasRole = hasRole;
+exports.hasRoleType = hasRoleType;
+const db_1 = require("../db");
+const sql_1 = require("./sql");
+const types_1 = require("./types");
+// ─── Role management ──────────────────────────────────────────────────────────
+function isValidRoleType(type) {
+    return types_1.VALID_ROLE_TYPES.includes(type);
+}
+async function addUserRole(userId, role, type) {
+    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];
+}
+async function removeUserRole(userId, role) {
+    const pool = (0, db_1.getPool)();
+    const { rowCount } = await pool.query(sql_1.DELETE_USER_ROLE, [userId, role]);
+    return (rowCount ?? 0) > 0;
+}
+async function getUserRoles(userId) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_ROLES_BY_USER_ID, [userId]);
+    return rows;
+}
+async function hasRole(userId, role) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.HAS_ROLE, [userId, role]);
+    return rows.length > 0;
+}
+async function hasRoleType(userId, type) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.HAS_ROLE_TYPE, [userId, type]);
+    return rows.length > 0;
+}

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

@@ -0,0 +1,22 @@
+/** 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";
+/** 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 *";
+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";
+/** 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 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 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";
+/** 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

@@ -0,0 +1,45 @@
+"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.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;
+/** 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';
+/** 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 *`;
+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';
+/** 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
+   FROM lt_users u
+   LEFT JOIN lt_user_roles r ON r.user_id = u.id
+   WHERE u.external_id = $1
+   ORDER BY r.created_at`;
+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.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';
+// ─── 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
+   WHERE user_id = $1
+     AND (
+       (role = $2 AND type IN ('admin', 'superadmin'))
+       OR type = 'superadmin'
+     )
+   LIMIT 1`;

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

@@ -0,0 +1,23 @@
+import type { LTRoleType, LTUserStatus } from '../../types';
+export declare const VALID_ROLE_TYPES: LTRoleType[];
+export interface CreateUserInput {
+    external_id: string;
+    email?: string;
+    display_name?: string;
+    password?: string;
+    status?: LTUserStatus;
+    metadata?: Record<string, any>;
+    roles?: {
+        role: string;
+        type: LTRoleType;
+    }[];
+    /** OAuth identity link (set during OAuth auto-provisioning). */
+    oauth_provider?: string;
+    oauth_provider_id?: string;
+}
+export interface UpdateUserInput {
+    email?: string;
+    display_name?: string;
+    status?: LTUserStatus;
+    metadata?: Record<string, any>;
+}

package/build/services/user/types.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_ROLE_TYPES = void 0;
+exports.VALID_ROLE_TYPES = ['superadmin', 'admin', 'member'];

package/build/services/workers/registry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * In-memory registry of active durable workers.
+ * Populated at startup after `Durable.Worker.create()`.
+ */
+export declare function registerWorker(name: string, taskQueue: string): void;
+export declare function getRegisteredWorkers(): Map<string, {
+    taskQueue: string;
+}>;
+/** System workflows excluded from the overview by default. */
+export declare const SYSTEM_WORKFLOWS: Set<string>;

package/build/services/workers/registry.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * In-memory registry of active durable workers.
+ * Populated at startup after `Durable.Worker.create()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYSTEM_WORKFLOWS = void 0;
+exports.registerWorker = registerWorker;
+exports.getRegisteredWorkers = getRegisteredWorkers;
+const workers = new Map();
+function registerWorker(name, taskQueue) {
+    workers.set(name, { taskQueue });
+}
+function getRegisteredWorkers() {
+    return workers;
+}
+/** System workflows excluded from the overview by default. */
+exports.SYSTEM_WORKFLOWS = new Set([
+    'mcpQuery',
+    'mcpDeterministic',
+    'mcpQueryRouter',
+    'mcpTriage',
+    'mcpTriageRouter',
+    'mcpTriageDeterministic',
+    'insightQuery',
+]);

package/build/services/workflow-invocation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Workflow invocation service.
+ *
+ * Encapsulates the business logic for starting a workflow by type:
+ * config lookup, role/scope enforcement, principal resolution,
+ * envelope building, and Durable client start.
+ *
+ * Transport-agnostic — called by HTTP routes, CLI, or other transports.
+ */
+export interface InvocationAuthContext {
+    /** JWT or API-key userId (external_id or UUID). */
+    userId: string;
+    /** High-level role from auth middleware (e.g. 'admin', 'superadmin'). */
+    role?: string;
+    /** Bot API key scopes (empty for human JWTs). */
+    scopes?: string[];
+}
+export interface InvokeWorkflowInput {
+    workflowType: string;
+    data: Record<string, any>;
+    metadata?: Record<string, any>;
+    /** Per-request execute_as override (admin-only). */
+    executeAs?: string;
+    auth: InvocationAuthContext;
+}
+export interface InvokeWorkflowResult {
+    workflowId: string;
+}
+export declare class InvocationError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+/**
+ * Start a workflow by its registered type.
+ *
+ * Validates config, roles, scopes, resolves principals, builds the
+ * LTEnvelope, and starts the workflow via the Durable client.
+ *
+ * Throws `InvocationError` with an appropriate status code on failure.
+ */
+export declare function invokeWorkflow(input: InvokeWorkflowInput): Promise<InvokeWorkflowResult>;
+/**
+ * Check invocation_roles when present on a workflow config.
+ * Throws InvocationError if the user lacks the required role.
+ */
+export declare function checkInvocationRoles(workflowType: string, userId: string): Promise<void>;

package/build/services/workflow-invocation.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * Workflow invocation service.
+ *
+ * Encapsulates the business logic for starting a workflow by type:
+ * config lookup, role/scope enforcement, principal resolution,
+ * envelope building, and Durable client start.
+ *
+ * Transport-agnostic — called by HTTP routes, CLI, or other transports.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvocationError = void 0;
+exports.invokeWorkflow = invokeWorkflow;
+exports.checkInvocationRoles = checkInvocationRoles;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const workers_1 = require("../workers");
+const configService = __importStar(require("./config"));
+const userService = __importStar(require("./user"));
+const defaults_1 = require("../modules/defaults");
+const registry_1 = require("./workers/registry");
+const principal_1 = require("./iam/principal");
+// ── Error types ─────────────────────────────────────────────────────────────
+class InvocationError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'InvocationError';
+    }
+}
+exports.InvocationError = InvocationError;
+// ── Service ─────────────────────────────────────────────────────────────────
+/**
+ * Start a workflow by its registered type.
+ *
+ * Validates config, roles, scopes, resolves principals, builds the
+ * LTEnvelope, and starts the workflow via the Durable client.
+ *
+ * Throws `InvocationError` with an appropriate status code on failure.
+ */
+async function invokeWorkflow(input) {
+    const { workflowType, data, metadata, executeAs: executeAsOverride, auth } = input;
+    // 1. Look up workflow config and resolve task queue
+    const taskQueue = await resolveTaskQueue(workflowType);
+    // 2. Enforce bot API key scopes
+    const authScopes = auth.scopes ?? [];
+    if (authScopes.length > 0 && !authScopes.includes('workflow:invoke')) {
+        throw new InvocationError('API key scope does not include workflow:invoke', 403);
+    }
+    // 3. Validate inputs
+    if (!data || typeof data !== 'object') {
+        throw new InvocationError('Request body must include a data object', 400);
+    }
+    if (executeAsOverride && auth.role !== 'admin' && auth.role !== 'superadmin') {
+        throw new InvocationError('execute_as override requires admin role', 403);
+    }
+    // 4. Resolve principals and build envelope
+    const wfConfig = await configService.getWorkflowConfig(workflowType);
+    const envelope = await buildEnvelope(data, metadata ?? {}, auth.userId, executeAsOverride, wfConfig?.execute_as ?? undefined);
+    // 5. Start workflow
+    const client = (0, workers_1.createClient)();
+    const workflowId = `${workflowType}-${hotmesh_1.Durable.guid()}`;
+    await client.workflow.start({
+        args: [envelope],
+        taskQueue,
+        workflowName: workflowType,
+        workflowId,
+        expire: defaults_1.JOB_EXPIRE_SECS,
+        entity: workflowType,
+    });
+    return { workflowId };
+}
+// ── Internal helpers ────────────────────────────────────────────────────────
+/**
+ * Resolve the task queue for a workflow type. Checks the config table
+ * first (with invocable/role guards), then falls back to active workers.
+ */
+async function resolveTaskQueue(workflowType) {
+    const wfConfig = await configService.getWorkflowConfig(workflowType);
+    if (wfConfig) {
+        if (!wfConfig.invocable) {
+            throw new InvocationError('Workflow is not invocable', 403);
+        }
+        if (!wfConfig.task_queue) {
+            throw new InvocationError('Workflow has no task_queue configured', 400);
+        }
+        return wfConfig.task_queue;
+    }
+    // No config — fall back to active worker registry
+    const worker = (0, registry_1.getRegisteredWorkers)().get(workflowType);
+    if (!worker) {
+        throw new InvocationError('Workflow not found (no config and no active worker)', 404);
+    }
+    return worker.taskQueue;
+}
+/**
+ * Check invocation_roles when present on a workflow config.
+ * Throws InvocationError if the user lacks the required role.
+ */
+async function checkInvocationRoles(workflowType, userId) {
+    const wfConfig = await configService.getWorkflowConfig(workflowType);
+    if (!wfConfig || wfConfig.invocation_roles.length === 0)
+        return;
+    const user = await userService.getUserByExternalId(userId);
+    if (!user) {
+        throw new InvocationError('User not registered', 403);
+    }
+    const userRoles = user.roles.map((r) => r.role);
+    const hasInvocationRole = wfConfig.invocation_roles.some((r) => userRoles.includes(r));
+    if (!hasInvocationRole) {
+        const isSuperAdmin = user.roles.some((r) => r.type === 'superadmin');
+        if (!isSuperAdmin) {
+            throw new InvocationError('Insufficient role for invocation', 403);
+        }
+    }
+}
+/**
+ * Build the LTEnvelope with IAM context.
+ */
+async function buildEnvelope(data, metadata, userId, executeAsOverride, configExecuteAs) {
+    const executeAs = executeAsOverride ?? configExecuteAs;
+    let principal;
+    let initiatingPrincipal;
+    if (executeAs) {
+        const [botP, userP] = await Promise.all([
+            (0, principal_1.resolvePrincipal)(executeAs),
+            userId ? (0, principal_1.resolvePrincipal)(userId) : Promise.resolve(null),
+        ]);
+        principal = botP ?? undefined;
+        initiatingPrincipal = userP ?? undefined;
+    }
+    else if (userId) {
+        principal = (await (0, principal_1.resolvePrincipal)(userId)) ?? undefined;
+    }
+    const resolvedUserId = principal?.id ?? userId;
+    const resolvedInitiatorId = initiatingPrincipal?.id ?? userId;
+    return {
+        data,
+        metadata,
+        lt: {
+            userId: executeAs ? principal?.id ?? executeAs : resolvedUserId,
+            principal: principal ?? undefined,
+            scopes: ['workflow:invoke'],
+            ...(executeAs && userId
+                ? {
+                    initiatedBy: resolvedInitiatorId,
+                    initiatingPrincipal: initiatingPrincipal ?? undefined,
+                }
+                : {}),
+        },
+    };
+}