@frockbot/connection-core 0.0.0 → 0.1.0

package/package.json

@@ -1,14 +1,26 @@
 {
   "name": "@frockbot/connection-core",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.6",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/connection-core"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/authorization-state.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeAuthorizationState,
+  encodeAuthorizationState,
+  isStrongAuthorizationStateSecretV1,
+  type AuthorizationState,
+} from "./authorization-state.js";
+
+const SECRET = "an-independent-random-secret-0123456789";
+
+function state(
+  overrides: Partial<AuthorizationState> = {},
+): AuthorizationState {
+  return {
+    schemaVersion: 1,
+    authorizationStateId: "state-1",
+    userId: "user-1",
+    connectionId: "mcp-1",
+    returnTarget: "browser",
+    expiresAt: Date.now() + 600_000,
+    ...overrides,
+  };
+}
+
+describe("the signed callback state", () => {
+  test("round-trips, and the payload is the identity a callback acts as", async () => {
+    const encoded = await encodeAuthorizationState(state(), SECRET);
+    expect(await decodeAuthorizationState(encoded, SECRET)).toMatchObject({
+      userId: "user-1",
+      connectionId: "mcp-1",
+      authorizationStateId: "state-1",
+    });
+  });
+
+  test("keeps the wire format it had inside plugin-composio", async () => {
+    // Two base64url segments joined by a dot: a state minted before the move
+    // to `connection-core` must still verify after it.
+    const encoded = await encodeAuthorizationState(state(), SECRET);
+    const [payload, signature, extra] = encoded.split(".");
+    expect(extra).toBeUndefined();
+    expect(payload).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(signature).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(
+      JSON.parse(atob(payload!.replaceAll("-", "+").replaceAll("_", "/"))),
+    ).toMatchObject({ schemaVersion: 1, userId: "user-1" });
+  });
+
+  test("refuses a tampered payload", async () => {
+    const encoded = await encodeAuthorizationState(state(), SECRET);
+    const [payload, signature] = encoded.split(".");
+    const forged = JSON.stringify({ ...state(), userId: "user-2" });
+    const swapped = btoa(forged)
+      .replaceAll("+", "-")
+      .replaceAll("/", "_")
+      .replace(/=+$/, "");
+    expect(swapped).not.toBe(payload);
+    await expect(
+      decodeAuthorizationState(`${swapped}.${signature}`, SECRET),
+    ).rejects.toThrow(/invalid/);
+  });
+
+  test("refuses a state signed with another secret", async () => {
+    const encoded = await encodeAuthorizationState(state(), SECRET);
+    await expect(
+      decodeAuthorizationState(encoded, `${SECRET}-other`),
+    ).rejects.toThrow(/invalid/);
+  });
+
+  test("refuses an expired state", async () => {
+    const encoded = await encodeAuthorizationState(
+      state({ expiresAt: Date.now() - 1 }),
+      SECRET,
+    );
+    await expect(decodeAuthorizationState(encoded, SECRET)).rejects.toThrow(
+      /expired/,
+    );
+  });
+
+  test("refuses a malformed token rather than reading half of one", async () => {
+    for (const value of ["", "a", "a.b.c", "..", "not-base64url!.x"]) {
+      await expect(decodeAuthorizationState(value, SECRET)).rejects.toThrow();
+    }
+  });
+});
+
+describe("the secret strength check", () => {
+  test("refuses short, repeated, and placeholder secrets", () => {
+    expect(isStrongAuthorizationStateSecretV1("short")).toBe(false);
+    expect(isStrongAuthorizationStateSecretV1("ab".repeat(32))).toBe(false);
+    expect(isStrongAuthorizationStateSecretV1("a".repeat(64))).toBe(false);
+    expect(
+      isStrongAuthorizationStateSecretV1(
+        "replace-with-an-independent-random-secret",
+      ),
+    ).toBe(false);
+  });
+
+  test("accepts an independent random secret", () => {
+    expect(isStrongAuthorizationStateSecretV1(SECRET)).toBe(true);
+  });
+});

package/src/authorization-state.ts

