@agentforge-io/core 2.0.16 → 2.0.17

package/dist/domain/connector.d.ts

@@ -28,11 +28,45 @@ export interface ConnectorToolFactory {
     definition: Omit<AgentToolDefinition, 'execute'>;
     build: (ctx: ConnectorToolContext) => AgentToolDefinition['execute'];
 }
+/**
+ * UI hints for connectors that authenticate via a user-pasted API key
+ * instead of the OAuth2 dance (Granola — and any future provider whose
+ * vendor doesn't ship OAuth for third-party apps).
+ *
+ * The runtime never reads these fields itself; they exist so the host's
+ * directory UI can render a sensible "Paste your key" panel without
+ * hard-coding per-provider copy. `expectedPrefix` is also used by the
+ * registry as a cheap sanity check before persisting — a key that doesn't
+ * start with `grn_` is almost certainly a paste mistake.
+ */
+export interface ApiKeyAuthConfig {
+    /** URL to the provider's docs page that explains where the user generates
+     *  the API key (e.g. Granola's Settings → Connectors → API keys). Shown
+     *  as a "Where do I get this?" link in the UI. */
+    instructionsUrl?: string;
+    /** Placeholder text shown inside the input field. */
+    placeholder?: string;
+    /** If set, the registry rejects keys that don't start with this prefix —
+     *  Granola's keys are `grn_…`, so a paste that doesn't start that way is
+     *  almost always a wrong copy. Skip the check by leaving this undefined. */
+    expectedPrefix?: string;
+}
 /**
  * Static connector definition. Lives in code (option 1 from the design
  * discussion): one of these per supported provider, registered into the
  * `ConnectorRegistry` at boot. The host wires `clientId` / `clientSecret`
  * from env into the `oauth` config before registering.
+ *
+ * Connectors come in two auth flavors:
+ *
+ *   - **OAuth2** (Google, Slack, Notion, …) — set `oauth`. The registry
+ *     drives the authorize → exchange → refresh dance.
+ *   - **API key** (Granola, …) — set `apiKey`. The user pastes their key
+ *     into the UI; the registry persists it via the same encrypted column
+ *     as an OAuth access token (no refresh, no expiry).
+ *
+ * Exactly one of `oauth` / `apiKey` must be present. The registry throws
+ * on `register()` if both are set or neither is.
  */
 export interface ConnectorDefinition {
     /** Stable slug used in URLs and the DB (`google`, `slack`, …). */
@@ -45,7 +79,10 @@ export interface ConnectorDefinition {
     category?: string;
     /** Optional URL of a logo asset served by the host. */
     iconUrl?: string;
-    oauth: OAuth2ProviderConfig;
+    /** OAuth2 connector config. Exactly one of `oauth` / `apiKey` is set. */
+    oauth?: OAuth2ProviderConfig;
+    /** API-key connector config. Exactly one of `oauth` / `apiKey` is set. */
+    apiKey?: ApiKeyAuthConfig;
     /** Tools this connector contributes to the agent's toolbelt once a user
      *  has authorized. */
     tools: ConnectorToolFactory[];

package/dist/services/connector-registry.service.d.ts

@@ -5,7 +5,7 @@ import type { ToolRegistryService } from './tool-registry.service';
 import type { AgentToolDefinition } from '../types';
 export declare class ConnectorError extends Error {
     status: number;
-    code: 'unknown_connector' | 'not_connected' | 'not_configured' | 'invalid_state' | 'token_exchange_failed';
+    code: 'unknown_connector' | 'not_connected' | 'not_configured' | 'invalid_state' | 'token_exchange_failed' | 'invalid_api_key' | 'wrong_auth_kind';
     constructor(code: ConnectorError['code'], message: string);
 }
 /**
@@ -141,6 +141,19 @@ export declare class ConnectorRegistryService {
         connectorId: string;
         userId: string;
     }>;
+    /**
+     * Persist a user-pasted API key as the connector credential for `userId`.
+     * Replaces any existing row (so reconnecting with a fresh key just works).
+     *
+     * The key is treated exactly like an OAuth access token from this point
+     * on: encrypted at rest via the same cipher, never expires (no refresh
+     * dance), and surfaced through `getAccessToken` for tool calls.
+     *
+     * Validation here is intentionally minimal — prefix check + non-empty. A
+     * provider ping ("does this key actually work?") belongs in the
+     * controller, where the per-connector HTTP client lives.
+     */
+    saveApiKey(connectorId: string, userId: string, apiKey: string): Promise<void>;
     listForUser(userId: string): Promise<ConnectorStatus[]>;
     disconnect(userId: string, connectorId: string): Promise<void>;
     /**

package/dist/services/connector-registry.service.js

@@ -70,6 +70,15 @@ class ConnectorRegistryService {
         if (this.defs.has(def.id)) {
             throw new Error(`Connector "${def.id}" already registered`);
         }
+        // Exactly one auth flavor. Catching this at register-time avoids
+        // confusing runtime errors deep inside startAuthorize / saveApiKey when
+        // the wrong branch is taken on a half-built def.
+        const hasOauth = !!def.oauth;
+        const hasApiKey = !!def.apiKey;
+        if (hasOauth === hasApiKey) {
+            throw new Error(`Connector "${def.id}" must declare exactly one of \`oauth\` or \`apiKey\`` +
+                ` (got ${hasOauth ? 'both' : 'neither'}).`);
+        }
         this.defs.set(def.id, def);
     }
     /**
@@ -118,6 +127,14 @@ class ConnectorRegistryService {
     // ─── OAuth flow ──────────────────────────────────────────────────────────
     async startAuthorize(connectorId, userId, redirectUri) {
         const def = this.get(connectorId);
+        if (!def.oauth) {
+            // API-key connectors don't run an OAuth dance. The controller is
+            // expected to route the request to `saveApiKey` instead — surface a
+            // distinct error code so the UI can render the right panel rather
+            // than retrying authorize.
+            throw new ConnectorError('wrong_auth_kind', `Connector "${connectorId}" authenticates with an API key, not OAuth. ` +
+                `Use POST /connectors/oauth/${connectorId}/api-key instead.`);
+        }
         if (!this.configured.has(connectorId)) {
             throw new ConnectorError('not_configured', `Connector "${connectorId}" is not configured — the operator must ` +
                 `set its OAuth credentials before users can connect.`);
@@ -144,6 +161,14 @@ class ConnectorRegistryService {
             throw new ConnectorError('invalid_state', 'OAuth state is unknown or expired');
         }
         const def = this.get(ctx.connectorId);
+        if (!def.oauth) {
+            // Belt + suspenders. `startAuthorize` already gates on this, but if
+            // an operator swapped an OAuth connector for an API-key one between
+            // the authorize redirect and the callback, the state would still be
+            // valid and we'd crash here. Fail loud.
+            throw new ConnectorError('wrong_auth_kind', `Connector "${ctx.connectorId}" no longer uses OAuth — the user must ` +
+                `re-connect using the API key flow.`);
+        }
         let tokens;
         try {
             tokens = await this.deps.oauth.exchangeCode(def.oauth, code, redirectUri, ctx.pkceVerifier);
@@ -154,6 +179,36 @@ class ConnectorRegistryService {
         await this.upsertAuth(ctx.userId, ctx.connectorId, tokens);
         return { connectorId: ctx.connectorId, userId: ctx.userId };
     }
+    // ─── API-key flow ────────────────────────────────────────────────────────
+    /**
+     * Persist a user-pasted API key as the connector credential for `userId`.
+     * Replaces any existing row (so reconnecting with a fresh key just works).
+     *
+     * The key is treated exactly like an OAuth access token from this point
+     * on: encrypted at rest via the same cipher, never expires (no refresh
+     * dance), and surfaced through `getAccessToken` for tool calls.
+     *
+     * Validation here is intentionally minimal — prefix check + non-empty. A
+     * provider ping ("does this key actually work?") belongs in the
+     * controller, where the per-connector HTTP client lives.
+     */
+    async saveApiKey(connectorId, userId, apiKey) {
+        const def = this.get(connectorId);
+        if (!def.apiKey) {
+            throw new ConnectorError('wrong_auth_kind', `Connector "${connectorId}" authenticates with OAuth, not an API key.`);
+        }
+        const trimmed = apiKey.trim();
+        if (!trimmed) {
+            throw new ConnectorError('invalid_api_key', 'API key is empty.');
+        }
+        if (def.apiKey.expectedPrefix && !trimmed.startsWith(def.apiKey.expectedPrefix)) {
+            throw new ConnectorError('invalid_api_key', `API key for "${connectorId}" must start with "${def.apiKey.expectedPrefix}".`);
+        }
+        // Synthesize a TokenSet so upsertAuth can be reused unchanged. No
+        // expiresIn, no refreshToken — same shape as a long-lived OAuth token
+        // (ClickUp, Slack, GitHub, Notion).
+        await this.upsertAuth(userId, connectorId, { accessToken: trimmed });
+    }
     // ─── Per-user listing ────────────────────────────────────────────────────
     async listForUser(userId) {
         const authed = await this.deps.authRepo.listForUser(userId);
@@ -285,6 +340,13 @@ class ConnectorRegistryService {
             throw new ConnectorError('not_connected', `Token for ${a.connectorId} expired and no refresh token is available; user must re-authorize`);
         }
         const def = this.get(a.connectorId);
+        if (!def.oauth) {
+            // Unreachable in practice: api-key connectors never persist a
+            // refresh token, so the earlier `!a.refreshTokenEncrypted` branch
+            // would have caught this. Belt + suspenders for the type checker
+            // and for the case where someone manually inserts a row.
+            throw new ConnectorError('wrong_auth_kind', `Connector "${a.connectorId}" uses API-key auth; cannot refresh.`);
+        }
         const refreshPlain = this.deps.cipher.decrypt(a.refreshTokenEncrypted);
         const fresh = await this.deps.oauth.refresh(def.oauth, refreshPlain);
         const expiresAt = fresh.expiresIn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/core",
-  "version": "2.0.16",
+  "version": "2.0.17",
   "description": "Framework-free AI runtime SDK. Owns: agent loop (Anthropic), conversations, tools, streaming, agent-job queue, SdkHooks. Identity, billing, infra (email/uploads/secrets) live in the host's modules — not here.",
   "license": "MIT",
   "main": "dist/index.js",