feat: POST /api/emails + route ephemeral key to RECOUP_API_KEY (#1815)

app/api/emails/route.ts

@@ -0,0 +1,46 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
+import { sendEmailHandler } from "@/lib/emails/sendEmailHandler";
+
+/**
+ * OPTIONS handler for CORS preflight requests.
+ *
+ * @returns A NextResponse with CORS headers.
+ */
+export async function OPTIONS() {
+ return new NextResponse(null, {
+ status: 204,
+ headers: getCorsHeaders(),
+ });
+}
+
+/**
+ * POST /api/emails
+ *
+ * Sends an email to one or more explicit recipients via Resend. Emails are sent
+ * from `Agent by Recoup <agent@recoupable.com>`. Account-scoped — requires
+ * authentication via x-api-key header or Authorization Bearer token.
+ *
+ * Body parameters:
+ * - to (required): array of recipient email addresses
+ * - subject (required): email subject line
+ * - text (optional): plain text / Markdown body
+ * - html (optional): raw HTML body (takes precedence over text)
+ * - cc (optional): array of CC email addresses
+ * - headers (optional): custom email headers
+ * - chat_id (optional): chat ID for a chat link in the footer
+ * - account_id (optional): UUID of the account to send for (org keys only)
+ *
+ * Recipient restriction: without a payment method on file, to/cc are limited to
+ * the account's own email; a card on file lifts the restriction (403 otherwise).
+ *
+ * @param request - The request object.
+ * @returns A NextResponse with the send result.
+ */
+export async function POST(request: NextRequest): Promise<NextResponse> {
+ return sendEmailHandler(request);
+}
+
+export const dynamic = "force-dynamic";
+export const fetchCache = "force-no-store";
+export const revalidate = 0;

lib/agent/tools/__tests__/buildRecoupExecEnv.test.ts

@@ -62,4 +62,25 @@ describe("buildRecoupExecEnv", () => {
  RECOUP_ACCESS_TOKEN: "jwt.value",
  });
  });
+
+ // recoupable/chat#1815: both a Privy JWT and an ephemeral `recoup_sk_` API
+ // key surface as RECOUP_ACCESS_TOKEN (Bearer). The server parses the token
+ // format and authenticates a `recoup_sk_` key over Bearer too, so there is no
+ // client-side x-api-key routing here.
+ it("surfaces a recoup_sk_ API key as RECOUP_ACCESS_TOKEN (Bearer)", () => {
+ const env = buildRecoupExecEnv({
+ sandbox: baseSandbox,
+ recoupAccessToken: "recoup_sk_abc123",
+ });
+ expect(env).toEqual({ RECOUP_ACCESS_TOKEN: "recoup_sk_abc123" });
+ });
+
+ it("injects RECOUP_ORG_ID alongside a recoup_sk_ key", () => {
+ const env = buildRecoupExecEnv({
+ sandbox: baseSandbox,
+ recoupOrgId: "org-uuid",
+ recoupAccessToken: "recoup_sk_xyz",
+ });
+ expect(env).toEqual({ RECOUP_ORG_ID: "org-uuid", RECOUP_ACCESS_TOKEN: "recoup_sk_xyz" });
+ });
 });

lib/agent/tools/buildRecoupExecEnv.ts

@@ -7,12 +7,14 @@ import { isAgentContext } from "@/lib/agent/tools/isAgentContext";
  *
  * Injects:
  * - `RECOUP_ORG_ID` — public organization UUID. Always safe.
