@invect/core 0.0.1

package/dist/types/auth.types.d.cts

@@ -0,0 +1,235 @@
+//#region src/types/auth.types.d.ts
+/**
+ * Invect Authentication & Authorization Types
+ *
+ * Authentication is handled by the auth plugin (better-auth).
+ * Invect handles authorization based on the identity resolved by the plugin's onRequest hook.
+ */
+/**
+ * Identity resolved from the host app's authentication system.
+ * Invect doesn't care HOW you authenticated - just WHO you are.
+ */
+interface InvectIdentity {
+  /** Unique user identifier from host app (e.g., user ID, email, API key ID) */
+  id: string;
+  /** Optional display name for UI and audit logs */
+  name?: string;
+  /**
+   * Role within Invect (maps to permissions).
+   * Host app can either:
+   * 1. Provide a Invect role directly (if they store it)
+   * 2. Use roleMapper in config to map their roles → Invect roles
+   */
+  role?: InvectRole;
+  /**
+   * Team IDs this user belongs to (from host app).
+   * Used for team-level flow access when useFlowAccessTable is enabled.
+   */
+  teamIds?: string[];
+  /**
+   * Optional: Direct permission overrides (advanced use case).
+   * These are checked IN ADDITION to role-based permissions.
+   */
+  permissions?: InvectPermission[];
+  /**
+   * Optional: Resource-level access control.
+   * Restricts access to specific resources by ID.
+   * E.g., user can only access specific flows they created.
+   *
+   * Use '*' to allow access to all resources of that type.
+   * Omit the key entirely to use role-based access (no resource restriction).
+   *
+   * Note: If useFlowAccessTable is enabled, flow access is looked up from
+   * the database instead of this field.
+   */
+  resourceAccess?: InvectResourceAccess;
+  /** Any additional metadata from host app (for audit logs, etc.) */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Resource-level access control configuration.
+ * Each property is either:
+ * - An array of resource IDs the user can access
+ * - '*' to allow access to all resources
+ * - undefined to not restrict (use role permissions only)
+ */
+interface InvectResourceAccess {
+  /** Flow IDs the user can access */
+  flows?: string[] | '*';
+  /** Credential IDs the user can access */
+  credentials?: string[] | '*';
+}
+/**
+ * Built-in roles with predefined permission sets.
+ * Custom roles can be defined via config.customRoles.
+ */
+type InvectBuiltInRole = 'admin' | 'editor' | 'operator' | 'viewer';
+/**
+ * Invect role - either a built-in role or a custom role string.
+ */
+type InvectRole = InvectBuiltInRole | string;
+/**
+ * Granular permissions for Invect resources.
+ */
+type InvectPermission = 'flow:create' | 'flow:read' | 'flow:update' | 'flow:delete' | 'flow:publish' | 'flow-version:create' | 'flow-version:read' | 'flow-run:create' | 'flow-run:read' | 'flow-run:cancel' | 'credential:create' | 'credential:read' | 'credential:update' | 'credential:delete' | 'agent-tool:read' | 'agent-tool:configure' | 'node:test' | 'admin:*';
+/**
+ * Resource types that can be protected by authorization.
+ */
+type InvectResourceType = 'flow' | 'flow-version' | 'flow-run' | 'node-execution' | 'credential' | 'agent-tool';
+/**
+ * Context provided to authorization checks.
+ */
+interface AuthorizationContext {
+  /** The identity making the request (null if unauthenticated) */
+  identity: InvectIdentity | null;
+  /** The permission being checked */
+  action: InvectPermission;
+  /** The resource being accessed (if applicable) */
+  resource?: {
+    type: InvectResourceType;
+    id?: string;
+  };
+}
+/**
+ * Result of an authorization check.
+ */
+interface AuthorizationResult {
+  /** Whether the action is allowed */
+  allowed: boolean;
+  /** Reason for denial (if not allowed) */
+  reason?: string;
+}
+/**
+ * Base event data for all auth events.
+ */
+interface AuthEventBase {
+  /** Timestamp of the event */
+  timestamp: Date;
+  /** Identity that triggered the event (null if unauthenticated) */
+  identity: InvectIdentity | null;
+  /** The permission that was checked */
+  action: InvectPermission;
+  /** The resource involved (if applicable) */
+  resource?: {
+    type: InvectResourceType;
+    id?: string;
+  };
+}
+/**
+ * Event emitted when authorization succeeds.
+ */
+interface AuthAuthorizedEvent extends AuthEventBase {
+  type: 'auth:authorized';
+  allowed: true;
+}
+/**
+ * Event emitted when authorization fails.
+ */
+interface AuthForbiddenEvent extends AuthEventBase {
+  type: 'auth:forbidden';
+  allowed: false;
+  reason: string;
+}
+/**
+ * Event emitted when authentication fails (no valid identity).
+ */
+interface AuthUnauthenticatedEvent {
+  type: 'auth:unauthenticated';
+  timestamp: Date;
+  /** The permission that was attempted */
+  action: InvectPermission;
+  /** The resource involved (if applicable) */
+  resource?: {
+    type: InvectResourceType;
+    id?: string;
+  };
+}
+/**
+ * Union of all auth events.
+ */
+type AuthEvent = AuthAuthorizedEvent | AuthForbiddenEvent | AuthUnauthenticatedEvent;
+/**
+ * Callback for custom authorization logic.
+ * Called after standard RBAC checks.
+ *
+ * @returns
+ * - true: Allow the action
+ * - false: Deny the action
+ * - undefined: Use default RBAC result
+ */
+type CustomAuthorizeFn = (context: AuthorizationContext) => Promise<boolean | undefined> | boolean | undefined;
+/**
+ * Authentication/Authorization configuration for Invect.
+ */
+interface InvectAuthConfig {
+  /**
+   * Enable RBAC (Role-Based Access Control).
+   * When false, all requests are allowed without authentication checks.
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * Map host app roles to Invect roles.
+   * Useful when host app has different role names.
+   *
+   * @example { 'super_admin': 'admin', 'content_editor': 'editor' }
+   */
+  roleMapper?: Record<string, InvectRole>;
+  /**
+   * Define custom roles with specific permissions.
+   * Extends built-in roles (admin, editor, operator, viewer).
+   *
+   * @example { 'qa_tester': ['flow:read', 'flow-run:create', 'flow-run:read'] }
+   */
+  customRoles?: Record<string, InvectPermission[]>;
+  /**
+   * Callback for custom authorization logic.
+   * Called after standard RBAC checks.
+   * Return true to allow, false to deny, undefined to use default.
+   */
+  customAuthorize?: CustomAuthorizeFn;
+  /**
+   * Routes that don't require authentication.
+   * Matched against the request path.
+   *
+   * @example ['/health', '/metrics', '/webhooks/*']
+   */
+  publicRoutes?: string[];
+  /**
+   * Default role for authenticated users without an explicit role.
+   * @default 'viewer'
+   */
+  defaultRole?: InvectRole;
+  /**
+   * Behavior when auth fails.
+   * - 'throw': Throw an error (401/403)
+   * - 'log': Log warning and continue (allow access)
+   * - 'deny': Silently deny access
+   * @default 'throw'
+   */
+  onAuthFailure?: 'throw' | 'log' | 'deny';
+  /**
+   * Use the flow_access database table to manage flow-level permissions.
+   * When enabled:
+   * - Invect stores flow access records in its own database
+   * - Flow access is looked up from the database
+   *
+   * When disabled (default):
+   * - Flow access is determined by resourceAccess.flows from the identity
+   *
+   * @default false
+   */
+  useFlowAccessTable?: boolean;
+}
+/**
+ * Default permission sets for built-in roles.
+ */
+declare const DEFAULT_ROLE_PERMISSIONS: Record<InvectBuiltInRole, InvectPermission[]>;
+/**
+ * Map of actions to the permission required.
+ * Used for route-level authorization.
+ */
+declare const ACTION_PERMISSION_MAP: Record<string, InvectPermission>;
+//#endregion
+export { ACTION_PERMISSION_MAP, AuthAuthorizedEvent, AuthEvent, AuthEventBase, AuthForbiddenEvent, AuthUnauthenticatedEvent, AuthorizationContext, AuthorizationResult, CustomAuthorizeFn, DEFAULT_ROLE_PERMISSIONS, InvectAuthConfig, InvectBuiltInRole, InvectIdentity, InvectPermission, InvectResourceAccess, InvectResourceType, InvectRole };
+//# sourceMappingURL=auth.types.d.cts.map

package/dist/types/auth.types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.types.d.cts","names":[],"sources":["../../src/types/auth.types.ts"],"mappings":";;AAeA;;;;;;;;;UAAiB,cAAA;EAKf;EAHA,EAAA;EAWO;EARP,IAAA;EAoBA;;;;;;EAZA,IAAA,GAAO,UAAA;EA4BU;AAUnB;;;EAhCE,OAAA;EAoCW;AAWb;;;EAzCE,WAAA,GAAc,gBAAA;EAyCa;AAK7B;;;;;AAKA;;;;;EAtCE,cAAA,GAAiB,oBAAA;EAoEW;EAjE5B,QAAA,GAAW,MAAA;AAAA;;AAgFb;;;;;;UAtEiB,oBAAA;EA+EW;EA7E1B,KAAA;EAsEU;EApEV,WAAA;AAAA;;;;;KAWU,iBAAA;;AAwEZ;;KAnEY,UAAA,GAAa,iBAAA;;;AAiFzB;KA5EY,gBAAA;;;;KA8BA,kBAAA;;;;UAeK,oBAAA;EAiCJ;EA/BX,QAAA,EAAU,cAAA;EAiCA;EA9BV,MAAA,EAAQ,gBAAA;EAgCA;EA7BR,QAAA;IACE,IAAA,EAAM,kBAAA;IACN,EAAA;EAAA;AAAA;;AAsCJ;;UA/BiB,mBAAA;EA+ByC;EA7BxD,OAAA;EA8BA;EA5BA,MAAA;AAAA;;AAmCF;;UAzBiB,aAAA;EAyBwC;EAvBvD,SAAA,EAAW,IAAA;EAwBX;EAtBA,QAAA,EAAU,cAAA;EAwBV;EAtBA,MAAA,EAAQ,gBAAA;EAsBF;EApBN,QAAA;IACE,IAAA,EAAM,kBAAA;IACN,EAAA;EAAA;AAAA;;;;UAOa,mBAAA,SAA4B,aAAA;EAC3C,IAAA;EACA,OAAA;AAAA;;;;UAMe,kBAAA,SAA2B,aAAA;EAC1C,IAAA;EACA,OAAA;EACA,MAAA;AAAA;;;;UAMe,wBAAA;EACf,IAAA;EACA,SAAA,EAAW,IAAA;EAa8E;EAXzF,MAAA,EAAQ,gBAAA;EAWoC;EAT5C,QAAA;IACE,IAAA,EAAM,kBAAA;IACN,EAAA;EAAA;AAAA;;;;KAOQ,SAAA,GAAY,mBAAA,GAAsB,kBAAA,GAAqB,wBAAA;;;;AAsBnE;;;;;;KAPY,iBAAA,IACV,OAAA,EAAS,oBAAA,KACN,OAAA;;;;UAKY,gBAAA;EAMf;;;;;EAAA,OAAA;EAgB6B;;;;;;EAR7B,UAAA,GAAa,MAAA,SAAe,UAAA;EAmD5B;;;AAUF;;;EArDE,WAAA,GAAc,MAAA,SAAe,gBAAA;EAqDkC;;;;;EA9C/D,eAAA,GAAkB,iBAAA;EA8C6C;;;AAyCjE;;;EA/EE,YAAA;EA+EiE;;;;EAzEjE,WAAA,GAAc,UAAA;;;;;;;;EASd,aAAA;;;;;;;;;;;;EAaA,kBAAA;AAAA;;;;cAUW,wBAAA,EAA0B,MAAA,CAAO,iBAAA,EAAmB,gBAAA;;;;;cAyCpD,qBAAA,EAAuB,MAAA,SAAe,gBAAA"}

package/dist/types/auth.types.d.ts

@@ -0,0 +1,235 @@
+//#region src/types/auth.types.d.ts
+/**
+ * Invect Authentication & Authorization Types
+ *
+ * Authentication is handled by the auth plugin (better-auth).
+ * Invect handles authorization based on the identity resolved by the plugin's onRequest hook.
+ */
+/**
+ * Identity resolved from the host app's authentication system.
+ * Invect doesn't care HOW you authenticated - just WHO you are.
+ */
+interface InvectIdentity {
+  /** Unique user identifier from host app (e.g., user ID, email, API key ID) */
+  id: string;
+  /** Optional display name for UI and audit logs */
+  name?: string;
+  /**
+   * Role within Invect (maps to permissions).
+   * Host app can either:
+   * 1. Provide a Invect role directly (if they store it)
+   * 2. Use roleMapper in config to map their roles → Invect roles
+   */
+  role?: InvectRole;
+  /**
+   * Team IDs this user belongs to (from host app).
+   * Used for team-level flow access when useFlowAccessTable is enabled.
+   */
+  teamIds?: string[];
+  /**
+   * Optional: Direct permission overrides (advanced use case).
+   * These are checked IN ADDITION to role-based permissions.
+   */
+  permissions?: InvectPermission[];
+  /**
+   * Optional: Resource-level access control.
+   * Restricts access to specific resources by ID.
+   * E.g., user can only access specific flows they created.
+   *
+   * Use '*' to allow access to all resources of that type.
+   * Omit the key entirely to use role-based access (no resource restriction).
+   *
+   * Note: If useFlowAccessTable is enabled, flow access is looked up from
+   * the database instead of this field.
+   */
+  resourceAccess?: InvectResourceAccess;
+  /** Any additional metadata from host app (for audit logs, etc.) */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Resource-level access control configuration.
+ * Each property is either:
+ * - An array of resource IDs the user can access
+ * - '*' to allow access to all resources
+ * - undefined to not restrict (use role permissions only)
+ */
+interface InvectResourceAccess {
+  /** Flow IDs the user can access */
+  flows?: string[] | '*';
+  /** Credential IDs the user can access */
+  credentials?: string[] | '*';
+}
+/**
+ * Built-in roles with predefined permission sets.
+ * Custom roles can be defined via config.customRoles.
+ */
+type InvectBuiltInRole = 'admin' | 'editor' | 'operator' | 'viewer';
+/**
+ * Invect role - either a built-in role or a custom role string.
+ */
+type InvectRole = InvectBuiltInRole | string;
+/**
+ * Granular permissions for Invect resources.
+ */
+type InvectPermission = 'flow:create' | 'flow:read' | 'flow:update' | 'flow:delete' | 'flow:publish' | 'flow-version:create' | 'flow-version:read' | 'flow-run:create' | 'flow-run:read' | 'flow-run:cancel' | 'credential:create' | 'credential:read' | 'credential:update' | 'credential:delete' | 'agent-tool:read' | 'agent-tool:configure' | 'node:test' | 'admin:*';
+/**
+ * Resource types that can be protected by authorization.
+ */
+type InvectResourceType = 'flow' | 'flow-version' | 'flow-run' | 'node-execution' | 'credential' | 'agent-tool';
+/**
+ * Context provided to authorization checks.
+ */
+interface AuthorizationContext {
+  /** The identity making the request (null if unauthenticated) */
+  identity: InvectIdentity | null;
+  /** The permission being checked */
+  action: InvectPermission;
+  /** The resource being accessed (if applicable) */
+  resource?: {
+    type: InvectResourceType;
+    id?: string;
+  };
+}
+/**
+ * Result of an authorization check.
+ */
+interface AuthorizationResult {
+  /** Whether the action is allowed */
+  allowed: boolean;
+  /** Reason for denial (if not allowed) */
+  reason?: string;
+}
+/**
+ * Base event data for all auth events.
+ */
+interface AuthEventBase {
+  /** Timestamp of the event */
+  timestamp: Date;
+  /** Identity that triggered the event (null if unauthenticated) */
+  identity: InvectIdentity | null;
+  /** The permission that was checked */
+  action: InvectPermission;
+  /** The resource involved (if applicable) */
+  resource?: {
+    type: InvectResourceType;
+    id?: string;
+  };
+}
+/**
+ * Event emitted when authorization succeeds.
+ */
+interface AuthAuthorizedEvent extends AuthEventBase {
+  type: 'auth:authorized';
+  allowed: true;
+}
+/**
+ * Event emitted when authorization fails.
+ */
+interface AuthForbiddenEvent extends AuthEventBase {
+  type: 'auth:forbidden';
+  allowed: false;
+  reason: string;
+}
+/**
+ * Event emitted when authentication fails (no valid identity).
+ */
+interface AuthUnauthenticatedEvent {
+  type: 'auth:unauthenticated';
+  timestamp: Date;
+  /** The permission that was attempted */
+  action: InvectPermission;
+  /** The resource involved (if applicable) */
+  resource?: {
+    type: InvectResourceType;
+    id?: string;
+  };
+}
+/**
+ * Union of all auth events.
+ */
+type AuthEvent = AuthAuthorizedEvent | AuthForbiddenEvent | AuthUnauthenticatedEvent;
+/**
+ * Callback for custom authorization logic.
+ * Called after standard RBAC checks.
+ *
+ * @returns
+ * - true: Allow the action
+ * - false: Deny the action
+ * - undefined: Use default RBAC result
+ */
+type CustomAuthorizeFn = (context: AuthorizationContext) => Promise<boolean | undefined> | boolean | undefined;
+/**
+ * Authentication/Authorization configuration for Invect.
+ */
+interface InvectAuthConfig {
+  /**
+   * Enable RBAC (Role-Based Access Control).
+   * When false, all requests are allowed without authentication checks.
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * Map host app roles to Invect roles.
+   * Useful when host app has different role names.
+   *
+   * @example { 'super_admin': 'admin', 'content_editor': 'editor' }
+   */
+  roleMapper?: Record<string, InvectRole>;
+  /**
+   * Define custom roles with specific permissions.
+   * Extends built-in roles (admin, editor, operator, viewer).
+   *
+   * @example { 'qa_tester': ['flow:read', 'flow-run:create', 'flow-run:read'] }
+   */
+  customRoles?: Record<string, InvectPermission[]>;
+  /**
+   * Callback for custom authorization logic.
+   * Called after standard RBAC checks.
+   * Return true to allow, false to deny, undefined to use default.
+   */
+  customAuthorize?: CustomAuthorizeFn;
+  /**
+   * Routes that don't require authentication.
+   * Matched against the request path.
+   *
+   * @example ['/health', '/metrics', '/webhooks/*']
+   */
+  publicRoutes?: string[];
+  /**
+   * Default role for authenticated users without an explicit role.
+   * @default 'viewer'
+   */
+  defaultRole?: InvectRole;
+  /**
+   * Behavior when auth fails.
+   * - 'throw': Throw an error (401/403)
+   * - 'log': Log warning and continue (allow access)
+   * - 'deny': Silently deny access
+   * @default 'throw'
+   */
+  onAuthFailure?: 'throw' | 'log' | 'deny';
+  /**
+   * Use the flow_access database table to manage flow-level permissions.
+   * When enabled:
+   * - Invect stores flow access records in its own database
+   * - Flow access is looked up from the database
+   *
+   * When disabled (default):
+   * - Flow access is determined by resourceAccess.flows from the identity
+   *
+   * @default false
+   */
+  useFlowAccessTable?: boolean;
+}
+/**
+ * Default permission sets for built-in roles.
+ */
+declare const DEFAULT_ROLE_PERMISSIONS: Record<InvectBuiltInRole, InvectPermission[]>;
+/**
+ * Map of actions to the permission required.
+ * Used for route-level authorization.
+ */
+declare const ACTION_PERMISSION_MAP: Record<string, InvectPermission>;
+//#endregion
+export { ACTION_PERMISSION_MAP, AuthAuthorizedEvent, AuthEvent, AuthEventBase, AuthForbiddenEvent, AuthUnauthenticatedEvent, AuthorizationContext, AuthorizationResult, CustomAuthorizeFn, DEFAULT_ROLE_PERMISSIONS, InvectAuthConfig, InvectBuiltInRole, InvectIdentity, InvectPermission, InvectResourceAccess, InvectResourceType, InvectRole };
+//# sourceMappingURL=auth.types.d.ts.map

package/dist/types/auth.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.types.d.ts","names":[],"sources":["../../src/types/auth.types.ts"],"mappings":";;AAeA;;;;;;;;;UAAiB,cAAA;EAKf;EAHA,EAAA;EAWO;EARP,IAAA;EAoBA;;;;;;EAZA,IAAA,GAAO,UAAA;EA4BU;AAUnB;;;EAhCE,OAAA;EAoCW;AAWb;;;EAzCE,WAAA,GAAc,gBAAA;EAyCa;AAK7B;;;;;AAKA;;;;;EAtCE,cAAA,GAAiB,oBAAA;EAoEW;EAjE5B,QAAA,GAAW,MAAA;AAAA;;AAgFb;;;;;;UAtEiB,oBAAA;EA+EW;EA7E1B,KAAA;EAsEU;EApEV,WAAA;AAAA;;;;;KAWU,iBAAA;;AAwEZ;;KAnEY,UAAA,GAAa,iBAAA;;;AAiFzB;KA5EY,gBAAA;;;;KA8BA,kBAAA;;;;UAeK,oBAAA;EAiCJ;EA/BX,QAAA,EAAU,cAAA;EAiCA;EA9BV,MAAA,EAAQ,gBAAA;EAgCA;EA7BR,QAAA;IACE,IAAA,EAAM,kBAAA;IACN,EAAA;EAAA;AAAA;;AAsCJ;;UA/BiB,mBAAA;EA+ByC;EA7BxD,OAAA;EA8BA;EA5BA,MAAA;AAAA;;AAmCF;;UAzBiB,aAAA;EAyBwC;EAvBvD,SAAA,EAAW,IAAA;EAwBX;EAtBA,QAAA,EAAU,cAAA;EAwBV;EAtBA,MAAA,EAAQ,gBAAA;EAsBF;EApBN,QAAA;IACE,IAAA,EAAM,kBAAA;IACN,EAAA;EAAA;AAAA;;;;UAOa,mBAAA,SAA4B,aAAA;EAC3C,IAAA;EACA,OAAA;AAAA;;;;UAMe,kBAAA,SAA2B,aAAA;EAC1C,IAAA;EACA,OAAA;EACA,MAAA;AAAA;;;;UAMe,wBAAA;EACf,IAAA;EACA,SAAA,EAAW,IAAA;EAa8E;EAXzF,MAAA,EAAQ,gBAAA;EAWoC;EAT5C,QAAA;IACE,IAAA,EAAM,kBAAA;IACN,EAAA;EAAA;AAAA;;;;KAOQ,SAAA,GAAY,mBAAA,GAAsB,kBAAA,GAAqB,wBAAA;;;;AAsBnE;;;;;;KAPY,iBAAA,IACV,OAAA,EAAS,oBAAA,KACN,OAAA;;;;UAKY,gBAAA;EAMf;;;;;EAAA,OAAA;EAgB6B;;;;;;EAR7B,UAAA,GAAa,MAAA,SAAe,UAAA;EAmD5B;;;AAUF;;;EArDE,WAAA,GAAc,MAAA,SAAe,gBAAA;EAqDkC;;;;;EA9C/D,eAAA,GAAkB,iBAAA;EA8C6C;;;AAyCjE;;;EA/EE,YAAA;EA+EiE;;;;EAzEjE,WAAA,GAAc,UAAA;;;;;;;;EASd,aAAA;;;;;;;;;;;;EAaA,kBAAA;AAAA;;;;cAUW,wBAAA,EAA0B,MAAA,CAAO,iBAAA,EAAmB,gBAAA;;;;;cAyCpD,qBAAA,EAAuB,MAAA,SAAe,gBAAA"}

package/dist/types/auth.types.js

@@ -0,0 +1,75 @@
+//#region src/types/auth.types.ts
+/**
+* Default permission sets for built-in roles.
+*/
+const DEFAULT_ROLE_PERMISSIONS = {
+	admin: ["admin:*"],
+	editor: [
+		"flow:create",
+		"flow:read",
+		"flow:update",
+		"flow:delete",
+		"flow:publish",
+		"flow-version:create",
+		"flow-version:read",
+		"flow-run:create",
+		"flow-run:read",
+		"flow-run:cancel",
+		"credential:create",
+		"credential:read",
+		"credential:update",
+		"credential:delete",
+		"agent-tool:read",
+		"agent-tool:configure",
+		"node:test"
+	],
+	operator: [
+		"flow:read",
+		"flow-version:read",
+		"flow-run:create",
+		"flow-run:read",
+		"flow-run:cancel",
+		"credential:read",
+		"agent-tool:read",
+		"node:test"
+	],
+	viewer: [
+		"flow:read",
+		"flow-version:read",
+		"flow-run:read",
+		"credential:read",
+		"agent-tool:read"
+	]
+};
+/**
+* Map of actions to the permission required.
+* Used for route-level authorization.
+*/
+const ACTION_PERMISSION_MAP = {
+	listFlows: "flow:read",
+	getFlow: "flow:read",
+	createFlow: "flow:create",
+	updateFlow: "flow:update",
+	deleteFlow: "flow:delete",
+	publishFlow: "flow:publish",
+	listFlowVersions: "flow-version:read",
+	getFlowVersion: "flow-version:read",
+	createFlowVersion: "flow-version:create",
+	listFlowRuns: "flow-run:read",
+	getFlowRun: "flow-run:read",
+	startFlowRun: "flow-run:create",
+	cancelFlowRun: "flow-run:cancel",
+	listCredentials: "credential:read",
+	getCredential: "credential:read",
+	createCredential: "credential:create",
+	updateCredential: "credential:update",
+	deleteCredential: "credential:delete",
+	listAgentTools: "agent-tool:read",
+	getAgentTool: "agent-tool:read",
+	testSqlQuery: "node:test",
+	testModel: "node:test"
+};
+//#endregion
+export { ACTION_PERMISSION_MAP, DEFAULT_ROLE_PERMISSIONS };
+
+//# sourceMappingURL=auth.types.js.map

package/dist/types/auth.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.types.js","names":[],"sources":["../../src/types/auth.types.ts"],"sourcesContent":["/**\n * Invect Authentication & Authorization Types\n *\n * Authentication is handled by the auth plugin (better-auth).\n * Invect handles authorization based on the identity resolved by the plugin's onRequest hook.\n */\n\n// =============================================================================\n// Identity Types\n// =============================================================================\n\n/**\n * Identity resolved from the host app's authentication system.\n * Invect doesn't care HOW you authenticated - just WHO you are.\n */\nexport interface InvectIdentity {\n  /** Unique user identifier from host app (e.g., user ID, email, API key ID) */\n  id: string;\n\n  /** Optional display name for UI and audit logs */\n  name?: string;\n\n  /**\n   * Role within Invect (maps to permissions).\n   * Host app can either:\n   * 1. Provide a Invect role directly (if they store it)\n   * 2. Use roleMapper in config to map their roles → Invect roles\n   */\n  role?: InvectRole;\n\n  /**\n   * Team IDs this user belongs to (from host app).\n   * Used for team-level flow access when useFlowAccessTable is enabled.\n   */\n  teamIds?: string[];\n\n  /**\n   * Optional: Direct permission overrides (advanced use case).\n   * These are checked IN ADDITION to role-based permissions.\n   */\n  permissions?: InvectPermission[];\n\n  /**\n   * Optional: Resource-level access control.\n   * Restricts access to specific resources by ID.\n   * E.g., user can only access specific flows they created.\n   *\n   * Use '*' to allow access to all resources of that type.\n   * Omit the key entirely to use role-based access (no resource restriction).\n   *\n   * Note: If useFlowAccessTable is enabled, flow access is looked up from\n   * the database instead of this field.\n   */\n  resourceAccess?: InvectResourceAccess;\n\n  /** Any additional metadata from host app (for audit logs, etc.) */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Resource-level access control configuration.\n * Each property is either:\n * - An array of resource IDs the user can access\n * - '*' to allow access to all resources\n * - undefined to not restrict (use role permissions only)\n */\nexport interface InvectResourceAccess {\n  /** Flow IDs the user can access */\n  flows?: string[] | '*';\n  /** Credential IDs the user can access */\n  credentials?: string[] | '*';\n}\n\n// =============================================================================\n// Role & Permission Types\n// =============================================================================\n\n/**\n * Built-in roles with predefined permission sets.\n * Custom roles can be defined via config.customRoles.\n */\nexport type InvectBuiltInRole = 'admin' | 'editor' | 'operator' | 'viewer';\n\n/**\n * Invect role - either a built-in role or a custom role string.\n */\nexport type InvectRole = InvectBuiltInRole | string;\n\n/**\n * Granular permissions for Invect resources.\n */\nexport type InvectPermission =\n  // Flow permissions\n  | 'flow:create'\n  | 'flow:read'\n  | 'flow:update'\n  | 'flow:delete'\n  | 'flow:publish' // Set live version\n  // Flow version permissions\n  | 'flow-version:create'\n  | 'flow-version:read'\n  // Execution permissions\n  | 'flow-run:create' // Start executions\n  | 'flow-run:read'\n  | 'flow-run:cancel'\n  // Credential permissions\n  | 'credential:create'\n  | 'credential:read'\n  | 'credential:update'\n  | 'credential:delete'\n  // Agent/tool permissions\n  | 'agent-tool:read'\n  | 'agent-tool:configure'\n  // Node testing\n  | 'node:test' // Test individual nodes (SQL, model, etc.)\n  // Admin permissions\n  | 'admin:*'; // Wildcard - all permissions\n\n/**\n * Resource types that can be protected by authorization.\n */\nexport type InvectResourceType =\n  | 'flow'\n  | 'flow-version'\n  | 'flow-run'\n  | 'node-execution'\n  | 'credential'\n  | 'agent-tool';\n\n// =============================================================================\n// Authorization Context & Results\n// =============================================================================\n\n/**\n * Context provided to authorization checks.\n */\nexport interface AuthorizationContext {\n  /** The identity making the request (null if unauthenticated) */\n  identity: InvectIdentity | null;\n\n  /** The permission being checked */\n  action: InvectPermission;\n\n  /** The resource being accessed (if applicable) */\n  resource?: {\n    type: InvectResourceType;\n    id?: string;\n  };\n}\n\n/**\n * Result of an authorization check.\n */\nexport interface AuthorizationResult {\n  /** Whether the action is allowed */\n  allowed: boolean;\n  /** Reason for denial (if not allowed) */\n  reason?: string;\n}\n\n// =============================================================================\n// Auth Events (for host app audit logging)\n// =============================================================================\n\n/**\n * Base event data for all auth events.\n */\nexport interface AuthEventBase {\n  /** Timestamp of the event */\n  timestamp: Date;\n  /** Identity that triggered the event (null if unauthenticated) */\n  identity: InvectIdentity | null;\n  /** The permission that was checked */\n  action: InvectPermission;\n  /** The resource involved (if applicable) */\n  resource?: {\n    type: InvectResourceType;\n    id?: string;\n  };\n}\n\n/**\n * Event emitted when authorization succeeds.\n */\nexport interface AuthAuthorizedEvent extends AuthEventBase {\n  type: 'auth:authorized';\n  allowed: true;\n}\n\n/**\n * Event emitted when authorization fails.\n */\nexport interface AuthForbiddenEvent extends AuthEventBase {\n  type: 'auth:forbidden';\n  allowed: false;\n  reason: string;\n}\n\n/**\n * Event emitted when authentication fails (no valid identity).\n */\nexport interface AuthUnauthenticatedEvent {\n  type: 'auth:unauthenticated';\n  timestamp: Date;\n  /** The permission that was attempted */\n  action: InvectPermission;\n  /** The resource involved (if applicable) */\n  resource?: {\n    type: InvectResourceType;\n    id?: string;\n  };\n}\n\n/**\n * Union of all auth events.\n */\nexport type AuthEvent = AuthAuthorizedEvent | AuthForbiddenEvent | AuthUnauthenticatedEvent;\n\n// =============================================================================\n// Configuration Types\n// =============================================================================\n\n/**\n * Callback for custom authorization logic.\n * Called after standard RBAC checks.\n *\n * @returns\n * - true: Allow the action\n * - false: Deny the action\n * - undefined: Use default RBAC result\n */\nexport type CustomAuthorizeFn = (\n  context: AuthorizationContext,\n) => Promise<boolean | undefined> | boolean | undefined;\n\n/**\n * Authentication/Authorization configuration for Invect.\n */\nexport interface InvectAuthConfig {\n  /**\n   * Enable RBAC (Role-Based Access Control).\n   * When false, all requests are allowed without authentication checks.\n   * @default false\n   */\n  enabled?: boolean;\n\n  /**\n   * Map host app roles to Invect roles.\n   * Useful when host app has different role names.\n   *\n   * @example { 'super_admin': 'admin', 'content_editor': 'editor' }\n   */\n  roleMapper?: Record<string, InvectRole>;\n\n  /**\n   * Define custom roles with specific permissions.\n   * Extends built-in roles (admin, editor, operator, viewer).\n   *\n   * @example { 'qa_tester': ['flow:read', 'flow-run:create', 'flow-run:read'] }\n   */\n  customRoles?: Record<string, InvectPermission[]>;\n\n  /**\n   * Callback for custom authorization logic.\n   * Called after standard RBAC checks.\n   * Return true to allow, false to deny, undefined to use default.\n   */\n  customAuthorize?: CustomAuthorizeFn;\n\n  /**\n   * Routes that don't require authentication.\n   * Matched against the request path.\n   *\n   * @example ['/health', '/metrics', '/webhooks/*']\n   */\n  publicRoutes?: string[];\n\n  /**\n   * Default role for authenticated users without an explicit role.\n   * @default 'viewer'\n   */\n  defaultRole?: InvectRole;\n\n  /**\n   * Behavior when auth fails.\n   * - 'throw': Throw an error (401/403)\n   * - 'log': Log warning and continue (allow access)\n   * - 'deny': Silently deny access\n   * @default 'throw'\n   */\n  onAuthFailure?: 'throw' | 'log' | 'deny';\n\n  /**\n   * Use the flow_access database table to manage flow-level permissions.\n   * When enabled:\n   * - Invect stores flow access records in its own database\n   * - Flow access is looked up from the database\n   *\n   * When disabled (default):\n   * - Flow access is determined by resourceAccess.flows from the identity\n   *\n   * @default false\n   */\n  useFlowAccessTable?: boolean;\n}\n\n// =============================================================================\n// Default Role Permissions\n// =============================================================================\n\n/**\n * Default permission sets for built-in roles.\n */\nexport const DEFAULT_ROLE_PERMISSIONS: Record<InvectBuiltInRole, InvectPermission[]> = {\n  admin: ['admin:*'],\n\n  editor: [\n    'flow:create',\n    'flow:read',\n    'flow:update',\n    'flow:delete',\n    'flow:publish',\n    'flow-version:create',\n    'flow-version:read',\n    'flow-run:create',\n    'flow-run:read',\n    'flow-run:cancel',\n    'credential:create',\n    'credential:read',\n    'credential:update',\n    'credential:delete',\n    'agent-tool:read',\n    'agent-tool:configure',\n    'node:test',\n  ],\n\n  operator: [\n    'flow:read',\n    'flow-version:read',\n    'flow-run:create',\n    'flow-run:read',\n    'flow-run:cancel',\n    'credential:read',\n    'agent-tool:read',\n    'node:test',\n  ],\n\n  viewer: ['flow:read', 'flow-version:read', 'flow-run:read', 'credential:read', 'agent-tool:read'],\n};\n\n/**\n * Map of actions to the permission required.\n * Used for route-level authorization.\n */\nexport const ACTION_PERMISSION_MAP: Record<string, InvectPermission> = {\n  // Flows\n  listFlows: 'flow:read',\n  getFlow: 'flow:read',\n  createFlow: 'flow:create',\n  updateFlow: 'flow:update',\n  deleteFlow: 'flow:delete',\n  publishFlow: 'flow:publish',\n\n  // Flow versions\n  listFlowVersions: 'flow-version:read',\n  getFlowVersion: 'flow-version:read',\n  createFlowVersion: 'flow-version:create',\n\n  // Flow runs\n  listFlowRuns: 'flow-run:read',\n  getFlowRun: 'flow-run:read',\n  startFlowRun: 'flow-run:create',\n  cancelFlowRun: 'flow-run:cancel',\n\n  // Credentials\n  listCredentials: 'credential:read',\n  getCredential: 'credential:read',\n  createCredential: 'credential:create',\n  updateCredential: 'credential:update',\n  deleteCredential: 'credential:delete',\n\n  // Agent tools\n  listAgentTools: 'agent-tool:read',\n  getAgentTool: 'agent-tool:read',\n\n  // Node testing\n  testSqlQuery: 'node:test',\n  testModel: 'node:test',\n};\n"],"mappings":";;;;AAyTA,MAAa,2BAA0E;CACrF,OAAO,CAAC,UAAU;CAElB,QAAQ;EACN;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD;CAED,UAAU;EACR;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD;CAED,QAAQ;EAAC;EAAa;EAAqB;EAAiB;EAAmB;EAAkB;CAClG;;;;;AAMD,MAAa,wBAA0D;CAErE,WAAW;CACX,SAAS;CACT,YAAY;CACZ,YAAY;CACZ,YAAY;CACZ,aAAa;CAGb,kBAAkB;CAClB,gBAAgB;CAChB,mBAAmB;CAGnB,cAAc;CACd,YAAY;CACZ,cAAc;CACd,eAAe;CAGf,iBAAiB;CACjB,eAAe;CACf,kBAAkB;CAClB,kBAAkB;CAClB,kBAAkB;CAGlB,gBAAgB;CAChB,cAAc;CAGd,cAAc;CACd,WAAW;CACZ"}

package/dist/types/base.cjs

@@ -0,0 +1,25 @@
+//#region src/types/base.ts
+let NodeExecutionStatus = /* @__PURE__ */ function(NodeExecutionStatus) {
+	NodeExecutionStatus["PENDING"] = "PENDING";
+	NodeExecutionStatus["RUNNING"] = "RUNNING";
+	NodeExecutionStatus["SUCCESS"] = "SUCCESS";
+	NodeExecutionStatus["FAILED"] = "FAILED";
+	NodeExecutionStatus["SKIPPED"] = "SKIPPED";
+	NodeExecutionStatus["BATCH_SUBMITTED"] = "BATCH_SUBMITTED";
+	return NodeExecutionStatus;
+}({});
+let FlowRunStatus = /* @__PURE__ */ function(FlowRunStatus) {
+	FlowRunStatus["PENDING"] = "PENDING";
+	FlowRunStatus["RUNNING"] = "RUNNING";
+	FlowRunStatus["SUCCESS"] = "SUCCESS";
+	FlowRunStatus["FAILED"] = "FAILED";
+	FlowRunStatus["PAUSED"] = "PAUSED";
+	FlowRunStatus["CANCELLED"] = "CANCELLED";
+	FlowRunStatus["PAUSED_FOR_BATCH"] = "PAUSED_FOR_BATCH";
+	return FlowRunStatus;
+}({});
+//#endregion
+exports.FlowRunStatus = FlowRunStatus;
+exports.NodeExecutionStatus = NodeExecutionStatus;
+
+//# sourceMappingURL=base.cjs.map

package/dist/types/base.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.cjs","names":[],"sources":["../../src/types/base.ts"],"sourcesContent":["// Node execution status\nexport enum NodeExecutionStatus {\n  PENDING = 'PENDING',\n  RUNNING = 'RUNNING',\n  SUCCESS = 'SUCCESS',\n  FAILED = 'FAILED',\n  SKIPPED = 'SKIPPED',\n  BATCH_SUBMITTED = 'BATCH_SUBMITTED',\n}\n\n// Execution status\nexport enum FlowRunStatus {\n  PENDING = 'PENDING',\n  RUNNING = 'RUNNING',\n  SUCCESS = 'SUCCESS',\n  FAILED = 'FAILED',\n  PAUSED = 'PAUSED',\n  CANCELLED = 'CANCELLED',\n  PAUSED_FOR_BATCH = 'PAUSED_FOR_BATCH',\n}\n"],"mappings":";AACA,IAAY,sBAAL,yBAAA,qBAAA;AACL,qBAAA,aAAA;AACA,qBAAA,aAAA;AACA,qBAAA,aAAA;AACA,qBAAA,YAAA;AACA,qBAAA,aAAA;AACA,qBAAA,qBAAA;;KACD;AAGD,IAAY,gBAAL,yBAAA,eAAA;AACL,eAAA,aAAA;AACA,eAAA,aAAA;AACA,eAAA,aAAA;AACA,eAAA,YAAA;AACA,eAAA,YAAA;AACA,eAAA,eAAA;AACA,eAAA,sBAAA;;KACD"}

package/dist/types/base.d.cts

@@ -0,0 +1,21 @@
+//#region src/types/base.d.ts
+declare enum NodeExecutionStatus {
+  PENDING = "PENDING",
+  RUNNING = "RUNNING",
+  SUCCESS = "SUCCESS",
+  FAILED = "FAILED",
+  SKIPPED = "SKIPPED",
+  BATCH_SUBMITTED = "BATCH_SUBMITTED"
+}
+declare enum FlowRunStatus {
+  PENDING = "PENDING",
+  RUNNING = "RUNNING",
+  SUCCESS = "SUCCESS",
+  FAILED = "FAILED",
+  PAUSED = "PAUSED",
+  CANCELLED = "CANCELLED",
+  PAUSED_FOR_BATCH = "PAUSED_FOR_BATCH"
+}
+//#endregion
+export { FlowRunStatus, NodeExecutionStatus };
+//# sourceMappingURL=base.d.cts.map

package/dist/types/base.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.cts","names":[],"sources":["../../src/types/base.ts"],"mappings":";aACY,mBAAA;EACV,OAAA;EACA,OAAA;EACA,OAAA;EACA,MAAA;EACA,OAAA;EACA,eAAA;AAAA;AAAA,aAIU,aAAA;EACV,OAAA;EACA,OAAA;EACA,OAAA;EACA,MAAA;EACA,MAAA;EACA,SAAA;EACA,gBAAA;AAAA"}

package/dist/types/base.d.ts

@@ -0,0 +1,21 @@
+//#region src/types/base.d.ts
+declare enum NodeExecutionStatus {
+  PENDING = "PENDING",
+  RUNNING = "RUNNING",
+  SUCCESS = "SUCCESS",
+  FAILED = "FAILED",
+  SKIPPED = "SKIPPED",
+  BATCH_SUBMITTED = "BATCH_SUBMITTED"
+}
+declare enum FlowRunStatus {
+  PENDING = "PENDING",
+  RUNNING = "RUNNING",
+  SUCCESS = "SUCCESS",
+  FAILED = "FAILED",
+  PAUSED = "PAUSED",
+  CANCELLED = "CANCELLED",
+  PAUSED_FOR_BATCH = "PAUSED_FOR_BATCH"
+}
+//#endregion
+export { FlowRunStatus, NodeExecutionStatus };
+//# sourceMappingURL=base.d.ts.map

package/dist/types/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","names":[],"sources":["../../src/types/base.ts"],"mappings":";aACY,mBAAA;EACV,OAAA;EACA,OAAA;EACA,OAAA;EACA,MAAA;EACA,OAAA;EACA,eAAA;AAAA;AAAA,aAIU,aAAA;EACV,OAAA;EACA,OAAA;EACA,OAAA;EACA,MAAA;EACA,MAAA;EACA,SAAA;EACA,gBAAA;AAAA"}