Connector SDK#

A connector (adapter) is the last line of defense: it is the component that actually performs an approved action against a downstream system, and it refuses to act unless the Authority Token verifies. You build one by extending BaseAdapter from @intended/connector-sdk and implementing a single method, executeAction. The base class does the security-critical work — token verification with kid pinning, tenant/adapter/target binding, expiry, and single-use nonce consumption — and it is fail-closed: if any check fails, your executeAction is never called.

The validation pipeline#

When the runtime dispatches an approved action, it hands your adapter a ConnectorEnvelope containing the authorityToken. BaseAdapter.execute() runs this pipeline before any action logic:

Validation runs before execution. Any failed check returns a rejected ExecutionResult and the downstream system is never touched.

Build a connector#

Extend BaseAdapter, provide a _manifest, and implement executeAction. The base class hands you the already-validated claims, so your code only contains system-specific logic.

import {
  BaseAdapter,
  type ConnectorEnvelope,
  type ConnectorManifest,
  type ExecutionResult,
} from "@intended/connector-sdk";
import type { AuthorityDecisionTokenClaims } from "@intended/contracts";

export class GithubActionsAdapter extends BaseAdapter {
  protected readonly _manifest: ConnectorManifest = {
    id: "github-actions-adapter",
    name: "GitHub Actions",
    version: "1.0.0",
    description: "Dispatches GitHub Actions workflows and opens PRs.",
    // Action patterns are {system}.{entity}.{verb}, lowercase + hyphens.
    capabilities: ["github.workflow.dispatch", "github.pull-request.create"],
    supportedAuthMethods: ["github-app", "pat"],
    status: "active",
  };

  // Called ONLY after BaseAdapter has fully validated the token.
  protected async executeAction(
    envelope: ConnectorEnvelope,
    claims: AuthorityDecisionTokenClaims,
  ): Promise<ExecutionResult> {
    // claims.adapterTarget is the verified target, e.g. "acme/platform-api".
    const remote = await this.dispatchWorkflow(envelope.payload, claims.adapterTarget);

    return {
      adapterId: this._manifest.id,
      attempted: true,
      status: "executed",
      reason: "workflow dispatched",
      executionTarget: claims.adapterTarget,
      remoteStatusCode: remote.status,
      validatedClaims: claims,
      data: { runId: remote.runId },
    };
  }

  private async dispatchWorkflow(_payload: unknown, _target: string) {
    // ... your GitHub API call here ...
    return { status: 204, runId: "run_123" };
  }
}

Manifest fields (ConnectorManifestSchema)#

Envelope fields (ConnectorEnvelopeSchema)#

Register the connector#

Register adapters in an AdapterRegistry. The registry refuses to silently overwrite an existing id and is what the execution engine looks up by adapterId.

import { AdapterRegistry } from "@intended/connector-sdk";

const registry = new AdapterRegistry();
registry.register(new GithubActionsAdapter());

// Look up by id (fail closed: get() returns undefined when missing).
const adapter = registry.getOrThrow("github-actions-adapter");
const result = await adapter.execute(envelope);

if (result.status !== "executed") {
  // result.reason is the failure code, e.g. TOKEN_EXPIRED or a nonce-replay reason.
}

AdapterRegistry also exposes get, listIds, listManifests, testConnection(adapterId, tenantId), and testAllConnections(tenantId).

Execution outcomes#

executeAction returns an ExecutionResult. The base class also synthesizes one on a failed validation or a thrown error.

Validation-failure reasons surfaced as reason on a rejected result include TOKEN_TENANT_MISMATCH, TOKEN_ADAPTER_MISMATCH, TOKEN_ADAPTER_TARGET_MISMATCH, TOKEN_DECISION_INVALID, TOKEN_EXPIRED, and the nonce-replay reason returned by consumeAuthorityTokenNonce. A thrown executeAction is caught and returned as rejected rather than propagating — the connector never half-executes on an error.

testConnection

BaseAdapter provides a default testConnection that reports the adapter as reachable. Override it with a real health check against your downstream system:

async testConnection(tenantId: string) {
  const start = Date.now();
  const ok = await this.ping();
  return {
    adapterId: this._manifest.id,
    reachable: ok,
    latencyMs: Date.now() - start,
  };
}

Next steps#

• Verify Decision Tokens — the verification the base class performs.
• Enforcement SDK — drive intents and verification from your app.
• Error Patterns — runtime error codes and remediation. </content>