@vorionsys/security 1.0.0

package/dist/intent/state-machine.js

@@ -0,0 +1,242 @@
+/**
+ * Intent Status State Machine
+ *
+ * Defines and enforces valid status transitions for intents.
+ * Prevents invalid state changes and provides detailed error messages.
+ */
+/**
+ * Valid status transitions map
+ * Key is the current status, value is a map of valid next statuses with metadata
+ */
+const VALID_TRANSITIONS = {
+    pending: new Map([
+        ['evaluating', { description: 'Begin evaluation process', event: 'intent.evaluation.started' }],
+        ['cancelled', { description: 'Cancel before processing', requiresReason: true, event: 'intent.cancelled' }],
+    ]),
+    evaluating: new Map([
+        ['approved', { description: 'Evaluation passed, intent approved', event: 'intent.approved' }],
+        ['denied', { description: 'Evaluation failed, intent denied', event: 'intent.denied' }],
+        ['escalated', { description: 'Requires human review', event: 'intent.escalated' }],
+        ['cancelled', { description: 'Cancel during evaluation', requiresReason: true, event: 'intent.cancelled' }],
+        ['failed', { description: 'Evaluation error', event: 'intent.failed' }],
+    ]),
+    escalated: new Map([
+        ['approved', { description: 'Human approved after escalation', requiresPermission: true, event: 'intent.approved' }],
+        ['denied', { description: 'Human denied after escalation', requiresPermission: true, event: 'intent.denied' }],
+        ['cancelled', { description: 'Cancel during escalation', requiresReason: true, event: 'intent.cancelled' }],
+    ]),
+    approved: new Map([
+        ['executing', { description: 'Begin execution', event: 'intent.execution.started' }],
+        ['cancelled', { description: 'Cancel before execution', requiresReason: true, event: 'intent.cancelled' }],
+    ]),
+    executing: new Map([
+        ['completed', { description: 'Execution succeeded', event: 'intent.completed' }],
+        ['failed', { description: 'Execution failed', event: 'intent.failed' }],
+    ]),
+    denied: new Map([
+        ['pending', { description: 'Replay denied intent', requiresPermission: true, event: 'intent.replayed' }],
+    ]),
+    failed: new Map([
+        ['pending', { description: 'Retry failed intent', requiresPermission: true, event: 'intent.replayed' }],
+    ]),
+    completed: new Map([
+    // Terminal state - no transitions allowed
+    ]),
+    cancelled: new Map([
+    // Terminal state - no transitions allowed
+    ]),
+};
+/**
+ * Terminal states that cannot transition to any other state
+ */
+export const TERMINAL_STATES = new Set(['completed', 'cancelled']);
+/**
+ * Active states where the intent is being processed
+ */
+export const ACTIVE_STATES = new Set([
+    'pending',
+    'evaluating',
+    'escalated',
+    'approved',
+    'executing',
+]);
+/**
+ * States that allow cancellation
+ */
+export const CANCELLABLE_STATES = new Set([
+    'pending',
+    'evaluating',
+    'escalated',
+    'approved',
+]);
+/**
+ * States that allow replay (restart from pending)
+ */
+export const REPLAYABLE_STATES = new Set([
+    'denied',
+    'failed',
+]);
+/**
+ * Check if a status transition is valid
+ */
+export function isValidTransition(fromStatus, toStatus) {
+    const validTargets = VALID_TRANSITIONS[fromStatus];
+    return validTargets?.has(toStatus) ?? false;
+}
+/**
+ * Get metadata for a transition
+ */
+export function getTransitionMeta(fromStatus, toStatus) {
+    return VALID_TRANSITIONS[fromStatus]?.get(toStatus);
+}
+/**
+ * Validate a status transition with detailed result
+ */
+export function validateTransition(fromStatus, toStatus, options) {
+    // Check if current status is terminal
+    if (TERMINAL_STATES.has(fromStatus)) {
+        return {
+            valid: false,
+            error: `Cannot transition from terminal state '${fromStatus}'`,
+            errorCode: 'TERMINAL_STATE',
+        };
+    }
+    // Check if transition is defined
+    const meta = getTransitionMeta(fromStatus, toStatus);
+    if (!meta) {
+        const validTargets = getValidTransitions(fromStatus);
+        return {
+            valid: false,
+            error: `Invalid transition from '${fromStatus}' to '${toStatus}'. Valid transitions: ${validTargets.join(', ') || 'none'}`,
+            errorCode: 'INVALID_TRANSITION',
+        };
+    }
+    // Check if reason is required
+    if (meta.requiresReason && !options?.hasReason) {
+        return {
+            valid: false,
+            meta,
+            error: `Transition to '${toStatus}' requires a reason`,
+            errorCode: 'REQUIRES_REASON',
+        };
+    }
+    // Check if permission is required
+    if (meta.requiresPermission && !options?.hasPermission) {
+        return {
+            valid: false,
+            meta,
+            error: `Transition to '${toStatus}' requires elevated permissions`,
+            errorCode: 'REQUIRES_PERMISSION',
+        };
+    }
+    return {
+        valid: true,
+        meta,
+    };
+}
+/**
+ * Get all valid transitions from a status
+ */
+export function getValidTransitions(fromStatus) {
+    const validTargets = VALID_TRANSITIONS[fromStatus];
+    return validTargets ? Array.from(validTargets.keys()) : [];
+}
+/**
+ * Get the event type for a transition
+ */
+export function getTransitionEvent(fromStatus, toStatus) {
+    return getTransitionMeta(fromStatus, toStatus)?.event;
+}
+/**
+ * Check if a status is terminal (no further transitions possible)
+ */
+export function isTerminalState(status) {
+    return TERMINAL_STATES.has(status);
+}
+/**
+ * Check if a status is active (intent is being processed)
+ */
+export function isActiveState(status) {
+    return ACTIVE_STATES.has(status);
+}
+/**
+ * Check if an intent can be cancelled from the given status
+ */
+export function canCancel(status) {
+    return CANCELLABLE_STATES.has(status);
+}
+/**
+ * Check if an intent can be replayed from the given status
+ */
+export function canReplay(status) {
+    return REPLAYABLE_STATES.has(status);
+}
+/**
+ * Get the next logical status for workflow progression
+ * Returns the primary "happy path" next status
+ */
+export function getNextWorkflowStatus(status) {
+    switch (status) {
+        case 'pending':
+            return 'evaluating';
+        case 'evaluating':
+            return 'approved'; // Or denied/escalated based on evaluation
+        case 'approved':
+            return 'executing';
+        case 'executing':
+            return 'completed';
+        case 'escalated':
+            return null; // Requires human decision
+        case 'denied':
+        case 'failed':
+        case 'completed':
+        case 'cancelled':
+            return null; // Terminal or special handling
+        default:
+            return null;
+    }
+}
+/**
+ * State machine error class
+ */
+export class StateMachineError extends Error {
+    fromStatus;
+    toStatus;
+    errorCode;
+    constructor(result, fromStatus, toStatus) {
+        super(result.error ?? `Invalid transition from ${fromStatus} to ${toStatus}`);
+        this.name = 'StateMachineError';
+        this.fromStatus = fromStatus;
+        this.toStatus = toStatus;
+        this.errorCode = result.errorCode;
+    }
+}
+/**
+ * Assert that a transition is valid, throwing if not
+ */
+export function assertValidTransition(fromStatus, toStatus, options) {
+    const result = validateTransition(fromStatus, toStatus, options);
+    if (!result.valid) {
+        throw new StateMachineError(result, fromStatus, toStatus);
+    }
+}
+/**
+ * Get a visual representation of the state machine
+ * Returns a mermaid diagram string
+ */
+export function getStateDiagram() {
+    const lines = ['stateDiagram-v2'];
+    for (const [fromStatus, transitions] of Object.entries(VALID_TRANSITIONS)) {
+        for (const [toStatus, meta] of transitions) {
+            const label = meta.event ? meta.event.replace('intent.', '') : '';
+            lines.push(`    ${fromStatus} --> ${toStatus}: ${label}`);
+        }
+    }
+    // Mark terminal states
+    lines.push('');
+    lines.push('    [*] --> pending');
+    lines.push('    completed --> [*]');
+    lines.push('    cancelled --> [*]');
+    return lines.join('\n');
+}
+//# sourceMappingURL=state-machine.js.map

