@emkodev/emkore 1.0.3

package/src/common/interceptor/audit-log.interceptor.ts

@@ -0,0 +1,181 @@
+import type { Interceptor } from "../abstract.interceptor.ts";
+import type { InterceptorContext } from "../type/interceptor-context.type.ts";
+
+/**
+ * Audit log entry structure for compliance and tracking
+ */
+export interface AuditLogEntry {
+  timestamp: string;
+  actorId: string;
+  businessId: string;
+  action: string;
+  resource: string;
+  status: "started" | "completed" | "failed";
+  duration?: number;
+  error?: string;
+  metadata?: Record<string, unknown>;
+  requiredPermissions?: string[];
+}
+
+/**
+ * Audit log interceptor for compliance and security tracking.
+ * Creates detailed audit trails of all usecase executions.
+ */
+export class AuditLogInterceptor<Input, Output>
+  implements Interceptor<Input, Output> {
+  readonly name = "AuditLogInterceptor";
+
+  private readonly startTimes = new Map<string, number>();
+
+  constructor(
+    private readonly logHandler: (
+      entry: AuditLogEntry,
+    ) => void | Promise<void> = (entry) =>
+      console.log("[Audit]", JSON.stringify(entry)),
+  ) {}
+
+  private getExecutionKey(context: InterceptorContext): string {
+    return `${context.actor.id}_${context.usecaseName.join("/")}`;
+  }
+
+  async beforeExecute(
+    input: Input,
+    context: InterceptorContext,
+  ): Promise<Input> {
+    const key = this.getExecutionKey(context);
+    this.startTimes.set(key, Date.now());
+
+    const entry: AuditLogEntry = {
+      timestamp: new Date().toISOString(),
+      actorId: context.actor.id,
+      businessId: context.actor.businessId,
+      action: context.usecaseName[0],
+      resource: context.usecaseName[1],
+      status: "started",
+      ...(context.requiredPermissions.length > 0 && {
+        requiredPermissions: context.requiredPermissions.map((p) =>
+          `${p.action}:${p.resource}`
+        ),
+      }),
+      ...(Object.keys(context.metadata).length > 0 && {
+        metadata: context.metadata,
+      }),
+    };
+
+    await this.logHandler(entry);
+
+    return input;
+  }
+
+  async afterExecute(
+    output: Output,
+    context: InterceptorContext,
+  ): Promise<Output> {
+    const key = this.getExecutionKey(context);
+    const startTime = this.startTimes.get(key);
+    this.startTimes.delete(key);
+
+    const entry: AuditLogEntry = {
+      timestamp: new Date().toISOString(),
+      actorId: context.actor.id,
+      businessId: context.actor.businessId,
+      action: context.usecaseName[0],
+      resource: context.usecaseName[1],
+      status: "completed",
+      ...(startTime !== undefined && {
+        duration: Date.now() - startTime,
+      }),
+    };
+
+    await this.logHandler(entry);
+
+    return output;
+  }
+
+  async onError(
+    error: Error,
+    context: InterceptorContext,
+  ): Promise<void> {
+    const key = this.getExecutionKey(context);
+    const startTime = this.startTimes.get(key);
+    this.startTimes.delete(key);
+
+    const entry: AuditLogEntry = {
+      timestamp: new Date().toISOString(),
+      actorId: context.actor.id,
+      businessId: context.actor.businessId,
+      action: context.usecaseName[0],
+      resource: context.usecaseName[1],
+      status: "failed",
+      error: `${error.name}: ${error.message}`,
+      ...(startTime !== undefined && {
+        duration: Date.now() - startTime,
+      }),
+    };
+
+    await this.logHandler(entry);
+  }
+}
+
+/**
+ * File-based audit logger that writes to a file
+ * This is an example implementation - in production you'd likely use a database or log aggregation service
+ */
+export class FileAuditLogger {
+  private entries: AuditLogEntry[] = [];
+
+  constructor(
+    private readonly maxEntries: number = 10000,
+    private readonly rotateCallback?: (
+      entries: AuditLogEntry[],
+    ) => void | Promise<void>,
+  ) {}
+
+  async log(entry: AuditLogEntry): Promise<void> {
+    this.entries.push(entry);
+
+    // Rotate log when it gets too large
+    if (this.entries.length >= this.maxEntries) {
+      const entriesToRotate = this.entries.splice(0, this.maxEntries / 2);
+      if (this.rotateCallback) {
+        await this.rotateCallback(entriesToRotate);
+      }
+    }
+  }
+
+  getEntries(
+    filter?: {
+      actorId?: string;
+      businessId?: string;
+      action?: string;
+      resource?: string;
+      status?: AuditLogEntry["status"];
+      from?: Date;
+      to?: Date;
+    },
+  ): AuditLogEntry[] {
+    if (!filter) {
+      return [...this.entries];
+    }
+
+    return this.entries.filter((entry) => {
+      if (filter.actorId && entry.actorId !== filter.actorId) return false;
+      if (filter.businessId && entry.businessId !== filter.businessId) {
+        return false;
+      }
+      if (filter.action && entry.action !== filter.action) return false;
+      if (filter.resource && entry.resource !== filter.resource) return false;
+      if (filter.status && entry.status !== filter.status) return false;
+
+      const entryTime = new Date(entry.timestamp);
+      if (filter.from && entryTime < filter.from) return false;
+      if (filter.to && entryTime > filter.to) return false;
+
+      return true;
+    });
+  }
+
+  clear(): void {
+    this.entries = [];
+  }
+}