@@ -0,0 +1,153 @@
+/**
+ * The signed `state` a redirect-based Connection carries through an external
+ * authorization server and back.
+ *
+ * This is the *only* identity a callback has. A `publicRoute` runs before the
+ * gateway has authenticated anyone — an authorization server redirects the
+ * User's browser to it with whatever query it likes — so the User the callback
+ * acts as is read from this token's verified payload and from nowhere else.
+ * Query parameters are data; the HMAC is the authority.
+ *
+ * It began inside `plugin-composio`. Two Packages now mint one, so it lives in
+ * `connection-core` where both can reach it. The wire format is byte-for-byte
+ * what Composio emitted, so a state minted before this move still verifies
+ * after it: `base64url(JSON payload).base64url(HMAC-SHA-256)`.
+ */
+
+/** A public identifier, as `@frockbot/configuration-core` defines one. */
+const PUBLIC_IDENTIFIER_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+
+function isIdentifier(value: unknown): value is string {
+  return typeof value === "string" && PUBLIC_IDENTIFIER_PATTERN.test(value);
+}
+
+export interface AuthorizationState {
+  schemaVersion: 1;
+  authorizationStateId: string;
+  userId: string;
+  connectionId: string;
+  returnTarget: "browser" | "desktop";
+  expiresAt: number;
+  nativeReturnNonce?: string;
+}
+
+const MINIMUM_AUTHORIZATION_STATE_SECRET_LENGTH = 32;
+const MINIMUM_AUTHORIZATION_STATE_SECRET_UNIQUE_CHARACTERS = 8;
+const FORBIDDEN_AUTHORIZATION_STATE_SECRETS = new Set([
+  "replace-with-an-independent-random-secret",
+]);
+
+function isRepeatedAuthorizationStateSecret(secret: string): boolean {
+  for (
+    let patternLength = 1;
+    patternLength <= Math.min(16, Math.floor(secret.length / 2));
+    patternLength += 1
+  ) {
+    if (
+      secret.length % patternLength === 0 &&
+      secret ===
+        secret.slice(0, patternLength).repeat(secret.length / patternLength)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a configured secret is strong enough to sign a callback identity
+ * with. A short, repeated, or placeholder secret is refused at configuration
+ * time rather than trusted at callback time.
+ */
+export function isStrongAuthorizationStateSecretV1(secret: string): boolean {
+  return (
+    secret.length >= MINIMUM_AUTHORIZATION_STATE_SECRET_LENGTH &&
+    new Set(secret).size >=
+      MINIMUM_AUTHORIZATION_STATE_SECRET_UNIQUE_CHARACTERS &&
+    !FORBIDDEN_AUTHORIZATION_STATE_SECRETS.has(secret) &&
+    !isRepeatedAuthorizationStateSecret(secret)
+  );
+}
+
+export function base64UrlEncodeV1(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/, "");
+}
+
+export function base64UrlDecodeV1(value: string): Uint8Array {
+  const padded = value.replaceAll("-", "+").replaceAll("_", "/");
+  const binary = atob(padded.padEnd(Math.ceil(padded.length / 4) * 4, "="));
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+async function stateKey(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"],
+  );
+}
+
+export async function encodeAuthorizationState(
+  state: AuthorizationState,
+  secret: string,
+): Promise<string> {
+  const payload = new TextEncoder().encode(JSON.stringify(state));
+  const signature = new Uint8Array(
+    await crypto.subtle.sign("HMAC", await stateKey(secret), payload),
+  );
+  return `${base64UrlEncodeV1(payload)}.${base64UrlEncodeV1(signature)}`;
+}
+
+export async function decodeAuthorizationState(
+  value: string,
+  secret: string,
+  now: number = Date.now(),
+): Promise<AuthorizationState> {
+  const [payloadPart, signaturePart, extra] = value.split(".");
+  if (!payloadPart || !signaturePart || extra !== undefined) {
+    throw new Error("Connection authorization state is invalid");
+  }
+  const payload = base64UrlDecodeV1(payloadPart);
+  const signature = base64UrlDecodeV1(signaturePart);
+  if (
+    !(await crypto.subtle.verify(
+      "HMAC",
+      await stateKey(secret),
+      new Uint8Array(signature).buffer,
+      new Uint8Array(payload).buffer,
+    ))
+  ) {
+    throw new Error("Connection authorization state is invalid");
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(new TextDecoder().decode(payload));
+  } catch {
+    throw new Error("Connection authorization state is invalid");
+  }
+  if (!decoded || typeof decoded !== "object") {
+    throw new Error("Connection authorization state is invalid");
+  }
+  const state = decoded as Partial<AuthorizationState>;
+  if (
+    state.schemaVersion !== 1 ||
+    !isIdentifier(state.authorizationStateId) ||
+    !isIdentifier(state.userId) ||
+    !isIdentifier(state.connectionId) ||
+    (state.returnTarget !== "browser" && state.returnTarget !== "desktop") ||
+    !Number.isSafeInteger(state.expiresAt) ||
+    (state.expiresAt as number) <= now ||
+    (state.nativeReturnNonce !== undefined &&
+      !isIdentifier(state.nativeReturnNonce))
+  ) {
+    throw new Error("Connection authorization state is invalid or expired");
+  }
+  return state as AuthorizationState;
+}

package/src/credentials.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeCredentialLeaseV1,
+  openCredentialV1,
+  parseCredentialKeyringV1,
+  sealCredentialV1,
+} from "./credentials.js";
+
+const key = Uint8Array.from({ length: 32 }, (_, index) => index + 1);
+let binary = "";
+for (const byte of key) binary += String.fromCharCode(byte);
+const encoded = btoa(binary)
+  .replaceAll("+", "-")
+  .replaceAll("/", "_")
+  .replace(/=+$/, "");
+
+const keyring = parseCredentialKeyringV1(
+  JSON.stringify({
+    schemaVersion: 1,
+    currentKeyId: "2026-08",
+    keys: { "2026-08": encoded },
+  }),
+);
+const context = {
+  accountId: "account-1",
+  connectionId: "connection-1",
+  packageId: "provider-ollama-cloud",
+  credentialGeneration: "generation-1",
+};
+
+describe("Connection credential envelopes", () => {
+  test("requires the current key to be an own keyring entry", () => {
+    expect(() =>
+      parseCredentialKeyringV1(
+        JSON.stringify({
+          schemaVersion: 1,
+          currentKeyId: "toString",
+          keys: { primary: encoded },
+        }),
+      ),
+    ).toThrow("credential keyring current key is unavailable");
+  });
+
+  test("round-trips a secret without placing plaintext in the envelope", async () => {
+    const envelope = await sealCredentialV1({
+      keyring,
+      context,
+      plaintext: "ollama-secret",
+      createdAt: "2026-08-30T00:00:00.000Z",
+      randomBytes: () => new Uint8Array(12).fill(7),
+    });
+
+    expect(JSON.stringify(envelope)).not.toContain("ollama-secret");
+    expect(await openCredentialV1({ keyring, context, envelope })).toBe(
+      "ollama-secret",
+    );
+  });
+
+  test("authenticates Connection ownership context", async () => {
+    const envelope = await sealCredentialV1({
+      keyring,
+      context,
+      plaintext: "ollama-secret",
+    });
+
+    await expect(
+      openCredentialV1({
+        keyring,
+        envelope,
+        context: { ...context, accountId: "another-account" },
+      }),
+    ).rejects.toThrow("credential envelope authentication failed");
+  });
+
+  test("decodes exact versioned credential leases at RPC seams", async () => {
+    const envelope = await sealCredentialV1({
+      keyring,
+      context,
+      plaintext: "ollama-secret",
+      createdAt: "2026-08-30T00:00:00.000Z",
+    });
+    const lease = {
+      schemaVersion: 1,
+      leaseId: "lease-1",
+      effectId: "effect-1",
+      connectionId: context.connectionId,
+      credentialGeneration: context.credentialGeneration,
+      expiresAt: "2026-08-30T01:00:00.000Z",
+      envelope,
+    } as const;
+
+    expect(decodeCredentialLeaseV1(lease)).toEqual(lease);
+    expect(() =>
+      decodeCredentialLeaseV1({ ...lease, unexpected: true }),
+    ).toThrow("Credential lease is invalid");
+    expect(() =>
+      decodeCredentialLeaseV1({
+        ...lease,
+        credentialGeneration: "generation-2",
+      }),
+    ).toThrow("Credential lease is invalid");
+  });
+
+  test("requires a versioned 32-byte keyring", () => {
+    expect(() =>
+      parseCredentialKeyringV1(
+        JSON.stringify({
+          schemaVersion: 1,
+          currentKeyId: "weak",
+          keys: { weak: "c2hvcnQ" },
+        }),
+      ),
+    ).toThrow('credential key "weak" must contain 32 bytes');
+  });
+});

package/src/credentials.ts

@@ -0,0 +1,303 @@
+export type ConnectionAuthorizationKind =
+  "none" | "api-key" | "ambient-native" | "grant";
+
+export interface CredentialDescriptorV1 {
+  schemaVersion: 1;
+  configured: boolean;
+  source: ConnectionAuthorizationKind;
+  writable: boolean;
+  generation?: string;
+  updatedAt?: string;
+}
+
+export interface CredentialEnvelopeV1 {
+  schemaVersion: 1;
+  algorithm: "AES-GCM";
+  keyId: string;
+  credentialGeneration: string;
+  nonce: string;
+  ciphertext: string;
+  createdAt: string;
+}
+
+export interface CredentialLeaseV1 {
+  schemaVersion: 1;
+  leaseId: string;
+  effectId: string;
+  connectionId: string;
+  credentialGeneration: string;
+  expiresAt: string;
+  envelope: CredentialEnvelopeV1;
+}
+
+export interface CredentialKeyringV1 {
+  schemaVersion: 1;
+  currentKeyId: string;
+  keys: Record<string, string>;
+}
+
+export interface CredentialContextV1 {
+  accountId: string;
+  connectionId: string;
+  packageId: string;
+  credentialGeneration: string;
+}
+
+function credentialRecord(input: unknown): Record<string, unknown> | undefined {
+  return input && typeof input === "object" && !Array.isArray(input)
+    ? (input as Record<string, unknown>)
+    : undefined;
+}
+
+function hasCredentialKeys(
+  value: Record<string, unknown>,
+  keys: readonly string[],
+): boolean {
+  return (
+    Object.keys(value).length === keys.length &&
+    keys.every((key) => Object.hasOwn(value, key))
+  );
+}
+
+function credentialString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+export function decodeCredentialEnvelopeV1(
+  input: unknown,
+): CredentialEnvelopeV1 {
+  const value = credentialRecord(input);
+  if (
+    !value ||
+    !hasCredentialKeys(value, [
+      "schemaVersion",
+      "algorithm",
+      "keyId",
+      "credentialGeneration",
+      "nonce",
+      "ciphertext",
+      "createdAt",
+    ]) ||
+    value.schemaVersion !== 1 ||
+    value.algorithm !== "AES-GCM" ||
+    !credentialString(value.keyId) ||
+    !credentialString(value.credentialGeneration) ||
+    !credentialString(value.nonce) ||
+    !credentialString(value.ciphertext) ||
+    !credentialString(value.createdAt) ||
+    !Number.isFinite(Date.parse(value.createdAt))
+  ) {
+    throw new Error("Credential envelope is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    algorithm: "AES-GCM",
+    keyId: value.keyId,
+    credentialGeneration: value.credentialGeneration,
+    nonce: value.nonce,
+    ciphertext: value.ciphertext,
+    createdAt: value.createdAt,
+  };
+}
+
+export function decodeCredentialLeaseV1(input: unknown): CredentialLeaseV1 {
+  const value = credentialRecord(input);
+  if (
+    !value ||
+    !hasCredentialKeys(value, [
+      "schemaVersion",
+      "leaseId",
+      "effectId",
+      "connectionId",
+      "credentialGeneration",
+      "expiresAt",
+      "envelope",
+    ]) ||
+    value.schemaVersion !== 1 ||
+    !credentialString(value.leaseId) ||
+    !credentialString(value.effectId) ||
+    !credentialString(value.connectionId) ||
+    !credentialString(value.credentialGeneration) ||
+    !credentialString(value.expiresAt) ||
+    !Number.isFinite(Date.parse(value.expiresAt))
+  ) {
+    throw new Error("Credential lease is invalid");
+  }
+  const envelope = decodeCredentialEnvelopeV1(value.envelope);
+  if (envelope.credentialGeneration !== value.credentialGeneration) {
+    throw new Error("Credential lease is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    leaseId: value.leaseId,
+    effectId: value.effectId,
+    connectionId: value.connectionId,
+    credentialGeneration: value.credentialGeneration,
+    expiresAt: value.expiresAt,
+    envelope,
+  };
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function base64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/, "");
+}
+
+function fromBase64Url(value: string): Uint8Array {
+  if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+    throw new Error("credential key material is not base64url");
+  }
+  const padded = value.replaceAll("-", "+").replaceAll("_", "/");
+  const binary = atob(padded.padEnd(Math.ceil(padded.length / 4) * 4, "="));
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+function contextBytes(context: CredentialContextV1): Uint8Array {
+  return encoder.encode(
+    JSON.stringify([
+      context.accountId,
+      context.connectionId,
+      context.packageId,
+      context.credentialGeneration,
+    ]),
+  );
+}
+
+function decodeKeyring(input: string): CredentialKeyringV1 {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(input);
+  } catch {
+    throw new Error("credential keyring is not valid JSON");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("credential keyring is invalid");
+  }
+  const value = parsed as Record<string, unknown>;
+  if (
+    value.schemaVersion !== 1 ||
+    typeof value.currentKeyId !== "string" ||
+    !value.currentKeyId ||
+    !value.keys ||
+    typeof value.keys !== "object" ||
+    Array.isArray(value.keys)
+  ) {
+    throw new Error("credential keyring is invalid");
+  }
+  const entries = Object.entries(value.keys as Record<string, unknown>);
+  if (entries.length === 0) throw new Error("credential keyring is empty");
+  const keys: Record<string, string> = Object.create(null) as Record<
+    string,
+    string
+  >;
+  for (const [keyId, encoded] of entries) {
+    if (!keyId || typeof encoded !== "string") {
+      throw new Error("credential keyring is invalid");
+    }
+    const bytes = fromBase64Url(encoded);
+    if (bytes.byteLength !== 32) {
+      throw new Error(`credential key "${keyId}" must contain 32 bytes`);
+    }
+    keys[keyId] = encoded;
+  }
+  if (!Object.hasOwn(keys, value.currentKeyId)) {
+    throw new Error("credential keyring current key is unavailable");
+  }
+  return {
+    schemaVersion: 1,
+    currentKeyId: value.currentKeyId,
+    keys,
+  };
+}
+
+async function encryptionKey(encoded: string): Promise<CryptoKey> {
+  const bytes = fromBase64Url(encoded);
+  return crypto.subtle.importKey(
+    "raw",
+    bytes as Uint8Array<ArrayBuffer>,
+    { name: "AES-GCM" },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+export function parseCredentialKeyringV1(input: string): CredentialKeyringV1 {
+  return decodeKeyring(input);
+}
+
+export async function sealCredentialV1(input: {
+  keyring: CredentialKeyringV1;
+  context: CredentialContextV1;
+  plaintext: string;
+  createdAt?: string;
+  randomBytes?: (length: number) => Uint8Array;
+}): Promise<CredentialEnvelopeV1> {
+  if (!input.plaintext) throw new Error("credential must not be empty");
+  const encodedKey = input.keyring.keys[input.keyring.currentKeyId];
+  if (!encodedKey) throw new Error("credential encryption key is unavailable");
+  const nonce = input.randomBytes
+    ? input.randomBytes(12)
+    : crypto.getRandomValues(new Uint8Array(12));
+  if (nonce.byteLength !== 12) {
+    throw new Error("credential nonce must contain 12 bytes");
+  }
+  const ciphertext = await crypto.subtle.encrypt(
+    {
+      name: "AES-GCM",
+      iv: nonce as Uint8Array<ArrayBuffer>,
+      additionalData: contextBytes(input.context) as Uint8Array<ArrayBuffer>,
+    },
+    await encryptionKey(encodedKey),
+    encoder.encode(input.plaintext),
+  );
+  return {
+    schemaVersion: 1,
+    algorithm: "AES-GCM",
+    keyId: input.keyring.currentKeyId,
+    credentialGeneration: input.context.credentialGeneration,
+    nonce: base64Url(nonce),
+    ciphertext: base64Url(new Uint8Array(ciphertext)),
+    createdAt: input.createdAt ?? new Date().toISOString(),
+  };
+}
+
+export async function openCredentialV1(input: {
+  keyring: CredentialKeyringV1;
+  context: CredentialContextV1;
+  envelope: CredentialEnvelopeV1;
+}): Promise<string> {
+  if (
+    input.envelope.schemaVersion !== 1 ||
+    input.envelope.algorithm !== "AES-GCM" ||
+    input.envelope.credentialGeneration !== input.context.credentialGeneration
+  ) {
+    throw new Error("credential envelope is invalid");
+  }
+  const encodedKey = input.keyring.keys[input.envelope.keyId];
+  if (!encodedKey) {
+    throw new Error(
+      `credential encryption key "${input.envelope.keyId}" is unavailable`,
+    );
+  }
+  try {
+    const plaintext = await crypto.subtle.decrypt(
+      {
+        name: "AES-GCM",
+        iv: fromBase64Url(input.envelope.nonce) as Uint8Array<ArrayBuffer>,
+        additionalData: contextBytes(input.context) as Uint8Array<ArrayBuffer>,
+      },
+      await encryptionKey(encodedKey),
+      fromBase64Url(input.envelope.ciphertext) as Uint8Array<ArrayBuffer>,
+    );
+    return decoder.decode(plaintext);
+  } catch {
+    throw new Error("credential envelope authentication failed");
+  }
+}