@auxiora/connectors 1.0.0

package/src/trigger-manager.ts

@@ -0,0 +1,95 @@
+import type { ConnectorRegistry } from './registry.js';
+import type { AuthManager } from './auth-manager.js';
+import type { TriggerEvent } from './types.js';
+
+export type TriggerHandler = (events: TriggerEvent[]) => void | Promise<void>;
+
+interface Subscription {
+  connectorId: string;
+  triggerId: string;
+  instanceId: string;
+  handler: TriggerHandler;
+  lastPollAt: number;
+}
+
+export class TriggerManager {
+  private registry: ConnectorRegistry;
+  private authManager: AuthManager;
+  private subscriptions = new Map<string, Subscription>();
+
+  constructor(registry: ConnectorRegistry, authManager: AuthManager) {
+    this.registry = registry;
+    this.authManager = authManager;
+  }
+
+  /** Subscribe to a trigger on a connector instance. Returns a subscription ID. */
+  subscribe(
+    connectorId: string,
+    triggerId: string,
+    instanceId: string,
+    handler: TriggerHandler,
+  ): string {
+    const connector = this.registry.get(connectorId);
+    if (!connector) {
+      throw new Error(`Connector "${connectorId}" not found`);
+    }
+
+    const trigger = connector.triggers.find((t) => t.id === triggerId);
+    if (!trigger) {
+      throw new Error(`Trigger "${triggerId}" not found in connector "${connectorId}"`);
+    }
+
+    const subId = `${connectorId}:${triggerId}:${instanceId}`;
+    this.subscriptions.set(subId, {
+      connectorId,
+      triggerId,
+      instanceId,
+      handler,
+      lastPollAt: Date.now(),
+    });
+
+    return subId;
+  }
+
+  /** Unsubscribe from a trigger. */
+  unsubscribe(subscriptionId: string): boolean {
+    return this.subscriptions.delete(subscriptionId);
+  }
+
+  /** Poll all subscriptions and invoke handlers for new events. */
+  async pollAll(): Promise<TriggerEvent[]> {
+    const allEvents: TriggerEvent[] = [];
+
+    for (const [subId, sub] of this.subscriptions) {
+      const connector = this.registry.get(sub.connectorId);
+      if (!connector?.pollTrigger) continue;
+
+      const token = this.authManager.getToken(sub.instanceId);
+      if (!token) continue;
+
+      try {
+        const events = await connector.pollTrigger(
+          sub.triggerId,
+          token.accessToken,
+          sub.lastPollAt,
+        );
+
+        if (events.length > 0) {
+          await sub.handler(events);
+          allEvents.push(...events);
+        }
+
+        sub.lastPollAt = Date.now();
+      } catch {
+        // Poll errors are silently ignored to avoid breaking other subscriptions
+      }
+    }
+
+    return allEvents;
+  }
+
+  /** Get all active subscription IDs. */
+  getSubscriptions(): string[] {
+    return [...this.subscriptions.keys()];
+  }
+}

package/src/types.ts

