@nightowlsdev/connectors 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,478 @@
+import { z } from 'zod';
+import { SwarmToolContext, SwarmContext, SwarmTool, AskField, SecretResolver } from '@nightowlsdev/core';
+
+/** Which connection (provider account) an action acts with. */
+interface ConnectionRef {
+    provider: string;
+    accountLabel?: string;
+}
+/** A backend-agnostic HTTP request a `BoundConnection` knows how to authorize + send. */
+interface ProxyRequest {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/**
+ * What an action's `execute` sees on `ctx.connection`: a live, tenant-scoped connection.
+ * `proxy()` ONLY — there is deliberately NO raw `token` field (connectors-architecture Codex #6):
+ * core has no redaction layer on tool outputs, so exposing a token would invite a custom `execute`
+ * returning it straight to the model.
+ */
+interface BoundConnection {
+    accountId: string;
+    proxy(req: ProxyRequest): Promise<unknown>;
+}
+/** The context a custom action `execute` receives — the tool context plus the resolved connection. */
+interface ConnectorActionContext extends SwarmToolContext {
+    connection: BoundConnection;
+}
+/** One agent-callable action of a connector. Provide EXACTLY ONE of `op` (declarative HTTP) or `execute` (custom). */
+interface ConnectorActionSpec<I = unknown> {
+    name: string;
+    description?: string;
+    inputSchema: z.ZodType<I>;
+    /**
+     * The connector DSL OWNS this default (connectors-architecture Codex #10): `defineTool` only defaults
+     * `needsApproval` for `origin:"mcp"`. Set it explicitly per action — `true` (side-effecting) by default.
+     */
+    needsApproval?: boolean;
+    /** Declarative HTTP op — the materialized tool calls `connection.proxy({ method, path, body: input })`. */
+    op?: {
+        method: ProxyRequest["method"];
+        path: string;
+    };
+    /** Custom execute — receives `ctx.connection`; its result is fenced by the backend. */
+    execute?: (input: I, ctx: ConnectorActionContext) => Promise<unknown>;
+}
+/** A subscribable event (used by the trigger intake — declared here, consumed in a later slice). */
+interface ConnectorEventSpec {
+    type: string;
+    normalize?: (raw: unknown) => unknown;
+}
+/** One declared unit bundling a single external service's actions + events + connection auth metadata. */
+interface ConnectorDef {
+    provider: string;
+    connection?: {
+        kind: "oauth2" | "apikey" | "static";
+        scopes?: string[];
+    };
+    actions: ConnectorActionSpec[];
+    events?: ConnectorEventSpec[];
+}
+/**
+ * A materialized connector action: a `SwarmTool` (so it can be granted to agents + inherits the SP5 gate),
+ * directly executable for delivery/tests. Its output is ALWAYS fenced (the per-backend contract, Codex #5).
+ */
+interface ConnectorTool extends SwarmTool {
+    execute(input: unknown, ctx: SwarmToolContext): Promise<{
+        fenced: string;
+    }>;
+}
+/** A pluggable backend (static/env, remote-MCP, or Nango) the connector seam swaps without agent-code change. */
+interface ConnectorBackend {
+    /** Materialize a connector's actions into SwarmTools (async/lazy, like `McpConnector.listTools`). */
+    materialize(def: ConnectorDef, ctx: SwarmContext): Promise<SwarmTool[]>;
+    /** Resolve a live, refreshed, tenant-scoped connection at call time. */
+    resolveConnection(ref: ConnectionRef, ctx: SwarmContext): Promise<BoundConnection>;
+    dispose?(): Promise<void>;
+}
+
+/**
+ * Declare a connector (plain validated data — engine-wall-clean, no Mastra types). Validation is compile-cheap and pure:
+ * a provider is required, action names are unique, and each action declares EXACTLY ONE of `op`/`execute`.
+ */
+declare function defineConnector(spec: ConnectorDef): ConnectorDef;
+
+/** Fence untrusted connector (external-service) output before it is returned to the model. */
+declare function fenceConnectorOutput(raw: unknown): {
+    fenced: string;
+};
+
+/**
+ * Adapt a set of connectors + a backend into the per-request resolver core's `defineSwarm({ connectorTools })`
+ * expects. Core stays connector-agnostic — it only ever sees `(ctx) => Promise<SwarmTool[]>` — so the dependency
+ * arrow is one-way (`@nightowlsdev/connectors → @nightowlsdev/core`), never circular.
+ *
+ * Fail-fast by design: a duplicate action name across connectors throws at construction (a name collision would
+ * otherwise silently last-wins in the agent's by-name tool map and route the model's call to the WRONG
+ * connection); a `backend.materialize` failure rejects the whole request rather than silently under-granting
+ * tools (a materialize failure is a real config/connection problem worth surfacing, not hiding).
+ */
+declare function materializeConnectors(connectors: ConnectorDef[], backend: ConnectorBackend): (ctx: SwarmContext) => Promise<SwarmTool[]>;
+
+/**
+ * First-party Slack connector (Web API via `staticBackend`). Credentials (`SLACK_BOT_TOKEN`) + the base URL come
+ * from the backend connection at request time; this def only declares the actions + their approval defaults.
+ *
+ * Approval defaults are OWNED here (parent Codex #10): `post_message` side-effects ⇒ gated; `search` is read-only.
+ */
+declare const slackConnector: ConnectorDef;
+
+/** First-party Linear connector (action + trigger). The bug-report example (gap-map) becomes real with this. */
+declare const linearConnector: ConnectorDef;
+
+/**
+ * Out-of-band HITL delivery (spec §5): ship a suspended run's `swarm.question` to a channel and return a
+ * correlation ref. Engine-wall clean, no DB — the backend (proxy) is injected. Delivery is gated on CONTENT
+ * (§5.5): the model's `prompt` is DATA inside a fixed template, rendered INERT (Slack Block Kit `plain_text`,
+ * which parses no mrkdwn/links/mentions), and may go ONLY to the run's route-allowlisted target.
+ */
+/** A route is resolved server-side (from thread/subscription config), NEVER from a model-named address (§5.5). */
+type DeliveryRoute = {
+    channel: "slack";
+    target: {
+        teamId: string;
+        channelId: string;
+    };
+} | {
+    channel: "email";
+    target: {
+        to: string;
+    };
+};
+/** The post-egress correlation handle (the message id/ts exists only after the send). */
+interface DeliveryRef {
+    channel: string;
+    ref: Record<string, unknown>;
+}
+interface QuestionToDeliver {
+    followupId: string;
+    toolCallId: string;
+    prompt: string;
+    field?: AskField;
+    to: string;
+}
+interface QuestionDelivery {
+    deliver(q: QuestionToDeliver, ctx: SwarmContext, route: DeliveryRoute): Promise<DeliveryRef>;
+}
+/** Neutralize Slack control sequences for the case a `mrkdwn` block is unavoidable (§5.5): escape `&<>` so
+ *  `<!channel>` / `<@U…>` / links can't be parsed as mentions/markup. `plain_text` blocks need no escaping. */
+declare function escapeSlackText(s: string): string;
+/** Render the ask as INERT Block Kit: the model's prompt sits in a `plain_text` block (no mrkdwn/mention parsing).
+ *  The `text` fallback is a FIXED agent-authored string — never the model prompt — so the notification preview
+ *  (which DOES parse mrkdwn) can't be used to inject. */
+declare function renderSlackQuestion(prompt: string, _field?: AskField): {
+    blocks: unknown[];
+    text: string;
+};
+/** Slack `QuestionDelivery` over a connector backend's proxy (`chat.postMessage`). Posts to the route's
+ *  allowlisted channel ONLY; returns `{team_id, channel_id, delivery_ts}` where `delivery_ts` is the new message
+ *  ts (each ask is its own top-level message, so the reply's `thread_ts` equals it — exact correlation, §5.3). */
+declare function slackQuestionDelivery(opts: {
+    backend: ConnectorBackend;
+    provider?: string;
+}): QuestionDelivery;
+
+/** First-party Email connector. `from` is deployment config (a verified sender), NOT model-controlled. The
+ *  `email.send` action is **text/plain only** (no `html` — no markup/injection surface) and SP5-gated, so a human
+ *  approves the recipient + body before any send. */
+declare function emailConnector(opts: {
+    from: string;
+}): ConnectorDef;
+/**
+ * Mint a tamper-proof reply token for a followup: `b64url({f,e?}).b64url(HMAC(payload))`, embedded in the
+ * delivery's `reply-to` (e.g. `reply+<token>@domain`) so an email reply correlates back to the followup without
+ * trusting any sender-controlled header.
+ *
+ * **TTL (Blocks #1):** pass `expiresInSec` to embed a signed expiry — a forwarded/leaked email's token then stops
+ * correlating after the window. (Independently, the followup record is itself a time-bound: `findSuspended` only
+ * returns LIVE suspended runs, so a token to an answered/dead followup correlates to nothing.)
+ *
+ * **Responder binding (Blocks #2):** the token authenticates the `followupId` ONLY — it does NOT authorize a
+ * sender. The K4 inbound pipeline's `authorizeReplier` independently checks the provider-VERIFIED replier against
+ * the ask's approver, so a forwarded email from a non-approver fails authz even with a valid token.
+ */
+declare function mintReplyToken(followupId: string, secret: string, opts?: {
+    expiresInSec?: number;
+    nowSec?: number;
+}): Promise<string>;
+/** Verify a reply token → the `followupId`, or null if malformed/tampered/expired (constant-time HMAC compare
+ *  BEFORE parsing the payload). */
+declare function verifyReplyToken(token: string, secret: string, opts?: {
+    nowSec?: number;
+}): Promise<string | null>;
+/** Extract the reply token from a `local+<token>@domain` inbound address. Null when there's no `+token` part. */
+declare function parseReplyToken(address: string): string | null;
+/** Verify an inbound-email provider webhook signature (HMAC-SHA256 over the raw body, hex). The reply's identity
+ *  comes from the provider's AUTHENTICATED result (the signed payload's verified `from` + SPF/DKIM verdict) —
+ *  never a raw `From` header. */
+declare function verifyInboundEmailSignature(input: {
+    payload: string;
+    signature: string | null | undefined;
+    secret: string;
+}): Promise<boolean>;
+/** Deliver a suspended run's ask over email (text/plain) with a signed reply-token in `reply-to`, so the human's
+ *  reply resumes the run via the K4 inbound pipeline. Goes ONLY to the route-allowlisted recipient (§5.5). */
+declare function emailQuestionDelivery(opts: {
+    backend: ConnectorBackend;
+    from: string;
+    /** Build the reply-to address carrying the token, e.g. `(t) => `reply+${t}@owls.example``. */
+    replyAddress: (token: string) => string;
+    tokenSecret: string;
+    /** Reply-token TTL (seconds). Default 7 days — a leaked/forwarded email stops correlating after the window. */
+    tokenTtlSec?: number;
+    provider?: string;
+}): QuestionDelivery;
+
+/** A statically-configured connection (creds from env/config — the zero-infra dev/test backend). */
+interface StaticConnection {
+    baseUrl: string;
+    /** A literal token (dev), OR a `secretRef` resolved via the `SecretResolver` at execute time. */
+    token?: string;
+    secretRef?: string;
+    accountId?: string;
+    /** Override the auth header (default: `{ Authorization: "Bearer <token>" }`). */
+    authHeader?: (token: string | undefined) => Record<string, string>;
+}
+interface StaticBackendOpts {
+    /** Connections keyed by provider. */
+    connections: Record<string, StaticConnection>;
+    secrets?: SecretResolver;
+    /** Injectable `fetch` (default: global `fetch`) — for tests/integration. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * The zero-infra reference backend: resolves credentials from env/config (no OAuth, no `owl_connections`),
+ * materializes each action into a fenced `SwarmTool`, and authorizes HTTP via a bearer-token proxy.
+ */
+declare function staticBackend(opts: StaticBackendOpts): ConnectorBackend;
+
+/** A single Nango proxy request — the host adapts the Nango SDK's `proxy()` to this shape. Returns the parsed
+ *  response body; throws on a non-2xx (the host adapter owns HTTP-status handling, like a `fetch` wrapper). */
+interface NangoProxyRequest {
+    connectionId: string;
+    providerConfigKey?: string;
+    /** Reuse the strict `ProxyRequest` union so a typo (e.g. `"POSTT"`) can't compile — the backend only ever
+     *  forwards a connector op's method, which is already that union. */
+    method: ProxyRequest["method"];
+    path: string;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/** The injected Nango client surface `nangoBackend` needs — Nango injects + refreshes the OAuth token internally,
+ *  so no raw token ever reaches this code (architecture §5: "in the Nango path we store no raw tokens"). */
+interface NangoProxy {
+    proxy(req: NangoProxyRequest): Promise<unknown>;
+}
+/** The resolved tenant connection: the Nango `connectionId` (token lives in Nango) + display metadata. */
+interface ResolvedNangoConnection {
+    connectionId: string;
+    accountId?: string;
+    providerConfigKey?: string;
+}
+/** Tenant-scoped connection lookup — the host backs this with `owl_connections WHERE org_id = ctx.tenantId AND
+ *  provider = …`. Returns `null` when the tenant hasn't connected the provider (⇒ the tool fails loud → re-auth). */
+type NangoConnectionLookup = (ref: ConnectionRef, ctx: SwarmContext) => Promise<ResolvedNangoConnection | null>;
+interface NangoBackendOpts {
+    nango: NangoProxy;
+    resolveConnection: NangoConnectionLookup;
+}
+/**
+ * The platform OAuth backend: resolves a tenant's connection at CALL time (so a resumed run gets current creds —
+ * architecture §5) and proxies authorized HTTP through Nango. Vendor-agnostic + hermetically testable: the Nango
+ * client and the `owl_connections`-backed lookup are injected (mirrors `staticBackend`'s injected `fetchImpl`).
+ */
+declare function nangoBackend(opts: NangoBackendOpts): ConnectorBackend;
+
+/**
+ * Trigger intake (architecture §4.2 / parent §6): a provider webhook → verify → dedupe → normalize → enqueue a
+ * run per subscription. Built in `@nightowlsdev/connectors` (engine-wall clean, no DB) — every side dependency is
+ * INJECTED, so the host wires the real dedupe store / subscription lookup / durable runner while this stays
+ * hermetically testable. Identity is SERVER-SIDE (from the subscription), never from the event body (Codex #2/#3);
+ * the raw event payload is FENCED untrusted in the run input (Codex #5).
+ */
+/** Verify a Slack request signature. Slack signs `v0:${timestamp}:${rawBody}` with HMAC-SHA256 keyed by the
+ *  signing secret, hex, as `v0=…` in `X-Slack-Signature`; the timestamp must be fresh (replay guard). */
+declare function verifySlackSignature(input: {
+    signingSecret: string;
+    signature: string | null | undefined;
+    timestamp: string | null | undefined;
+    body: string;
+    nowSec?: number;
+    maxSkewSec?: number;
+}): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/** Verify a Linear webhook signature: HMAC-SHA256 of the RAW body keyed by the webhook signing secret, hex, in
+ *  the `linear-signature` header (no prefix). Web Crypto + constant-time compare, like the Slack verifier. */
+declare function verifyLinearSignature(input: {
+    secret: string;
+    signature: string | null | undefined;
+    body: string;
+}): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/** A code-defined (v1) subscription: which agent, owned by which user, in which org/thread, fires on an event. */
+interface TriggerSubscription {
+    orgId: string;
+    ownerUserId: string;
+    agentSlug: string;
+    threadId: string;
+    workflow?: string;
+}
+/** The durable runner seam (a subset of the core runner's `enqueue`) — injected so this stays @mastra-free. */
+type TriggerEnqueue = (input: {
+    message: string;
+    context?: Record<string, unknown>;
+    workflow?: string;
+}, ctx: {
+    tenantId: string;
+    userId: string;
+    agentSlug: string;
+    threadId: string;
+    runId: string;
+}) => Promise<{
+    runId: string;
+}>;
+/** Idempotency store (Codex #8). `markSeen` returns true if the key is NEW (first time), false if already seen. */
+interface TriggerDedupe {
+    markSeen(key: {
+        provider: string;
+        externalId: string;
+    }): Promise<boolean>;
+}
+interface HandleTriggerOpts {
+    connector: ConnectorDef;
+    /** The Slack signing secret — required UNLESS `skipSignatureCheck` (the caller already verified, e.g. Nango). */
+    signingSecret?: string;
+    signature?: string | null | undefined;
+    timestamp?: string | null | undefined;
+    /**
+     * Skip the provider HMAC because the request was already authenticated by a trusted forwarder (Nango verifies
+     * the provider signature before forwarding with its own Nango signature). The caller MUST have verified the
+     * forwarder's signature first. (The url_verification handler still runs but is never reached via a forwarded
+     * event — Nango answers Slack's challenge itself during webhook setup.)
+     */
+    skipSignatureCheck?: boolean;
+    dedupe: TriggerDedupe;
+    lookupSubscriptions: (input: {
+        provider: string;
+        workspaceId?: string;
+        eventType: string;
+    }) => Promise<TriggerSubscription[]>;
+    enqueue: TriggerEnqueue;
+    mintRunId: () => string;
+    nowSec?: () => number;
+    maxSkewSec?: number;
+}
+type HandleTriggerResult = {
+    status: "challenge";
+    challenge: string;
+} | {
+    status: "rejected";
+    reason: string;
+} | {
+    status: "ignored";
+    reason: string;
+} | {
+    status: "enqueued";
+    runs: Array<{
+        runId: string;
+        agentSlug: string;
+    }>;
+    failed: number;
+};
+declare function handleTriggerEvent(provider: string, rawPayload: string, opts: HandleTriggerOpts): Promise<HandleTriggerResult>;
+
+/**
+ * Inbound reply → resume (spec §5.4): correlate an untrusted channel reply back to its `followupId` and resume
+ * the suspended run — EXACTLY ONCE, treating the reply as untrusted. Engine-wall clean; every side effect
+ * (transport dedupe, correlation, authz, the answer-once CAS, resume) is injected, so this stays hermetic.
+ */
+/** Strip quoted text / signatures and cap size — the reply is UNTRUSTED before it becomes `answer` (§5.4 step 4). */
+declare function sanitizeReply(raw: string, opts?: {
+    maxChars?: number;
+}): string;
+/** Pull the exact Slack correlation keys from a verified inbound message event: the reply's `thread_ts` equals
+ *  the ask's `delivery_ts` (each ask is its own top-level message — one reply ↔ one ask, §5.3). */
+declare function correlateSlackInbound(event: unknown): {
+    teamId: string;
+    channelId: string;
+    threadTs: string;
+    text: string;
+    userId: string;
+} | null;
+interface CorrelatedFollowup {
+    tenantId: string;
+    followupId: string;
+    runId: string;
+    toolCallId: string;
+    approverUserId: string;
+}
+interface InboundReplyInput {
+    provider: string;
+    externalId: string;
+    text: string;
+    /** Provider-VERIFIED replier identity (slack member id within team / verified email) — never raw `From`. */
+    replier: {
+        externalId: string;
+        teamId?: string;
+    };
+    /** Exact correlation keys (provider-specific), passed to `correlate`. */
+    correlation: Record<string, unknown>;
+}
+interface ResumeCtx {
+    tenantId: string;
+    userId: string;
+    agentSlug: string;
+    threadId: string;
+    runId: string;
+}
+interface HandleInboundOpts {
+    /** Atomic insert-or-false on (provider, external_id): true ⇒ NEW (proceed); false ⇒ retried event (ignore). */
+    recordInboundOnce: (key: {
+        provider: string;
+        externalId: string;
+    }) => Promise<boolean>;
+    /** Resolve the inbound reply to its pending followup via the exact delivery keys. Null ⇒ no match (ignore). */
+    correlate: (input: InboundReplyInput) => Promise<CorrelatedFollowup | null>;
+    /** Map the VERIFIED replier identity → an internal user (user_channel_identity, verified_at set). Null ⇒ deny. */
+    authorizeReplier: (input: {
+        tenantId: string;
+        provider: string;
+        replier: {
+            externalId: string;
+            teamId?: string;
+        };
+    }) => Promise<{
+        userId: string;
+    } | null>;
+    /** The answer-once CAS (storage.markFollowupAnswered): true ⇒ THIS call won (resume); false ⇒ already answered. */
+    answerOnce: (followupId: string, tenantId: string) => Promise<boolean>;
+    /** Reconstruct the run's SwarmContext from its row (as the resume route does). */
+    resolveContext: (corr: CorrelatedFollowup) => Promise<ResumeCtx>;
+    /** Durable resume — returns {runId}, never streams (a webhook can't drain a stream). */
+    resumeEnqueue: (args: {
+        runId: string;
+        toolCallId: string;
+        followupId: string;
+        answer: unknown;
+    }, ctx: ResumeCtx) => Promise<{
+        runId: string;
+    }>;
+    sanitize?: (raw: string) => string;
+}
+type HandleInboundResult = {
+    status: "resumed";
+    runId: string;
+} | {
+    status: "ignored";
+    reason: string;
+};
+/**
+ * The §5.4 pipeline: transport-dedupe → correlate → authz → sanitize → answer-once CAS → durable resume. NEVER
+ * resumes twice: two DISTINCT inbound events for one followup both pass dedupe + correlate, but only the CAS
+ * winner resumes (the loser is ignored). Returns a result for every path — the host ACKs 200 on `ignored`.
+ */
+declare function handleInboundReply(input: InboundReplyInput, opts: HandleInboundOpts): Promise<HandleInboundResult>;
+
+export { type BoundConnection, type ConnectionRef, type ConnectorActionContext, type ConnectorActionSpec, type ConnectorBackend, type ConnectorDef, type ConnectorEventSpec, type ConnectorTool, type CorrelatedFollowup, type DeliveryRef, type DeliveryRoute, type HandleInboundOpts, type HandleInboundResult, type HandleTriggerOpts, type HandleTriggerResult, type InboundReplyInput, type NangoBackendOpts, type NangoConnectionLookup, type NangoProxy, type NangoProxyRequest, type ProxyRequest, type QuestionDelivery, type QuestionToDeliver, type ResolvedNangoConnection, type ResumeCtx, type StaticBackendOpts, type StaticConnection, type TriggerDedupe, type TriggerEnqueue, type TriggerSubscription, correlateSlackInbound, defineConnector, emailConnector, emailQuestionDelivery, escapeSlackText, fenceConnectorOutput, handleInboundReply, handleTriggerEvent, linearConnector, materializeConnectors, mintReplyToken, nangoBackend, parseReplyToken, renderSlackQuestion, sanitizeReply, slackConnector, slackQuestionDelivery, staticBackend, verifyInboundEmailSignature, verifyLinearSignature, verifyReplyToken, verifySlackSignature };