- * - `RECOUP_ACCESS_TOKEN` — short-lived Privy JWT, when the handler
- * plumbed one through `AgentContext.recoupAccessToken`. Used by the
- * `recoup-api` skill's curl examples to authenticate as the user.
- * Long-lived api keys are deliberately NOT forwarded — only the
- * short-lived bearer token is, and only when the caller used
- * bearer auth (the handler enforces that gating).
+ * - `RECOUP_ACCESS_TOKEN` — the short-lived credential from
+ * `AgentContext.recoupAccessToken`, which the `recoup-api` skill sends as
+ * `Authorization: Bearer`. This may be a Privy JWT (interactive path) or an
+ * ephemeral `recoup_sk_` API key (headless `/api/chat/runs`) — the server
+ * parses the format and authenticates either over Bearer, so there's no
+ * client-side routing here (recoupable/chat#1815). Long-lived api keys are
+ * deliberately NOT forwarded — only the short-lived credential the handler
+ * plumbed through.
  *
  * Returns `undefined` when nothing is available to inject so callers can
  * cleanly spread a conditional `...(env ? { env } : {})` into exec opts.

lib/auth/__tests__/getAuthenticatedAccountId.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { NextRequest } from "next/server";
+import { getAuthenticatedAccountId } from "@/lib/auth/getAuthenticatedAccountId";
+import { getAccountIdByApiKey } from "@/lib/auth/getAccountIdByApiKey";
+import { getOrCreateAccountIdByAuthToken } from "@/lib/privy/getOrCreateAccountIdByAuthToken";
+
+vi.mock("@/lib/networking/getCorsHeaders", () => ({ getCorsHeaders: () => ({}) }));
+vi.mock("@/lib/auth/getAccountIdByApiKey", () => ({ getAccountIdByApiKey: vi.fn() }));
+vi.mock("@/lib/privy/getOrCreateAccountIdByAuthToken", () => ({
+ getOrCreateAccountIdByAuthToken: vi.fn(),
+}));
+
+function req(bearer?: string) {
+ const headers = new Headers();
+ if (bearer) headers.set("authorization", `Bearer ${bearer}`);
+ return new NextRequest("https://x.test/api", { headers });
+}
+
+describe("getAuthenticatedAccountId", () => {
+ beforeEach(() => vi.clearAllMocks());
+
+ it("401 when no bearer token", async () => {
+ const res = await getAuthenticatedAccountId(req());
+ expect((res as Response).status).toBe(401);
+ });
+
+ it("validates a recoup_sk_ Bearer token as an API key (no Privy call)", async () => {
+ vi.mocked(getAccountIdByApiKey).mockResolvedValue("acc-key");
+
+ const res = await getAuthenticatedAccountId(req("recoup_sk_abc"));
+
+ expect(res).toBe("acc-key");
+ expect(getAccountIdByApiKey).toHaveBeenCalledWith("recoup_sk_abc");
+ expect(getOrCreateAccountIdByAuthToken).not.toHaveBeenCalled();
+ });
+
+ it("401 when a recoup_sk_ Bearer key is unknown/expired", async () => {
+ vi.mocked(getAccountIdByApiKey).mockResolvedValue(null);
+
+ const res = await getAuthenticatedAccountId(req("recoup_sk_bad"));
+
+ expect((res as Response).status).toBe(401);
+ expect(getOrCreateAccountIdByAuthToken).not.toHaveBeenCalled();
+ });
+
+ it("treats a non-recoup_sk_ token as a Privy JWT (no API-key call)", async () => {
+ vi.mocked(getOrCreateAccountIdByAuthToken).mockResolvedValue("acc-privy");
+
+ const res = await getAuthenticatedAccountId(req("eyJhbGci.jwt.value"));
+
+ expect(res).toBe("acc-privy");
+ expect(getOrCreateAccountIdByAuthToken).toHaveBeenCalledWith("eyJhbGci.jwt.value");
+ expect(getAccountIdByApiKey).not.toHaveBeenCalled();
+ });
+});

lib/auth/getAccountIdByApiKey.ts

@@ -0,0 +1,35 @@
+import { hashApiKey } from "@/lib/keys/hashApiKey";
+import { isApiKeyExpired } from "@/lib/keys/isApiKeyExpired";
+import { PRIVY_PROJECT_SECRET } from "@/lib/const";
+import { selectAccountApiKeys } from "@/lib/supabase/account_api_keys/selectAccountApiKeys";
+
+/**
+ * Resolve the account id for a raw Recoup API key (`recoup_sk_…`), or `null`
+ * when the key is unknown, the lookup fails, or the key is past its `expires_at`
+ * TTL (ephemeral keys — chat#1813).
+ *
+ * Shared by both auth entry points so a `recoup_sk_` key authenticates the same
+ * way whether it arrives as `x-api-key` (`getApiKeyAccountId`) or as
+ * `Authorization: Bearer` (`getAuthenticatedAccountId`).
+ *
+ * @param apiKey - The raw API key string.
+ */
+export async function getAccountIdByApiKey(apiKey: string): Promise<string | null> {
+ const keyHash = hashApiKey(apiKey, PRIVY_PROJECT_SECRET);
+ const apiKeys = await selectAccountApiKeys({ keyHash });
+
+ if (apiKeys === null) {
+ console.error("[ERROR] selectAccountApiKeys returned null");
+ return null;
+ }
+
+ const matched = apiKeys[0];
+ const accountId = matched?.account ?? null;
+
+ // Reject an unknown key, or an ephemeral key past its TTL.
+ if (!accountId || isApiKeyExpired(matched?.expires_at)) {
+ return null;
+ }
+
+ return accountId;
+}

lib/auth/getApiKeyAccountId.ts

@@ -1,13 +1,11 @@
 import { NextRequest, NextResponse } from "next/server";
 import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
-import { hashApiKey } from "@/lib/keys/hashApiKey";
-import { isApiKeyExpired } from "@/lib/keys/isApiKeyExpired";
-import { PRIVY_PROJECT_SECRET } from "@/lib/const";
-import { selectAccountApiKeys } from "@/lib/supabase/account_api_keys/selectAccountApiKeys";
+import { getAccountIdByApiKey } from "@/lib/auth/getAccountIdByApiKey";
 
 /**
- * Extracts and validates the API key from the request,
- * then returns the associated account ID.
+ * Extracts the API key from the `x-api-key` header and returns the associated
+ * account ID, delegating the hash/lookup/TTL check to `getAccountIdByApiKey`
+ * (shared with the Bearer path).
  *
  * @param request - The NextRequest object
  * @returns Either the account ID string, or a NextResponse error if validation fails
@@ -17,64 +15,19 @@ export async function getApiKeyAccountId(request: NextRequest): Promise<string |
 
  if (!apiKey) {
  return NextResponse.json(
- {
- status: "error",
- message: "x-api-key header required",
- },
- {
- status: 401,
- headers: getCorsHeaders(),
- },
+ { status: "error", message: "x-api-key header required" },
+ { status: 401, headers: getCorsHeaders() },
  );
  }
 
- try {
- const keyHash = hashApiKey(apiKey, PRIVY_PROJECT_SECRET);
- const apiKeys = await selectAccountApiKeys({ keyHash });
+ const accountId = await getAccountIdByApiKey(apiKey);
 
- if (apiKeys === null) {
- console.error("[ERROR] selectAccountApiKeys returned null");
- return NextResponse.json(
- {
- status: "error",
- message: "Internal server error",
- },
- {
- status: 500,
- headers: getCorsHeaders(),
- },
- );
- }
-
- const matched = apiKeys[0];
- const accountId = matched?.account ?? null;
-
- // Reject an unknown key, or an ephemeral key past its TTL (chat#1813).
- if (!accountId || isApiKeyExpired(matched?.expires_at)) {
- return NextResponse.json(
- {
- status: "error",
- message: "Unauthorized",
- },
- {
- status: 401,
- headers: getCorsHeaders(),
- },
- );
- }
-
- return accountId;
- } catch (error) {
- console.error("[ERROR] getApiKeyAccountId:", error);
+ if (!accountId) {
  return NextResponse.json(
- {
- status: "error",
- message: "Internal server error",
- },
- {
- status: 500,
- headers: getCorsHeaders(),
- },
+ { status: "error", message: "Unauthorized" },
+ { status: 401, headers: getCorsHeaders() },
  );
  }
+
+ return accountId;
 }

lib/auth/getAuthenticatedAccountId.ts

@@ -1,14 +1,19 @@
 import { NextRequest, NextResponse } from "next/server";
 import { getBearerToken } from "@/lib/auth/getBearerToken";
+import { getAccountIdByApiKey } from "@/lib/auth/getAccountIdByApiKey";
 import { getOrCreateAccountIdByAuthToken } from "@/lib/privy/getOrCreateAccountIdByAuthToken";
 import { getCorsHeaders } from "@/lib/networking/getCorsHeaders";
 
 /**
  * Extracts and validates the authentication token from the request,
- * then returns the authenticated account ID. A recoupable account is
- * provisioned on the fly when none yet exists for the user's Privy
- * email, mirroring the idempotent fetch-or-create semantics of
- * `POST /api/accounts`.
+ * then returns the authenticated account ID.
+ *
+ * The Bearer token may be either a Recoup API key (`recoup_sk_…`) or a Privy
+ * access token — the server parses the format and routes accordingly, so a
+ * caller only ever needs to set one credential. A `recoup_sk_` key is validated
+ * against `account_api_keys`; anything else is treated as a Privy JWT, and a
+ * recoupable account is provisioned on the fly when none yet exists for the
+ * user's Privy email (idempotent fetch-or-create, mirroring `POST /api/accounts`).
  *
  * @param request - The NextRequest object
  * @returns Either the account ID string, or a NextResponse error if authentication fails
@@ -32,6 +37,19 @@ export async function getAuthenticatedAccountId(
  );
  }
 
+ // A Recoup API key sent as a Bearer token: validate it as an API key instead
+ // of attempting (and failing) Privy JWT verification.
+ if (authToken.startsWith("recoup_sk_")) {
+ const accountId = await getAccountIdByApiKey(authToken);
+ if (!accountId) {
+ return NextResponse.json(
+ { status: "error", message: "Unauthorized" },
+ { status: 401, headers: getCorsHeaders() },
+ );
+ }
+ return accountId;
+ }
+
  try {
  const accountId = await getOrCreateAccountIdByAuthToken(authToken);
  return accountId;

lib/emails/__tests__/assertRecipientsAllowed.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { assertRecipientsAllowed } from "../assertRecipientsAllowed";
+
+const mockAccountHasPaymentMethod = vi.fn();
+const mockSelectAccountEmails = vi.fn();
+
+vi.mock("@/lib/stripe/accountHasPaymentMethod", () => ({
+ accountHasPaymentMethod: (...args: unknown[]) => mockAccountHasPaymentMethod(...args),
+}));
+
+vi.mock("@/lib/supabase/account_emails/selectAccountEmails", () => ({
+ default: (...args: unknown[]) => mockSelectAccountEmails(...args),
+}));
+
+describe("assertRecipientsAllowed", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ mockSelectAccountEmails.mockResolvedValue([{ email: "owner@account.com" }]);
+ });
+
+ it("allows any recipient when a payment method is on file", async () => {
+ mockAccountHasPaymentMethod.mockResolvedValue(true);
+
+ const result = await assertRecipientsAllowed({
+ accountId: "acct-1",
+ recipients: ["stranger@example.com", "another@example.com"],
+ });
+
+ expect(result.allowed).toBe(true);
+ // No need to look up account emails when a card is on file.
+ expect(mockSelectAccountEmails).not.toHaveBeenCalled();
+ });
+
+ it("allows the account's own email without a payment method (case-insensitive)", async () => {
+ mockAccountHasPaymentMethod.mockResolvedValue(false);
+
+ const result = await assertRecipientsAllowed({
+ accountId: "acct-1",
+ recipients: ["OWNER@Account.com"],
+ });
+
+ expect(result.allowed).toBe(true);
+ });
+
+ it("blocks foreign recipients without a payment method and lists them", async () => {
+ mockAccountHasPaymentMethod.mockResolvedValue(false);
+
+ const result = await assertRecipientsAllowed({
+ accountId: "acct-1",
+ recipients: ["owner@account.com", "stranger@example.com"],
+ });
+
+ expect(result.allowed).toBe(false);
+ if (result.allowed === false) {
+ expect(result.disallowed).toEqual(["stranger@example.com"]);
+ }
+ });
+});