@@ -0,0 +1,111 @@
+import type { TrustLevel, TrustDomain } from '@auxiora/autonomy';
+
+/** Supported authentication methods for connectors. */
+export type AuthType = 'oauth2' | 'api_key' | 'token';
+
+/** OAuth2 configuration for connectors that use OAuth2 auth. */
+export interface OAuth2Config {
+  authUrl: string;
+  tokenUrl: string;
+  scopes: string[];
+  clientId?: string;
+  clientSecret?: string;
+}
+
+/** Authentication configuration for a connector. */
+export interface AuthConfig {
+  type: AuthType;
+  oauth2?: OAuth2Config;
+  /** Human-readable instructions for obtaining credentials. */
+  instructions?: string;
+}
+
+/** Defines a single action that a connector can perform. */
+export interface ActionDefinition {
+  id: string;
+  name: string;
+  description: string;
+  /** Minimum trust level required to execute this action. */
+  trustMinimum: TrustLevel;
+  /** Trust domain this action operates in. */
+  trustDomain: TrustDomain;
+  /** Whether this action can be reversed/undone. */
+  reversible: boolean;
+  /** Whether this action has external side effects. */
+  sideEffects: boolean;
+  /** Parameter schema (JSON Schema-like). */
+  params: Record<string, ParamDefinition>;
+}
+
+/** Parameter definition for an action. */
+export interface ParamDefinition {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  description: string;
+  required?: boolean;
+  default?: unknown;
+}
+
+/** Defines a trigger that a connector can listen for. */
+export interface TriggerDefinition {
+  id: string;
+  name: string;
+  description: string;
+  /** How this trigger is detected. */
+  type: 'poll' | 'webhook';
+  /** Polling interval in ms (for poll triggers). */
+  pollIntervalMs?: number;
+}
+
+/** Defines an entity type that a connector exposes. */
+export interface EntityDefinition {
+  id: string;
+  name: string;
+  description: string;
+  /** Fields exposed by this entity. */
+  fields: Record<string, string>;
+}
+
+/** Full connector definition. */
+export interface Connector {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  category: string;
+  icon?: string;
+  auth: AuthConfig;
+  actions: ActionDefinition[];
+  triggers: TriggerDefinition[];
+  entities: EntityDefinition[];
+  /** Action handler called to execute actions. */
+  executeAction: (actionId: string, params: Record<string, unknown>, token: string) => Promise<unknown>;
+  /** Trigger poll handler. */
+  pollTrigger?: (triggerId: string, token: string, lastPollAt?: number) => Promise<TriggerEvent[]>;
+}
+
+/** Event emitted by a trigger. */
+export interface TriggerEvent {
+  triggerId: string;
+  connectorId: string;
+  data: Record<string, unknown>;
+  timestamp: number;
+}
+
+/** Stored token data for a connector instance. */
+export interface StoredToken {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+  tokenType?: string;
+  scopes?: string[];
+}
+
+/** A configured instance of a connector with auth credentials. */
+export interface ConnectorInstance {
+  id: string;
+  connectorId: string;
+  label: string;
+  createdAt: number;
+  /** Whether auth is configured and valid. */
+  authenticated: boolean;
+}

