PaperClipAI/server/src/services/paperclip-cloud-connector.test.ts

import {
  createCipheriv,
  createHash,
  diffieHellman,
  generateKeyPairSync,
  hkdfSync,
  randomBytes,
  type KeyObject,
} from "node:crypto";
import { SLACK_MANAGER_SCOPES } from "@paperclipai/shared";
import { describe, expect, it, vi } from "vitest";
import { readFileSync } from "node:fs";

import {
  createPaperclipCloudConnector,
  invalidatePaperclipCloudConnectorCapabilities,
  GMAIL_CONNECTOR_SCOPES,
  GOOGLE_WORKSPACE_CONNECTOR_PROFILES,
  paperclipCloudConnectorCapabilitiesFromEnv,
  paperclipCloudConnectorConfigFromEnv,
  PaperclipCloudConnectorError,
  type PaperclipCloudConnectorConfig,
} from "./paperclip-cloud-connector.js";

const instanceId = "inst_test";
const companyId = "company_test";
const subject = "user_test";

// Captured from the producer's in-memory HTTP integration test, using synthetic
// enrollment and a signed request with a callback outside the enrolled origins.
// Retain only the HTTP status and exact JSON error body, never request data.
const originRejectionContract = JSON.parse(readFileSync(
  new URL("./fixtures/cloud-connector-origin-rejection.json", import.meta.url), "utf8",
)) as { status: number; body: { error: string } };
const refreshReauthorizationContract = JSON.parse(readFileSync(
  new URL("./fixtures/cloud-connector-refresh-reauthorization.json", import.meta.url), "utf8",
)) as { status: number; body: { error: string } };

function rawPrivateKey(key: KeyObject): string {
  const jwk = key.export({ format: "jwk" }) as { d?: string };
  if (!jwk.d) throw new Error("missing private key bytes");
  return jwk.d;
}

function config() {
  const signing = generateKeyPairSync("ed25519");
  const sealing = generateKeyPairSync("x25519");
  return {
    config: {
      baseUrl: "https://my.example.test",
      instanceId,
      environment: "staging",
      signPrivateKey: rawPrivateKey(signing.privateKey),
      sealPrivateKey: rawPrivateKey(sealing.privateKey),
    } satisfies PaperclipCloudConnectorConfig,
    sealPublicKey: sealing.publicKey,
  };
}

