@zackbart/connecta 0.15.1 → 0.16.1

package/examples/node/README.md

@@ -1,52 +0,0 @@
-# connecta — Node repository example
-
-This example runs against the current package source. For an independently
-installable deployment, use the root initializer instead:
-
-```sh
-npx @zackbart/connecta init my-connecta
-```
-
-From the package repository, run this example with:
-
-```sh
-npm install
-CONNECTA_TOKEN=dev-token npx tsx examples/node/src/index.ts
-```
-
-It serves the prescribed seven-tool code-first surface: `execute_code` in a
-bounded QuickJS child plus the six explicit boundary tools.
-
-- MCP endpoint: `http://localhost:8787/mcp`, with
-  `Authorization: Bearer dev-token`
-- Operator pages: Connections at `http://localhost:8787/`, Credentials at
-  `/credentials`, and Activity at `/activity` (paste the same token; this
-  bearer-only example cannot manage credentials)
-- Health: `http://localhost:8787/health`
-
-`PORT` defaults to `8787`; `CONNECTA_TOKEN` is required. Use a long random
-value outside this local example.
-
-## The deployment contract
-
-Keep this deployment small:
-
-- Edit `src/index.ts` to change connectors, auth, storage, and the public URL.
-- Keep the required `executor: quickJsExecutor()` configuration.
-- Keep secrets in environment variables or an external secret store. Never put
-  tokens in `src/index.ts`, connector guides, or committed JSON.
-- Add application code only when implementing a deliberate `api()` connector.
-  Do not copy Connecta internals into the deployment.
-- Run the repository's `npm run check` after a package change.
-
-`fileStorage("./.connecta-state.json")` persists downstream OAuth tokens and
-tool catalogs across restarts. `memoryStorage()` is sufficient only when the
-deployment needs neither. Add `remoteMcp(...)` entries for downstream MCP
-servers or `api(...)` connectors for HTTP APIs you deliberately expose.
-Downstream OAuth also requires `publicUrl` to be an origin the browser can
-reach.
-
-Docker packaging of the same code-first shape is
-[repository-only](https://github.com/zackbart/connecta/tree/main/examples/docker).
-The standalone template used by the initializer is in
-[`../../templates/node/`](../../templates/node/).

package/examples/node/src/index.ts

@@ -1,71 +0,0 @@
-/**
- * connecta on Node.
- *
- * One MCP endpoint aggregating two in-code HTTP API connectors behind the
- * seven-tool code-first surface (execute_code in a QuickJS/WASM sandbox plus the
- * six explicit tools), guarded by a static bearer token, with OAuth/cache state
- * on disk.
- *
- * Run:
- *   CONNECTA_TOKEN=dev-token npx tsx examples/node/src/index.ts
- *   # then point an MCP client at http://localhost:8787/mcp with
- *   #   Authorization: Bearer dev-token
- */
-import { api, bearerToken, createConnecta } from "@zackbart/connecta";
-import { fileStorage, listen } from "@zackbart/connecta/node";
-import { quickJsExecutor } from "@zackbart/connecta/quickjs";
-
-const token = process.env.CONNECTA_TOKEN;
-if (!token) {
-  throw new Error(
-    "CONNECTA_TOKEN is required. Refusing to start without inbound auth.",
-  );
-}
-const port = Number(process.env.PORT ?? 8787);
-
-const connecta = createConnecta({
-  // fileStorage persists downstream-OAuth/cache state across restarts.
-  // Swap for memoryStorage() if you don't need persistence.
-  storage: fileStorage("./.connecta-state.json"),
-  auth: bearerToken(token, { subjectId: "operator" }),
-  // Downstream OAuth callbacks use this deployment origin.
-  publicUrl: `http://localhost:${port}`,
-  // Required: QuickJS runs model-written JS in a bounded disposable child.
-  executor: quickJsExecutor(),
-  connectors: [
-    api("time", {
-      description: "Time — current timestamp",
-      tools: [
-        {
-          name: "get_now",
-          description: "Return the current time as an ISO 8601 timestamp.",
-          inputSchema: { type: "object", properties: {} },
-          annotations: { readOnlyHint: true },
-          handler: async () => ({ now: new Date().toISOString() }),
-        },
-      ],
-    }),
-    api("text", {
-      description: "Text — string utilities",
-      tools: [
-        {
-          name: "upper",
-          description: "Uppercase the given text.",
-          inputSchema: {
-            type: "object",
-            properties: { text: { type: "string" } },
-            required: ["text"],
-          },
-          annotations: { readOnlyHint: true },
-          handler: async ({ text }: { text: string }) => ({
-            text: text.toUpperCase(),
-          }),
-        },
-      ],
-    }),
-  ],
-});
-
-listen(connecta, port);
-
-console.log(`connecta listening on http://localhost:${port}/mcp`);

package/src/access-tokens.ts

@@ -1,289 +0,0 @@
-import type { AuthResult, InboundAuth, KVStorage } from "./types.js";
-
-const TOKEN_PREFIX = "cta_";
-const TOKEN_BYTES = 32;
-const TOKEN_VALUE_RE = /^cta_[A-Za-z0-9_-]{43}$/;
-const RECORD_PREFIX = "access-token:v1:record:";
-const LOOKUP_PREFIX = "access-token:v1:lookup:";
-const MAX_NAME_CHARACTERS = 80;
-const DEFAULT_MAX_ACTIVE = 100;
-const MAX_CONFIGURED_ACTIVE = 1_000;
-const encoder = new TextEncoder();
-
-interface StoredAccessToken {
-  version: 1;
-  id: string;
-  name: string;
-  tokenHash: string;
-  tokenPrefix: string;
-  createdAt: string;
-  createdBy: string;
-  revokedAt?: string;
-  revokedBy?: string;
-}
-
-interface TokenLookup {
-  version: 1;
-  id: string;
-}
-
-export interface AccessTokenMetadata {
-  id: string;
-  name: string;
-  tokenPrefix: string;
-  createdAt: string;
-  revokedAt?: string;
-}
-
-export interface CreatedAccessToken {
-  token: string;
-  accessToken: AccessTokenMetadata;
-}
-
-function recordKey(id: string): string {
-  return `${RECORD_PREFIX}${id}`;
-}
-
-function lookupKey(hash: string): string {
-  return `${LOOKUP_PREFIX}${hash}`;
-}
-
-function bytesToBase64Url(bytes: Uint8Array): string {
-  let binary = "";
-  for (const byte of bytes) binary += String.fromCharCode(byte);
-  return btoa(binary)
-    .replaceAll("+", "-")
-    .replaceAll("/", "_")
-    .replace(/=+$/u, "");
-}
-
-function bytesToHex(bytes: Uint8Array): string {
-  return [...bytes]
-    .map((byte) => byte.toString(16).padStart(2, "0"))
-    .join("");
-}
-
-async function hashToken(token: string): Promise<string> {
-  return bytesToHex(
-    new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(token))),
-  );
-}
-
-function normalizeName(value: unknown): string {
-  if (typeof value !== "string") {
-    throw new Error("Token name must be a string");
-  }
-  const compact = value.replace(/\s+/gu, " ").trim();
-  if (!compact) throw new Error("Token name cannot be empty");
-  if (Array.from(compact).length > MAX_NAME_CHARACTERS) {
-    throw new Error(
-      `Token name cannot exceed ${MAX_NAME_CHARACTERS} characters`,
-    );
-  }
-  return compact;
-}
-
-function parseRecord(raw: string): StoredAccessToken {
-  try {
-    const value = JSON.parse(raw) as Partial<StoredAccessToken>;
-    if (
-      value.version !== 1 ||
-      typeof value.id !== "string" ||
-      !/^[0-9a-f-]{36}$/u.test(value.id) ||
-      typeof value.name !== "string" ||
-      typeof value.tokenHash !== "string" ||
-      !/^[0-9a-f]{64}$/u.test(value.tokenHash) ||
-      typeof value.tokenPrefix !== "string" ||
-      typeof value.createdAt !== "string" ||
-      typeof value.createdBy !== "string" ||
-      (value.revokedAt !== undefined &&
-        typeof value.revokedAt !== "string") ||
-      (value.revokedBy !== undefined &&
-        typeof value.revokedBy !== "string")
-    ) {
-      throw new Error("invalid token record");
-    }
-    return value as StoredAccessToken;
-  } catch {
-    throw new Error("Stored access token metadata is invalid or corrupted");
-  }
-}
-
-function parseLookup(raw: string): TokenLookup | null {
-  try {
-    const value = JSON.parse(raw) as Partial<TokenLookup>;
-    return value.version === 1 && typeof value.id === "string"
-      ? { version: 1, id: value.id }
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-function metadata(record: StoredAccessToken): AccessTokenMetadata {
-  return {
-    id: record.id,
-    name: record.name,
-    tokenPrefix: record.tokenPrefix,
-    createdAt: record.createdAt,
-    ...(record.revokedAt ? { revokedAt: record.revokedAt } : {}),
-  };
-}
-
-function unauthorized(): AuthResult {
-  return {
-    ok: false,
-    response: new Response(JSON.stringify({ error: "unauthorized" }), {
-      status: 401,
-      headers: {
-        "Content-Type": "application/json",
-        "WWW-Authenticate": "Bearer",
-      },
-    }),
-  };
-}
-
-/**
- * Deployment-scoped personal access tokens. Secret material is never
- * recoverable: authentication indexes a SHA-256 digest of a random 256-bit
- * token, while separately enumerable metadata powers operator management.
- */
-export class AccessTokenManager {
-  readonly auth: InboundAuth;
-  private readonly maxActive: number;
-
-  constructor(
-    private readonly storage: KVStorage,
-    options: { maxActive?: number } = {},
-  ) {
-    if (!storage.list) {
-      throw new Error(
-        "accessTokens requires a storage adapter that implements list(prefix)",
-      );
-    }
-    const maxActive = options.maxActive ?? DEFAULT_MAX_ACTIVE;
-    if (
-      !Number.isInteger(maxActive) ||
-      maxActive < 1 ||
-      maxActive > MAX_CONFIGURED_ACTIVE
-    ) {
-      throw new Error(
-        `accessTokens.maxActive must be a whole number from 1 to ${MAX_CONFIGURED_ACTIVE}`,
-      );
-    }
-    this.maxActive = maxActive;
-    this.auth = {
-      kind: "access_token",
-      activityActorNamespace: "connecta:access-tokens:v1",
-      activityActorLabel: async (id) => {
-        try {
-          return (await this.read(id))?.name;
-        } catch {
-          return undefined;
-        }
-      },
-      authorize: (request) => this.authorize(request),
-    };
-  }
-
-  private async read(id: string): Promise<StoredAccessToken | null> {
-    const raw = await this.storage.get(recordKey(id));
-    return raw ? parseRecord(raw) : null;
-  }
-
-  async list(): Promise<AccessTokenMetadata[]> {
-    const keys = await this.storage.list!(RECORD_PREFIX);
-    const records = await Promise.all(
-      keys.map(async (key) => {
-        const raw = await this.storage.get(key);
-        return raw ? parseRecord(raw) : null;
-      }),
-    );
-    return records
-      .filter((record): record is StoredAccessToken => Boolean(record))
-      .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
-      .map(metadata);
-  }
-
-  async create(name: unknown, createdBy: string): Promise<CreatedAccessToken> {
-    const normalizedName = normalizeName(name);
-    const active = (await this.list()).filter((token) => !token.revokedAt);
-    if (active.length >= this.maxActive) {
-      throw new Error(
-        `This deployment already has the maximum of ${this.maxActive} active access tokens`,
-      );
-    }
-    const secretBytes = crypto.getRandomValues(new Uint8Array(TOKEN_BYTES));
-    const token = TOKEN_PREFIX + bytesToBase64Url(secretBytes);
-    const hash = await hashToken(token);
-    if (await this.storage.get(lookupKey(hash))) {
-      throw new Error("Access token collision; create another token");
-    }
-    const record: StoredAccessToken = {
-      version: 1,
-      id: crypto.randomUUID(),
-      name: normalizedName,
-      tokenHash: hash,
-      tokenPrefix: token.slice(0, 12),
-      createdAt: new Date().toISOString(),
-      createdBy,
-    };
-    await this.storage.set(recordKey(record.id), JSON.stringify(record));
-    try {
-      await this.storage.set(
-        lookupKey(hash),
-        JSON.stringify({ version: 1, id: record.id } satisfies TokenLookup),
-      );
-    } catch (error) {
-      await this.storage.delete(recordKey(record.id)).catch(() => {});
-      throw error;
-    }
-    return { token, accessToken: metadata(record) };
-  }
-
-  async rename(
-    id: string,
-    name: unknown,
-  ): Promise<AccessTokenMetadata | null> {
-    const record = await this.read(id);
-    if (!record) return null;
-    record.name = normalizeName(name);
-    await this.storage.set(recordKey(id), JSON.stringify(record));
-    return metadata(record);
-  }
-
-  async revoke(
-    id: string,
-    revokedBy: string,
-  ): Promise<AccessTokenMetadata | null> {
-    const record = await this.read(id);
-    if (!record) return null;
-    if (!record.revokedAt) {
-      // Admission disappears first. A metadata-write failure may leave the UI
-      // calling the record active, but can never leave a token labelled
-      // revoked while its lookup still admits requests.
-      await this.storage.delete(lookupKey(record.tokenHash));
-      record.revokedAt = new Date().toISOString();
-      record.revokedBy = revokedBy;
-      await this.storage.set(recordKey(id), JSON.stringify(record));
-    }
-    return metadata(record);
-  }
-
-  private async authorize(request: Request): Promise<AuthResult> {
-    const header = request.headers.get("authorization") ?? "";
-    const match = /^Bearer\s+(.+)$/iu.exec(header);
-    const token = match?.[1];
-    if (!token || !TOKEN_VALUE_RE.test(token)) return unauthorized();
-    const hash = await hashToken(token);
-    const lookupRaw = await this.storage.get(lookupKey(hash));
-    if (!lookupRaw) return unauthorized();
-    const lookup = parseLookup(lookupRaw);
-    if (!lookup) return unauthorized();
-    const record = await this.read(lookup.id);
-    if (!record || record.revokedAt || record.tokenHash !== hash) {
-      return unauthorized();
-    }
-    return { ok: true, subjectId: record.id };
-  }
-}

package/src/activity.ts

@@ -1,234 +0,0 @@
-import { boundedEchoText } from "./errors.js";
-import type { Logger } from "./types.js";
-
-/**
- * How long an identity field may be before the store stops believing it.
- *
- * `connectorId` and `toolName` are ordinarily operator- and connector-authored,
- * and 128 bytes is far past any real one. But an address that resolved to
- * nothing is recorded *as written*, which puts a caller-authored string in both
- * fields — and "payload-free by construction" has to mean the event type has
- * nowhere to put a payload, not merely that connecta declines to. A 40 KB
- * invented connector id is a payload wearing an id's clothing.
- *
- * Clamped rather than dropped: the invented id is precisely what an operator
- * needs to see, and its first 128 bytes identify the mistake as well as all
- * 40,000 would. The `…` marker keeps a clamped value from reading as a real one.
- */
-const MAX_ACTIVITY_NAME_BYTES = 128;
-
-/** Two names and the dot between them. */
-const MAX_ACTIVITY_ADDRESS_BYTES = MAX_ACTIVITY_NAME_BYTES * 2 + 1;
-
-export type ActivityCallSource =
-  | "call_tool"
-  | "call_destructive_tool"
-  // Read-only history. Nothing emits `batch_call` since issue #273 removed the
-  // tool, but activity storage is append-only: rows written by older
-  // deployments are still read back — the D1 example maps a stored row straight
-  // into this type — and an operator's timeline should not have to lie about
-  // where a call came from. Never widen this member back into a live source.
-  | "batch_call"
-  | "execute_code";
-
-export type ActivityOutcome =
-  | "success"
-  | "error"
-  | "timeout"
-  | "cancelled";
-
-export type AgentFriction =
-  | "tool_not_found"
-  | "schema_retry"
-  | "destructive_reroute"
-  | "auth_required"
-  | "result_too_large";
-
-/** Coarse recovery class derived without inspecting payloads or error prose. */
-export function agentFrictionForCode(
-  code: string | undefined,
-): AgentFriction | undefined {
-  switch (code) {
-    case "unknown_address":
-    case "unknown_tool":
-    case "ambiguous_tool_alias":
-      return "tool_not_found";
-    case "invalid_args":
-      return "schema_retry";
-    case "destructive_tool_requires_approval":
-      return "destructive_reroute";
-    case "auth_required":
-      return "auth_required";
-    case "result_too_large":
-      return "result_too_large";
-    default:
-      return undefined;
-  }
-}
-
-/**
- * Authenticated identity attached to an activity event. `id` is intentionally
- * optional: open deployments and shared bearer tokens cannot honestly identify
- * a person.
- */
-export interface ActivityActor {
-  kind: string;
-  id?: string;
-  /**
-   * Stable, non-secret identity-directory namespace supplied by the admitting
-   * auth provider. It lets authorized reads resolve ids through the same
-   * provider rather than another provider that happens to share `kind`.
-   */
-  namespace?: string;
-}
-
-/**
- * Privacy-minimal history of one resolved downstream connector call.
- *
- * Arguments, results, generated code, search text, and raw errors are excluded
- * by construction. Deployments that need a safe human summary can add a
- * separate, explicit connector-level feature later.
- */
-export interface ToolCallActivityEvent {
-  schemaVersion: 1;
-  id: string;
-  occurredAt: string;
-  requestId: string;
-  actor: ActivityActor;
-  connectorId: string;
-  toolName: string;
-  address: string;
-  source: ActivityCallSource;
-  outcome: ActivityOutcome;
-  durationMs: number;
-  attempts: number;
-  /** Set only when the call actually failed; a truncated success has none. */
-  errorCode?: string;
-  /**
-   * Payload-free recovery class. Usually derived from `errorCode`, but it can
-   * also stand alone: a result too large to return inline is friction for the
-   * agent while remaining an `outcome: "success"` call with no error code.
-   */
-  friction?: AgentFriction;
-  serverName: string;
-  serverVersion: string;
-  deploymentId?: string;
-}
-
-export interface ActivityPage {
-  events: ToolCallActivityEvent[];
-  nextCursor?: string;
-}
-
-/** Display-only actor returned by the authenticated activity read API. */
-export interface ActivityReadActor extends ActivityActor {
-  label?: string;
-}
-
-export type ActivityReadEvent = Omit<ToolCallActivityEvent, "actor"> & {
-  actor: ActivityReadActor;
-};
-
-export interface ActivityReadPage {
-  events: ActivityReadEvent[];
-  nextCursor?: string;
-}
-
-/** Write-only deployments can implement only this small, vendor-neutral seam. */
-export interface ActivitySink {
-  record(event: ToolCallActivityEvent): void | Promise<void>;
-}
-
-/** Optional read side used by Connecta's authenticated Activity UI. */
-export interface ActivityReader {
-  list(options: { cursor?: string; limit: number }): Promise<ActivityPage>;
-}
-
-export interface ActivityStore extends ActivitySink {
-  list?: ActivityReader["list"];
-}
-
-/** Reader implementations throw this for an opaque cursor they cannot decode. */
-export class InvalidActivityCursorError extends Error {
-  override name = "InvalidActivityCursorError";
-
-  constructor() {
-    super("invalid activity cursor");
-  }
-}
-
-export type ActivityReadGate = (
-  actor: ActivityActor,
-) => boolean | Promise<boolean>;
-
-/** Request-scoped context shared by direct, batch, and code-mode call paths. */
-export interface ActivityRequestContext {
-  sink: ActivitySink;
-  actor: ActivityActor;
-  requestId: string;
-  serverInfo: { name: string; version: string };
-  deploymentId?: string;
-  defer?: (promise: Promise<unknown>) => void;
-  logger: Logger;
-}
-
-export type ActivityEventInput = Pick<
-  ToolCallActivityEvent,
-  | "connectorId"
-  | "toolName"
-  | "address"
-  | "source"
-  | "outcome"
-  | "durationMs"
-  | "attempts"
-  | "errorCode"
-  | "friction"
->;
-
-/**
- * Best-effort by design: activity storage can never change a tool result.
- * Workers attach async sinks to waitUntil; synchronous sinks such as Analytics
- * Engine complete inline; Node promises remain detached from the response.
- */
-export function recordToolActivity(
-  context: ActivityRequestContext | undefined,
-  input: ActivityEventInput,
-): void {
-  if (!context) return;
-  // A caller-supplied class wins because it knows something the code table
-  // cannot: friction that belongs to a call which did not fail.
-  const friction = input.friction ?? agentFrictionForCode(input.errorCode);
-  const event: ToolCallActivityEvent = {
-    schemaVersion: 1,
-    id: crypto.randomUUID(),
-    occurredAt: new Date().toISOString(),
-    requestId: context.requestId,
-    actor: context.actor,
-    connectorId: boundedEchoText(input.connectorId, MAX_ACTIVITY_NAME_BYTES),
-    toolName: boundedEchoText(input.toolName, MAX_ACTIVITY_NAME_BYTES),
-    address: boundedEchoText(input.address, MAX_ACTIVITY_ADDRESS_BYTES),
-    source: input.source,
-    outcome: input.outcome,
-    durationMs: Math.max(0, Math.trunc(input.durationMs)),
-    attempts: Math.max(1, Math.trunc(input.attempts)),
-    ...(input.errorCode ? { errorCode: input.errorCode } : {}),
-    ...(friction ? { friction } : {}),
-    serverName: context.serverInfo.name,
-    serverVersion: context.serverInfo.version,
-    ...(context.deploymentId
-      ? { deploymentId: context.deploymentId }
-      : {}),
-  };
-  try {
-    const result = context.sink.record(event);
-    if (!result || typeof (result as Promise<unknown>).then !== "function") {
-      return;
-    }
-    const pending = Promise.resolve(result).catch((error) => {
-      context.logger.warn("[connecta] activity record failed", error);
-    });
-    if (context.defer) context.defer(pending);
-  } catch (error) {
-    context.logger.warn("[connecta] activity record failed", error);
-  }
-}