package/tests/auth-manager.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { AuthManager } from '../src/auth-manager.js';
+import type { AuthConfig } from '../src/types.js';
+import type { AuthManagerVault } from '../src/auth-manager.js';
+
+function createMockVault(data: Record<string, string> = {}): AuthManagerVault {
+  const store = new Map(Object.entries(data));
+  return {
+    get: (name: string) => store.get(name),
+    has: (name: string) => store.has(name),
+    add: async (name: string, value: string) => { store.set(name, value); },
+  };
+}
+
+describe('AuthManager', () => {
+  let authManager: AuthManager;
+
+  beforeEach(() => {
+    authManager = new AuthManager();
+  });
+
+  it('should authenticate with api_key', async () => {
+    const config: AuthConfig = { type: 'api_key' };
+    const token = await authManager.authenticate('inst-1', config, { apiKey: 'sk-123' });
+    expect(token.accessToken).toBe('sk-123');
+    expect(token.tokenType).toBe('api_key');
+  });
+
+  it('should authenticate with oauth2', async () => {
+    const config: AuthConfig = {
+      type: 'oauth2',
+      oauth2: { authUrl: 'https://auth.example.com', tokenUrl: 'https://token.example.com', scopes: ['read'] },
+    };
+    const token = await authManager.authenticate('inst-2', config, {
+      accessToken: 'at-abc',
+      refreshToken: 'rt-xyz',
+    });
+    expect(token.accessToken).toBe('at-abc');
+    expect(token.refreshToken).toBe('rt-xyz');
+    expect(token.scopes).toEqual(['read']);
+  });
+
+  it('should authenticate with token', async () => {
+    const config: AuthConfig = { type: 'token' };
+    const token = await authManager.authenticate('inst-3', config, { token: 'tok-456' });
+    expect(token.accessToken).toBe('tok-456');
+    expect(token.tokenType).toBe('Bearer');
+  });
+
+  it('should throw on missing api key', async () => {
+    const config: AuthConfig = { type: 'api_key' };
+    await expect(authManager.authenticate('inst-4', config, {})).rejects.toThrow('apiKey');
+  });
+
+  it('should throw on missing oauth2 access token', async () => {
+    const config: AuthConfig = { type: 'oauth2' };
+    await expect(authManager.authenticate('inst-5', config, {})).rejects.toThrow('accessToken');
+  });
+
+  it('should throw on missing token', async () => {
+    const config: AuthConfig = { type: 'token' };
+    await expect(authManager.authenticate('inst-6', config, {})).rejects.toThrow('token');
+  });
+
+  it('should get stored token', async () => {
+    const config: AuthConfig = { type: 'api_key' };
+    await authManager.authenticate('inst-1', config, { apiKey: 'sk-123' });
+    const token = authManager.getToken('inst-1');
+    expect(token?.accessToken).toBe('sk-123');
+  });
+
+  it('should return undefined for unknown instance', () => {
+    expect(authManager.getToken('unknown')).toBeUndefined();
+  });
+
+  it('should revoke token', async () => {
+    const config: AuthConfig = { type: 'api_key' };
+    await authManager.authenticate('inst-1', config, { apiKey: 'sk-123' });
+    expect(authManager.hasToken('inst-1')).toBe(true);
+    await authManager.revokeToken('inst-1');
+    expect(authManager.hasToken('inst-1')).toBe(false);
+  });
+
+  it('should detect expired tokens', async () => {
+    const config: AuthConfig = { type: 'oauth2' };
+    await authManager.authenticate('inst-exp', config, {
+      accessToken: 'at-exp',
+      expiresAt: String(Date.now() - 1000),
+    });
+    expect(authManager.isTokenExpired('inst-exp')).toBe(true);
+  });
+
+  it('should refresh oauth2 token', async () => {
+    // refreshToken now makes a real HTTP call, so we mock fetch and provide vault credentials
+    const vault = createMockVault({
+      'connectors.inst-ref.credentials': JSON.stringify({ clientId: 'cid', clientSecret: 'csecret' }),
+    });
+    const mgr = new AuthManager(vault);
+    const config: AuthConfig = {
+      type: 'oauth2',
+      oauth2: { authUrl: 'https://auth.example.com', tokenUrl: 'https://token.example.com', scopes: ['read'] },
+    };
+    await mgr.authenticate('inst-ref', config, {
+      accessToken: 'at-old',
+      refreshToken: 'rt-xyz',
+    });
+
+    // Mock the global fetch to return a fake token response
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ access_token: 'at-new', expires_in: 3600 }),
+    });
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = mockFetch as any;
+    try {
+      const refreshed = await mgr.refreshToken('inst-ref', config);
+      expect(refreshed.accessToken).toBe('at-new');
+      expect(refreshed.expiresAt).toBeGreaterThan(Date.now());
+      expect(refreshed.refreshToken).toBe('rt-xyz');
+      expect(mockFetch).toHaveBeenCalledOnce();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('should throw when refreshing non-oauth2 token', async () => {
+    const config: AuthConfig = { type: 'api_key' };
+    await authManager.authenticate('inst-api', config, { apiKey: 'key' });
+    await expect(authManager.refreshToken('inst-api', config)).rejects.toThrow('OAuth2');
+  });
+
+  it('should throw when refreshing unknown instance', async () => {
+    const config: AuthConfig = { type: 'oauth2' };
+    await expect(authManager.refreshToken('unknown', config)).rejects.toThrow('No token found');
+  });
+});