describe("Paperclip Cloud connector", () => {
  it("accepts actual partial Workspace consent inside an envelope bound to the full requested profile", async () => {
    const keys = config();
    const scopes = ["https://www.googleapis.com/auth/documents"];
    const credentials = { v: 1, accessToken: "test-access", refreshToken: "test-refresh", tokenType: "Bearer",
      accessTokenExpiresAt: null, refreshTokenExpiresAt: null, scopes, subject, companyId, instanceId,
      environment: keys.config.environment, provider: "google", profile: "workspace.all" };
    let sealed = seal(credentials, keys.sealPublicKey, "initial", keys.config, "workspace.all");
    const connector = createPaperclipCloudConnector({ config: keys.config,
      request: vi.fn(async () => Response.json({ sealed })) as typeof fetch });
    await expect(connector.claim({ subject, companyId, profile: "workspace.all", claimId: "test-claim", redemptionId: "test-state" })).resolves.toEqual(credentials);
    sealed = seal(credentials, keys.sealPublicKey, "access", keys.config, "workspace.all");
    await expect(connector.refresh({ subject, companyId, profile: "workspace.all", refreshToken: "test-refresh" })).resolves.toEqual(credentials);
    for (const invalid of [[], [...scopes, "https://www.googleapis.com/auth/gmail.send"]]) {
      credentials.scopes = invalid;
      sealed = seal(credentials, keys.sealPublicKey, "initial", keys.config, "workspace.all");
      await expect(connector.claim({ subject, companyId, profile: "workspace.all", claimId: "test-claim", redemptionId: "test-state" })).rejects.toMatchObject({ code: "REAUTHORIZATION_REQUIRED" });
      sealed = seal(credentials, keys.sealPublicKey, "access", keys.config, "workspace.all");
      await expect(connector.refresh({ subject, companyId, profile: "workspace.all", refreshToken: "test-refresh" })).rejects.toMatchObject({ code: "REAUTHORIZATION_REQUIRED" });
    }
    sealed = seal({ ...credentials, scopes: undefined }, keys.sealPublicKey, "access", keys.config, "workspace.all");
    await expect(connector.refresh({ subject, companyId, profile: "workspace.all", refreshToken: "test-refresh" })).rejects.toBeInstanceOf(PaperclipCloudConnectorError);
  });
  it("accepts a managed test identity and rejects other environments at its broker", () => {
    const identity = config().config;
    const env = {
      PAPERCLIP_CLOUD_CONNECTOR_INSTANCE_ID: identity.instanceId,
      PAPERCLIP_CLOUD_CONNECTOR_SIGN_PRIVATE_KEY: identity.signPrivateKey,
      PAPERCLIP_CLOUD_CONNECTOR_SEAL_PRIVATE_KEY: identity.sealPrivateKey,
      PAPERCLIP_CLOUD_CONNECTOR_BASE_URL: "https://test.paperclip.app",
      PAPERCLIP_CLOUD_CONNECTOR_ENVIRONMENT: "test",
    };
    expect(paperclipCloudConnectorConfigFromEnv(env)).toMatchObject({ environment: "test", baseUrl: env.PAPERCLIP_CLOUD_CONNECTOR_BASE_URL });
    for (const environment of ["development", "staging", "production"]) {
      expect(() => paperclipCloudConnectorConfigFromEnv({ ...env, PAPERCLIP_CLOUD_CONNECTOR_ENVIRONMENT: environment })).toThrow(/broker and environment do not match/);
    }
    for (const baseUrl of ["https://my.paperclip.app", "https://my-staging.paperclip.app"]) {
      expect(() => paperclipCloudConnectorConfigFromEnv({ ...env, PAPERCLIP_CLOUD_CONNECTOR_BASE_URL: baseUrl })).toThrow(/broker and environment do not match/);
    }
  });

  async function rejection(response: Response) {
    const connector = createPaperclipCloudConnector({
      config: config().config,
      request: vi.fn(async () => response) as typeof fetch,
    });
    return connector.startAuthorization({
      subject, companyId, profile: "gmail.read",
      returnUri: "https://paperclip.example.test/api/tools/oauth/cloud-connector/callback",
      returnState: "private-state",
    }).catch((error: unknown) => error);
  }

  it("accepts the producer's origin-rejection HTTP contract", async () => {
    expect(await rejection(Response.json(originRejectionContract.body, {
      status: originRejectionContract.status,
    }))).toMatchObject({
      code: "CONNECTOR_REQUEST_FAILED", status: 400,
      message: "Paperclip Cloud connector rejected the request (operation=session, status=400, reason=RETURN_ORIGIN_NOT_ENROLLED)",
    });
  });

  it("retains an allowlisted rejection reason without broker messages or credentials", async () => {
    const error = await rejection(Response.json({
      error: "RETURN_ORIGIN_NOT_ENROLLED",
      message: "DO_NOT_REPORT private-state access-secret https://private.example.test",
    }, { status: 400 }));
    expect(error).toBeInstanceOf(PaperclipCloudConnectorError);
    expect(error).toMatchObject({
      code: "CONNECTOR_REQUEST_FAILED", status: 400,
      message: "Paperclip Cloud connector rejected the request (operation=session, status=400, reason=RETURN_ORIGIN_NOT_ENROLLED)",
    });
    expect(JSON.stringify(error)).not.toMatch(/DO_NOT_REPORT|private-state|access-secret|private\.example/);
  });

  it.each([
    JSON.stringify({ error: "CUSTOM_SECRET_ERROR", message: "DO_NOT_REPORT" }),
    JSON.stringify({ error: { code: "RETURN_ORIGIN_NOT_ENROLLED" } }),
    "<html>DO_NOT_REPORT</html>",
    JSON.stringify({ error: "RETURN_ORIGIN_NOT_ENROLLED", padding: "x".repeat(4_096) }),
  ])("drops unknown, malformed, or oversized rejection bodies", async (body) => {
    const error = await rejection(new Response(body, { status: 409 }));
    expect(error).toMatchObject({
      code: "REAUTHORIZATION_REQUIRED", status: 409,
      message: "Paperclip Cloud connector rejected the request (operation=session, status=409, reason=UNKNOWN_BROKER_ERROR)",
    });
  });

  it("asks for reconnection when the provider rejects a refresh grant", async () => {
    const connector = createPaperclipCloudConnector({
      config: config().config,
      request: vi.fn(async () => Response.json(refreshReauthorizationContract.body, {
        status: refreshReauthorizationContract.status,
      })) as typeof fetch,
    });
    const error = await connector.refresh({
      subject, companyId, profile: "gmail.read", refreshToken: "refresh-secret",
    }).catch((caught: unknown) => caught);
    expect(error).toBeInstanceOf(PaperclipCloudConnectorError);
    expect(error).toMatchObject({
      code: "REAUTHORIZATION_REQUIRED", status: 409,
      message: "Paperclip Cloud connector rejected the request (operation=refresh, status=409, reason=PROVIDER_REAUTHORIZATION_REQUIRED)",
    });
    expect(JSON.stringify(error)).not.toContain("refresh-secret");
  });

  it("keeps the original status when the error body stream fails", async () => {
    const response = new Response(new ReadableStream({
      start(controller) { controller.error(new Error("DO_NOT_REPORT")); },
    }), { status: 503 });
    expect(await rejection(response)).toMatchObject({
      code: "CONNECTOR_REQUEST_FAILED", status: 503,
      message: expect.stringContaining("reason=UNKNOWN_BROKER_ERROR"),
    });
  });

  it("keeps the original failure when a response body is absent or already locked", async () => {
    const locked = Response.json({ error: "RETURN_ORIGIN_NOT_ENROLLED" }, { status: 401 });
    const reader = locked.body!.getReader();
    try {
      for (const response of [new Response(null, { status: 401 }), locked]) {
        expect(await rejection(response)).toMatchObject({
          code: "CONNECTOR_REQUEST_FAILED", status: 401,
          message: expect.stringContaining("reason=UNKNOWN_BROKER_ERROR"),
        });
      }
    } finally {
      await reader.cancel();
    }
  });

  it("bounds a stalled diagnostic read and does not wait for cancellation", async () => {
    vi.useFakeTimers();
    const cancel = vi.fn(() => new Promise<void>(() => {}));
    try {
      const pending = rejection(new Response(new ReadableStream({ cancel }), { status: 400 }));
      await vi.advanceTimersByTimeAsync(500);
      expect(await pending).toMatchObject({
        code: "CONNECTOR_REQUEST_FAILED", status: 400,
        message: expect.stringContaining("reason=UNKNOWN_BROKER_ERROR"),
      });
      expect(cancel).toHaveBeenCalledOnce();
    } finally {
      vi.useRealTimers();
    }
  });

  it("refreshes capabilities after enrollment and rejects stale cache writes", async () => {
    const keys = config().config;
    const env = {
      PAPERCLIP_CLOUD_CONNECTOR_BASE_URL: keys.baseUrl,
      PAPERCLIP_CLOUD_CONNECTOR_INSTANCE_ID: keys.instanceId,
      PAPERCLIP_CLOUD_CONNECTOR_ENVIRONMENT: keys.environment,
      PAPERCLIP_CLOUD_CONNECTOR_SIGN_PRIVATE_KEY: keys.signPrivateKey,
      PAPERCLIP_CLOUD_CONNECTOR_SEAL_PRIVATE_KEY: keys.sealPrivateKey,
    };
    let completeOldRequest!: (response: Response) => void;
    const request = vi.spyOn(globalThis, "fetch")
      .mockResolvedValueOnce(Response.json({ status: "pending", active: false }))
      .mockImplementationOnce(() => new Promise<Response>((resolve) => { completeOldRequest = resolve; }))
      .mockResolvedValue(Response.json({ status: "active", active: true, profiles: ["gmail.read"] }));
    invalidatePaperclipCloudConnectorCapabilities();
    try {
      await expect(paperclipCloudConnectorCapabilitiesFromEnv(env)).resolves.toEqual([]);
      await expect(paperclipCloudConnectorCapabilitiesFromEnv(env)).resolves.toEqual([]);
      expect(request).toHaveBeenCalledTimes(1);
      invalidatePaperclipCloudConnectorCapabilities();
      const oldRequest = paperclipCloudConnectorCapabilitiesFromEnv(env);
      invalidatePaperclipCloudConnectorCapabilities();
      await expect(paperclipCloudConnectorCapabilitiesFromEnv(env)).resolves.toEqual(["gmail.read"]);
      completeOldRequest(Response.json({ status: "pending", active: false }));
      await expect(oldRequest).resolves.toEqual([]);
      await expect(paperclipCloudConnectorCapabilitiesFromEnv(env)).resolves.toEqual(["gmail.read"]);
      expect(request).toHaveBeenCalledTimes(3);
    } finally {
      request.mockRestore();
      invalidatePaperclipCloudConnectorCapabilities();
    }
  });

  it.each(["chat.read", "chat.write"] as const)("signs reduced Chat scopes for %s", async (profile) => {
    const keys = config();
    const scopes = ["chat.spaces.readonly", "chat.messages.readonly", ...(profile === "chat.write" ? ["chat.messages.create"] : [])]
      .map((scope) => `https://www.googleapis.com/auth/${scope}`);
    const request = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
      const body = JSON.parse(String(init?.body));
      const claims = JSON.parse(Buffer.from(body.request.split(".")[1], "base64url").toString("utf8"));
      expect(claims.prf).toBe(profile);
      expect(claims.scp).toEqual(scopes);
      return Response.json({ confirmationUrl: "https://my.example.test/connections/confirm?session=chat", expiresAt: "2099-01-01T00:00:00Z" });
    });
    const connector = createPaperclipCloudConnector({ config: keys.config, request: request as typeof fetch });
    await connector.startAuthorization({ subject, companyId, profile,
      returnUri: "https://paperclip.example.test/api/tools/oauth/cloud-connector/callback", returnState: "chat-state" });
    expect(request).toHaveBeenCalledOnce();
  });

  it("signs selected Workspace scopes without substituting the full profile", async () => {
    const keys = config();
    const scopes = ["https://www.googleapis.com/auth/gmail.readonly"];
    const request = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
      const body = JSON.parse(String(init?.body));
      const claims = JSON.parse(Buffer.from(body.request.split(".")[1], "base64url").toString("utf8"));
      expect(claims).toMatchObject({ prf: "workspace.all", scp: scopes });
      return Response.json({ confirmationUrl: "https://my.example.test/connections/confirm?session=workspace", expiresAt: "2099-01-01T00:00:00Z" });
    });
    const connector = createPaperclipCloudConnector({ config: keys.config, request: request as typeof fetch });
    await connector.startAuthorization({ subject, companyId, profile: "workspace.all", scopes,
      returnUri: "https://paperclip.example.test/api/tools/oauth/cloud-connector/callback", returnState: "workspace-state" });
    expect(request).toHaveBeenCalledOnce();
  });

  it("starts a signed session with exact endpoint audience and scope contract", async () => {
    const keys = config();
    const request = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
      const body = JSON.parse(String(init?.body)) as { request: string };
      const [encodedHeader, encodedClaims] = body.request.split(".");
      expect(JSON.parse(Buffer.from(encodedHeader!, "base64url").toString("utf8"))).toEqual({
        alg: "EdDSA",
        typ: "paperclip-cloud-connector-request+jwt",
      });
      const claims = JSON.parse(Buffer.from(encodedClaims!, "base64url").toString("utf8"));
      expect(claims).toMatchObject({
        iss: instanceId,
        aud: "https://my.example.test/v1/connector/sessions",
        sub: subject,
        cid: companyId,
        env: "staging",
        op: "session",
        prv: "google",
        prf: "gmail.draft",
        scp: [...GMAIL_CONNECTOR_SCOPES],
        ruri: "https://paperclip.example.test/api/tools/oauth/cloud-connector/callback",
        rst: "state-1",
      });
      return Response.json({
        confirmationUrl: "https://my.example.test/connections/confirm?session=broker-state",
        handoff: {
          kind: "tenant_background",
          session: "broker_state_abcdefghijklmnop",
        },
        expiresAt: "2026-08-21T20:00:00.000Z",
      }, { status: 201 });
    });
    const connector = createPaperclipCloudConnector({ config: keys.config, request: request as typeof fetch });

    await expect(connector.startAuthorization({
      subject,
      companyId,
      returnUri: "https://paperclip.example.test/api/tools/oauth/cloud-connector/callback",
      returnState: "state-1",
    })).resolves.toMatchObject({
      authorizationUrl: expect.stringContaining("/connections/confirm"),
      handoff: {
        kind: "paperclip_cloud",
        session: "broker_state_abcdefghijklmnop",
      },
    });
  });

  it("prefers a validated HTTPS provider URL over the legacy confirmation URL", async () => {
    const keys = config();
    const connector = createPaperclipCloudConnector({
      config: keys.config,
      request: vi.fn(async () => Response.json({
        confirmationUrl: "https://my.example.test/connections/confirm?session=broker-state",
        authorizationUrl: "https://github.com/login/oauth/authorize?client_id=client&state=broker-state",
        expiresAt: "2099-08-21T20:00:00.000Z",
      })) as typeof fetch,
    });

    await expect(connector.startAuthorization({
      subject,
      companyId,
      profile: "github.code",
      returnUri: "https://paperclip.example.test/api/tools/oauth/cloud-connector/callback",
      returnState: "state-direct",
    })).resolves.toMatchObject({
      authorizationUrl: "https://github.com/login/oauth/authorize?client_id=client&state=broker-state",
    });
  });

  it.each([
    ["https://app.asana.com/-/oauth_authorize", true],
    ["https://mcp.asana.com/authorize", false],
    ["https://app.asana.com/other", false],
  ])("validates Asana's exact v2 authorization endpoint %s", async (authorizationUrl, accepted) => {
    const keys = config();
    const connector = createPaperclipCloudConnector({ config: keys.config,
      request: vi.fn(async (_url, init) => {
        const body = JSON.parse(String(init?.body));
        const claims = JSON.parse(Buffer.from(body.request.split(".")[1], "base64url").toString("utf8"));
        expect(claims).toMatchObject({ prv: "asana", prf: "asana.mcp", scp: ["default"] });
        return Response.json({ confirmationUrl: "https://my.example.test/connections/confirm?session=test",
          authorizationUrl, expiresAt: "2099-01-01T00:00:00Z" });
      }) as typeof fetch,
    });
    const result = connector.startAuthorization({ subject, companyId, profile: "asana.mcp",
      returnUri: "https://paperclip.example.test/api/tools/oauth/cloud-connector/callback", returnState: "state" });
    if (accepted) await expect(result).resolves.toMatchObject({ authorizationUrl });
    else await expect(result).rejects.toMatchObject({ code: "CONNECTOR_BAD_RESPONSE" });
  });

  it("accepts the fixed Google authorization endpoint for Google profiles", async () => {
    const keys = config();
    const connector = createPaperclipCloudConnector({
      config: keys.config,
      request: vi.fn(async () => Response.json({
        confirmationUrl: "https://my.example.test/connections/confirm?session=broker-state",
        authorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth?client_id=client&state=broker-state",
        expiresAt: "2099-08-21T20:00:00.000Z",
      })) as typeof fetch,
    });

    await expect(connector.startAuthorization({
      subject,
      companyId,
      profile: "gmail.draft",
      returnUri: "https://paperclip.example.test/api/tools/oauth/cloud-connector/callback",
      returnState: "state-direct-google",
    })).resolves.toMatchObject({
      authorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth?client_id=client&state=broker-state",
    });
  });

  it.each([
    ["non-string", { href: "https://github.com/login/oauth/authorize" }],
    ["plaintext HTTP", "http://github.com/login/oauth/authorize"],
    ["embedded credentials", "https://user:password@github.com/login/oauth/authorize"],
    ["fragment", "https://github.com/login/oauth/authorize#unexpected"],
    ["unapproved HTTPS origin", "https://attacker.example.test/login/oauth/authorize"],
    ["unapproved provider path", "https://github.com/session/authorize"],
    ["not a URL", "not-a-url"],
  ])("rejects a malformed direct provider URL: %s", async (_label, authorizationUrl) => {
    const keys = config();
    const connector = createPaperclipCloudConnector({
      config: keys.config,
      request: vi.fn(async () => Response.json({
        confirmationUrl: "https://my.example.test/connections/confirm?session=broker-state",
        authorizationUrl,
        expiresAt: "2099-08-21T20:00:00.000Z",
      })) as typeof fetch,
    });

    await expect(connector.startAuthorization({
      subject,
      companyId,
      profile: "github.code",
      returnUri: "https://paperclip.example.test/api/tools/oauth/cloud-connector/callback",
      returnState: "state-malformed-direct",
    })).rejects.toMatchObject({ code: "CONNECTOR_BAD_RESPONSE" });
  });

  it("binds active GitHub installations to proof from the current user token", async () => {
    const keys = config();
    const request = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
      const body = JSON.parse(String(init?.body)) as { request: string; binding: string };
      const claims = JSON.parse(Buffer.from(body.request.split(".")[1]!, "base64url").toString("utf8"));
      const binding = JSON.parse(body.binding);
      expect(binding).toEqual({
        id: "binding-1",
        installationId: "42",
        connectionId: "connection-1",
        grantId: "grant-1",
        active: true,
        accessToken: "ghu-user-token",
      });
      expect(claims.sh).toBe(createHash("sha256").update(body.binding).digest("base64url"));
      return Response.json({ active: true, installationId: "42" });
    });
    const connector = createPaperclipCloudConnector({ config: keys.config, request: request as typeof fetch });

    await expect(connector.setWebhookBinding({
      subject,
      companyId,
      id: "binding-1",
      installationId: "42",
      connectionId: "connection-1",
      grantId: "grant-1",
      active: true,
      accessToken: "ghu-user-token",
    })).resolves.toBeUndefined();
    await expect(connector.setWebhookBinding({
      subject,
      companyId,
      id: "binding-2",
      installationId: "43",
      connectionId: "connection-1",
      grantId: "grant-1",
      active: true,
    })).rejects.toMatchObject({ code: "CONNECTOR_CONFIG_INVALID" });
    expect(request).toHaveBeenCalledTimes(1);
  });

  it("keeps legacy session responses compatible and rejects malformed handoff descriptors", async () => {
    const keys = config();
    const legacy = createPaperclipCloudConnector({
      config: keys.config,
      request: vi.fn(async () => Response.json({
        confirmationUrl: "https://my.example.test/connections/confirm?session=broker-state",
        expiresAt: "2099-08-21T20:00:00.000Z",
      })) as typeof fetch,
    });
    await expect(legacy.startAuthorization({
      subject,
      companyId,
      returnUri: "https://paperclip.example.test/api/tools/oauth/cloud-connector/callback",
      returnState: "state-legacy",
    })).resolves.not.toHaveProperty("handoff");

    const malformed = createPaperclipCloudConnector({
      config: keys.config,
      request: vi.fn(async () => Response.json({
        confirmationUrl: "https://my.example.test/connections/confirm?session=broker-state",
        handoff: { kind: "tenant_background", session: "not valid" },
        expiresAt: "2099-08-21T20:00:00.000Z",
      })) as typeof fetch,
    });
    await expect(malformed.startAuthorization({
      subject,
      companyId,
      returnUri: "https://paperclip.example.test/api/tools/oauth/cloud-connector/callback",
      returnState: "state-malformed",
    })).rejects.toMatchObject({ code: "CONNECTOR_BAD_RESPONSE" });
  });

  it("opens Slack manager handoffs with their exact profile and personal identity", async () => {
    const keys = config();
    const credentials = { v: 1, accessToken: "manager-access-canary", refreshToken: "manager-refresh-canary", tokenType: "user", accessTokenExpiresAt: "2030-01-01T00:00:00.000Z", refreshTokenExpiresAt: null,
      scopes: [...SLACK_MANAGER_SCOPES], subject, companyId, instanceId, environment: "staging", provider: "slack", profile: "slack.manager",
      slackManager: { appId: "AMANAGER", workspaceId: "TWORKSPACE", workspaceName: "Paperclip", userId: "UOWNER" } };
    const sealed = seal(credentials, keys.sealPublicKey, "initial", keys.config, "slack.manager");
    const connector = createPaperclipCloudConnector({ config: keys.config, request: vi.fn(async () => Response.json({ claimId: "claim", scopes: [...SLACK_MANAGER_SCOPES], sealed })) as typeof fetch });
    await expect(connector.claim({ subject, companyId, profile: "slack.manager", claimId: "claim", redemptionId: "manager-state" })).resolves.toEqual(credentials);
    await expect(connector.claim({ subject: "another-user", companyId, profile: "slack.manager", claimId: "claim", redemptionId: "manager-state" })).rejects.toThrow();
  });
  it("opens an instance-sealed claim and verifies its user, company, and exact scopes", async () => {
    const keys = config();
    const credentials = {
      v: 1 as const,
      accessToken: "access-secret",
      refreshToken: "refresh-secret",
      tokenType: "Bearer",
      accessTokenExpiresAt: "2026-08-21T20:00:00.000Z",
      refreshTokenExpiresAt: null,
      scopes: [...GMAIL_CONNECTOR_SCOPES],
      subject,
      companyId,
      instanceId,
      environment: "staging" as const,
      provider: "google" as const,
      profile: "gmail.draft",
    };
    const sealed = seal(credentials, keys.sealPublicKey, "initial", keys.config, "gmail.draft");
    const request = vi.fn(async () => Response.json({
      claimId: "clm_test",
      scopes: [...GMAIL_CONNECTOR_SCOPES],
      sealed,
    }));
    const connector = createPaperclipCloudConnector({ config: keys.config, request: request as typeof fetch });

    await expect(connector.claim({
      subject,
      companyId,
      claimId: "clm_test",
      redemptionId: "local-oauth-state-1",
    })).resolves.toEqual(credentials);
  });

  it("binds non-Gmail credentials and requests to their exact connector profile", async () => {
    const keys = config();
    const profile = "drive.read" as const;
    const credentials = {
      v: 1 as const,
      accessToken: "drive-access-secret",
      refreshToken: "drive-refresh-secret",
      tokenType: "Bearer",
      accessTokenExpiresAt: "2026-08-21T20:00:00.000Z",
      refreshTokenExpiresAt: null,
      scopes: [...GOOGLE_WORKSPACE_CONNECTOR_PROFILES[profile].scopes],
      subject,
      companyId,
      instanceId,
      environment: "staging" as const,
      provider: "google" as const,
      profile,
    };
    const sealed = seal(credentials, keys.sealPublicKey, "initial", keys.config, profile);
    const request = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
      const body = JSON.parse(String(init?.body)) as { request: string };
      const [, encodedClaims] = body.request.split(".");
      const claims = JSON.parse(Buffer.from(encodedClaims!, "base64url").toString("utf8"));
      expect(claims.prf).toBe(profile);
      expect(claims.rid).toBe("local-oauth-state-drive");
      return Response.json({ claimId: "clm_drive", scopes: credentials.scopes, sealed });
    });
    const connector = createPaperclipCloudConnector({ config: keys.config, request: request as typeof fetch });

    await expect(connector.claim({
      subject,
      companyId,
      profile,
      claimId: "clm_drive",
      redemptionId: "local-oauth-state-drive",
    })).resolves.toEqual(credentials);
  });

  it("accepts only the current capability protocol and known profiles", async () => {
    const keys = config();
    const request = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
      const body = JSON.parse(String(init?.body)) as { request: string };
      const [, encodedClaims] = body.request.split(".");
      const claims = JSON.parse(Buffer.from(encodedClaims!, "base64url").toString("utf8"));
      expect(claims).toMatchObject({
        iss: instanceId,
        aud: "https://my.example.test/v1/connector/instance-status",
        sub: "instance-capabilities",
        cid: "instance-capabilities",
        env: "staging",
        op: "status",
      });
      expect(claims).not.toHaveProperty("prv");
      expect(claims).not.toHaveProperty("prf");
      expect(claims).not.toHaveProperty("scp");
      return Response.json({
        active: true,
        status: "active",
        profiles: ["gmail.read", "drive.write", "unknown.profile", "gmail.read"],
      });
    });
    const connector = createPaperclipCloudConnector({ config: keys.config, request: request as typeof fetch });
    await expect(connector.getCapabilities()).resolves.toEqual(["gmail.read", "drive.write"]);
  });

  it("fails capability discovery closed for inactive, legacy, malformed, or rejected status responses", async () => {
    const keys = config();
    const responses = [
      Response.json({ active: false, status: "suspended", profiles: ["gmail.read"] }),
      Response.json({ active: true, status: "active" }),
      Response.json({ active: true, status: "active", profiles: "gmail.read" }),
      new Response("detail must not escape", { status: 403 }),
    ];
    for (const response of responses) {
      const connector = createPaperclipCloudConnector({
        config: keys.config,
        request: vi.fn(async () => response) as typeof fetch,
      });
      await expect(connector.getCapabilities()).resolves.toEqual([]);
    }
  });

  it("checks Cloud enrollment status with an instance-only signed request", async () => {
    const keys = config();
    const request = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
      const body = JSON.parse(String(init?.body)) as { request: string };
      const [, encodedClaims] = body.request.split(".");
      const claims = JSON.parse(Buffer.from(encodedClaims!, "base64url").toString("utf8"));
      expect(claims).toMatchObject({
        iss: instanceId,
        aud: "https://my.example.test/v1/connector/instance-status",
        sub: "instance-status",
        cid: "instance-status",
        env: "staging",
        op: "status",
      });
      expect(claims).not.toHaveProperty("prv");
      expect(claims).not.toHaveProperty("prf");
      expect(claims).not.toHaveProperty("scp");
      return Response.json({ active: true, status: "active" });
    });
    const connector = createPaperclipCloudConnector({ config: keys.config, request: request as typeof fetch });

    await expect(connector.getInstanceStatus()).resolves.toBe("active");
  });

  it("treats an unknown Cloud enrollment as removed without exposing Cloud detail", async () => {
    const keys = config();
    const connector = createPaperclipCloudConnector({
      config: keys.config,
      request: vi.fn(async () => new Response("unknown instance detail", { status: 401 })) as typeof fetch,
    });

    await expect(connector.getInstanceStatus()).resolves.toBe("removed");
  });

  it("does not expose a broker response body when a request fails", async () => {
    const keys = config();
    const request = vi.fn(async () => new Response(JSON.stringify({
      error: "provider rejected access-secret refresh-secret",
    }), { status: 502 }));
    const connector = createPaperclipCloudConnector({ config: keys.config, request: request as typeof fetch });

    const error = await connector.refresh({ subject, companyId, refreshToken: "refresh-secret" }).catch((caught) => caught);
    expect(error).toBeInstanceOf(PaperclipCloudConnectorError);
    expect(String(error)).not.toContain("access-secret");
    expect(String(error)).not.toContain("refresh-secret");
    expect(request).toHaveBeenCalledOnce();
  });

  it("requires an all-or-nothing environment configuration and loopback for HTTP", () => {
    expect(paperclipCloudConnectorConfigFromEnv({})).toBeNull();
    expect(() => paperclipCloudConnectorConfigFromEnv({
      PAPERCLIP_CLOUD_CONNECTOR_INSTANCE_ID: instanceId,
    })).toThrowError(/incomplete/);
    expect(() => paperclipCloudConnectorConfigFromEnv({
      PAPERCLIP_CLOUD_CONNECTOR_INSTANCE_ID: instanceId,
      PAPERCLIP_CLOUD_CONNECTOR_SIGN_PRIVATE_KEY: "key",
      PAPERCLIP_CLOUD_CONNECTOR_SEAL_PRIVATE_KEY: "key",
      PAPERCLIP_CLOUD_CONNECTOR_ENVIRONMENT: "development",
      PAPERCLIP_CLOUD_CONNECTOR_BASE_URL: "http://my.example.test",
    })).toThrowError(/HTTPS/);
    const legacyError = (() => {
      try {
        paperclipCloudConnectorConfigFromEnv({
          PAPERCLIP_ID_CONNECTOR_INSTANCE_ID: instanceId,
          PAPERCLIP_ID_CONNECTOR_SIGN_PRIVATE_KEY: "key",
          PAPERCLIP_ID_CONNECTOR_SEAL_PRIVATE_KEY: "key",
          PAPERCLIP_ID_CONNECTOR_ENVIRONMENT: "development",
          PAPERCLIP_ID_CONNECTOR_BASE_URL: "https://id.paperclip.app",
        });
        return null;
      } catch (error) {
        return error;
      }
    })();
    expect(legacyError).toMatchObject({ code: "CONNECTOR_MIGRATION_REQUIRED" });
    expect(String(legacyError)).toContain("incompatible legacy protocol");
  });

  it("keeps gallery capability discovery available during incomplete enrollment", async () => {
    await expect(paperclipCloudConnectorCapabilitiesFromEnv({
      PAPERCLIP_CLOUD_CONNECTOR_BASE_URL: "https://my-staging.paperclip.app",
      PAPERCLIP_CLOUD_CONNECTOR_ENVIRONMENT: "staging",
    })).resolves.toEqual([]);
  });
});