package/dist/intent/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sourceRoot":"","sources":["../../src/intent/state-machine.ts"],"names":[],"mappings":"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"}

package/dist/intent/tracing.d.ts

@@ -0,0 +1,152 @@
+/**
+ * INTENT Distributed Tracing - OpenTelemetry Integration
+ *
+ * Provides distributed tracing for intent processing workflows.
+ * Enables end-to-end visibility across queue workers and API calls.
+ */
+import { type Span, type Tracer, type Context } from '@opentelemetry/api';
+import type { Intent, IntentStatus } from '../common/types.js';
+/**
+ * Get the intent tracer
+ */
+export declare function getTracer(): Tracer;
+/**
+ * Span attribute names for intent operations
+ */
+export declare const IntentAttributes: {
+    readonly INTENT_ID: "intent.id";
+    readonly INTENT_TYPE: "intent.type";
+    readonly INTENT_STATUS: "intent.status";
+    readonly INTENT_PRIORITY: "intent.priority";
+    readonly TENANT_ID: "tenant.id";
+    readonly ENTITY_ID: "entity.id";
+    readonly TRUST_LEVEL: "trust.level";
+    readonly ESCALATION_ID: "escalation.id";
+    readonly ESCALATION_REASON: "escalation.reason";
+    readonly ESCALATION_STATUS: "escalation.status";
+    readonly QUEUE_NAME: "queue.name";
+    readonly JOB_ID: "job.id";
+};
+/**
+ * Create a span for intent submission
+ */
+export declare function traceIntentSubmission<T>(tenantId: string, entityId: string, intentType: string | null | undefined, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Create a span for queue job processing
+ */
+export declare function traceQueueJob<T>(queueName: string, jobId: string, intentId: string, fn: (span: Span) => Promise<T>, parentContext?: Context): Promise<T>;
+/**
+ * Create a span for trust evaluation
+ */
+export declare function traceTrustEvaluation<T>(intentId: string, tenantId: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Create a span for rule evaluation
+ */
+export declare function traceRuleEvaluation<T>(intentId: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Create a span for escalation creation
+ */
+export declare function traceEscalationCreate<T>(intentId: string, tenantId: string, reason: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Create a span for escalation resolution
+ */
+export declare function traceEscalationResolve<T>(escalationId: string, resolution: 'approved' | 'rejected', fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Create a span for decision making
+ */
+export declare function traceDecision<T>(intentId: string, tenantId: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Add intent attributes to current span
+ */
+export declare function addIntentAttributes(span: Span, intent: Intent): void;
+/**
+ * Add trust attributes to current span
+ */
+export declare function addTrustAttributes(span: Span, trustLevel: number, trustScore?: number): void;
+/**
+ * Record a status transition event
+ */
+export declare function recordStatusTransitionEvent(span: Span, fromStatus: IntentStatus | 'new', toStatus: IntentStatus): void;
+/**
+ * Record an evaluation result event
+ */
+export declare function recordEvaluationEvent(span: Span, evaluationType: 'trust' | 'rules' | 'policy', result: 'passed' | 'failed' | 'escalated', details?: Record<string, string | number | boolean>): void;
+/**
+ * Extract trace context for propagation to queue jobs
+ */
+export declare function extractTraceContext(): Record<string, string>;
+/**
+ * Inject trace context from carrier into context
+ */
+export declare function injectTraceContext(_carrier: Record<string, string>): Context;
+/**
+ * Span attribute names for additional tracing operations
+ */
+export declare const AdditionalAttributes: {
+    readonly DEDUPE_HASH: "dedupe.hash";
+    readonly DEDUPE_FOUND: "dedupe.found";
+    readonly LOCK_KEY: "lock.key";
+    readonly LOCK_ACQUIRED: "lock.acquired";
+    readonly LOCK_TIMEOUT_MS: "lock.timeout_ms";
+    readonly CRYPTO_OPERATION: "crypto.operation";
+    readonly CRYPTO_SIZE_BYTES: "crypto.size_bytes";
+    readonly CRYPTO_SUCCESS: "crypto.success";
+    readonly POLICY_COUNT: "policy.count";
+    readonly POLICY_MATCHED_COUNT: "policy.matched_count";
+    readonly POLICY_NAMESPACE: "policy.namespace";
+    readonly POLICY_FINAL_ACTION: "policy.final_action";
+    readonly WEBHOOK_ID: "webhook.id";
+    readonly WEBHOOK_URL_REDACTED: "webhook.url_redacted";
+    readonly WEBHOOK_STATUS_CODE: "webhook.status_code";
+    readonly WEBHOOK_SUCCESS: "webhook.success";
+    readonly WEBHOOK_EVENT_TYPE: "webhook.event_type";
+};
+/**
+ * Create a span for deduplication check
+ */
+export declare function traceDedupeCheck<T>(tenantId: string, entityId: string, hash: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Create a span for lock acquisition
+ */
+export declare function traceLockAcquire<T>(tenantId: string, lockKey: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Create a span for encryption operation (async)
+ */
+export declare function traceEncrypt<T>(sizeBytes: number, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Create a span for encryption operation (sync)
+ */
+export declare function traceEncryptSync<T>(sizeBytes: number, fn: (span: Span) => T): T;
+/**
+ * Create a span for decryption operation (async)
+ */
+export declare function traceDecrypt<T>(sizeBytes: number, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Create a span for decryption operation (sync)
+ */
+export declare function traceDecryptSync<T>(sizeBytes: number, fn: (span: Span) => T): T;
+/**
+ * Create a span for policy evaluation
+ */
+export declare function tracePolicyEvaluate<T>(intentId: string, tenantId: string, namespace: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Create a span for webhook delivery
+ */
+export declare function traceWebhookDeliver<T>(webhookId: string, url: string, eventType: string, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Record policy evaluation result on span
+ */
+export declare function recordPolicyEvaluationResult(span: Span, policyCount: number, matchedCount: number, finalAction: string): void;
+/**
+ * Record webhook delivery result on span
+ */
+export declare function recordWebhookResult(span: Span, success: boolean, statusCode?: number): void;
+/**
+ * Record lock acquisition result on span
+ */
+export declare function recordLockResult(span: Span, acquired: boolean, timeoutMs?: number): void;
+/**
+ * Record deduplication check result on span
+ */
+export declare function recordDedupeResult(span: Span, found: boolean): void;
+//# sourceMappingURL=tracing.d.ts.map

package/dist/intent/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/intent/tracing.ts"],"names":[],"mappings":"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"}