package/tests/define-connector.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { defineConnector } from '../src/define-connector.js';
+
+describe('defineConnector', () => {
+  const baseOpts = {
+    id: 'my-connector',
+    name: 'My Connector',
+    description: 'A connector',
+    version: '1.0.0',
+    category: 'testing',
+    auth: { type: 'api_key' as const },
+    actions: [
+      {
+        id: 'action-1',
+        name: 'Action 1',
+        description: 'Does something',
+        trustMinimum: 1 as const,
+        trustDomain: 'integrations' as const,
+        reversible: false,
+        sideEffects: false,
+        params: {},
+      },
+    ],
+    executeAction: async () => ({}),
+  };
+
+  it('should create a valid connector', () => {
+    const connector = defineConnector(baseOpts);
+    expect(connector.id).toBe('my-connector');
+    expect(connector.name).toBe('My Connector');
+    expect(connector.actions).toHaveLength(1);
+    expect(connector.triggers).toEqual([]);
+    expect(connector.entities).toEqual([]);
+  });
+
+  it('should include triggers and entities when provided', () => {
+    const connector = defineConnector({
+      ...baseOpts,
+      triggers: [{ id: 't1', name: 'Trigger', description: 'A trigger', type: 'poll' }],
+      entities: [{ id: 'e1', name: 'Entity', description: 'An entity', fields: { name: 'string' } }],
+    });
+    expect(connector.triggers).toHaveLength(1);
+    expect(connector.entities).toHaveLength(1);
+  });
+
+  it('should throw if id is missing', () => {
+    expect(() => defineConnector({ ...baseOpts, id: '' })).toThrow('id and name are required');
+  });
+
+  it('should throw if name is missing', () => {
+    expect(() => defineConnector({ ...baseOpts, name: '' })).toThrow('id and name are required');
+  });
+
+  it('should throw if no actions are defined', () => {
+    expect(() => defineConnector({ ...baseOpts, actions: [] })).toThrow('at least one action');
+  });
+
+  it('should throw if auth is missing', () => {
+    expect(() => defineConnector({ ...baseOpts, auth: undefined as any })).toThrow('auth config is required');
+  });
+});

package/tests/executor.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { ConnectorRegistry } from '../src/registry.js';
+import { AuthManager } from '../src/auth-manager.js';
+import { ActionExecutor } from '../src/executor.js';
+import { defineConnector } from '../src/define-connector.js';
+import { TrustEngine, TrustGate, ActionAuditTrail } from '@auxiora/autonomy';
+
+describe('ActionExecutor', () => {
+  let tmpDir: string;
+  let registry: ConnectorRegistry;
+  let authManager: AuthManager;
+  let trustGate: TrustGate;
+  let auditTrail: ActionAuditTrail;
+  let executor: ActionExecutor;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'executor-'));
+    const engine = new TrustEngine({ defaultLevel: 2 }, path.join(tmpDir, 'state.json'));
+    await engine.load();
+
+    registry = new ConnectorRegistry();
+    authManager = new AuthManager();
+    trustGate = new TrustGate(engine);
+    auditTrail = new ActionAuditTrail(path.join(tmpDir, 'audit.json'));
+    executor = new ActionExecutor(registry, authManager, trustGate, auditTrail);
+
+    // Register a test connector
+    registry.register(
+      defineConnector({
+        id: 'test',
+        name: 'Test',
+        description: 'Test connector',
+        version: '1.0.0',
+        category: 'testing',
+        auth: { type: 'api_key' },
+        actions: [
+          {
+            id: 'do-thing',
+            name: 'Do Thing',
+            description: 'Does a thing',
+            trustMinimum: 1,
+            trustDomain: 'integrations',
+            reversible: true,
+            sideEffects: true,
+            params: {},
+          },
+          {
+            id: 'high-trust',
+            name: 'High Trust Action',
+            description: 'Needs high trust',
+            trustMinimum: 4,
+            trustDomain: 'integrations',
+            reversible: false,
+            sideEffects: true,
+            params: {},
+          },
+        ],
+        executeAction: async (actionId) => {
+          if (actionId === 'do-thing') return { result: 'done' };
+          throw new Error('Action failed');
+        },
+      }),
+    );
+
+    // Authenticate instance
+    await authManager.authenticate('inst-1', { type: 'api_key' }, { apiKey: 'test-key' });
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('should execute an action successfully', async () => {
+    const result = await executor.execute('test', 'do-thing', {}, 'inst-1');
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual({ result: 'done' });
+    expect(result.auditId).toBeDefined();
+  });
+
+  it('should deny action when trust level is insufficient', async () => {
+    const result = await executor.execute('test', 'high-trust', {}, 'inst-1');
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('denied');
+  });
+
+  it('should fail for unknown connector', async () => {
+    const result = await executor.execute('unknown', 'action', {}, 'inst-1');
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('not found');
+  });
+
+  it('should fail for unknown action', async () => {
+    const result = await executor.execute('test', 'unknown', {}, 'inst-1');
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('not found');
+  });
+
+  it('should fail when no auth token exists', async () => {
+    const result = await executor.execute('test', 'do-thing', {}, 'no-token');
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('authentication token');
+  });
+
+  it('should record audit entry on success', async () => {
+    const result = await executor.execute('test', 'do-thing', {}, 'inst-1');
+    const entry = auditTrail.getById(result.auditId!);
+    expect(entry).toBeDefined();
+    expect(entry!.outcome).toBe('success');
+    expect(entry!.executed).toBe(true);
+  });
+
+  it('should record audit entry on trust denial', async () => {
+    const result = await executor.execute('test', 'high-trust', {}, 'inst-1');
+    const entry = auditTrail.getById(result.auditId!);
+    expect(entry).toBeDefined();
+    expect(entry!.outcome).toBe('failure');
+    expect(entry!.executed).toBe(false);
+  });
+});