function seal(
  payload: unknown,
  recipientPublicKey: KeyObject,
  purpose: "initial" | "access" | "events",
  configValue: PaperclipCloudConnectorConfig,
  profile: keyof typeof GOOGLE_WORKSPACE_CONNECTOR_PROFILES | "slack.manager" | "github.bot" | "github.code",
) {
  const provider = profile.startsWith("github.") ? "github" : profile === "slack.manager" ? "slack" : "google";
  const scopes = provider === "github" ? [] : profile === "slack.manager" ? SLACK_MANAGER_SCOPES : GOOGLE_WORKSPACE_CONNECTOR_PROFILES[profile as keyof typeof GOOGLE_WORKSPACE_CONNECTOR_PROFILES].scopes;
  const ephemeral = generateKeyPairSync("x25519");
  const ephemeralJwk = ephemeral.publicKey.export({ format: "jwk" }) as { x: string };
  const recipientJwk = recipientPublicKey.export({ format: "jwk" }) as { x: string };
  const ephemeralRaw = Buffer.from(ephemeralJwk.x, "base64url");
  const recipientRaw = Buffer.from(recipientJwk.x, "base64url");
  const aad = Buffer.from([
    1,
    "X25519-HKDF-SHA256-A256GCM",
    purpose,
    configValue.instanceId,
    configValue.environment,
    provider,
    profile,
    [...scopes].sort().join(" "),
  ].join("\n"));
  const key = Buffer.from(hkdfSync(
    "sha256",
    diffieHellman({ privateKey: ephemeral.privateKey, publicKey: recipientPublicKey }),
    Buffer.concat([ephemeralRaw, recipientRaw]),
    profile === "workspace.all" ? createHash("sha256").update(aad).digest() : aad,
    32,
  ));
  const iv = randomBytes(12);
  const cipher = createCipheriv("aes-256-gcm", key, iv);
  cipher.setAAD(aad);
  const ciphertext = Buffer.concat([cipher.update(JSON.stringify(payload), "utf8"), cipher.final(), cipher.getAuthTag()]);
  return {
    v: 1,
    alg: "X25519-HKDF-SHA256-A256GCM",
    purpose,
    provider,
    profile,
    epk: ephemeralJwk.x,
    iv: iv.toString("base64url"),
    ct: ciphertext.toString("base64url"),
  };
}

