Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

docs(secret-rotation): drop the stripe rotation plan and design spec

Calvine00a0ab4a60b
diff --git a/docs/superpowers/plans/2026-09-18-stripe-api-key-rotation.md b/docs/superpowers/plans/2026-09-18-stripe-api-key-rotation.md
deleted file mode 100644
index 41d8f4cf64..0000000000
--- a/docs/superpowers/plans/2026-09-18-stripe-api-key-rotation.md
+++ /dev/null
@@ -1,2055 +0,0 @@
-# Stripe API Key Secret Rotation Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add a Stripe API key secret rotation provider that mints a new restricted key on each rotation and expires the one from two rotations ago, using the existing Stripe app connection.
-
-**Architecture:** A rotation factory in `backend/src/ee/services/secret-rotation-v2/stripe-api-key/` following the sibling providers. Rotation is create-then-retire, never Stripe's `rotate` endpoint, because `rotate` kills the old token instantly. The framework's two-slot credential model supplies the handover window. Stripe encrypts the new secret to a public key we supply, so each create generates a throwaway RSA keypair and decrypts the JWE in-process.
-
-**Tech Stack:** TypeScript, Fastify 4, Zod, Knex, BullMQ, Vitest, React 18, TanStack Query, react-hook-form.
-
-**Spec:** `docs/superpowers/specs/2026-09-17-stripe-api-key-rotation-design.md`
-
-## Global Constraints
-
-- Read `backend/CODE_QUALITY.md` before any backend task and check the work against it before calling a task done.
-- Default to no comments. A comment earns its place only by explaining why: a non-obvious constraint, a workaround, or an ordering dependency. Never narrate the next line.
-- Every Stripe HTTP call happens outside the database transaction. The transaction is opened inside the framework's callback and touches only Postgres.
-- Never log a raw Stripe response body. The key list endpoint returns plaintext secrets.
-- No em dashes in any prose, including docs and code comments.
-- Frontend UI follows `DESIGN.md` v3 components. Use `@app/components/v3`, never v2, in new files.
-- Preview API version is `2026-08-26.preview` and is defined in exactly one place.
-- Stripe key ids look like `mk_...`, and the secrets they carry are `rk_...` restricted keys. Never assert an `sk_` prefix.
-
-## Corrections to the spec, applied in this plan
-
-Two spec statements turned out to be unbuildable as written. The plan supersedes them.
-
-- The spec says the 158 permission names ship as "one backend constant, frontend imports that same list". The frontend and backend are separate packages and cannot import each other. Instead the names ride on the rotation's list-option `template`, which the form already reads through `useSecretRotationV2Option`.
-- The spec names minted keys `infisical-rotation-<rotationId>-<timestamp>`. At create time the factory receives only `{ parameters, secretsMapping, connection, rotationInterval }` (`secret-rotation-v2-service.ts:614`), so there is no rotation id. Keys are named from the mapped secret name instead.
-
----
-
-### Task 1: Stripe public client
-
-Extracts the auth, headers and error shaping that are currently private inside `stripe-connection-fns.ts`, so rotation and the connection check share one definition.
-
-**Files:**
-- Create: `backend/src/services/app-connection/stripe/stripe-connection-public-client.ts`
-- Create: `backend/src/services/app-connection/stripe/stripe-connection-public-client.test.ts`
-- Modify: `backend/src/services/app-connection/stripe/stripe-connection-fns.ts`
-
-**Interfaces:**
-- Consumes: nothing.
-- Produces: `STRIPE_PREVIEW_API_VERSION: string`, `STRIPE_API_KEYS_URL: string`, `getStripeSecretKey(): string`, `getStripePlatformRequestConfig(accountId: string): AxiosRequestConfig`, `getStripeMerchantRequestConfig(apiKey: string): AxiosRequestConfig`, `withIdempotencyKey(config: AxiosRequestConfig): AxiosRequestConfig`, `getStripeErrorMessage(error: unknown): string`, `getStripeErrorStatus(error: unknown): number | undefined`, `throwStripeApiKeyManagementError(accountId: string, error: unknown): never`.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `backend/src/services/app-connection/stripe/stripe-connection-public-client.test.ts`:
-
-```ts
-import { AxiosError } from "axios";
-import { describe, expect, it, vi } from "vitest";
-
-vi.mock("@app/lib/config/env", () => ({
- getConfig: () => ({ INF_APP_CONNECTION_STRIPE_SECRET_KEY: "sk_test_platform" })
-}));
-
-// eslint-disable-next-line import/first
-import {
- getStripeErrorMessage,
- getStripeErrorStatus,
- getStripeMerchantRequestConfig,
- getStripePlatformRequestConfig,
- STRIPE_PREVIEW_API_VERSION,
- withIdempotencyKey
-} from "./stripe-connection-public-client";
-
-const axiosErrorWith = (status: number, data: unknown) =>
- new AxiosError("Request failed", "ERR_BAD_REQUEST", undefined, undefined, {
- status,
- statusText: "",
- headers: {},
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- config: {} as any,
- data
- });
-
-describe("stripe public client", () => {
- it("authenticates as the platform and names the account", () => {
- const config = getStripePlatformRequestConfig("acct_123");
-
- expect(config.auth).toEqual({ username: "sk_test_platform", password: "" });
- expect(config.headers).toEqual({
- "Stripe-Version": STRIPE_PREVIEW_API_VERSION,
- "Stripe-Context": "acct_123"
- });
- });
-
- it("authenticates as a merchant key without context or preview version", () => {
- const config = getStripeMerchantRequestConfig("rk_test_merchant");
-
- expect(config.auth).toEqual({ username: "rk_test_merchant", password: "" });
- expect(config.headers).toBeUndefined();
- });
-
- it("adds an idempotency key without dropping existing headers", () => {
- const config = withIdempotencyKey(getStripePlatformRequestConfig("acct_123"));
-
- expect(config.headers?.["Stripe-Context"]).toBe("acct_123");
- expect(config.headers?.["Idempotency-Key"]).toMatch(
- /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
- );
- });
-
- it("reads Stripe's own error message when there is one", () => {
- const error = axiosErrorWith(400, { error: { message: "Invalid permissions: nope" } });
-
- expect(getStripeErrorMessage(error)).toBe("Invalid permissions: nope");
- expect(getStripeErrorStatus(error)).toBe(400);
- });
-
- it("falls back to the axios message and handles plain errors", () => {
- expect(getStripeErrorMessage(axiosErrorWith(500, undefined))).toBe("Request failed");
- expect(getStripeErrorMessage(new Error("socket hang up"))).toBe("socket hang up");
- expect(getStripeErrorStatus(new Error("socket hang up"))).toBeUndefined();
- });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `make test-api-unit SPEC=stripe-connection-public-client`
-Expected: FAIL, cannot resolve `./stripe-connection-public-client`.
-
-- [ ] **Step 3: Write the implementation**
-
-Create `backend/src/services/app-connection/stripe/stripe-connection-public-client.ts`:
-
-```ts
-import crypto from "node:crypto";
-
-import { AxiosError, AxiosRequestConfig } from "axios";
-
-import { getConfig } from "@app/lib/config/env";
-import { BadRequestError, InternalServerError } from "@app/lib/errors";
-import { IntegrationUrls } from "@app/services/integration-auth/integration-list";
-
-// The Managed API Keys API is in private preview and is only served under a preview API version.
-export const STRIPE_PREVIEW_API_VERSION = "2026-08-26.preview";
-
-export const STRIPE_API_KEYS_URL = `${IntegrationUrls.STRIPE_API_URL}/v2/iam/api_keys`;
-
-export const getStripeSecretKey = () => {
- const { INF_APP_CONNECTION_STRIPE_SECRET_KEY } = getConfig();
-
- if (!INF_APP_CONNECTION_STRIPE_SECRET_KEY) {
- throw new InternalServerError({
- message: "Stripe is not configured on this instance. Set the Stripe App Connection credentials to enable it."
- });
- }
-
- return INF_APP_CONNECTION_STRIPE_SECRET_KEY;
-};
-
-/** Infisical acting on a customer's account: our own key, with Stripe-Context naming the account. */
-export const getStripePlatformRequestConfig = (accountId: string): AxiosRequestConfig => ({
- auth: { username: getStripeSecretKey(), password: "" },
- headers: {
- "Stripe-Version": STRIPE_PREVIEW_API_VERSION,
- "Stripe-Context": accountId
- }
-});
-
-/** A rotated merchant key acting as itself. It is not the platform, so it carries neither header. */
-export const getStripeMerchantRequestConfig = (apiKey: string): AxiosRequestConfig => ({
- auth: { username: apiKey, password: "" }
-});
-
-export const withIdempotencyKey = (config: AxiosRequestConfig): AxiosRequestConfig => ({
- ...config,
- headers: { ...config.headers, "Idempotency-Key": crypto.randomUUID() }
-});
-```
-
-Axios types `headers` as a union that includes `AxiosHeaders`, so if the spread above does not
-type-check, narrow it with `...(config.headers as Record<string, string>)` rather than widening the
-helper's return type.
-
-```ts
-
-export const getStripeErrorMessage = (error: unknown): string => {
- if (error instanceof AxiosError) {
- const message = (error.response?.data as { error?: { message?: string } } | undefined)?.error?.message;
-
- return typeof message === "string" ? message : error.message;
- }
-
- return (error as Error)?.message ?? "Unknown error";
-};
-
-export const getStripeErrorStatus = (error: unknown): number | undefined =>
- error instanceof AxiosError ? error.response?.status : undefined;
-
-/**
- * Nothing proactively notices that a customer uninstalled the app, because the connection stores no
- * tokens, so it arrives here as a 403. The remedy is offered conditionally rather than asserted.
- */
-export const throwStripeApiKeyManagementError = (accountId: string, error: unknown): never => {
- throw new BadRequestError({
- message:
- `Infisical cannot manage API keys on Stripe account '${accountId}'. ` +
- `Stripe returned ${getStripeErrorStatus(error) ?? "no status"}: ${getStripeErrorMessage(error)}. ` +
- `If the Infisical app was removed from this Stripe account, reinstall it and reconnect.`
- });
-};
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `make test-api-unit SPEC=stripe-connection-public-client`
-Expected: PASS, 5 tests.
-
-- [ ] **Step 5: Refactor the connection onto the client**
-
-In `backend/src/services/app-connection/stripe/stripe-connection-fns.ts`, delete the local `STRIPE_PREVIEW_API_VERSION` constant and the local `getStripeSecretKey`, and import from the public client instead. Replace the body of `assertCanManageApiKeys` with:
-
-```ts
-const assertCanManageApiKeys = async (accountId: string) => {
- try {
- await request.get(STRIPE_API_KEYS_URL, getStripePlatformRequestConfig(accountId));
- } catch (error) {
- throwStripeApiKeyManagementError(accountId, error);
- }
-};
-```
-
-Keep `exchangeStripeOAuthCode` as it is, other than sourcing `getStripeSecretKey` from the client. Its error handling reads `error_description`, which is an OAuth-shaped body rather than a Stripe API error, so it does not use `getStripeErrorMessage`.
-
-- [ ] **Step 6: Verify nothing else broke**
-
-Run: `cd backend && npm run type:check`
-Expected: no errors.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add backend/src/services/app-connection/stripe/
-git commit -m "refactor(app-connections): extract shared Stripe request client"
-```
-
----
-
-### Task 2: JWE decryption
-
-Isolated crypto with no HTTP in it, so it can be tested exhaustively against fixtures. Also pins the FIPS behaviour the whole live-mode path depends on.
-
-**Files:**
-- Create: `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-jwe.ts`
-- Create: `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-jwe.test.ts`
-
-**Interfaces:**
-- Consumes: nothing.
-- Produces: `generateStripeEncryptionKeyPair(): Promise<{ publicKey: string; privateKey: string }>`, `decryptStripeJwe(jwe: string, privateKeyPem: string): string`, `readStripeSecret(secretKey: TStripeSecretKeyField | undefined, privateKeyPem: string): string`, and the type `TStripeSecretKeyField = { token?: string | null; encrypted_secret?: { ciphertext?: string | null } | null }`.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-jwe.test.ts`:
-
-```ts
-import crypto from "node:crypto";
-
-import { describe, expect, it } from "vitest";
-
-import {
- decryptStripeJwe,
- generateStripeEncryptionKeyPair,
- readStripeSecret
-} from "./stripe-api-key-jwe";
-
-/** Builds the compact JWE Stripe would return, so the test proves the real unwrap path. */
-const encryptJwe = (
- plaintext: string,
- publicKeyPem: string,
- { alg = "RSA-OAEP", enc = "A256GCM" }: { alg?: string; enc?: string } = {}
-) => {
- const header = Buffer.from(JSON.stringify({ alg, enc })).toString("base64url");
- const contentKey = crypto.randomBytes(32);
- const wrapped = crypto.publicEncrypt(
- {
- key: publicKeyPem,
- padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
- oaepHash: alg === "RSA-OAEP" ? "sha1" : "sha256"
- },
- contentKey
- );
- const iv = crypto.randomBytes(12);
- const cipher = crypto.createCipheriv("aes-256-gcm", contentKey, iv);
- cipher.setAAD(Buffer.from(header, "ascii"));
- const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
-
- return [
- header,
- wrapped.toString("base64url"),
- iv.toString("base64url"),
- ciphertext.toString("base64url"),
- cipher.getAuthTag().toString("base64url")
- ].join(".");
-};
-
-describe("decryptStripeJwe", () => {
- it("round-trips both algorithms Stripe may use, under FIPS", async () => {
- // The unit suite runs with --force-fips. OAEP with SHA-1 is the algorithm Stripe returns as
- // `RSA-OAEP`, and this assertion is what stops a toolchain bump from breaking live mode silently.
- expect(crypto.getFips()).toBe(1);
-
- const { publicKey, privateKey } = await generateStripeEncryptionKeyPair();
-
- for (const alg of ["RSA-OAEP", "RSA-OAEP-256"]) {
- const jwe = encryptJwe("rk_live_secret", publicKey, { alg });
- expect(decryptStripeJwe(jwe, privateKey)).toBe("rk_live_secret");
- }
- });
-
- it("rejects a JWE without exactly five segments", async () => {
- const { privateKey } = await generateStripeEncryptionKeyPair();
-
- expect(() => decryptStripeJwe("a.b.c", privateKey)).toThrow(/5 segments, got 3/);
- });
-
- it("names an unsupported key algorithm rather than guessing", async () => {
- const { publicKey, privateKey } = await generateStripeEncryptionKeyPair();
- const jwe = encryptJwe("rk_live_secret", publicKey, { alg: "RSA1_5" });
-
- expect(() => decryptStripeJwe(jwe, privateKey)).toThrow(/RSA1_5/);
- });
-
- it("rejects an unsupported content encryption algorithm", async () => {
- const { publicKey, privateKey } = await generateStripeEncryptionKeyPair();
- const jwe = encryptJwe("rk_live_secret", publicKey, { enc: "A128GCM" });
-
- expect(() => decryptStripeJwe(jwe, privateKey)).toThrow(/A128GCM/);
- });
-
- it("fails a tampered ciphertext", async () => {
- const { publicKey, privateKey } = await generateStripeEncryptionKeyPair();
- const segments = encryptJwe("rk_live_secret", publicKey).split(".");
- segments[4] = Buffer.alloc(16).toString("base64url");
-
- expect(() => decryptStripeJwe(segments.join("."), privateKey)).toThrow();
- });
-});
-
-describe("readStripeSecret", () => {
- it("prefers the plaintext token test mode returns", async () => {
- const { privateKey } = await generateStripeEncryptionKeyPair();
-
- expect(readStripeSecret({ token: "rk_test_plain", encrypted_secret: null }, privateKey)).toBe(
- "rk_test_plain"
- );
- });
-
- it("decrypts the JWE live mode returns", async () => {
- const { publicKey, privateKey } = await generateStripeEncryptionKeyPair();
- const jwe = encryptJwe("rk_live_secret", publicKey);
-
- expect(readStripeSecret({ encrypted_secret: { ciphertext: jwe } }, privateKey)).toBe(
- "rk_live_secret"
- );
- });
-
- it("throws when Stripe returns neither", async () => {
- const { privateKey } = await generateStripeEncryptionKeyPair();
-
- expect(() => readStripeSecret({}, privateKey)).toThrow(/without a secret/);
- expect(() => readStripeSecret(undefined, privateKey)).toThrow(/without a secret/);
- });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `make test-api-unit SPEC=stripe-api-key-jwe`
-Expected: FAIL, cannot resolve `./stripe-api-key-jwe`.
-
-- [ ] **Step 3: Write the implementation**
-
-Create `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-jwe.ts`:
-
-```ts
-import crypto from "node:crypto";
-
-import { BadRequestError } from "@app/lib/errors";
-
-export type TStripeSecretKeyField = {
- token?: string | null;
- encrypted_secret?: { ciphertext?: string | null } | null;
-};
-
-// Stripe names OAEP with SHA-1 `RSA-OAEP`, which is the JOSE spelling. Both are accepted by the
-// FIPS provider for key transport, so neither needs a fallback.
-const SUPPORTED_KEY_ALGORITHMS: Record<string, "sha1" | "sha256"> = {
- "RSA-OAEP": "sha1",
- "RSA-OAEP-256": "sha256"
-};
-
-const SUPPORTED_CONTENT_ALGORITHM = "A256GCM";
-
-export const generateStripeEncryptionKeyPair = async () =>
- new Promise<{ publicKey: string; privateKey: string }>((resolve, reject) => {
- crypto.generateKeyPair(
- "rsa",
- {
- modulusLength: 2048,
- publicKeyEncoding: { type: "spki", format: "pem" },
- privateKeyEncoding: { type: "pkcs8", format: "pem" }
- },
- (error, publicKey, privateKey) => (error ? reject(error) : resolve({ publicKey, privateKey }))
- );
- });
-
-export const decryptStripeJwe = (jwe: string, privateKeyPem: string): string => {
- const segments = jwe.split(".");
-
- if (segments.length !== 5) {
- throw new BadRequestError({
- message: `Stripe returned a malformed encrypted secret: expected a compact JWE with 5 segments, got ${segments.length}.`
- });
- }
-
- const [protectedHeader, wrappedKey, iv, ciphertext, authTag] = segments;
-
- let header: { alg?: string; enc?: string };
-
- try {
- header = JSON.parse(Buffer.from(protectedHeader, "base64url").toString()) as typeof header;
- } catch {
- throw new BadRequestError({
- message: "Stripe returned an encrypted secret whose JWE header could not be parsed."
- });
- }
-
- const oaepHash = header.alg ? SUPPORTED_KEY_ALGORITHMS[header.alg] : undefined;
-
- if (!oaepHash) {
- throw new BadRequestError({
- message: `Stripe encrypted the secret with an unsupported key algorithm '${header.alg ?? "none"}'. Infisical supports RSA-OAEP and RSA-OAEP-256.`
- });
- }
-
- if (header.enc !== SUPPORTED_CONTENT_ALGORITHM) {
- throw new BadRequestError({
- message: `Stripe encrypted the secret with an unsupported content algorithm '${header.enc ?? "none"}'. Infisical supports ${SUPPORTED_CONTENT_ALGORITHM}.`
- });
- }
-
- const contentKey = crypto.privateDecrypt(
- { key: privateKeyPem, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash },
- Buffer.from(wrappedKey, "base64url")
- );
-
- const decipher = crypto.createDecipheriv("aes-256-gcm", contentKey, Buffer.from(iv, "base64url"));
- decipher.setAAD(Buffer.from(protectedHeader, "ascii"));
- decipher.setAuthTag(Buffer.from(authTag, "base64url"));
-
- return Buffer.concat([decipher.update(Buffer.from(ciphertext, "base64url")), decipher.final()]).toString();
-};
-
-/**
- * Test and sandbox accounts return the secret in plaintext, live accounts return a JWE. Both shapes
- * are real, and the one we develop against is not the one that matters.
- */
-export const readStripeSecret = (secretKey: TStripeSecretKeyField | undefined, privateKeyPem: string): string => {
- if (secretKey?.token) return secretKey.token;
-
- const ciphertext = secretKey?.encrypted_secret?.ciphertext;
-
- if (!ciphertext) {
- throw new BadRequestError({
- message: "Stripe returned an API key without a secret. The key may need to be created again."
- });
- }
-
- return decryptStripeJwe(ciphertext, privateKeyPem);
-};
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `make test-api-unit SPEC=stripe-api-key-jwe`
-Expected: PASS, 8 tests.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add backend/src/ee/services/secret-rotation-v2/stripe-api-key/
-git commit -m "feat(secret-rotation): add Stripe JWE secret decryption"
-```
-
----
-
-### Task 3: List API keys for the form, without leaking secrets
-
-Stripe returns every key's plaintext secret in the list response. This task exists as much to strip that as to paginate.
-
-**Files:**
-- Modify: `backend/src/services/app-connection/stripe/stripe-connection-public-client.ts`
-- Create: `backend/src/services/app-connection/stripe/stripe-connection-service.ts`
-- Create: `backend/src/services/app-connection/stripe/stripe-connection-service.test.ts`
-- Modify: `backend/src/services/app-connection/stripe/index.ts`
-- Modify: `backend/src/services/app-connection/app-connection-service.ts:1415`
-- Modify: `backend/src/server/routes/v1/app-connection-routers/stripe-connection-router.ts`
-
-**Interfaces:**
-- Consumes: `getStripePlatformRequestConfig`, `STRIPE_API_KEYS_URL`, `throwStripeApiKeyManagementError` from Task 1.
-- Produces: `listStripeApiKeys(accountId: string): Promise<TStripeApiKeyListItem[]>` from the public client, and `stripeConnectionService(getAppConnection)` exposing `listApiKeys(connectionId, actor): Promise<TStripeApiKeySummary[]>` where `TStripeApiKeySummary = { id: string; name: string; status: string; permissions: string[]; connectPermissions: string[] }`.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `backend/src/services/app-connection/stripe/stripe-connection-service.test.ts`:
-
-```ts
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const { getMock } = vi.hoisted(() => ({ getMock: vi.fn() }));
-
-vi.mock("@app/lib/config/env", () => ({
- getConfig: () => ({ INF_APP_CONNECTION_STRIPE_SECRET_KEY: "sk_test_platform" })
-}));
-vi.mock("@app/lib/config/request", () => ({
- // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return
- request: { get: (...args: unknown[]) => (getMock as any)(...args) }
-}));
-vi.mock("@app/lib/logger", () => ({
- logger: { error: vi.fn(), info: vi.fn(), warn: vi.fn(), debug: vi.fn() }
-}));
-
-// eslint-disable-next-line import/first
-import { stripeConnectionService } from "./stripe-connection-service";
-
-const keyPage = (id: string, next?: string) => ({
- data: {
- data: [
- {
- id,
- name: `key-${id}`,
- status: "active",
- permissions: ["charge_read"],
- connect_permissions: [],
- // Stripe really does return this, in full, for every key.
- secret_key: { token: `rk_test_${id}_full_plaintext_secret`, secret_token_redacted: "rk_test_...ab12" }
- }
- ],
- next_page_url: next ?? null
- }
-});
-
-const makeService = () =>
- stripeConnectionService(
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- vi.fn(async () => ({ credentials: { accountId: "acct_123" } })) as any
- );
-
-describe("stripeConnectionService.listApiKeys", () => {
- beforeEach(() => getMock.mockReset());
-
- it("never returns the plaintext secret Stripe includes in every list item", async () => {
- getMock.mockResolvedValueOnce(keyPage("mk_1"));
-
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- const keys = await makeService().listApiKeys("connection-id", {} as any);
-
- expect(keys).toEqual([
- {
- id: "mk_1",
- name: "key-mk_1",
- status: "active",
- permissions: ["charge_read"],
- connectPermissions: []
- }
- ]);
- expect(JSON.stringify(keys)).not.toContain("plaintext_secret");
- expect(JSON.stringify(keys)).not.toContain("secret_key");
- });
-
- it("follows next_page_url instead of returning only the first page", async () => {
- getMock
- .mockResolvedValueOnce(keyPage("mk_1", "https://api.stripe.com/v2/iam/api_keys?page=2"))
- .mockResolvedValueOnce(keyPage("mk_2"));
-
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- const keys = await makeService().listApiKeys("connection-id", {} as any);
-
- expect(keys.map((key) => key.id)).toEqual(["mk_1", "mk_2"]);
- expect(getMock).toHaveBeenCalledTimes(2);
- expect(getMock.mock.calls[0][0]).toContain("limit=100");
- expect(getMock.mock.calls[1][0]).toBe("https://api.stripe.com/v2/iam/api_keys?page=2");
- });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `make test-api-unit SPEC=stripe-connection-service`
-Expected: FAIL, cannot resolve `./stripe-connection-service`.
-
-- [ ] **Step 3: Add the paginated list to the public client**
-
-Append to `stripe-connection-public-client.ts`, and add `/* eslint-disable no-await-in-loop */` as the first line of the file:
-
-```ts
-export type TStripeApiKeyListItem = {
- id: string;
- name?: string | null;
- status?: string | null;
- permissions?: string[] | null;
- connect_permissions?: string[] | null;
-};
-
-const STRIPE_LIST_PAGE_SIZE = 100;
-
-// Stripe rejects limit=200 with "The maximum page limit is 100", so this is the largest page it
-// serves. The page cap is a runaway guard, not an expected bound.
-const STRIPE_LIST_MAX_PAGES = 50;
-
-export const listStripeApiKeys = async (accountId: string): Promise<TStripeApiKeyListItem[]> => {
- const config = getStripePlatformRequestConfig(accountId);
- const keys: TStripeApiKeyListItem[] = [];
-
- let url: string | undefined = `${STRIPE_API_KEYS_URL}?limit=${STRIPE_LIST_PAGE_SIZE}`;
- let pages = 0;
-
- while (url && pages < STRIPE_LIST_MAX_PAGES) {
- const { data } = await request.get<{
- data?: TStripeApiKeyListItem[];
- next_page_url?: string | null;
- }>(url, config);
-
- keys.push(...(data?.data ?? []));
- url = data?.next_page_url ?? undefined;
- pages += 1;
- }
-
- if (url) {
- logger.warn(
- `listStripeApiKeys: stopped after ${STRIPE_LIST_MAX_PAGES} pages for account ${accountId}, the list is truncated`
- );
- }
-
- return keys;
-};
-```
-
-Add `import { request } from "@app/lib/config/request";` and `import { logger } from "@app/lib/logger";` to the file's imports.
-
-- [ ] **Step 4: Write the service**
-
-Create `backend/src/services/app-connection/stripe/stripe-connection-service.ts`:
-
-```ts
-import { OrgServiceActor } from "@app/lib/types";
-
-import { AppConnection } from "../app-connection-enums";
-import { listStripeApiKeys, throwStripeApiKeyManagementError } from "./stripe-connection-public-client";
-import { TStripeConnection } from "./stripe-connection-types";
-
-type TGetAppConnectionFunc = (
- app: AppConnection,
- connectionId: string,
- actor: OrgServiceActor
-) => Promise<TStripeConnection>;
-
-export type TStripeApiKeySummary = {
- id: string;
- name: string;
- status: string;
- permissions: string[];
- connectPermissions: string[];
-};
-
-export const stripeConnectionService = (getAppConnection: TGetAppConnectionFunc) => {
- const listApiKeys = async (connectionId: string, actor: OrgServiceActor): Promise<TStripeApiKeySummary[]> => {
- const appConnection = await getAppConnection(AppConnection.Stripe, connectionId, actor);
- const { accountId } = appConnection.credentials;
-
- try {
- const keys = await listStripeApiKeys(accountId);
-
- // Stripe returns secret_key.token, in full plaintext, for every key in the account. Mapping to
- // an explicit shape here is what keeps it out of the HTTP response.
- return keys.map((key) => ({
- id: key.id,
- name: key.name ?? "",
- status: key.status ?? "",
- permissions: key.permissions ?? [],
- connectPermissions: key.connect_permissions ?? []
- }));
- } catch (error) {
- return throwStripeApiKeyManagementError(accountId, error);
- }
- };
-
- return { listApiKeys };
-};
-```
-
-- [ ] **Step 5: Run test to verify it passes**
-
-Run: `make test-api-unit SPEC=stripe-connection-service`
-Expected: PASS, 2 tests.
-
-- [ ] **Step 6: Wire the service and the route**
-
-Add both of these to `backend/src/services/app-connection/stripe/index.ts`:
-
-```ts
-export * from "./stripe-connection-public-client";
-export * from "./stripe-connection-service";
-```
-
-The rotation factory imports the public client by its direct path, matching the Supabase rotation, but
-`app-connection-service.ts` resolves `stripeConnectionService` through this barrel.
-
-In `backend/src/services/app-connection/app-connection-service.ts`, beside `supabase:` at line 1415, add:
-
-```ts
- stripe: stripeConnectionService(connectAppConnectionById),
-```
-
-This is a plain object literal, so omitting it compiles and then 500s at runtime. Import `stripeConnectionService` from `./stripe` alongside the other connection service imports.
-
-In `backend/src/server/routes/v1/app-connection-routers/stripe-connection-router.ts`, add the endpoint after `registerAppConnectionEndpoints`:
-
-```ts
- // The below endpoints are not exposed and for Infisical App use
- server.route({
- method: "GET",
- url: `/:connectionId/api-keys`,
- config: {
- rateLimit: readLimit
- },
- schema: {
- operationId: "listStripeApiKeys",
- params: z.object({
- connectionId: z.string().uuid()
- }),
- response: {
- 200: z.object({
- // An allowlist, deliberately. Stripe's own list response carries every key's plaintext
- // secret, so a passthrough schema here would ship them to the browser.
- apiKeys: z
- .object({
- id: z.string(),
- name: z.string(),
- status: z.string(),
- permissions: z.string().array(),
- connectPermissions: z.string().array()
- })
- .array()
- })
- }
- },
- onRequest: verifyAuth([AuthMode.JWT, AuthMode.OAUTH]),
- handler: async (req) => {
- const { connectionId } = req.params;
-
- const apiKeys = await server.services.appConnection.stripe.listApiKeys(connectionId, req.permission);
-
- return { apiKeys };
- }
- });
-```
-
-Add the imports `z` from `zod`, `readLimit` from `@app/server/config/rateLimiter`, `verifyAuth` from `@app/server/plugins/auth/verify-auth`, and `AuthMode` from `@app/services/auth/auth-type`, matching `supabase-connection-router.ts`.
-
-- [ ] **Step 7: Verify**
-
-Run: `cd backend && npm run type:check`
-Expected: no errors.
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add backend/src/services/app-connection/ backend/src/server/routes/v1/app-connection-routers/stripe-connection-router.ts
-git commit -m "feat(app-connections): list Stripe API keys without exposing secrets"
-```
-
----
-
-### Task 4: Rotation schemas, types and constants
-
-**Files:**
-- Create: `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-rotation-constants.ts`
-- Create: `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-rotation-schemas.ts`
-- Create: `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-rotation-types.ts`
-- Create: `backend/src/ee/services/secret-rotation-v2/stripe-api-key/index.ts`
-- Modify: `backend/src/ee/services/secret-rotation-v2/secret-rotation-v2-enums.ts`
-- Modify: `backend/src/lib/api-docs/constants.ts`
-
-**Interfaces:**
-- Consumes: nothing.
-- Produces: `SecretRotation.StripeApiKey = "stripe-api-key"`, `STRIPE_API_KEY_PERMISSIONS` (readonly 158-name tuple), `STRIPE_API_KEY_ROTATION_LIST_OPTION`, `StripeApiKeyRotationSchema`, `CreateStripeApiKeyRotationSchema`, `UpdateStripeApiKeyRotationSchema`, `StripeApiKeyRotationGeneratedCredentialsSchema`, `StripeApiKeyRotationListItemSchema`, and the types `TStripeApiKeyRotation`, `TStripeApiKeyRotationInput`, `TStripeApiKeyRotationListItem`, `TStripeApiKeyRotationWithConnection`, `TStripeApiKeyRotationGeneratedCredentials`.
-
-- [ ] **Step 1: Add the enum member**
-
-In `backend/src/ee/services/secret-rotation-v2/secret-rotation-v2-enums.ts`, add to `SecretRotation`:
-
-```ts
- StripeApiKey = "stripe-api-key"
-```
-
-This breaks every exhaustive `Record<SecretRotation, ...>` map in the codebase, which is intended. Task 6 fixes them all.
-
-- [ ] **Step 2: Write the permission constant**
-
-Create `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-rotation-constants.ts` starting with the permission list. Stripe has no wildcard and no endpoint that lists these, so the list is maintained by hand and was enumerated by probing each name.
-
-```ts
-import { SecretRotation } from "@app/ee/services/secret-rotation-v2/secret-rotation-v2-enums";
-import { TSecretRotationV2ListItem } from "@app/ee/services/secret-rotation-v2/secret-rotation-v2-types";
-import { AppConnection } from "@app/services/app-connection/app-connection-enums";
-
-/**
- * Every permission the Managed API Keys API accepts. There is no wildcard, no unrestricted key type
- * and no endpoint that lists these, so full access means naming all 158. Verified by probing each
- * one against a gated sandbox.
- */
-export const STRIPE_API_KEY_PERMISSIONS = [
- "account_link_write",
- "adjustment_read",
- "api_key_write",
- "apple_pay_domain_read",
- "apple_pay_domain_write",
- "application_fee_read",
- "application_fee_write",
- "balance_read",
- "balance_transaction_source_read",
- "billing_analytics_meter_usage_read",
- "billing_clock_read",
- "billing_clock_write",
- "billing_intent_read",
- "billing_meter_event_read",
- "billing_meter_event_write",
- "billing_meter_read",
- "billing_meter_write",
- "billing_profile_read",
- "billing_profile_write",
- "billing_settings_read",
- "billing_settings_write",
- "capital_for_platforms_financing_offer_read",
- "capital_for_platforms_financing_offer_write",
- "capital_for_platforms_financing_summary_read",
- "capital_for_platforms_financing_transaction_read",
- "charge_read",
- "charge_write",
- "checkout_session_read",
- "checkout_session_write",
- "confirmation_token_client_read",
- "confirmation_token_client_write",
- "confirmation_token_read",
- "connected_account_read",
- "coupon_read",
- "coupon_write",
- "credit_note_read",
- "credit_note_write",
- "customer_portal_read",
- "customer_portal_write",
- "customer_read",
- "customer_session_read",
- "customer_session_write",
- "customer_write",
- "dispute_read",
- "dispute_write",
- "edit_link_write",
- "entitlement_read",
- "event_read",
- "fee_domain_resources_read",
- "file_read",
- "file_write",
- "financial_account_read",
- "inbound_transfer_read",
- "invoice_read",
- "invoice_write",
- "issuing_authorization_read",
- "issuing_authorization_write",
- "issuing_card_read",
- "issuing_card_write",
- "issuing_cardholder_read",
- "issuing_cardholder_write",
- "issuing_credit_ledger_read",
- "issuing_credit_ledger_write",
- "issuing_dispute_read",
- "issuing_dispute_write",
- "issuing_read",
- "issuing_token_network_data_read",
- "issuing_token_read",
- "issuing_token_write",
- "issuing_transaction_read",
- "issuing_transaction_write",
- "issuing_verification_write",
- "issuing_write",
- "mandate_read",
- "mandate_write",
- "order_read",
- "order_write",
- "outbound_payment_read",
- "outbound_transfer_read",
- "payment_intent_read",
- "payment_intent_write",
- "payment_links_read",
- "payment_links_write",
- "payment_method_configurations_read",
- "payment_method_configurations_write",
- "payment_method_domain_read",
- "payment_method_domain_write",
- "payment_method_read",
- "payment_method_write",
- "payment_records_read",
- "payment_records_write",
- "payout_intent_read",
- "payout_read",
- "payout_write",
- "plan_read",
- "plan_write",
- "product_catalog_import_read",
- "product_catalog_import_write",
- "product_read",
- "product_write",
- "promotion_code_read",
- "promotion_code_write",
- "provisioning_account_request_read",
- "provisioning_account_request_write",
- "provisioning_project_read",
- "provisioning_project_write",
- "provisioning_resource_read",
- "provisioning_resource_write",
- "quote_read",
- "quote_write",
- "rate_card_subscription_write",
- "rate_card_write",
- "received_credit_read",
- "received_debit_read",
- "recipient_verification_read",
- "report_runs_and_report_types_read",
- "report_runs_and_report_types_write",
- "review_read",
- "review_write",
- "secret_read",
- "secret_write",
- "setup_intent_read",
- "setup_intent_write",
- "shipping_rate_read",
- "shipping_rate_write",
- "sku_read",
- "sku_write",
- "source_read",
- "source_write",
- "subscription_read",
- "subscription_write",
- "tax_calculations_and_transactions_read",
- "tax_calculations_and_transactions_write",
- "tax_locations_read",
- "tax_locations_write",
- "tax_rate_read",
- "tax_rate_write",
- "tax_settings_read",
- "tax_settings_write",
- "terminal_configuration_read",
- "terminal_configuration_write",
- "terminal_connection_token_write",
- "terminal_location_read",
- "terminal_location_write",
- "terminal_reader_read",
- "terminal_reader_write",
- "token_read",
- "token_write",
- "top_up_read",
- "top_up_write",
- "transaction_read",
- "transfer_read",
- "transfer_write",
- "treasury_transaction_read",
- "usage_record_read",
- "usage_record_write",
- "webhook_read",
- "webhook_write"
-] as const;
-
-export const STRIPE_API_KEY_ROTATION_LIST_OPTION: TSecretRotationV2ListItem = {
- name: "Stripe API Key",
- type: SecretRotation.StripeApiKey,
- connection: AppConnection.Stripe,
- template: {
- secretsMapping: {
- apiKey: "STRIPE_API_KEY"
- },
- // The frontend picker reads the permission names from here. It cannot import this file, since
- // the frontend is a separate package, and Stripe has no endpoint that lists them.
- permissions: [...STRIPE_API_KEY_PERMISSIONS]
- }
-};
-```
-
-- [ ] **Step 3: Write the schemas**
-
-Create `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-rotation-schemas.ts`:
-
-```ts
-import { z } from "zod";
-
-import { SecretRotation } from "@app/ee/services/secret-rotation-v2/secret-rotation-v2-enums";
-import {
- BaseCreateSecretRotationSchema,
- BaseSecretRotationSchema,
- BaseUpdateSecretRotationSchema
-} from "@app/ee/services/secret-rotation-v2/secret-rotation-v2-schemas";
-import { SecretRotations } from "@app/lib/api-docs";
-import { SecretNameSchema } from "@app/server/lib/schemas";
-import { AppConnection } from "@app/services/app-connection/app-connection-enums";
-
-import { STRIPE_API_KEY_PERMISSIONS } from "./stripe-api-key-rotation-constants";
-
-export const StripeApiKeyPermissionSchema = z.enum(STRIPE_API_KEY_PERMISSIONS);
-
-export const StripeApiKeyRotationGeneratedCredentialsSchema = z
- .object({
- keyId: z.string(),
- apiKey: z.string()
- })
- .array()
- .min(1)
- .max(2);
-
-const StripeApiKeyRotationParametersSchema = z.object({
- permissions: StripeApiKeyPermissionSchema.array()
- .min(1, "At least one permission is required")
- .max(STRIPE_API_KEY_PERMISSIONS.length)
- .describe(SecretRotations.PARAMETERS.STRIPE_API_KEY.permissions),
- connectPermissions: StripeApiKeyPermissionSchema.array()
- .max(STRIPE_API_KEY_PERMISSIONS.length)
- .optional()
- .describe(SecretRotations.PARAMETERS.STRIPE_API_KEY.connectPermissions)
-});
-
-const StripeApiKeyRotationSecretsMappingSchema = z.object({
- apiKey: SecretNameSchema.describe(SecretRotations.SECRETS_MAPPING.STRIPE_API_KEY.apiKey)
-});
-
-export const StripeApiKeyRotationTemplateSchema = z.object({
- secretsMapping: z.object({
- apiKey: z.string()
- }),
- permissions: z.string().array()
-});
-
-export const StripeApiKeyRotationSchema = BaseSecretRotationSchema(SecretRotation.StripeApiKey).extend({
- type: z.literal(SecretRotation.StripeApiKey),
- parameters: StripeApiKeyRotationParametersSchema,
- secretsMapping: StripeApiKeyRotationSecretsMappingSchema
-});
-
-export const CreateStripeApiKeyRotationSchema = BaseCreateSecretRotationSchema(SecretRotation.StripeApiKey).extend({
- parameters: StripeApiKeyRotationParametersSchema,
- secretsMapping: StripeApiKeyRotationSecretsMappingSchema
-});
-
-export const UpdateStripeApiKeyRotationSchema = BaseUpdateSecretRotationSchema(SecretRotation.StripeApiKey).extend({
- parameters: StripeApiKeyRotationParametersSchema.optional(),
- secretsMapping: StripeApiKeyRotationSecretsMappingSchema.optional()
-});
-
-export const StripeApiKeyRotationListItemSchema = z.object({
- name: z.literal("Stripe API Key"),
- connection: z.literal(AppConnection.Stripe),
- type: z.literal(SecretRotation.StripeApiKey),
- template: StripeApiKeyRotationTemplateSchema
-});
-```
-
-- [ ] **Step 4: Write the types**
-
-Create `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-rotation-types.ts`:
-
-```ts
-import { z } from "zod";
-
-import { TStripeConnection } from "@app/services/app-connection/stripe";
-
-import { TStripeSecretKeyField } from "./stripe-api-key-jwe";
-import {
- CreateStripeApiKeyRotationSchema,
- StripeApiKeyRotationGeneratedCredentialsSchema,
- StripeApiKeyRotationListItemSchema,
- StripeApiKeyRotationSchema
-} from "./stripe-api-key-rotation-schemas";
-
-export type TStripeApiKeyRotation = z.infer<typeof StripeApiKeyRotationSchema>;
-
-export type TStripeApiKeyRotationInput = z.infer<typeof CreateStripeApiKeyRotationSchema>;
-
-export type TStripeApiKeyRotationListItem = z.infer<typeof StripeApiKeyRotationListItemSchema>;
-
-export type TStripeApiKeyRotationWithConnection = TStripeApiKeyRotation & {
- connection: TStripeConnection;
-};
-
-export type TStripeApiKeyRotationGeneratedCredentials = z.infer<
- typeof StripeApiKeyRotationGeneratedCredentialsSchema
->;
-
-export type TStripeApiKeyCreateResponse = {
- id?: string;
- secret_key?: TStripeSecretKeyField;
-};
-```
-
-- [ ] **Step 5: Write the barrel**
-
-Create `backend/src/ee/services/secret-rotation-v2/stripe-api-key/index.ts`:
-
-```ts
-export * from "./stripe-api-key-rotation-constants";
-export * from "./stripe-api-key-rotation-schemas";
-export * from "./stripe-api-key-rotation-types";
-```
-
-- [ ] **Step 6: Add the API docs strings**
-
-In `backend/src/lib/api-docs/constants.ts`, add to `SecretRotations.PARAMETERS`:
-
-```ts
- STRIPE_API_KEY: {
- permissions:
- "The permissions granted to the generated Stripe API key. Stripe has no wildcard permission, so this is the full list of what the key may do.",
- connectPermissions:
- "The permissions the generated Stripe API key has over connected accounts. Only meaningful when the account is a Connect platform."
- },
-```
-
-and to `SecretRotations.SECRETS_MAPPING`:
-
-```ts
- STRIPE_API_KEY: {
- apiKey: "The name of the secret that the rotated Stripe API key will be mapped to."
- },
-```
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add backend/src/ee/services/secret-rotation-v2/ backend/src/lib/api-docs/constants.ts
-git commit -m "feat(secret-rotation): add Stripe API key rotation schemas"
-```
-
-Type checking will still fail at this point because the exhaustive maps do not yet have a Stripe arm. Task 6 closes that.
-
----
-
-### Task 5: The rotation factory
-
-**Files:**
-- Create: `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-rotation-fns.ts`
-- Create: `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-rotation-fns.test.ts`
-
-**Interfaces:**
-- Consumes: `generateStripeEncryptionKeyPair`, `readStripeSecret` (Task 2); `STRIPE_API_KEYS_URL`, `getStripePlatformRequestConfig`, `getStripeMerchantRequestConfig`, `withIdempotencyKey`, `getStripeErrorMessage`, `getStripeErrorStatus`, `throwStripeApiKeyManagementError` (Task 1); the types from Task 4.
-- Produces: `stripeApiKeyRotationFactory`, matching `TRotationFactory<TStripeApiKeyRotationWithConnection, TStripeApiKeyRotationGeneratedCredentials>`.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-rotation-fns.test.ts`:
-
-```ts
-/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument */
-import { AxiosError } from "axios";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const { getMock, postMock } = vi.hoisted(() => ({ getMock: vi.fn(), postMock: vi.fn() }));
-
-vi.mock("@app/lib/config/env", () => ({
- getConfig: () => ({ INF_APP_CONNECTION_STRIPE_SECRET_KEY: "sk_test_platform" })
-}));
-vi.mock("@app/lib/config/request", () => ({
- request: {
- get: (...args: unknown[]) => (getMock as any)(...args),
- post: (...args: unknown[]) => (postMock as any)(...args)
- }
-}));
-vi.mock("@app/lib/logger", () => ({
- logger: { error: vi.fn(), info: vi.fn(), warn: vi.fn(), debug: vi.fn() }
-}));
-
-// eslint-disable-next-line import/first
-import { stripeApiKeyRotationFactory } from "./stripe-api-key-rotation-fns";
-
-const httpError = (status: number, message = "boom") =>
- new AxiosError("Request failed", "ERR_BAD_REQUEST", undefined, undefined, {
- status,
- statusText: "",
- headers: {},
- config: {} as any,
- data: { error: { message } }
- });
-
-const makeFactory = () =>
- stripeApiKeyRotationFactory(
- {
- connection: { id: "connection-id", credentials: { accountId: "acct_123" } },
- parameters: { permissions: ["customer_read"], connectPermissions: [] },
- secretsMapping: { apiKey: "STRIPE_API_KEY" }
- } as any,
- {} as any,
- {} as any,
- {} as any,
- {} as any,
- {} as any
- );
-
-const isCreate = (url: string) => url.endsWith("/v2/iam/api_keys");
-const isExpire = (url: string) => url.endsWith("/expire");
-const expireCalls = (keyId?: string) =>
- postMock.mock.calls.filter(
- ([url]) => isExpire(url) && (keyId === undefined || url.includes(`/${keyId}/expire`))
- );
-
-/** Test mode returns the secret in plaintext, which is the shape the sandbox produces. */
-const mockStripe = ({
- createIds = ["mk_new"],
- expire = async () => ({ data: {} })
-}: { createIds?: string[]; expire?: (keyId: string) => Promise<unknown> } = {}) => {
- const ids = [...createIds];
- postMock.mockImplementation(async (url: string) => {
- if (isCreate(url)) {
- const id = ids.shift() ?? "mk_extra";
- return { data: { id, secret_key: { token: `rk_test_${id}` } } };
- }
- if (isExpire(url)) return expire(url.split("/").slice(-2)[0]);
- throw new Error(`unexpected request to ${url}`);
- });
-};
-
-describe("stripeApiKeyRotationFactory", () => {
- beforeEach(() => {
- getMock.mockReset();
- postMock.mockReset();
- });
-
- it("mints a key and hands the plaintext secret to the callback", async () => {
- mockStripe();
- const callback = vi.fn(async (credentials: unknown) => credentials);
-
- const result = await makeFactory().issueCredentials(callback as any);
-
- expect(result).toEqual({ keyId: "mk_new", apiKey: "rk_test_mk_new" });
- const [, body] = postMock.mock.calls.find(([url]) => isCreate(url))!;
- expect(body.type).toBe("secret_key");
- expect(body.permissions).toEqual(["customer_read"]);
- expect(body.public_key.pem_key.data).toContain("BEGIN PUBLIC KEY");
- });
-
- it("expires the new key when the create commit fails", async () => {
- mockStripe();
- const callback = vi.fn(async () => {
- throw new Error("conflicting secret");
- });
-
- await expect(makeFactory().issueCredentials(callback as any)).rejects.toThrow("conflicting secret");
- expect(expireCalls("mk_new")).toHaveLength(1);
- });
-
- it("retires the previous key before committing the new one", async () => {
- mockStripe({ createIds: ["mk_new"] });
- const callback = vi.fn(async (credentials: unknown) => credentials);
-
- await makeFactory().rotateCredentials({ keyId: "mk_old", apiKey: "rk_old" } as any, callback as any, {} as any);
-
- const order = postMock.mock.calls.map(([url]) => (isCreate(url) ? "create" : url.split("/").slice(-2)[0]));
- expect(order).toEqual(["create", "mk_old"]);
- expect(callback).toHaveBeenCalledWith({ keyId: "mk_new", apiKey: "rk_test_mk_new" });
- });
-
- it("cleans up the new key and fails when the retirement fails", async () => {
- mockStripe({
- expire: async (keyId) => {
- if (keyId === "mk_old") throw httpError(500, "Stripe is down");
- return { data: {} };
- }
- });
- const callback = vi.fn(async (credentials: unknown) => credentials);
-
- await expect(
- makeFactory().rotateCredentials({ keyId: "mk_old" } as any, callback as any, {} as any)
- ).rejects.toThrow("Stripe is down");
-
- expect(expireCalls("mk_new")).toHaveLength(1);
- expect(callback).not.toHaveBeenCalled();
- });
-
- it("names the stranded key when the cleanup also fails", async () => {
- mockStripe({
- expire: async () => {
- throw httpError(500, "Stripe is down");
- }
- });
- const callback = vi.fn(async (credentials: unknown) => credentials);
-
- await expect(
- makeFactory().rotateCredentials({ keyId: "mk_old" } as any, callback as any, {} as any)
- ).rejects.toThrow(/mk_new/);
- });
-
- it("treats a 404 on expire as already gone", async () => {
- mockStripe({
- expire: async (keyId) => {
- if (keyId === "mk_old") throw httpError(404, "No such key");
- return { data: {} };
- }
- });
- const callback = vi.fn(async (credentials: unknown) => credentials);
-
- await expect(
- makeFactory().rotateCredentials({ keyId: "mk_old" } as any, callback as any, {} as any)
- ).resolves.toBeDefined();
- });
-
- it("maps only the API key into the secrets payload", () => {
- expect(makeFactory().getSecretsPayload({ keyId: "mk_new", apiKey: "rk_test" } as any)).toEqual([
- { key: "STRIPE_API_KEY", value: "rk_test" }
- ]);
- });
-
- it("treats 403 as a live key and 401 as a dead one", async () => {
- getMock.mockRejectedValueOnce(httpError(403, "Insufficient permissions"));
- await expect(
- makeFactory().checkActiveCredentials!({ keyId: "mk", apiKey: "rk_test" } as any)
- ).resolves.toBeUndefined();
-
- getMock.mockRejectedValueOnce(httpError(401, "Invalid API Key"));
- await expect(
- makeFactory().checkActiveCredentials!({ keyId: "mk", apiKey: "rk_test" } as any)
- ).rejects.toThrow("Invalid API Key");
- });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `make test-api-unit SPEC=stripe-api-key-rotation-fns`
-Expected: FAIL, cannot resolve `./stripe-api-key-rotation-fns`.
-
-- [ ] **Step 3: Write the implementation**
-
-Create `backend/src/ee/services/secret-rotation-v2/stripe-api-key/stripe-api-key-rotation-fns.ts`:
-
-```ts
-import {
- TRotationFactory,
- TRotationFactoryCheckActiveCredentials,
- TRotationFactoryGetSecretsPayload,
- TRotationFactoryIssueCredentials,
- TRotationFactoryRevokeCredentials,
- TRotationFactoryRotateCredentials
-} from "@app/ee/services/secret-rotation-v2/secret-rotation-v2-types";
-import { request } from "@app/lib/config/request";
-import { BadRequestError } from "@app/lib/errors";
-import {
- getStripeErrorMessage,
- getStripeErrorStatus,
- getStripeMerchantRequestConfig,
- getStripePlatformRequestConfig,
- STRIPE_API_KEYS_URL,
- throwStripeApiKeyManagementError,
- withIdempotencyKey
-} from "@app/services/app-connection/stripe/stripe-connection-public-client";
-import { IntegrationUrls } from "@app/services/integration-auth/integration-list";
-
-import { generateStripeEncryptionKeyPair, readStripeSecret } from "./stripe-api-key-jwe";
-import {
- TStripeApiKeyCreateResponse,
- TStripeApiKeyRotationGeneratedCredentials,
- TStripeApiKeyRotationWithConnection
-} from "./stripe-api-key-rotation-types";
-
-const STRIPE_KEY_NAME_MAX_LENGTH = 100;
-
-const getErrorMessage = (error: unknown): string => (error instanceof Error ? error.message : "Unknown error");
-
-export const stripeApiKeyRotationFactory: TRotationFactory<
- TStripeApiKeyRotationWithConnection,
- TStripeApiKeyRotationGeneratedCredentials
-> = (secretRotation) => {
- const {
- connection,
- parameters: { permissions, connectPermissions },
- secretsMapping
- } = secretRotation;
-
- const { accountId } = connection.credentials;
-
- // The factory is built without an id at create time, so the name comes from the mapped secret.
- // It is what makes a key stranded by a timed-out create identifiable in the Stripe dashboard.
- const $keyName = () => `infisical-${secretsMapping.apiKey}-${Date.now()}`.slice(0, STRIPE_KEY_NAME_MAX_LENGTH);
-
- const $createApiKey = async () => {
- const { publicKey, privateKey } = await generateStripeEncryptionKeyPair();
-
- let data: TStripeApiKeyCreateResponse;
-
- try {
- ({ data } = await request.post<TStripeApiKeyCreateResponse>(
- STRIPE_API_KEYS_URL,
- {
- type: "secret_key",
- name: $keyName(),
- permissions,
- ...(connectPermissions?.length ? { connect_permissions: connectPermissions } : {}),
- public_key: { pem_key: { data: publicKey, algorithm: "RSA" } }
- },
- withIdempotencyKey(getStripePlatformRequestConfig(accountId))
- ));
- } catch (error) {
- return throwStripeApiKeyManagementError(accountId, error);
- }
-
- if (!data?.id) {
- throw new BadRequestError({ message: "Stripe did not return an ID for the created API key." });
- }
-
- return { keyId: data.id, apiKey: readStripeSecret(data.secret_key, privateKey) };
- };
-
- /**
- * Expire is the whole retirement. Stripe decides when it takes effect, so nothing here claims the
- * key is dead. Narrowing the key's permissions first would stop it sooner, and was measured
- * working, but is deliberately not in v1. See the design doc.
- */
- const $retireKey = async (keyId: string) => {
- try {
- await request.post(
- `${STRIPE_API_KEYS_URL}/${keyId}/expire`,
- {},
- withIdempotencyKey(getStripePlatformRequestConfig(accountId))
- );
- } catch (error) {
- if (getStripeErrorStatus(error) === 404) return;
-
- throwStripeApiKeyManagementError(accountId, error);
- }
- };
-
- /** A key exists in Stripe before the row does, so a failed commit has to take the key with it. */
- const $commitOrCleanUp = async <T>(
- credentials: { keyId: string; apiKey: string },
- callback: (credentials: { keyId: string; apiKey: string }) => Promise<T>
- ): Promise<T> => {
- try {
- return await callback(credentials);
- } catch (commitError) {
- try {
- await $retireKey(credentials.keyId);
- } catch (cleanupError) {
- throw new BadRequestError({
- message: `${getErrorMessage(commitError)} The newly created Stripe API key ${credentials.keyId} could not be expired and may need to be removed manually: ${getErrorMessage(cleanupError)}`
- });
- }
-
- throw commitError;
- }
- };
-
- const issueCredentials: TRotationFactoryIssueCredentials<TStripeApiKeyRotationGeneratedCredentials> = async (
- callback
- ) => {
- const credentials = await $createApiKey();
-
- return $commitOrCleanUp(credentials, callback);
- };
-
- const revokeCredentials: TRotationFactoryRevokeCredentials<TStripeApiKeyRotationGeneratedCredentials> = async (
- credentials,
- callback
- ) => {
- if (!credentials?.length) return callback();
-
- for (const { keyId } of credentials) {
- // eslint-disable-next-line no-await-in-loop
- await $retireKey(keyId);
- }
-
- return callback();
- };
-
- const rotateCredentials: TRotationFactoryRotateCredentials<TStripeApiKeyRotationGeneratedCredentials> = async (
- credentialsToRevoke,
- callback
- ) => {
- const newCredentials = await $createApiKey();
-
- // Retire before committing, so a failure leaves Postgres and Stripe agreeing with each other and
- // the key we just minted gets cleaned up rather than orphaned across BullMQ's retries.
- if (credentialsToRevoke?.keyId) {
- try {
- await $retireKey(credentialsToRevoke.keyId);
- } catch (retireError) {
- try {
- await $retireKey(newCredentials.keyId);
- } catch (cleanupError) {
- throw new BadRequestError({
- message: `${getErrorMessage(retireError)} The newly created Stripe API key ${newCredentials.keyId} could not be expired and may need to be removed manually: ${getErrorMessage(cleanupError)}`
- });
- }
-
- throw retireError;
- }
- }
-
- return $commitOrCleanUp(newCredentials, callback);
- };
-
- const getSecretsPayload: TRotationFactoryGetSecretsPayload<TStripeApiKeyRotationGeneratedCredentials> = ({
- apiKey
- }) => [{ key: secretsMapping.apiKey, value: apiKey }];
-
- const checkActiveCredentials: TRotationFactoryCheckActiveCredentials<
- TStripeApiKeyRotationGeneratedCredentials
- > = async ({ apiKey }) => {
- try {
- await request.get(`${IntegrationUrls.STRIPE_API_URL}/v1/customers?limit=1`, getStripeMerchantRequestConfig(apiKey));
- } catch (error) {
- // 403 means the key authenticated and simply lacks customer_read, which is a healthy narrow
- // key. Only 401 means the key is gone.
- if (getStripeErrorStatus(error) === 403) return;
-
- throw new BadRequestError({
- message: `Stripe API key verification failed: ${getStripeErrorMessage(error)}`
- });
- }
- };
-
- return {
- issueCredentials,
- revokeCredentials,
- rotateCredentials,
- getSecretsPayload,
- checkActiveCredentials
- };
-};
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `make test-api-unit SPEC=stripe-api-key-rotation-fns`
-Expected: PASS, 8 tests.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add backend/src/ee/services/secret-rotation-v2/stripe-api-key/
-git commit -m "feat(secret-rotation): add Stripe API key rotation factory"
-```
-
----
-
-### Task 6: Backend wiring
-
-Closes every map, union and router the new enum member broke, plus the ones the compiler will not catch.
-
-**Files:**
-- Modify: `backend/src/ee/services/secret-rotation-v2/secret-rotation-v2-maps.ts`
-- Modify: `backend/src/ee/services/secret-rotation-v2/secret-rotation-v2-fns.ts`
-- Modify: `backend/src/ee/services/secret-rotation-v2/secret-rotation-v2-service.ts`
-- Modify: `backend/src/ee/services/secret-rotation-v2/secret-rotation-v2-types.ts`
-- Modify: `backend/src/ee/services/secret-rotation-v2/secret-rotation-v2-union-schema.ts`
-- Create: `backend/src/ee/routes/v2/secret-rotation-v2-routers/stripe-api-key-rotation-router.ts`
-- Modify: `backend/src/ee/routes/v2/secret-rotation-v2-routers/index.ts`
-- Modify: `backend/src/ee/routes/v2/secret-rotation-v2-routers/secret-rotation-v2-router.ts`
-
-**Interfaces:**
-- Consumes: everything from Tasks 4 and 5.
-- Produces: a registered, reachable set of `/secret-rotations/stripe-api-key` endpoints.
-
-- [ ] **Step 1: Let the compiler list the work**
-
-Run: `cd backend && npm run type:check`
-Expected: FAIL, with an error per exhaustive map missing a `SecretRotation.StripeApiKey` arm. Keep this output, it is the checklist for step 2.
-
-- [ ] **Step 2: Add the compiler-enforced arms**
-
-In `secret-rotation-v2-maps.ts`:
-
-```ts
- [SecretRotation.StripeApiKey]: "Stripe API Key",
-```
-in `SECRET_ROTATION_NAME_MAP`, and
-
-```ts
- [SecretRotation.StripeApiKey]: AppConnection.Stripe,
-```
-in `SECRET_ROTATION_CONNECTION_MAP`.
-
-In `secret-rotation-v2-fns.ts`, import `STRIPE_API_KEY_ROTATION_LIST_OPTION` from `./stripe-api-key` and add:
-
-```ts
- [SecretRotation.StripeApiKey]: STRIPE_API_KEY_ROTATION_LIST_OPTION,
-```
-
-In `secret-rotation-v2-service.ts`, import `stripeApiKeyRotationFactory` from `./stripe-api-key/stripe-api-key-rotation-fns` and add to `SECRET_ROTATION_FACTORY_MAP`:
-
-```ts
- [SecretRotation.StripeApiKey]: stripeApiKeyRotationFactory as TRotationFactoryImplementation,
-```
-
-Match the casting style of the neighbouring entries exactly.
-
-- [ ] **Step 3: Add the arms the compiler will not catch**
-
-In `secret-rotation-v2-types.ts`, add `TStripeApiKeyRotation`, `TStripeApiKeyRotationInput`, `TStripeApiKeyRotationListItem`, `TStripeApiKeyRotationWithConnection` and `TStripeApiKeyRotationGeneratedCredentials` to the five corresponding union types, importing them from `./stripe-api-key`.
-
-In `secret-rotation-v2-union-schema.ts`, import `StripeApiKeyRotationSchema` from `./stripe-api-key` and add it to the `z.discriminatedUnion("type", [...])` array.
-
-In `secret-rotation-v2-router.ts`, add `StripeApiKeyRotationListItemSchema` to the list-item schema union.
-
-These are array members rather than object keys, so nothing fails to compile when one is missed. Confirm each by grepping for a neighbour, for example `grep -n CloudflareApiTokenRotationSchema backend/src/ee/services/secret-rotation-v2/secret-rotation-v2-union-schema.ts`.
-
-- [ ] **Step 4: Add the router**
-
-Create `backend/src/ee/routes/v2/secret-rotation-v2-routers/stripe-api-key-rotation-router.ts`:
-
-```ts
-import {
- CreateStripeApiKeyRotationSchema,
- StripeApiKeyRotationGeneratedCredentialsSchema,
- StripeApiKeyRotationSchema,
- UpdateStripeApiKeyRotationSchema
-} from "@app/ee/services/secret-rotation-v2/stripe-api-key";
-import { SecretRotation } from "@app/ee/services/secret-rotation-v2/secret-rotation-v2-enums";
-
-import { registerSecretRotationEndpoints } from "./secret-rotation-v2-endpoints";
-
-export const registerStripeApiKeyRotationRouter = async (server: FastifyZodProvider) =>
- registerSecretRotationEndpoints({
- type: SecretRotation.StripeApiKey,
- server,
- responseSchema: StripeApiKeyRotationSchema,
- createSchema: CreateStripeApiKeyRotationSchema,
- updateSchema: UpdateStripeApiKeyRotationSchema,
- generatedCredentialsSchema: StripeApiKeyRotationGeneratedCredentialsSchema
- });
-```
-
-Export it from `secret-rotation-v2-routers/index.ts` and add it to the router map there, following the `CloudflareApiToken` entry.
-
-- [ ] **Step 5: Verify**
-
-Run: `cd backend && npm run type:check`
-Expected: no errors.
-
-Run: `make test-api-unit SPEC=stripe`
-Expected: PASS, all three Stripe spec files.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add backend/src/ee/
-git commit -m "feat(secret-rotation): wire Stripe API key rotation"
-```
-
----
-
-### Task 7: Frontend API layer
-
-**Files:**
-- Create: `frontend/src/hooks/api/appConnections/stripe/queries.tsx`
-- Create: `frontend/src/hooks/api/appConnections/stripe/types.ts`
-- Create: `frontend/src/hooks/api/appConnections/stripe/index.ts`
-- Create: `frontend/src/hooks/api/secretRotationsV2/types/stripe-api-key-rotation.ts`
-- Modify: `frontend/src/hooks/api/secretRotationsV2/enums.ts`
-- Modify: `frontend/src/hooks/api/secretRotationsV2/types/index.ts`
-- Modify: `frontend/src/helpers/secretRotationsV2.ts`
-
-**Interfaces:**
-- Consumes: the `/api/v1/app-connections/stripe/:connectionId/api-keys` route from Task 3.
-- Produces: `useStripeConnectionListApiKeys(connectionId, options)`, `TStripeApiKey`, `TStripeApiKeyRotation`, `TStripeApiKeyRotationGeneratedCredentialsResponse`, `TStripeApiKeyRotationOption`, and `SecretRotation.StripeApiKey`.
-
-- [ ] **Step 1: Add the enum member and helper map entries**
-
-In `frontend/src/hooks/api/secretRotationsV2/enums.ts`, add `StripeApiKey = "stripe-api-key"` to `SecretRotation`.
-
-In `frontend/src/helpers/secretRotationsV2.ts`, add the arm to every `Record<SecretRotation, ...>`:
-
-```ts
- [SecretRotation.StripeApiKey]: "Stripe API Key",
-```
-in the name map,
-
-```ts
- [SecretRotation.StripeApiKey]: "Stripe.svg",
-```
-in the image map. Confirm the filename with `ls frontend/public/images/integrations | grep -i stripe`, since neighbouring entries use `.png` and Stripe's asset is an svg.
-
-```ts
- [SecretRotation.StripeApiKey]: AppConnection.Stripe,
-```
-in the connection map, and
-
-```ts
- [SecretRotation.StripeApiKey]: true,
-```
-in `IS_ROTATION_DUAL_CREDENTIALS`, because Stripe rotation is create-then-retire and keeps two live keys.
-
-- [ ] **Step 2: Add the connection query hook**
-
-Create `frontend/src/hooks/api/appConnections/stripe/types.ts`:
-
-```ts
-export type TStripeApiKey = {
- id: string;
- name: string;
- status: string;
- permissions: string[];
- connectPermissions: string[];
-};
-```
-
-Create `frontend/src/hooks/api/appConnections/stripe/queries.tsx`, following `appConnections/supabase/queries.tsx`:
-
-```tsx
-import { useQuery, UseQueryOptions } from "@tanstack/react-query";
-
-import { apiRequest } from "@app/config/request";
-import { appConnectionKeys } from "@app/hooks/api/appConnections";
-
-import { TStripeApiKey } from "./types";
-
-const stripeConnectionKeys = {
- all: [...appConnectionKeys.all, "stripe"] as const,
- listApiKeys: (connectionId: string) => [...stripeConnectionKeys.all, "api-keys", connectionId] as const
-};
-
-export const useStripeConnectionListApiKeys = (
- connectionId: string,
- options?: Omit<
- UseQueryOptions<
- TStripeApiKey[],
- unknown,
- TStripeApiKey[],
- ReturnType<typeof stripeConnectionKeys.listApiKeys>
- >,
- "queryKey" | "queryFn"
- >
-) => {
- return useQuery({
- queryKey: stripeConnectionKeys.listApiKeys(connectionId),
- queryFn: async () => {
- const { data } = await apiRequest.get<{ apiKeys: TStripeApiKey[] }>(
- `/api/v1/app-connections/stripe/${connectionId}/api-keys`
- );
-
- return data.apiKeys;
- },
- ...options
- });
-};
-```
-
-Create `frontend/src/hooks/api/appConnections/stripe/index.ts` re-exporting both, matching the supabase barrel.
-
-- [ ] **Step 3: Add the rotation types**
-
-Create `frontend/src/hooks/api/secretRotationsV2/types/stripe-api-key-rotation.ts`:
-
-```ts
-import { AppConnection } from "@app/hooks/api/appConnections/enums";
-import { SecretRotation } from "@app/hooks/api/secretRotationsV2";
-import {
- TSecretRotationV2Base,
- TSecretRotationV2GeneratedCredentialsResponseBase
-} from "@app/hooks/api/secretRotationsV2/types/shared";
-
-export type TStripeApiKeyRotation = TSecretRotationV2Base & {
- type: SecretRotation.StripeApiKey;
- parameters: {
- permissions: string[];
- connectPermissions?: string[];
- };
- secretsMapping: {
- apiKey: string;
- };
-};
-
-export type TStripeApiKeyRotationGeneratedCredentials = {
- keyId: string;
- apiKey: string;
-};
-
-export type TStripeApiKeyRotationGeneratedCredentialsResponse =
- TSecretRotationV2GeneratedCredentialsResponseBase<
- SecretRotation.StripeApiKey,
- TStripeApiKeyRotationGeneratedCredentials
- >;
-
-export type TStripeApiKeyRotationOption = {
- name: string;
- type: SecretRotation.StripeApiKey;
- connection: AppConnection.Stripe;
- template: {
- secretsMapping: TStripeApiKeyRotation["secretsMapping"];
- permissions: string[];
- };
-};
-```
-
-Add the re-export and the union members in `frontend/src/hooks/api/secretRotationsV2/types/index.ts`, following the `cloudflare-api-token-rotation` entries.
-
-- [ ] **Step 4: Verify**
-
-Run: `cd frontend && npm run type:check`
-Expected: errors only about the missing form components, which Task 8 adds.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add frontend/src/hooks/api/ frontend/src/helpers/secretRotationsV2.ts
-git commit -m "feat(secret-rotation): add Stripe API key rotation API types"
-```
-
----
-
-### Task 8: Frontend form
-
-**Files:**
-- Create: `frontend/src/components/secret-rotations-v2/forms/schemas/stripe-api-key-rotation-schema.ts`
-- Modify: `frontend/src/components/secret-rotations-v2/forms/schemas/index.ts`
-- Create: `frontend/src/components/secret-rotations-v2/forms/SecretRotationV2ParametersFields/StripeApiKeyRotationParametersFields.tsx`
-- Create: `frontend/src/components/secret-rotations-v2/forms/SecretRotationV2ReviewFields/StripeApiKeyRotationReviewFields.tsx`
-- Create: `frontend/src/components/secret-rotations-v2/forms/SecretRotationV2SecretsMappingFields/StripeApiKeyRotationSecretsMappingFields.tsx`
-- Create: `frontend/src/components/secret-rotations-v2/ViewSecretRotationV2GeneratedCredentials/ViewStripeApiKeyRotationGeneratedCredentials.tsx`
-- Modify: the four registry files that switch on rotation type
-
-**Interfaces:**
-- Consumes: `useStripeConnectionListApiKeys`, `TStripeApiKeyRotation` (Task 7); `rotationOption.template.permissions` served by the backend list-options endpoint (Task 4).
-- Produces: a working create and edit form for the rotation.
-
-- [ ] **Step 1: Write the form schema**
-
-Create `frontend/src/components/secret-rotations-v2/forms/schemas/stripe-api-key-rotation-schema.ts`:
-
-```ts
-import { z } from "zod";
-
-import { BaseSecretRotationSchema } from "@app/components/secret-rotations-v2/forms/schemas/base-secret-rotation-v2-schema";
-import { SecretRotation } from "@app/hooks/api/secretRotationsV2";
-
-export const StripeApiKeyRotationSchema = z
- .object({
- type: z.literal(SecretRotation.StripeApiKey),
- parameters: z.object({
- permissions: z
- .string()
- .trim()
- .array()
- .min(1, "At least one permission is required"),
- connectPermissions: z.string().trim().array().optional()
- }),
- secretsMapping: z.object({
- apiKey: z.string().trim().min(1, "API Key secret name required")
- })
- })
- .merge(BaseSecretRotationSchema);
-```
-
-Add it to the union in `forms/schemas/index.ts`, following the `CloudflareApiTokenRotationSchema` entry.
-
-- [ ] **Step 2: Write the parameters fields**
-
-Create `StripeApiKeyRotationParametersFields.tsx`. The permission picker is a v3 `Combobox` with `multiple` and `isSelectAll`. Do not build a new component: `ComboboxSelectAll` is internal, and `isSelectAll` is the supported API. Select-all covers only the options matching the current search, which is why the label says "Select all matching".
-
-```tsx
-import { useMemo } from "react";
-import { Controller, useFormContext, useWatch } from "react-hook-form";
-
-import { TSecretRotationV2Form } from "@app/components/secret-rotations-v2/forms/schemas";
-import { Button, Combobox, Field, FieldError, FieldLabel } from "@app/components/v3";
-import { useStripeConnectionListApiKeys } from "@app/hooks/api/appConnections/stripe";
-import { SecretRotation, useSecretRotationV2Option } from "@app/hooks/api/secretRotationsV2";
-
-export const StripeApiKeyRotationParametersFields = () => {
- const { control, setValue } = useFormContext<
- TSecretRotationV2Form & { type: SecretRotation.StripeApiKey }
- >();
-
- const connectionId = useWatch({ control, name: "connection.id" });
- const { rotationOption } = useSecretRotationV2Option(SecretRotation.StripeApiKey);
- const { data: apiKeys = [] } = useStripeConnectionListApiKeys(connectionId, {
- enabled: Boolean(connectionId)
- });
-
- const permissions = useMemo(() => rotationOption?.template.permissions ?? [], [rotationOption]);
-
- return (
- <>
- <Controller
- render={({ field: { value, onChange }, fieldState: { error } }) => (
- <Field data-invalid={Boolean(error)}>
- <FieldLabel htmlFor="stripe-permissions">Permissions</FieldLabel>
- <Combobox
- id="stripe-permissions"
- multiple
- isSelectAll
- options={permissions}
- value={value ?? []}
- onValueChange={onChange}
- getOptionValue={(permission) => permission}
- getOptionLabel={(permission) => permission}
- placeholder="Select permissions..."
- searchPlaceholder="Search permissions..."
- searchAriaLabel="Search Stripe permissions"
- clearAriaLabel="Clear all permissions"
- />
- <FieldError>{error?.message}</FieldError>
- </Field>
- )}
- control={control}
- name="parameters.permissions"
- />
- {apiKeys.length > 0 && (
- <div className="flex flex-wrap items-center gap-2">
- <span className="text-sm text-mineshaft-300">Copy permissions from an existing key:</span>
- {apiKeys.map((apiKey) => (
- <Button
- key={apiKey.id}
- size="xs"
- variant="outline_bg"
- onClick={() => {
- setValue("parameters.permissions", apiKey.permissions, { shouldDirty: true });
- setValue("parameters.connectPermissions", apiKey.connectPermissions, {
- shouldDirty: true
- });
- }}
- >
- {apiKey.name || apiKey.id}
- </Button>
- ))}
- </div>
- )}
- </>
- );
-};
-```
-
-Check the exact `Button` variant and text colour class against a neighbouring v3 form before committing, and adjust to match. `DESIGN.md` governs here.
-
-- [ ] **Step 3: Write the remaining three components**
-
-`StripeApiKeyRotationSecretsMappingFields.tsx`: copy `CloudflareApiTokenRotationSecretsMappingFields.tsx` and reduce it to a single item, `name: "API Key"`, bound to `secretsMapping.apiKey` with placeholder `rotationOption?.template.secretsMapping.apiKey`.
-
-`StripeApiKeyRotationReviewFields.tsx`: follow `CloudflareApiTokenRotationReviewFields.tsx`, showing the permission count and the first few names rather than all 158.
-
-`ViewStripeApiKeyRotationGeneratedCredentials.tsx`: copy `ViewCloudflareApiTokenRotationGeneratedCredentials.tsx`, replacing the two credential displays with `<CredentialDisplay label="Key ID">{...keyId}</CredentialDisplay>` and `<CredentialDisplay isSensitive label="API Key">{...apiKey}</CredentialDisplay>`.
-
-- [ ] **Step 4: Register all four**
-
-Add a `case SecretRotation.StripeApiKey:` arm to each of `SecretRotationV2ParametersFields.tsx`, `SecretRotationReviewFields.tsx`, `SecretRotationV2SecretsMappingFields.tsx` and `ViewSecretRotationV2GeneratedCredentials.tsx`.
-
-- [ ] **Step 5: Verify**
-
-Run: `make reviewable-ui`
-Expected: lint and type check both clean.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add frontend/src/components/secret-rotations-v2/
-git commit -m "feat(secret-rotation): add Stripe API key rotation form"
-```
-
----
-
-### Task 9: Documentation
-
-**Files:**
-- Create: `docs/documentation/platform/secret-rotation/stripe-api-key.mdx`
-- Create: `docs/integrations/app-connections/stripe.mdx`
-- Create: eight pages under `docs/api-reference/endpoints/secret-rotations/stripe-api-key/`
-- Modify: `docs/docs.json`
-- Modify: `docs/snippets/RotationsBrowser.jsx`
-
-- [ ] **Step 1: Load the docs skill**
-
-Invoke the `docs-style` skill. It carries the procedure for `docs/STYLE_GUIDE.md`, which is required for anything under `docs/`.
-
-- [ ] **Step 2: Write the rotation page**
-
-Copy the structure of `docs/documentation/platform/secret-rotation/cloudflare-api-token.mdx`. Four things must be stated plainly, because each is a support ticket otherwise:
-
-- The minted key's mode follows the instance's Stripe key, so a test-mode instance mints test keys. There is no per-rotation choice.
-- Infisical never touches keys it did not create. The user's original key stays live until they expire it themselves, once their applications have picked up the rotated secret.
-- Retirement expires the key, and Stripe decides when that takes effect, so a retired key may keep answering briefly. Do not write anything that claims the key is dead.
-- The rotated value is an `rk_` restricted key, not an `sk_` secret key, so anything asserting on the prefix will break.
-
-- [ ] **Step 3: Write the connection page and API reference**
-
-`docs/integrations/app-connections/stripe.mdx` was left outstanding by the connection PR. Base it on `stripe-app/README.md` for the setup sequence, and on `docs/integrations/app-connections/cloudflare.mdx` for structure.
-
-The eight API reference pages mirror `docs/api-reference/endpoints/secret-rotations/cloudflare-api-token/`: create, delete, get-by-id, get-by-name, get-generated-credentials-by-id, list, rotate-secrets, update. Register every new page in `docs/docs.json` and add the rotation to `docs/snippets/RotationsBrowser.jsx`.
-
-- [ ] **Step 4: Verify**
-
-Run: `make lint-docs-branch`
-Expected: exit 0. Read the printed output rather than trusting the exit code: `Infisical.UIActions` and `Infisical.Contractions` report below error level and never fail the run. Vale also cannot see prose indented four or more spaces inside Mintlify components, so a clean run is not evidence that nested content was checked.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add docs/
-git commit -m "docs(secret-rotation): document Stripe API key rotation"
-```
-
----
-
-### Task 10: Final verification
-
-- [ ] **Step 1: Run the full backend gate**
-
-Run: `make reviewable-api`
-Expected: lint and type check clean.
-
-- [ ] **Step 2: Run the full frontend gate**
-
-Run: `make reviewable-ui`
-Expected: lint and type check clean.
-
-- [ ] **Step 3: Run the unit suite**
-
-Run: `make test-api-unit`
-Expected: PASS. This runs under `--force-fips`, which is what makes the JWE test meaningful.
-
-- [ ] **Step 4: Check against the code quality guide**
-
-Re-read `backend/CODE_QUALITY.md` and check this change against it. The sections that bite here are third-party pagination, transaction and connection-pool discipline, input validation, and user-facing error messages.
-
-- [ ] **Step 5: Manual verification against the sandbox**
-
-The gated sandbox is the only way to exercise the real API, and it is test mode, so it cannot verify the live-mode JWE path. Record the results in the PR:
-
-- Create a rotation and confirm a key appears in the Stripe dashboard named `infisical-<secret name>-<timestamp>`.
-- Confirm the mapped secret holds an `rk_` value that authenticates.
-- Rotate twice and confirm the first key is expired while the second stays live.
-- Delete the rotation with revoke and confirm both keys expire.
-- Confirm the form's "copy from an existing key" prefill populates the permission picker.
-- In the browser devtools network tab, confirm the `api-keys` response contains no `secret_key` field.
-
-- [ ] **Step 6: Commit any fixes**
-
-```bash
-git add -A
-git commit -m "chore(secret-rotation): address review gate findings"
-```
-
----
-
-## Still open after this plan
-
-Live mode is unverified and cannot be verified from the sandbox. Everything about the encrypted path is asserted: that create accepts `public_key`, that the response carries `secret_key.encrypted_secret.ciphertext`, that `alg` is `RSA-OAEP` or `RSA-OAEP-256`, and that `enc` is `A256GCM`. The design rejects anything else by name, so a surprise there fails in production and nowhere earlier. The unit tests cannot catch it, because they decrypt what they themselves encrypted.
-
-This needs a live-mode account with the Managed API Keys API gated on, which has lead time. It should be in flight before this work merges, not after.
diff --git a/docs/superpowers/specs/2026-09-17-stripe-api-key-rotation-design.md b/docs/superpowers/specs/2026-09-17-stripe-api-key-rotation-design.md
deleted file mode 100644
index 8f7e0b6270..0000000000
--- a/docs/superpowers/specs/2026-09-17-stripe-api-key-rotation-design.md
+++ /dev/null
@@ -1,468 +0,0 @@
-# Stripe API key secret rotation (ENG-5685)
-
-Design for rotating Stripe secret API keys on top of the Stripe app connection landed in
-`551d660262`. Ticket: [ENG-5685](https://linear.app/infisical/issue/ENG-5685). Draft PR:
-[#8194](https://github.com/Infisical/infisical/pull/8194).
-
-## The constraint that shapes everything
-
-Stripe does not let any API key create another API key. The only principal that can is an installed
-Stripe App holding `api_key_write`, which is why the connection exists at all.
-
-Infisical authenticates with its own Stripe secret key (`INF_APP_CONNECTION_STRIPE_SECRET_KEY`) and
-names the customer's account with the `Stripe-Context` header. The OAuth exchange's access and
-refresh tokens are deliberately not stored, so the connection persists only the customer's
-`accountId`. Rotation reads that `accountId` off the connection and otherwise uses instance
-configuration. There is no per-connection token to refresh and no expiry to track.
-
-One consequence: nothing proactively notices that a customer uninstalled the app. It surfaces as a
-403 at rotation time. That is the accepted cost of storing no tokens, and the error handling below
-accounts for it.
-
-## What we measured
-
-Everything in this section was measured against a gated Stripe sandbox
-(`acct_1UG1HNCkOyYCRDAl`, test mode) on 2026-09-17, not inferred from the PoC's comments. The PoC at
-[stripe-secret-rotation-poc](https://github.com/Infisical/stripe-secret-rotation-poc) asserts some of
-these in source comments, but it records no output and its claims about the empty permission list
-turned out to be wrong.
-
-| Question | Answer |
-| --- | --- |
-| Does `rotate` leave a grace period? | No. It mints a new key object with a new id, the old id 404s, and the old token dies at once. |
-| Does `expire` take effect immediately? | No. The key kept authenticating for ~9s, then returned 401. |
-| Does `permissions: []` revoke a key? | No. It returns 200 and silently changes nothing. Stored permissions were unchanged 60s later and the key still worked. |
-| Does narrowing to a non-empty list work? | Yes, and it bites within ~1s. |
-| Can we narrow to a permission the key never held? | Yes. All four candidates tried were accepted and dropped every real capability to 403 within 1.5s. |
-| Is `status` updatable? | No. `'status: Unknown field, did you mean name, note?'` |
-| Is `ip_allowlist` updatable? | No. Readable on the key object, but `'ip_allowlist: Unknown field.'` on update. |
-| Which fields does update accept? | `name`, `note`, `permissions`, `connect_permissions`. |
-| What does the list endpoint return? | `data`, `next_page_url`, `previous_page_url`. |
-| Does retrieve carry the permission lists? | Yes, both `permissions` and `connect_permissions` as arrays. |
-| What does create return in test mode? | The secret in plaintext at `secret_key.token`. |
-| Can the FIPS image decrypt Stripe's JWE? | Yes. Under `--force-fips` with `crypto.getFips() === 1`, OAEP-SHA1, OAEP-SHA256 and A256GCM all round-trip. |
-| Can `permissions` and `connect_permissions` be narrowed in one request? | Yes, on a Connect-platform sandbox. Both stored as sent. Untested against an account that is not a Connect platform. |
-| Do list items carry the permission arrays? | Yes, both, so the form's prefill needs no per-key retrieve. |
-| Does the list endpoint return secrets? | Yes. Every item carries `secret_key.token` in full plaintext, alongside `secret_token_redacted`. |
-| What is the maximum page size? | 100. `limit=200` returns 400 `'limit: The maximum page limit is 100'`. |
-| What prefix do minted keys carry? | `rk_`, a restricted key, not `sk_`. |
-
-The FIPS result settles whether *we* can decrypt what Stripe sends: even if Stripe returns
-`alg: RSA-OAEP` (OAEP with SHA-1) rather than OAEP-256, the OpenSSL 3 FIPS provider permits it for
-key transport, so there is no lead time on Stripe. It does not settle what Stripe actually sends,
-which is a separate and still-open risk. See "Open risks".
-
-The ~9s expire delay is a single sample from one sandbox, so we treat the expire window as unknown
-rather than as 9 seconds.
-
-## The list endpoint returns live secrets
-
-Every item `GET /v2/iam/api_keys` returns carries `secret_key.token` in full plaintext, for every key
-in the account, not just the ones we manage. A redacted form sits beside it in
-`secret_token_redacted`.
-
-This makes `listApiKeys` a handling problem rather than a plumbing one. Three rules follow, and none
-of them are optional:
-
-- `listApiKeys` maps each item to a narrow shape (`{ id, name, permissions, connectPermissions,
- status }`) and never returns the Stripe object. The mapping happens in the service, not the router,
- so no caller can reach the raw object.
-- The route's response schema is an explicit allowlist, never a passthrough or a `.partial()` of a
- Stripe shape. A passthrough schema here ships every secret key in the customer's Stripe account to
- the browser.
-- Nothing logs the raw response body. The shared error extractor already reads only
- `error.response.data.error.message`, which is safe, but a `logger.debug(response.data)` added later
- would not be.
-
-The test for `listApiKeys` asserts the absence of `secret_key` in its output, so that a future
-refactor that widens the mapping fails the suite rather than leaking quietly.
-
-## Rotation is create-then-retire, not `rotate`
-
-Stripe's `rotate` endpoint is disqualified. It kills the old token instantly and mints a new id, so
-every consumer of the secret breaks at the moment of rotation. Rotation has to create a new key and
-retire an old one separately.
-
-That maps cleanly onto the framework's existing two-slot model. `rotateGeneratedCredentials` keeps
-two generations of credentials and hands the factory the *inactive* one to revoke, which is the key
-from two rotations ago, not the live one. So the handover window is a full rotation interval and it
-does not depend on expire being prompt. This is the reason the design survives treating the expire
-window as unknown.
-
-## Where the code goes
-
-```
-backend/src/services/app-connection/stripe/
- stripe-connection-public-client.ts new: shared auth, headers, error shaping, pagination
- stripe-connection-service.ts new: listApiKeys, backing the form's prefill
- stripe-connection-fns.ts refactored onto the public client
-
-backend/src/ee/services/secret-rotation-v2/stripe-api-key/
- stripe-api-key-rotation-constants.ts
- stripe-api-key-rotation-schemas.ts
- stripe-api-key-rotation-types.ts
- stripe-api-key-rotation-fns.ts
- stripe-api-key-rotation-fns.test.ts
- stripe-api-key-jwe.ts parse and decrypt, no HTTP
- stripe-api-key-jwe.test.ts
- index.ts
-```
-
-The public client is a targeted fix rather than a drive-by refactor. `getStripeSecretKey`, the
-`STRIPE_PREVIEW_API_VERSION` constant and the error-message extraction are private inside
-`stripe-connection-fns.ts` today, and rotation needs all three. Following the
-`supabase-connection-public-client.ts` precedent keeps one definition of what a Stripe request looks
-like, so the connection check and the rotation cannot drift on the preview version header.
-
-JWE parsing lives in its own file with no HTTP in it, so the crypto is testable against fixtures
-without mocking a request.
-
-Wiring points mirror the app-connection ones in `551d660262`, but "the compiler will find them" is
-only half true, so they are enumerated here.
-
-The compiler catches these, because adding the enum member breaks them:
-
-- `secret-rotation-v2-maps.ts`, both the name map and the connection map
-- `secret-rotation-v2-fns.ts`, the list-options map
-- `secret-rotation-v2-service.ts`, `SECRET_ROTATION_FACTORY_MAP`
-- `secret-rotation-v2-routers/index.ts`, the router map
-- `frontend/src/helpers/secretRotationsV2.ts`, the name/image map, the connection map, and
- `IS_ROTATION_DUAL_CREDENTIALS`, which is `true` here because Stripe is create-then-retire
-- the four frontend registries: Parameters, Review, SecretsMapping and ViewGeneratedCredentials
-
-The compiler does not catch these, and missing one breaks the feature silently:
-
-- `secret-rotation-v2-union-schema.ts`, an array member in a discriminated union
-- `secret-rotation-v2-router.ts`, the list-item schema union
-- `secret-rotation-v2-types.ts`, five separate union members
-- `backend/src/lib/api-docs/constants.ts`, the `SecretRotations.PARAMETERS` and `SECRETS_MAPPING`
- describe strings
-- `frontend/src/components/secret-rotations-v2/forms/schemas/index.ts`, the union
-- a new `stripe-api-key-rotation-router.ts`
-
-New, and specific to the `listApiKeys` route:
-
-- the endpoint in `stripe-connection-router.ts`, which today only calls
- `registerAppConnectionEndpoints`. `supabase-connection-router.ts` is the template, with
- `readLimit`, an `operationId`, a named response key and `verifyAuth([AuthMode.JWT, AuthMode.OAUTH])`
-- `stripe: stripeConnectionService(connectAppConnectionById)` in `app-connection-service.ts`, beside
- `supabase:` at line 1415. This is a plain object literal, so omitting it compiles and then 500s at
- runtime
-- `frontend/src/hooks/api/appConnections/stripe/queries.tsx`, plus its types and query-key wiring
-
-The frontend image entry needs `Stripe.svg`. The integrations image directory carries an svg, so the
-`.png` in neighbouring entries is not a template to copy.
-
-## What the user configures
-
-Permissions are ordinary rotation parameters, following the Cloudflare API token and dbt service
-token precedent:
-
-- `permissions: string[]`, minimum one entry.
-- `connectPermissions: string[]`, optional.
-- Secrets mapping has one entry, `apiKey`, defaulting to `STRIPE_SECRET_KEY`.
-- Generated credentials are `{ keyId, apiKey }`.
-
-There are two established patterns in this repo for where a rotated credential's permissions come
-from. Most providers name a container that already owns them (`serviceAccountId` for the Datadog application key,
-`projectId` for OpenAI, `projectRef` for Supabase, `objectId` for Azure). Cloudflare and dbt declare
-them explicitly as parameters, because permissions attach to the credential itself and there is no
-container in between. Stripe is the second case: a key's permissions live on the key, and there is no
-service account or project object. So Cloudflare is the analogue and explicit parameters are the
-precedent.
-
-The 158 permission names live in one backend constant, validated with `z.nativeEnum`, and the
-frontend picker imports that same list. An earlier draft validated shape only and kept the list on
-the frontend, on the argument that Stripe would validate the names for us when `issueCredentials`
-mints the first key. That argument does not survive contact with `PATCH`: updating an existing
-rotation's permissions mints nothing, so a bad name would sit there until the next scheduled
-rotation, which is precisely the 3am failure the argument claimed to avoid.
-
-A backend enum also follows dbt, which is the closest precedent and validates membership with
-`z.nativeEnum(DbtPermissionsSet)` over 27 names. Cloudflare's `permissionGroupIds` are free-form only
-because they are opaque Cloudflare-generated IDs rather than a fixed vocabulary. Stripe's names are a
-fixed vocabulary, so dbt is the model. `CODE_QUALITY.md` asks for the same thing twice over, once for
-enums appearing in the generated docs and once for bounding every string.
-
-Alongside the enum, the array carries `.max(200)`, comfortably above the 158 that exist, so a caller
-cannot post an unbounded list.
-
-The cost is that a permission Stripe adds later is rejected until we update the constant. That is a
-one-line change, it fails loudly at request time rather than silently at rotation time, and it is the
-trade the guide asks for.
-
-Permissions have no wildcard and there is no unrestricted key type, so "full access" means listing
-all 158. The PoC enumerated them by probing each one, which implies there is no endpoint that lists
-them, so the constant has to be maintained by hand.
-
-## Retiring a key
-
-One helper, `$retireKey(keyId)`, owns retirement and both callers go through it: the retirement
-inside a rotation, and delete-with-revoke. For v1 it does one thing.
-
-`POST /v2/iam/api_keys/{id}/expire`, treating 404 as already gone. A failure here is fatal, because
-this is the retirement.
-
-### Why there is no permission narrowing in v1
-
-Narrowing a key's permissions is the only lever Stripe gives us with immediate effect, and we
-measured it working: about a second to drop every capability to 403, including when narrowing to a
-permission the key never held. An earlier draft of this design used it, setting retired keys to
-`apple_pay_domain_read` before expiring them.
-
-It is deliberately not in v1. Expire lands within minutes, rotations run on a weekly or monthly
-cadence, and the key being retired stopped being the live secret a full interval earlier. Against
-that, the delay expire leaves is insignificant, and narrowing costs an extra call, an extra failure
-mode, a hardcoded permission name needing explanation wherever a customer might see it, and a
-fallback path for accounts that are not Connect platforms.
-
-The measured facts are kept in this document so adding it back is a decision, not a re-investigation.
-It goes inside `$retireKey` and nothing else in the factory needs to know.
-
-## Lifecycle
-
-`issueCredentials`: mint key #1 from the parameters and commit. Nothing else is touched. If the
-commit throws, expire the key we just minted and rethrow, for the same reason `rotateCredentials`
-does. This is not theoretical: the create callback takes an advisory lock and re-runs
-`$throwOnConflictingSecrets` inside the transaction
-(`secret-rotation-v2-service.ts:653`), so a racing create legitimately throws after the key exists in
-Stripe.
-
-`rotateCredentials(credentialsToRevoke, callback, activeCredentials)`:
-
-1. Mint a new key from `secretRotation.parameters.permissions` with a freshly generated RSA keypair.
-2. Retire `credentialsToRevoke`, the key from two rotations ago, through `$retireKey`.
-3. Commit through the callback.
-4. If the commit throws, expire the key we just minted and rethrow, so a failed database write does
- not leave a live Stripe key nobody is tracking.
-
-Step 2 before step 3 is deliberate, and follows the Azure ordering rather than the Supabase one. It
-keeps Postgres and Stripe consistent: nothing is committed until the retirement has happened, so the
-stored credentials always describe keys that exist in the state we think they do. The Supabase
-ordering commits first, so each of BullMQ's five attempts would mint and commit another key.
-
-It does not make orphans impossible. When retirement fails for a reason that also breaks the cleanup
-expire (a Stripe outage, a network partition mid-sequence), each attempt mints a key it then cannot
-clean up. What bounds the damage is that the most likely cause of a retirement 403, a revoked app
-install, fails the create first, so nothing is minted at all.
-
-## Minting a key
-
-`POST /v2/iam/api_keys` with `type: "secret_key"`, a generated `name`, the two permission lists from
-parameters, and a `public_key` Stripe encrypts the result to. Publishable keys are out of scope,
-since they are not secrets.
-
-The minted key's mode follows the mode of the instance's `INF_APP_CONNECTION_STRIPE_SECRET_KEY`. An
-instance configured with a test key mints test keys, and there is no per-rotation choice. That is a
-property of the connection design rather than something rotation can fix, so it belongs in the docs.
-
-### The RSA keypair is ephemeral
-
-Generate a fresh RSA-2048 keypair inside the create call, use it for that one request, and let it
-fall out of scope when the function returns. Use the asynchronous `generateKeyPair`, not
-`generateKeyPairSync`: this runs in a process that is also serving API traffic, and Node is
-single-threaded, so tens of milliseconds of synchronous keygen is exactly the stall `CODE_QUALITY.md`
-warns about. The private key is never written anywhere, never
-KMS-wrapped, and never reused.
-
-This settles the open question in the handoff about where the private key lives and how long it
-lives. There is no per-rotation, per-connection or instance-wide keypair to decide about, because the
-key exists for the duration of one HTTP request. The cost is one RSA-2048 keygen per rotation,
-off the event loop, against a call that already crosses the internet.
-
-### Two response shapes, both real
-
-Test and sandbox accounts return the secret in plaintext at `secret_key.token`. Live accounts return
-`secret_key.encrypted_secret.ciphertext`, a compact JWE. We handle both and throw a clear error if
-neither is present. This is not defensive padding: the sandbox we develop against takes the first
-branch and production takes the second, so shipping only one means the feature is untested in exactly
-the mode that matters.
-
-### JWE handling
-
-A JWE is the encrypted counterpart of a JWT. Where a JWS is signed and its payload is readable by
-anyone, a JWE's payload is unreadable without the key, and the compact form has five dot-separated
-segments rather than three: `header.encryptedKey.iv.ciphertext.tag`. It is a hybrid scheme because
-RSA cannot encrypt much data directly, so Stripe encrypts the secret with a random AES-256-GCM
-content key and encrypts that content key with our RSA public key. That is why the header carries two
-algorithm fields, `alg` for how the content key was wrapped and `enc` for how the payload was
-encrypted.
-
-`stripe-api-key-jwe.ts` does the following, with no HTTP in it:
-
-- Split on `.` and require exactly five segments.
-- Parse the protected header, accepting `alg` of `RSA-OAEP` (OAEP with SHA-1) or `RSA-OAEP-256`
- (SHA-256), and rejecting anything else by name. The PoC does
- `alg === "RSA-OAEP" ? "sha1" : "sha256"`, which silently treats an unrecognised algorithm as
- SHA-256 and surfaces it as an opaque padding failure.
-- Require `enc` of `A256GCM`.
-- Unwrap the content key with `privateDecrypt`, then AES-256-GCM with the auth tag and the ASCII
- bytes of the protected header segment as AAD.
-
-The GCM tag already guarantees integrity, so there is no prefix check on the decrypted token.
-Asserting it starts with `sk_` would only add a rule to maintain when Stripe introduces a prefix we
-have not seen.
-
-### Idempotency, and what it does not buy us
-
-Every POST carries a fresh `Idempotency-Key`. It covers transport-level retries inside a single call,
-not BullMQ's five attempts, since each attempt is a fresh rotation that should mint a fresh key
-anyway.
-
-The residual failure is a create that times out after Stripe committed it. We never learn the id, so
-we cannot expire it, and the customer is left with a key we do not track. We mitigate by naming keys
-`infisical-rotation-<rotationId>-<timestamp>`, so a stray is identifiable in the Stripe dashboard as
-ours and traceable to a rotation. Reconciling by listing keys and matching the name prefix before
-every mint would add a paginated list call and a whole class of "is this stray mine" judgement to
-every rotation, which is not worth it for a window that only opens on a timed-out request.
-
-## Error handling
-
-We reuse the connection's existing phrasing, which names the account, the status and Stripe's own
-message, and asserts nothing about why:
-
-```
-Infisical cannot manage API keys on Stripe account 'acct_x'. Stripe returned 403: <stripe's message>.
-```
-
-A revoked app install surfaces here as a 403. We do not assert that as the cause, because we have not
-checked it, but the 403 case is narrow enough to offer the remedy conditionally: if the app was
-removed from this Stripe account, reinstall it and reconnect. The rotation docs page carries the
-same remedy at more length.
-
-What happens when a step fails:
-
-- Create fails: rotation fails, nothing changed, BullMQ retries. Clean.
-- Retirement fails: abort before committing, expire the key we just minted, and throw the retirement
- error. If that cleanup also fails, the message names the stranded key id so a human can remove it,
- following the Azure precedent.
-- Expire returns 404: the key is already gone, treat as success.
-- Commit throws after a successful retirement: expire the new key and rethrow. If that expire also
- fails, the message names the stranded key, the same as the retirement path.
-- The transaction commits but the promise rejects, for instance a dropped connection on the response.
- Step 4 would then expire the key that is now the live secret in the database. Low probability, high
- blast radius, and nothing in the factory can distinguish it from a genuine commit failure. We
- accept it and note it here rather than pretending the cleanup is free.
-- A permission name Stripe does not recognise: rejected by our own enum at request time, on create
- and on update alike.
-
-Stripe 429s ride on BullMQ's existing exponential backoff. There is no Stripe equivalent of the
-concurrent-request quirk that forced Azure to grow its own retry loop, so we do not build one.
-
-Nothing we write claims a key is dead. On delete-with-revoke we say Infisical expired the key in
-Stripe, which is exactly what we did.
-
-## Tests
-
-`stripe-api-key-jwe.test.ts`, fixtures built in-test from a local keypair: both algorithms
-round-trip, wrong segment count rejected, unknown `alg` and `enc` rejected by name, a tampered tag
-fails. Plus the FIPS assertion, which is what stops a toolchain bump from breaking live-mode
-decryption silently. The suite already runs under `--force-fips` in the FIPS toolchain image, so this
-costs nothing to keep honest.
-
-`stripe-api-key-rotation-fns.test.ts`, mocking `request` the way the Azure suite does: the plaintext
-and JWE response paths, retirement happening before the commit, commit failure expiring the new key
-on both `issueCredentials` and `rotateCredentials`, cleanup failure naming the stranded key, 404 on
-expire tolerated, permissions taken from parameters, and `checkActiveCredentials` treating 403 as
-alive and 401 as dead.
-
-`listApiKeys` gets two tests. One for pagination, since reading page one and calling it a list is a
-bug under CODE_QUALITY, and one asserting that no `secret_key` field survives the mapping, so that a
-future refactor which widens the shape fails the suite rather than leaking every Stripe key in the
-customer's account.
-
-There is no e2e test, because it needs the gated sandbox. Manual verification steps against it go in
-the PR instead, mirroring its existing verification section.
-
-## Frontend
-
-File-per-provider, following the Cloudflare API token rotation:
-
-- `hooks/api/secretRotationsV2/types/stripe-api-key-rotation.ts`, plus the enum and index entries.
-- `forms/schemas/stripe-api-key-rotation-schema.ts`.
-- `StripeApiKeyRotationParametersFields.tsx`.
-- `StripeApiKeyRotationReviewFields.tsx`, `StripeApiKeyRotationSecretsMappingFields.tsx`,
- `ViewStripeApiKeyRotationGeneratedCredentials.tsx`, and the three registry files that switch on
- rotation type.
-
-The parameters field is the only non-mechanical piece. It holds the permission multi-select and a
-"copy from an existing key" prefill backed by a `useStripeConnectionListApiKeys` query against the
-new route. The prefill matters because re-deriving a working permission set by hand from 158 entries
-risks minting a key that is missing something the caller needs, and that failure lands in production
-right after the secret is swapped.
-
-No new shared component is needed. The v3 `Combobox` has a `multiple` chips-based variant, search via
-`getOptionKeywords`, and select-all with a count, switched on with the `isSelectAll` prop.
-`ComboboxSelectAll` itself is internal and is not exported, so consumers pass the prop rather than
-composing the subcomponent. The
-[component lifecycle ledger](../../../frontend/src/components/COMPONENT_LIFECYCLE.md) also names
-`Combobox` as the replacement for the deprecated `FilterableSelect`, so using it moves with the
-migration rather than against it.
-
-Two of its behaviours matter at this list size. Select-all covers only the currently visible result
-set, by design, so with a search term active it selects the matches rather than all 158. That is the
-right behaviour but it means the UI must not label it in a way that implies otherwise. And the
-multiple variant renders one chip per selection, so a full-access rotation renders 158 chips. We keep
-the default wrapping layout rather than `singleLine`, which would put 158 chips in a horizontal
-scroller, and we accept the height the wrapping list takes.
-
-## Docs
-
-Per the `docs-style` skill, with `make lint-docs-branch` after:
-
-- `docs/documentation/platform/secret-rotation/stripe-api-key.mdx`.
-- `docs/integrations/app-connections/stripe.mdx`, still outstanding from the connection PR.
-- Eight API reference pages under `docs/api-reference/endpoints/secret-rotations/stripe-api-key/`,
- matching the Cloudflare set, plus `docs.json` and `RotationsBrowser.jsx`.
-
-The rotation page has to state four things plainly, because each is a support ticket otherwise:
-
-- The minted key's mode follows the instance's Stripe key, so a test-mode instance mints test keys.
-- Infisical never touches keys it did not create, so the user's original key stays live until they
- expire it themselves, once their applications have picked up the rotated secret.
-- Expiry timing is Stripe's, so we describe what we did rather than claiming the key is dead.
-- Retirement expires the key, and Stripe decides when that takes effect, so a retired key may keep
- answering briefly.
-
-The connection page has to note that the rotated value is an `rk_` restricted key rather than an
-`sk_` secret key, since anything asserting on the prefix will break.
-
-## Out of scope
-
-- Publishable keys. They are not secrets.
-- Mapping `keyId` to a secret. It is tracked in the generated credentials but not exposed to
- consumers, unlike Cloudflare and Datadog which map both. Nothing consumes a Stripe key id.
-- A user-supplied key `name`, which Cloudflare, dbt, Datadog and OpenAI all take. We generate
- `infisical-rotation-<rotationId>-<timestamp>` instead, because a predictable name is what makes a
- stray key identifiable as ours in the Stripe dashboard.
-- Choosing live or test mode per rotation. It follows the instance's Stripe key.
-- Re-reading permissions from Stripe on each rotation. Parameters are the source of truth, so
- broadening a key's permissions means editing the rotation.
-- Proactive detection of a revoked app install. It surfaces as a 403 at rotation time, which is the
- accepted cost of storing no tokens.
-- The shared dev redirect URI question and publishing the app from a clean non-Connect account. Both
- are on the PR's pre-merge checklist and are connection concerns, not rotation ones.
-
-## Open risks
-
-### Live mode is entirely unverified
-
-Everything we measured came from a test-mode sandbox, which returns the secret in plaintext. The live
-path is asserted, not observed: that create accepts a `public_key` field, that the response carries
-`secret_key.encrypted_secret.ciphertext`, that `alg` is `RSA-OAEP` or `RSA-OAEP-256`, and that `enc`
-is `A256GCM`. Our design rejects any other `alg` or `enc` by name, so if Stripe sends something else,
-rotation fails in production and nowhere before it. The unit tests cannot catch this by construction,
-because they build their fixtures from a local keypair and therefore only prove we can decrypt what
-we ourselves encrypted.
-
-This is the top risk on the feature, and the FIPS measurement does not touch it. FIPS answered
-whether we can decrypt OAEP-SHA1, not what Stripe actually sends. Verifying it needs a live-mode
-account with the Managed API Keys API gated on, which is a Daniel question and has lead time, so it
-should start now rather than at the end.
-
-### Stripe's silent 200 on an empty permission list
-
-Returning 200 for `permissions: []` while silently ignoring it looks like a bug, and we are raising
-it with them. It does not affect v1, which does not narrow. If they fix it, adding an immediate
-revocation step to `$retireKey` becomes a two-line change with no hardcoded permission name to
-explain, which is the version of narrowing worth having.