package/tests/registry.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ConnectorRegistry } from '../src/registry.js';
+import { defineConnector } from '../src/define-connector.js';
+import type { Connector } from '../src/types.js';
+
+function makeConnector(overrides: Partial<Connector> = {}): Connector {
+  return defineConnector({
+    id: overrides.id ?? 'test-connector',
+    name: overrides.name ?? 'Test Connector',
+    description: 'A test connector',
+    version: '1.0.0',
+    category: overrides.category ?? 'testing',
+    auth: { type: 'api_key' },
+    actions: [
+      {
+        id: 'test-action',
+        name: 'Test Action',
+        description: 'Does a test thing',
+        trustMinimum: 1,
+        trustDomain: 'integrations',
+        reversible: false,
+        sideEffects: false,
+        params: {},
+      },
+    ],
+    triggers: [
+      {
+        id: 'test-trigger',
+        name: 'Test Trigger',
+        description: 'A test trigger',
+        type: 'poll',
+        pollIntervalMs: 60000,
+      },
+    ],
+    executeAction: async () => ({ ok: true }),
+  });
+}
+
+describe('ConnectorRegistry', () => {
+  let registry: ConnectorRegistry;
+
+  beforeEach(() => {
+    registry = new ConnectorRegistry();
+  });
+
+  it('should register and retrieve a connector', () => {
+    const connector = makeConnector();
+    registry.register(connector);
+    expect(registry.get('test-connector')).toBe(connector);
+  });
+
+  it('should throw when registering a duplicate', () => {
+    const connector = makeConnector();
+    registry.register(connector);
+    expect(() => registry.register(connector)).toThrow('already registered');
+  });
+
+  it('should list all connectors', () => {
+    registry.register(makeConnector({ id: 'a', name: 'A' }));
+    registry.register(makeConnector({ id: 'b', name: 'B' }));
+    expect(registry.list()).toHaveLength(2);
+  });
+
+  it('should list connectors by category', () => {
+    registry.register(makeConnector({ id: 'a', category: 'productivity' }));
+    registry.register(makeConnector({ id: 'b', category: 'devtools' }));
+    registry.register(makeConnector({ id: 'c', category: 'productivity' }));
+    expect(registry.listByCategory('productivity')).toHaveLength(2);
+    expect(registry.listByCategory('devtools')).toHaveLength(1);
+    expect(registry.listByCategory('unknown')).toHaveLength(0);
+  });
+
+  it('should get actions for a connector', () => {
+    registry.register(makeConnector());
+    const actions = registry.getActions('test-connector');
+    expect(actions).toHaveLength(1);
+    expect(actions[0].id).toBe('test-action');
+  });
+
+  it('should return empty array for unknown connector actions', () => {
+    expect(registry.getActions('unknown')).toEqual([]);
+  });
+
+  it('should get triggers for a connector', () => {
+    registry.register(makeConnector());
+    const triggers = registry.getTriggers('test-connector');
+    expect(triggers).toHaveLength(1);
+    expect(triggers[0].id).toBe('test-trigger');
+  });
+
+  it('should unregister a connector', () => {
+    registry.register(makeConnector());
+    expect(registry.has('test-connector')).toBe(true);
+    registry.unregister('test-connector');
+    expect(registry.has('test-connector')).toBe(false);
+  });
+
+  it('should return undefined for unknown connector', () => {
+    expect(registry.get('nonexistent')).toBeUndefined();
+  });
+});