@hotmeshio/long-tail 0.4.18 → 0.4.19

package/README.md

@@ -62,8 +62,6 @@ Dashboard at [http://localhost:3000](http://localhost:3000). The [boilerplate](h
 
 ## The pattern
 
-Most systems start with a durable workflow and stop there. Long Tail keeps going.
-
 **Step 1 — Author a durable workflow.** Your function checkpoints to Postgres. It can sleep, branch, call child workflows, wait for signals. Standard durable execution.
 
 **Step 2 — Certify it.** Promotion to certified adds interceptor guarantees: failures escalate instead of throwing, escalation chains route through RBAC-scoped roles, and every error is either handled or surfaced. It cannot silently fail.

package/build/api/auth-sso.d.ts

@@ -0,0 +1,12 @@
+import type { Request } from 'express';
+import type { LTApiResult } from '../types/sdk';
+/**
+ * Exchange host authentication for a Long Tail JWT.
+ *
+ * Calls `sso.resolve(req)` to extract the host identity, JIT provisions
+ * the user in `lt_users`, and returns a signed JWT the dashboard can
+ * store for subsequent API calls.
+ *
+ * No request body required — the host's cookies/headers carry the auth.
+ */
+export declare function exchangeSSO(req: Request): Promise<LTApiResult>;

package/build/api/auth-sso.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exchangeSSO = exchangeSSO;
+const sso_1 = require("../modules/sso");
+const sso_provision_1 = require("../services/user/sso-provision");
+const auth_1 = require("../modules/auth");
+/**
+ * Exchange host authentication for a Long Tail JWT.
+ *
+ * Calls `sso.resolve(req)` to extract the host identity, JIT provisions
+ * the user in `lt_users`, and returns a signed JWT the dashboard can
+ * store for subsequent API calls.
+ *
+ * No request body required — the host's cookies/headers carry the auth.
+ */
+async function exchangeSSO(req) {
+    try {
+        const ssoConfig = (0, sso_1.getSSOConfig)();
+        if (!ssoConfig) {
+            return { status: 404, error: 'SSO not configured' };
+        }
+        const identity = await ssoConfig.resolve(req);
+        if (!identity) {
+            return { status: 401, error: 'Host authentication required' };
+        }
+        const provisioned = await (0, sso_provision_1.ssoProvision)(identity, ssoConfig);
+        const highestType = provisioned.roles.some((r) => r.type === 'superadmin')
+            ? 'superadmin'
+            : provisioned.roles.some((r) => r.type === 'admin')
+                ? 'admin'
+                : 'member';
+        const token = (0, auth_1.signToken)({
+            userId: provisioned.userId,
+            role: highestType,
+            roles: provisioned.roles,
+            sso: true,
+        }, '24h');
+        return {
+            status: 200,
+            data: {
+                token,
+                user: {
+                    id: provisioned.userId,
+                    external_id: identity.externalId,
+                    display_name: identity.displayName || identity.externalId,
+                    roles: provisioned.roles,
+                },
+            },
+        };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/escalations/bulk.js

@@ -141,8 +141,8 @@ async function bulkAssign(input, auth) {
         if (!perm.allowed)
             return perm;
         // Non-superadmin: target user must hold each escalation's role
-        const isSuperAdminUser = await userService.isSuperAdmin(auth.userId);
-        if (!isSuperAdminUser) {
+        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
+        if (!hasGlobal) {
             const roles = await escalationService.getEscalationRoles(ids);
             for (const role of roles) {
                 const targetHasRole = await userService.hasRole(targetUserId, role);

package/build/api/escalations/claim.js

@@ -37,7 +37,7 @@ exports.claimEscalation = claimEscalation;
 exports.releaseEscalation = releaseEscalation;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
-const publish_1 = require("../../lib/events/publish");
+const helpers_1 = require("./helpers");
 /**
  * Claim a pending escalation for the authenticated user.
  *
@@ -57,8 +57,8 @@ async function claimEscalation(input, auth) {
         if (!escalation) {
             return { status: 404, error: 'Escalation not found' };
         }
-        const isSuperAdminUser = await userService.isSuperAdmin(auth.userId);
-        if (!isSuperAdminUser) {
+        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
+        if (!hasGlobal) {
             const userHasRole = await userService.hasRole(auth.userId, escalation.role);
             if (!userHasRole) {
                 return {
@@ -94,16 +94,6 @@ async function releaseEscalation(input, auth) {
         if (!result) {
             return { status: 409, error: 'Escalation not found or not claimed by you' };
         }
-        (0, publish_1.publishEscalationEvent)({
-            type: 'escalation.released',
-            source: 'api',
-            workflowId: result.workflow_id || '',
-            workflowName: result.workflow_type || '',
-            taskQueue: result.task_queue || '',
-            escalationId: input.id,
-            status: 'released',
-            data: { released_by: auth.userId },
-        });
         return { status: 200, data: { escalation: result } };
     }
     catch (err) {

package/build/api/escalations/create.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEscalation = createEscalation;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
+const helpers_1 = require("./helpers");
 // ── Create ────────────────────────────────────────────────────────────────
 /**
  * Create a standalone escalation (not tied to a workflow).
@@ -65,8 +66,8 @@ async function createEscalation(input, auth) {
             return { status: 400, error: 'role is required' };
         }
         // RBAC: caller must hold the target role or be superadmin
-        const isSuperAdminUser = await userService.isSuperAdmin(auth.userId);
-        if (!isSuperAdminUser) {
+        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
+        if (!hasGlobal) {
             const userHasRole = await userService.hasRole(auth.userId, role);
             if (!userHasRole) {
                 return { status: 403, error: `You must hold the "${role}" role or be a superadmin to create escalations for it` };

package/build/api/escalations/helpers.d.ts

@@ -1,3 +1,4 @@
+export { hasGlobalEscalationAccess } from '../../services/user';
 export declare function getVisibleRoles(userId: string): Promise<string[] | undefined>;
 export declare function validateIds(ids: unknown): ids is string[];
 export declare function checkBulkPermission(userId: string, ids: string[]): Promise<{

package/build/api/escalations/helpers.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasGlobalEscalationAccess = void 0;
 exports.getVisibleRoles = getVisibleRoles;
 exports.validateIds = validateIds;
 exports.checkBulkPermission = checkBulkPermission;
@@ -42,9 +43,11 @@ const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
 const publish_1 = require("../../lib/events/publish");
 // ── Private helpers ────────────────────────────────────────────────────────
+// Re-export from service layer for use by escalation API modules
+var user_1 = require("../../services/user");
+Object.defineProperty(exports, "hasGlobalEscalationAccess", { enumerable: true, get: function () { return user_1.hasGlobalEscalationAccess; } });
 async function getVisibleRoles(userId) {
-    const isSuperAdminUser = await userService.isSuperAdmin(userId);
-    if (isSuperAdminUser)
+    if (await userService.hasGlobalEscalationAccess(userId))
         return undefined;
     const userRoles = await userService.getUserRoles(userId);
     return userRoles.map((r) => r.role);
@@ -53,8 +56,7 @@ function validateIds(ids) {
     return Array.isArray(ids) && ids.length > 0;
 }
 async function checkBulkPermission(userId, ids) {
-    const isSuperAdminUser = await userService.isSuperAdmin(userId);
-    if (isSuperAdminUser)
+    if (await userService.hasGlobalEscalationAccess(userId))
         return { allowed: true };
     const roles = await escalationService.getEscalationRoles(ids);
     for (const role of roles) {

package/build/api/escalations/list.d.ts

@@ -24,6 +24,7 @@ export declare function listEscalations(input: {
     type?: string;
     subtype?: string;
     assigned_to?: string;
+    claimed?: boolean;
     priority?: number;
     limit?: number;
     offset?: number;

package/build/api/escalations/list.js

@@ -71,6 +71,7 @@ async function listEscalations(input, auth) {
             type: input.type,
             subtype: input.subtype,
             assigned_to: input.assigned_to,
+            claimed: input.claimed,
             priority: input.priority,
             limit: input.limit,
             offset: input.offset,

package/build/api/escalations/metadata.js

@@ -97,8 +97,8 @@ async function claimByMetadata(input, auth) {
             return { status: 404, error: 'No pending escalation found for this metadata' };
         }
         const candidate = candidates.escalations[0];
-        const isSuperAdmin = await userService.isSuperAdmin(auth.userId);
-        if (!isSuperAdmin) {
+        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
+        if (!hasGlobal) {
             const userHasRole = await userService.hasRole(claimUserId, candidate.role);
             if (!userHasRole) {
                 return { status: 403, error: `User must have the "${candidate.role}" role to claim this escalation` };
@@ -144,8 +144,8 @@ async function resolveByMetadata(input, auth) {
         if ('error' in resolved)
             return resolved.error;
         const resolveUserId = resolved.userId;
-        const isSuperAdmin = await userService.isSuperAdmin(auth.userId);
-        if (!isSuperAdmin) {
+        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
+        if (!hasGlobal) {
             const userHasRole = await userService.hasRole(resolveUserId, escalation.role);
             if (!userHasRole) {
                 return { status: 403, error: `User must have the "${escalation.role}" role` };

package/build/api/escalations/single.js

@@ -39,6 +39,7 @@ exports.escalateToRole = escalateToRole;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
 const roleService = __importStar(require("../../services/role"));
+const helpers_1 = require("./helpers");
 // ── Single-escalation routes ───────────────────────────────────────────────
 /**
  * Get a single escalation by ID.
@@ -55,8 +56,8 @@ async function getEscalation(input, auth) {
         if (!escalation) {
             return { status: 404, error: 'Escalation not found' };
         }
-        const isSuperAdminUser = await userService.isSuperAdmin(auth.userId);
-        if (!isSuperAdminUser) {
+        const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
+        if (!hasGlobal) {
             const userHasRole = await userService.hasRole(auth.userId, escalation.role);
             if (!userHasRole) {
                 return { status: 403, error: 'Not authorized to view this escalation' };

package/build/api/settings.js

@@ -7,6 +7,7 @@ const nats_1 = require("../lib/events/nats");
 const socketio_1 = require("../lib/events/socketio");
 const nats_ws_proxy_1 = require("../lib/events/nats-ws-proxy");
 const config_1 = require("../modules/config");
+const sso_1 = require("../modules/sso");
 const defaults_1 = require("../modules/defaults");
 const llm_1 = require("../services/llm");
 /**
@@ -60,6 +61,10 @@ async function getSettings(req) {
                     transport,
                     natsWsUrl: natsAdapter ? resolveNatsWsUrl(natsAdapter, req) : null,
                 },
+                auth: {
+                    sso: (0, sso_1.isSSOEnabled)(),
+                    ssoLogoutUrl: (0, sso_1.getSSOConfig)()?.logoutUrl ?? null,
+                },
                 ai: {
                     enabled: (0, llm_1.hasLLMApiKey)(),
                 },

package/build/api/topics.d.ts

@@ -20,8 +20,17 @@ export declare function updateTopic(input: {
 export declare function deleteTopic(input: {
     topic: string;
 }): Promise<LTApiResult>;
+/**
+ * Validate that a subject is a valid variant of a topic pattern.
+ * Each `*` in the pattern matches exactly one literal segment in the subject.
+ * Each `>` in the pattern matches one or more trailing segments.
+ * Literal segments must match exactly.
+ */
+export declare function isValidVariant(pattern: string, subject: string): boolean;
 export declare function publishTopic(input: {
     topic: string;
+    subject?: string;
+    eventId?: string;
     data: Record<string, any>;
     source?: string;
 }): Promise<LTApiResult>;

package/build/api/topics.js

@@ -38,6 +38,7 @@ exports.getTopic = getTopic;
 exports.createTopic = createTopic;
 exports.updateTopic = updateTopic;
 exports.deleteTopic = deleteTopic;
+exports.isValidVariant = isValidVariant;
 exports.publishTopic = publishTopic;
 const topicService = __importStar(require("../services/topics"));
 const events_1 = require("../lib/events");
@@ -104,10 +105,38 @@ async function deleteTopic(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Validate that a subject is a valid variant of a topic pattern.
+ * Each `*` in the pattern matches exactly one literal segment in the subject.
+ * Each `>` in the pattern matches one or more trailing segments.
+ * Literal segments must match exactly.
+ */
+function isValidVariant(pattern, subject) {
+    const patternParts = pattern.split('.');
+    const subjectParts = subject.split('.');
+    let pi = 0;
+    let si = 0;
+    while (pi < patternParts.length && si < subjectParts.length) {
+        const pp = patternParts[pi];
+        if (pp === '>')
+            return true; // match-rest: everything from here is valid
+        if (pp !== '*' && pp !== subjectParts[si])
+            return false;
+        pi++;
+        si++;
+    }
+    return pi === patternParts.length && si === subjectParts.length;
+}
 async function publishTopic(input) {
     try {
+        const publishSubject = input.subject || input.topic;
+        // Validate subject is a valid variant of the topic pattern
+        if (input.subject && !isValidVariant(input.topic, input.subject)) {
+            return { status: 400, error: `Subject "${input.subject}" does not match topic pattern "${input.topic}"` };
+        }
         const event = {
-            type: input.topic,
+            id: input.eventId,
+            type: publishSubject,
             source: input.source || 'dashboard',
             workflowId: '',
             workflowName: '',
@@ -116,7 +145,7 @@ async function publishTopic(input) {
             timestamp: new Date().toISOString(),
         };
         await events_1.eventRegistry.publish(event);
-        return { status: 200, data: { published: true, topic: input.topic, timestamp: event.timestamp } };
+        return { status: 200, data: { published: true, topic: publishSubject, timestamp: event.timestamp } };
     }
     catch (err) {
         return { status: 500, error: err.message };

package/build/lib/events/index.d.ts

@@ -12,6 +12,7 @@ declare class LTEventRegistry {
     connect(): Promise<void>;
     /**
      * Publish an event to all registered adapters.
+     * Auto-assigns an idempotent event ID if not provided.
      * Best-effort: individual adapter failures are logged, not thrown.
      */
     publish(event: LTEvent): Promise<void>;

package/build/lib/events/index.js

@@ -24,11 +24,15 @@ class LTEventRegistry {
     }
     /**
      * Publish an event to all registered adapters.
+     * Auto-assigns an idempotent event ID if not provided.
      * Best-effort: individual adapter failures are logged, not thrown.
      */
     async publish(event) {
         if (!this.adapters.length)
             return;
+        if (!event.id) {
+            event.id = `evt-${Date.now()}-${Math.random().toString(16).slice(2, 6)}`;
+        }
         await Promise.allSettled(this.adapters.map((a) => a.publish(event).catch((err) => {
             logger_1.loggerRegistry.error(`[lt-events] adapter publish failed: ${err?.message}`);
         })));

package/build/lib/events/publish.d.ts

@@ -15,7 +15,8 @@ export declare function publishMilestoneEvent(params: {
     data?: Record<string, any>;
 }): Promise<void>;
 /**
- * Publish a task lifecycle event (created, started, completed, escalated, failed).
+ * Publish a task lifecycle event.
+ * Subject: system.task.{taskId}.{action}
  */
 export declare function publishTaskEvent(params: {
     type: 'task.created' | 'task.started' | 'task.completed' | 'task.escalated' | 'task.failed';
@@ -30,7 +31,8 @@ export declare function publishTaskEvent(params: {
     data?: Record<string, any>;
 }): Promise<void>;
 /**
- * Publish an escalation lifecycle event (created, resolved).
+ * Publish an escalation lifecycle event.
+ * Subject: system.escalation.{escalationId}.{action}
  */
 export declare function publishEscalationEvent(params: {
     type: 'escalation.created' | 'escalation.resolved' | 'escalation.claimed' | 'escalation.released';
@@ -46,7 +48,7 @@ export declare function publishEscalationEvent(params: {
 }): Promise<void>;
 /**
  * Publish an activity lifecycle event for YAML workflow steps.
- * Lightweight — no payload data, just progress signals.
+ * Subject: system.activity.{workflowId}.{activityName}.{action}
  */
 export declare function publishActivityEvent(params: {
     type: 'activity.started' | 'activity.completed' | 'activity.failed';
@@ -57,9 +59,8 @@ export declare function publishActivityEvent(params: {
     data?: Record<string, any>;
 }): Promise<void>;
 /**
- * Publish a knowledge lifecycle event (stored, deleted).
- * Lightweight — no workflow context required since knowledge writes
- * happen both inside and outside workflows.
+ * Publish a knowledge lifecycle event.
+ * Subject: system.knowledge.{domain}.{action}
  */
 export declare function publishKnowledgeEvent(params: {
     type: 'knowledge.stored' | 'knowledge.deleted';
@@ -67,8 +68,8 @@ export declare function publishKnowledgeEvent(params: {
     key: string;
 }): Promise<void>;
 /**
- * Publish a file storage event (stored, deleted).
- * Includes rich metadata: path, name, extension, mime type, size.
+ * Publish a file storage event.
+ * Subject: system.file.{action}
  */
 export declare function publishFileEvent(params: {
     type: 'file.stored' | 'file.deleted';
@@ -78,6 +79,7 @@ export declare function publishFileEvent(params: {
 }): Promise<void>;
 /**
  * Publish an agent lifecycle event.
+ * Subject: system.agent.{agentName}.{action}
  */
 export declare function publishAgentEvent(params: {
     type: 'agent.started' | 'agent.completed' | 'agent.failed' | 'agent.status_changed';
@@ -87,7 +89,8 @@ export declare function publishAgentEvent(params: {
     data?: Record<string, any>;
 }): Promise<void>;
 /**
- * Publish a workflow lifecycle event (started, completed, failed).
+ * Publish a workflow lifecycle event.
+ * Subject: system.workflow.{workflowId}.{action}
  */
 export declare function publishWorkflowEvent(params: {
     type: 'workflow.started' | 'workflow.completed' | 'workflow.failed';

package/build/lib/events/publish.js

@@ -28,7 +28,7 @@ function publishMilestoneEvent(params) {
     if (!params.milestones?.length)
         return Promise.resolve();
     return fireAndForget({
-        type: 'milestone',
+        type: `system.milestone.${params.workflowId}`,
         source: params.source,
         workflowId: params.workflowId,
         workflowName: params.workflowName,
@@ -41,11 +41,13 @@ function publishMilestoneEvent(params) {
     });
 }
 /**
- * Publish a task lifecycle event (created, started, completed, escalated, failed).
+ * Publish a task lifecycle event.
+ * Subject: system.task.{taskId}.{action}
  */
 function publishTaskEvent(params) {
+    const action = params.type.split('.')[1]; // created, started, completed, escalated, failed
     return fireAndForget({
-        type: params.type,
+        type: `system.task.${params.taskId}.${action}`,
         source: params.source,
         workflowId: params.workflowId,
         workflowName: params.workflowName,
@@ -59,11 +61,13 @@ function publishTaskEvent(params) {
     });
 }
 /**
- * Publish an escalation lifecycle event (created, resolved).
+ * Publish an escalation lifecycle event.
+ * Subject: system.escalation.{escalationId}.{action}
  */
 function publishEscalationEvent(params) {
+    const action = params.type.split('.')[1];
     return fireAndForget({
-        type: params.type,
+        type: `system.escalation.${params.escalationId}.${action}`,
         source: params.source,
         workflowId: params.workflowId,
         workflowName: params.workflowName,
@@ -78,11 +82,12 @@ function publishEscalationEvent(params) {
 }
 /**
  * Publish an activity lifecycle event for YAML workflow steps.
- * Lightweight — no payload data, just progress signals.
+ * Subject: system.activity.{workflowId}.{activityName}.{action}
  */
 function publishActivityEvent(params) {
+    const action = params.type.split('.')[1];
     return fireAndForget({
-        type: params.type,
+        type: `system.activity.${params.workflowId}.${params.activityName}.${action}`,
         source: 'yaml-worker',
         workflowId: params.workflowId,
         workflowName: params.workflowName,
@@ -93,13 +98,13 @@ function publishActivityEvent(params) {
     });
 }
 /**
- * Publish a knowledge lifecycle event (stored, deleted).
- * Lightweight — no workflow context required since knowledge writes
- * happen both inside and outside workflows.
+ * Publish a knowledge lifecycle event.
+ * Subject: system.knowledge.{domain}.{action}
  */
 function publishKnowledgeEvent(params) {
+    const action = params.type.split('.')[1];
     return fireAndForget({
-        type: params.type,
+        type: `system.knowledge.${params.domain}.${action}`,
         source: 'knowledge',
         workflowId: '',
         workflowName: '',
@@ -109,17 +114,18 @@ function publishKnowledgeEvent(params) {
     });
 }
 /**
- * Publish a file storage event (stored, deleted).
- * Includes rich metadata: path, name, extension, mime type, size.
+ * Publish a file storage event.
+ * Subject: system.file.{action}
  */
 function publishFileEvent(params) {
+    const action = params.type.split('.')[1];
     const parsed = params.path.split('/');
     const filename = parsed[parsed.length - 1] || '';
     const dotIdx = filename.lastIndexOf('.');
     const name = dotIdx > 0 ? filename.slice(0, dotIdx) : filename;
     const extension = dotIdx > 0 ? filename.slice(dotIdx + 1) : '';
     return fireAndForget({
-        type: params.type,
+        type: `system.file.${action}`,
         source: 'file-storage',
         workflowId: '',
         workflowName: '',
@@ -137,10 +143,12 @@ function publishFileEvent(params) {
 }
 /**
  * Publish an agent lifecycle event.
+ * Subject: system.agent.{agentName}.{action}
  */
 function publishAgentEvent(params) {
+    const action = params.type.replace('agent.', '');
     return fireAndForget({
-        type: params.type,
+        type: `system.agent.${params.agentName}.${action}`,
         source: 'agent',
         workflowId: params.agentId,
         workflowName: params.agentName,
@@ -151,11 +159,13 @@ function publishAgentEvent(params) {
     });
 }
 /**
- * Publish a workflow lifecycle event (started, completed, failed).
+ * Publish a workflow lifecycle event.
+ * Subject: system.workflow.{workflowId}.{action}
  */
 function publishWorkflowEvent(params) {
+    const action = params.type.split('.')[1];
     return fireAndForget({
-        type: params.type,
+        type: `system.workflow.${params.workflowId}.${action}`,
         source: params.source,
         workflowId: params.workflowId,
         workflowName: params.workflowName,

package/build/modules/auth.d.ts

@@ -52,6 +52,13 @@ export declare function setAuthAdapter(adapter: LTAuthAdapter): void;
  * JWT `role` claim for stateless admin checks. Returns 403 otherwise.
  */
 export declare const requireAdmin: RequestHandler;
+/**
+ * Middleware that requires builder access. Must be placed AFTER requireAuth.
+ *
+ * Builders are superadmin, admin, or users with the 'engineer' role.
+ * This is the backend equivalent of the dashboard's `isBuilder` check.
+ */
+export declare const requireBuilder: RequestHandler;
 /**
  * Generate a JWT token. Utility for tests and token provisioning.
  */