package/src/common/interceptor/authorization.interceptor.ts

@@ -0,0 +1,252 @@
+import type { Interceptor } from "../abstract.interceptor.ts";
+import type { InterceptorContext } from "../type/interceptor-context.type.ts";
+import {
+  type Permission,
+  type ResourceConstraints,
+  ResourceScope,
+} from "../type/permission.type.ts";
+import { AuthorizationException } from "../exception/authorization-exception.ts";
+
+export class AuthorizationInterceptor<Input, Output>
+  implements Interceptor<Input, Output> {
+  readonly name = "AuthorizationInterceptor";
+
+  // Pre-computed scope satisfaction matrix for O(1) lookups
+  // PROJECT and TEAM are parallel scopes under BUSINESS
+  private static readonly SCOPE_SATISFIES = new Map<
+    ResourceScope,
+    Set<ResourceScope>
+  >([
+    [
+      ResourceScope.ALL,
+      new Set([
+        ResourceScope.ALL,
+        ResourceScope.BUSINESS,
+        ResourceScope.PROJECT,
+        ResourceScope.TEAM,
+        ResourceScope.OWNED,
+      ]),
+    ],
+    [
+      ResourceScope.BUSINESS,
+      new Set([
+        ResourceScope.BUSINESS,
+        ResourceScope.PROJECT,
+        ResourceScope.TEAM,
+        ResourceScope.OWNED,
+      ]),
+    ],
+    [
+      ResourceScope.PROJECT,
+      new Set([ResourceScope.PROJECT, ResourceScope.OWNED]),
+    ],
+    [ResourceScope.TEAM, new Set([ResourceScope.TEAM, ResourceScope.OWNED])],
+    [ResourceScope.OWNED, new Set([ResourceScope.OWNED])],
+  ]);
+
+  beforeExecute(
+    input: Input,
+    context: InterceptorContext,
+  ): Input {
+    this._checkAuthorization(context);
+    return input;
+  }
+
+  private _checkAuthorization(context: InterceptorContext): void {
+    const requiredPerms = context.requiredPermissions;
+
+    if (requiredPerms.length === 0) {
+      return;
+    }
+
+    // Index actor permissions for O(1) lookups
+    const actorPermIndex = this._indexPermissions(context.actor.permissions);
+
+    if (!this._hasPermissionsIndexed(actorPermIndex, requiredPerms)) {
+      const missingPermissions = this._findMissingPermissions(
+        context.actor.permissions,
+        requiredPerms,
+      );
+
+      throw new AuthorizationException(
+        `Insufficient permissions for actor ${context.actor.id}`,
+        {
+          actorId: context.actor.id,
+          resource: context.usecaseName[1],
+          action: context.usecaseName[0],
+          missingPermissions,
+        },
+      );
+    }
+  }
+
+  private _indexPermissions(
+    permissions: Permission[],
+  ): Map<string, Permission[]> {
+    const index = new Map<string, Permission[]>();
+
+    for (const perm of permissions) {
+      const key = `${perm.resource}:${perm.action}`;
+      if (!index.has(key)) {
+        index.set(key, []);
+      }
+      index.get(key)!.push(perm);
+    }
+
+    return index;
+  }
+
+  private _hasPermissionsIndexed(
+    actorPermIndex: Map<string, Permission[]>,
+    requiredPermissions: Permission[],
+  ): boolean {
+    if (requiredPermissions.length === 0) {
+      return true;
+    }
+
+    for (const required of requiredPermissions) {
+      if (!this._hasPermissionIndexed(actorPermIndex, required)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  private _hasPermissionIndexed(
+    actorPermIndex: Map<string, Permission[]>,
+    required: Permission,
+  ): boolean {
+    const key = `${required.resource}:${required.action}`;
+    const candidates = actorPermIndex.get(key) || [];
+
+    // Only check constraints for exact resource:action matches (O(1) lookup)
+    for (const permission of candidates) {
+      if (
+        this._constraintsSatisfied(permission.constraints, required.constraints)
+      ) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private _hasPermission(
+    actorPermissions: Permission[],
+    required: Permission,
+  ): boolean {
+    for (const permission of actorPermissions) {
+      if (this._permissionMatches(permission, required)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private _permissionMatches(
+    granted: Permission,
+    required: Permission,
+  ): boolean {
+    if (
+      granted.resource === required.resource &&
+      granted.action === required.action
+    ) {
+      return this._constraintsSatisfied(
+        granted.constraints,
+        required.constraints,
+      );
+    }
+    return false;
+  }
+
+  private _constraintsSatisfied(
+    granted?: ResourceConstraints,
+    required?: ResourceConstraints,
+  ): boolean {
+    if (!required) {
+      return true;
+    }
+
+    if (!granted) {
+      return false;
+    }
+
+    // Check scope constraints
+    if (required.scope) {
+      if (!granted.scope) return false;
+      if (!this._scopeSatisfied(granted.scope, required.scope)) return false;
+    }
+
+    // Check status constraints
+    if (required.statuses) {
+      if (!granted.statuses) return false;
+      const requiredSet = new Set(required.statuses);
+      const grantedSet = new Set(granted.statuses);
+      for (const status of requiredSet) {
+        if (!grantedSet.has(status)) return false;
+      }
+    }
+
+    // Check time constraints
+    if (required.timeRestriction) {
+      if (!granted.timeRestriction) return false;
+      const now = new Date();
+      if (
+        now < granted.timeRestriction.from ||
+        now > granted.timeRestriction.to
+      ) {
+        return false;
+      }
+    }
+
+    // Check businessId constraints
+    if (required.businessId) {
+      if (!granted.businessId) return false;
+      if (granted.businessId !== required.businessId) return false;
+    }
+
+    // Check projectId constraints
+    if (required.projectId) {
+      if (!granted.projectId) return false;
+      if (granted.projectId !== required.projectId) return false;
+    }
+
+    // Check team constraints
+    if (required.teamId) {
+      if (!granted.teamId) return false;
+      if (granted.teamId !== required.teamId) return false;
+    }
+
+    // Check resourceId constraints
+    if (required.resourceId) {
+      if (!granted.resourceId) return false;
+      if (granted.resourceId !== required.resourceId) return false;
+    }
+
+    return true;
+  }
+
+  private _scopeSatisfied(
+    granted: ResourceScope,
+    required: ResourceScope,
+  ): boolean {
+    return AuthorizationInterceptor.SCOPE_SATISFIES.get(granted)?.has(
+      required,
+    ) ?? false;
+  }
+
+  private _findMissingPermissions(
+    actorPermissions: Permission[],
+    requiredPermissions: Permission[],
+  ): string[] {
+    const missing: string[] = [];
+
+    for (const required of requiredPermissions) {
+      if (!this._hasPermission(actorPermissions, required)) {
+        missing.push(`${required.action}:${required.resource}`);
+      }
+    }
+
+    return missing;
+  }
+}

package/src/common/interceptor/performance.interceptor.ts

@@ -0,0 +1,101 @@
+import type { Interceptor } from "../abstract.interceptor.ts";
+import type { InterceptorContext } from "../type/interceptor-context.type.ts";
+
+/**
+ * Performance interceptor that measures usecase execution time.
+ * Tracks slow operations and warns when they exceed thresholds.
+ */
+export class PerformanceInterceptor<Input, Output>
+  implements Interceptor<Input, Output> {
+  readonly name = "PerformanceInterceptor";
+
+  private readonly startTimes = new Map<string, number>();
+
+  constructor(
+    private readonly slowThresholdMs: number = 1000,
+    private readonly logger: (message: string) => void = console.log,
+  ) {}
+
+  private getExecutionKey(context: InterceptorContext): string {
+    return `${context.actor.id}_${context.usecaseName.join("/")}`;
+  }
+
+  beforeExecute(
+    input: Input,
+    context: InterceptorContext,
+  ): Input {
+    const key = this.getExecutionKey(context);
+    this.startTimes.set(key, performance.now());
+
+    return input;
+  }
+
+  afterExecute(
+    output: Output,
+    context: InterceptorContext,
+  ): Output {
+    const key = this.getExecutionKey(context);
+    const startTime = this.startTimes.get(key);
+    this.startTimes.delete(key);
+
+    if (startTime !== undefined) {
+      const duration = performance.now() - startTime;
+      const action = context.usecaseName[0];
+      const resource = context.usecaseName[1];
+
+      this.logger(
+        `[Performance] ${action}/${resource} executed in ${
+          duration.toFixed(2)
+        }ms`,
+      );
+
+      // Warn if execution was slow
+      if (duration > this.slowThresholdMs) {
+        this.logger(
+          `[Performance WARNING] ${action}/${resource} exceeded threshold ` +
+            `(${duration.toFixed(2)}ms > ${this.slowThresholdMs}ms)`,
+        );
+      }
+    }
+
+    return output;
+  }
+
+  onError(
+    _error: Error,
+    context: InterceptorContext,
+  ): void {
+    const key = this.getExecutionKey(context);
+    const startTime = this.startTimes.get(key);
+    this.startTimes.delete(key);
+
+    if (startTime !== undefined) {
+      const duration = performance.now() - startTime;
+      const action = context.usecaseName[0];
+      const resource = context.usecaseName[1];
+
+      this.logger(
+        `[Performance] ${action}/${resource} failed after ${
+          duration.toFixed(2)
+        }ms`,
+      );
+    }
+  }
+
+  /**
+   * Get current performance metrics (useful for monitoring)
+   */
+  getMetrics(): { activeExecutions: number; keys: string[] } {
+    return {
+      activeExecutions: this.startTimes.size,
+      keys: Array.from(this.startTimes.keys()),
+    };
+  }
+
+  /**
+   * Clear all tracked executions (useful for cleanup)
+   */
+  clear(): void {
+    this.startTimes.clear();
+  }
+}

package/src/common/llm/api-definition.type.ts

@@ -0,0 +1,185 @@
+import type {
+  JsonSchema,
+  MutableJsonSchema,
+} from "../type/json-schema.type.ts";
+
+// Base interface for all parameters
+interface LlmBaseParameter {
+  readonly name: string;
+  readonly description: string;
+  readonly isRequired?: boolean;
+}
+
+// Primitive type parameters
+interface LlmStringParameter extends LlmBaseParameter {
+  readonly type: "string";
+}
+
+interface LlmNumberParameter extends LlmBaseParameter {
+  readonly type: "number" | "integer";
+}
+
+interface LlmBooleanParameter extends LlmBaseParameter {
+  readonly type: "boolean";
+}
+
+interface LlmNullParameter extends LlmBaseParameter {
+  readonly type: "null";
+}
+
+// Complex type parameters
+interface LlmArrayParameter extends LlmBaseParameter {
+  readonly type: "array";
+  readonly items: {
+    readonly type: string;
+    readonly description?: string;
+    readonly properties?: JsonSchema;
+  };
+}
+
+interface LlmObjectParameter extends LlmBaseParameter {
+  readonly type: "object";
+  readonly properties?: Record<string, JsonSchema>;
+  readonly required?: readonly string[];
+}
+
+// Discriminated union for parameters
+export type LlmParameter =
+  | LlmStringParameter
+  | LlmNumberParameter
+  | LlmBooleanParameter
+  | LlmNullParameter
+  | LlmArrayParameter
+  | LlmObjectParameter;
+
+// Base interface for all return values
+interface LlmBaseReturnValue {
+  readonly description: string;
+}
+
+// Primitive type returns
+interface LlmStringReturnValue extends LlmBaseReturnValue {
+  readonly type: "string";
+}
+
+interface LlmNumberReturnValue extends LlmBaseReturnValue {
+  readonly type: "number" | "integer";
+}
+
+interface LlmBooleanReturnValue extends LlmBaseReturnValue {
+  readonly type: "boolean";
+}
+
+interface LlmNullReturnValue extends LlmBaseReturnValue {
+  readonly type: "null";
+}
+
+// Complex type returns
+interface LlmArrayReturnValue extends LlmBaseReturnValue {
+  readonly type: "array";
+  readonly items: {
+    readonly type: string;
+    readonly description?: string;
+    readonly properties?: JsonSchema;
+  };
+}
+
+interface LlmObjectReturnValue extends LlmBaseReturnValue {
+  readonly type: "object";
+  readonly properties?: Record<string, JsonSchema>;
+  readonly required?: readonly string[];
+}
+
+// Discriminated union for return values
+export type LlmReturnValue =
+  | LlmStringReturnValue
+  | LlmNumberReturnValue
+  | LlmBooleanReturnValue
+  | LlmNullReturnValue
+  | LlmArrayReturnValue
+  | LlmObjectReturnValue;
+
+export interface ApiDefinition {
+  readonly name: string;
+  readonly description: string;
+  readonly parameters: LlmParameter[];
+  readonly returns: LlmReturnValue;
+}
+
+export function apiDefinitionToJsonSchema(
+  definition: ApiDefinition,
+): JsonSchema {
+  const properties: Record<string, MutableJsonSchema> = {};
+  const required: string[] = [];
+
+  for (const param of definition.parameters) {
+    const paramSchema: MutableJsonSchema = {
+      type: param.type,
+      description: param.description,
+    };
+
+    // Add items for array types (JSON Schema 2020-12 compliance)
+    if (param.type === "array" && "items" in param) {
+      const arrayParam = param as LlmArrayParameter;
+      paramSchema.items = arrayParam.items as MutableJsonSchema;
+    }
+
+    // Add properties and required for object types (JSON Schema 2020-12 compliance)
+    if (param.type === "object" && "properties" in param) {
+      const objectParam = param as LlmObjectParameter;
+      if (objectParam.properties) {
+        paramSchema.properties = objectParam.properties as Record<
+          string,
+          MutableJsonSchema
+        >;
+      }
+      if (objectParam.required) {
+        paramSchema.required = [...objectParam.required];
+      }
+    }
+
+    properties[param.name] = paramSchema;
+
+    if (param.isRequired !== false) {
+      required.push(param.name);
+    }
+  }
+
+  const returnsSchema: MutableJsonSchema = {
+    type: definition.returns.type,
+    description: definition.returns.description,
+  };
+
+  // Add items for array return types (JSON Schema 2020-12 compliance)
+  if (definition.returns.type === "array" && "items" in definition.returns) {
+    const arrayReturn = definition.returns as LlmArrayReturnValue;
+    returnsSchema.items = arrayReturn.items as MutableJsonSchema;
+  }
+
+  // Add properties and required for object return types (JSON Schema 2020-12 compliance)
+  if (
+    definition.returns.type === "object" && "properties" in definition.returns
+  ) {
+    const objectReturn = definition.returns as LlmObjectReturnValue;
+    if (objectReturn.properties) {
+      returnsSchema.properties = objectReturn.properties as Record<
+        string,
+        MutableJsonSchema
+      >;
+    }
+    if (objectReturn.required) {
+      returnsSchema.required = [...objectReturn.required];
+    }
+  }
+
+  return {
+    name: definition.name,
+    description: definition.description,
+    parameters: {
+      type: "object",
+      properties,
+      required,
+    },
+    returns: returnsSchema,
+  } as JsonSchema;
+}