describe("dedicated App gateway delivery", () => {
  it.each([1, 2])("requires the stack-owned setup protocol version (%s)", async version => {
    const connector = createPaperclipCloudConnector({ config: config().config, request: vi.fn(async () => Response.json({active:true,githubApps:{version}})) as typeof fetch });
    expect(await connector.githubAppsAvailable()).toBe(version === 2);
  });
  it("decrypts opaque webhook bytes sealed before Cloud storage", async () => {
    const keys = config();
    const rawBody = Buffer.from('{ "comment": { "body": "private comment" } }').toString("base64");
    const packet = { v:1,instanceId,environment:"staging",registrationId:"route-a",rawBody,headers:{"x-github-event":"issue_comment","x-github-delivery":"delivery-a","x-hub-signature-256":"signature"} };
    const inner = seal(packet,keys.sealPublicKey,"events",keys.config,"github.bot");
    const outer = seal({v:1,instanceId,environment:"staging",leaseId:"lease-a",events:[{id:"transport-a",provider:"github",event:"gateway_delivery",payload:{githubApp:{registrationId:"route-a",sealed:inner}},bindingIds:["github-app:route-a"]}]},keys.sealPublicKey,"events",keys.config,"github.code");
    const connector = createPaperclipCloudConnector({config:keys.config,request:vi.fn(async()=>Response.json({leaseId:"lease-a",sealed:outer})) as typeof fetch});
    expect((await connector.leaseEvents({subject,companyId}))?.events[0].payload.githubApp).toEqual(packet);
    expect(JSON.stringify(inner)).not.toContain("private comment");
  });
  it("retains an inner envelope swapped from another opaque route for retry", async () => {
    const keys = config();
    const inner = seal({v:1,instanceId,environment:"staging",registrationId:"route-b"},keys.sealPublicKey,"events",keys.config,"github.bot");
    const outer = seal({v:1,instanceId,environment:"staging",leaseId:"lease-a",events:[{id:"transport-a",provider:"github",event:"gateway_delivery",payload:{githubApp:{registrationId:"route-a",sealed:inner}},bindingIds:["github-app:route-a"]}]},keys.sealPublicKey,"events",keys.config,"github.code");
    const connector=createPaperclipCloudConnector({config:keys.config,request:vi.fn(async()=>Response.json({leaseId:"lease-a",sealed:outer})) as typeof fetch});
    await expect(connector.leaseEvents({subject,companyId})).resolves.toMatchObject({
      leaseId: "lease-a", events: [], failedEventIds: ["transport-a"],
    });
  });

  it.each(["ciphertext", "lease"])("still rejects an invalid outer %s binding", async failure => {
    const keys = config();
    const outer = seal({ v: 1, instanceId, environment: "staging", leaseId: "lease-a", events: [] },
      failure === "ciphertext" ? config().sealPublicKey : keys.sealPublicKey, "events", keys.config, "github.code");
    const connector = createPaperclipCloudConnector({ config: keys.config,
      request: vi.fn(async () => Response.json({ leaseId: failure === "lease" ? "other-lease" : "lease-a", sealed: outer })) as typeof fetch });
    await expect(connector.leaseEvents({ subject, companyId })).rejects.toBeInstanceOf(PaperclipCloudConnectorError);
  });

  it("isolates a stale-key event while decrypting healthy siblings and legacy events", async () => {
    const keys = config();
    const staleKeys = config();
    const packet = { v: 1, instanceId, environment: "staging", registrationId: "route-a", rawBody: "e30=" };
    const event = (id: string, inner: unknown) => ({ id, provider: "github", event: "gateway_delivery",
      payload: { githubApp: { registrationId: "route-a", sealed: inner } }, bindingIds: ["github-app:route-a"] });
    const outer = seal({ v: 1, instanceId, environment: "staging", leaseId: "lease-a", events: [
      event("stale", seal(packet, staleKeys.sealPublicKey, "events", keys.config, "github.bot")),
      event("healthy", seal(packet, keys.sealPublicKey, "events", keys.config, "github.bot")),
      { id: "legacy", provider: "github", event: "installation", payload: {}, bindingIds: [] },
    ] }, keys.sealPublicKey, "events", keys.config, "github.code");
    const connector = createPaperclipCloudConnector({ config: keys.config,
      request: vi.fn(async () => Response.json({ leaseId: "lease-a", sealed: outer })) as typeof fetch });
    const result = await connector.leaseEvents({ subject, companyId });
    expect(result?.failedEventIds).toEqual(["stale"]);
    expect(result?.events.map(event => event.id)).toEqual(["healthy", "legacy"]);
    expect(result?.events[0]?.payload.githubApp).toEqual(packet);
    expect(JSON.stringify(result)).not.toContain('"ct"');
  });
});