Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
feat: define new endpoint to receive callbacks from the external deleagated service
adilson6b32f9ddd8a4
diff --git a/CLAUDE.md b/CLAUDE.mdindex b7a431abeb..51c34b45a3 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -174,13 +174,22 @@ policy blocked by pending requests is freed for editing. Every provider implemen(`dispatch/providers/<name>/`); a new policy type adds an arm to `TDelegatedApprovalDispatchDetails` and abuilder in `DELEGATED_APPROVAL_DISPATCH_DETAILS_BUILDER_MAP` rather than branching in a provider. The workerreads from the primary, never checks the license, and throws bullmq's `UnrecoverableError` for anything a retry-cannot fix. The callback contract (token issuance now, the inbound route and approve / reject later) is its own+cannot fix. The callback contract (token issuance, the inbound route; approve / reject later) is its ownmodule, `backend/src/services/delegated-approval-callback/`, so the delegated approval module never grows a-callback branch. A request gets exactly one callback token for its whole life: it is random, issued on the first-dispatch attempt, and stored encrypted under the org KMS key in `encryptedCallbackToken` so every retry resends-the same value; the inbound side finds the row by the provider's record id and compares the decrypted token with-the presented one. Never send a provider a token that differs from the one stored for the request; the provider-keeps the first token it was given and cannot be told another, so a mismatch is unrecoverable.+callback branch. A request gets exactly one callback token for its whole life: it is random, prefixed `inf_ext_`,+issued on the first dispatch attempt, and stored encrypted under the org KMS key in `encryptedCallbackToken` so+every retry resends the same value. Never send a provider a token that differs from the one stored for the+request; the provider keeps the first token it was given and cannot be told another, so a mismatch is+unrecoverable. The provider calls `POST /api/v1/delegated-approvals/callback` (unauthenticated, IP rate limited)+with the token in the `Infisical-Approval-Token` header and a body naming the event and the provider's record id;+the body carries no decision, which a later worker reads back from the provider. The route finds the row by+`providerRequestId` (404 when none), counts the callback in `callbackAttempts` before checking anything else so a+wrong token for a known record still burns the request, and on the sixth callback sets the row `failed` with a+readable `statusReason` and cancels the attached approval request in the same transaction, so the policy is freed+and the UI stops offering Cancel. Every other refusal (bad or missing token, request not `waiting_approval`)+gets one neutral 403 while the reason goes to the log. An accepted callback only emits an outbox event: `eventType` is the body's event,+`idempotencyKey` is the delegated request id so a repeat is dropped, and the `delegated-approval-callback`+consumer is a placeholder that marks the row delivered until the read-back worker replaces it.### API Layer (Frontend)diff --git a/backend/src/server/config/rateLimiter.ts b/backend/src/server/config/rateLimiter.tsindex bda9eb5c9b..1c67e16cf6 100644--- a/backend/src/server/config/rateLimiter.ts+++ b/backend/src/server/config/rateLimiter.ts@@ -77,9 +77,10 @@ export const ocspLimit: RateLimitOptions = {keyGenerator: (req) => req.realIp};-// The delegated approval callback is unauthenticated, so the IP is all there is to key on. Each request-// accepts at most a handful of callbacks before it is invalidated, so one instance never needs more.-export const delegatedApprovalCallbackLimit: RateLimitOptions = {+// For callbacks an external system sends us without an Infisical identity (delegated approvals), so+// the IP is all there is to key on. Each resource accepts a bounded number of callbacks before it is+// closed, so one integration never needs more than this per address.+export const externalInboundCallbackLimit: RateLimitOptions = {timeWindow: 60 * 1000,hook: "preValidation",max: 60,diff --git a/backend/src/server/routes/v1/delegated-approval-callback-router.ts b/backend/src/server/routes/v1/delegated-approval-callback-router.tsnew file mode 100644index 0000000000..618083916d--- /dev/null+++ b/backend/src/server/routes/v1/delegated-approval-callback-router.ts@@ -0,0 +1,65 @@+import { z } from "zod";++import { externalInboundCallbackLimit } from "@app/server/config/rateLimiter";+import {+ DELEGATED_APPROVAL_CALLBACK_TOKEN_HEADER,+ DELEGATED_APPROVAL_CALLBACK_TOKEN_MAX_LENGTH+} from "@app/services/delegated-approval-callback/delegated-approval-callback-constants";+import { DelegatedApprovalCallbackEvent } from "@app/services/delegated-approval-callback/delegated-approval-callback-enums";++export const registerDelegatedApprovalCallbackRouter = async (server: FastifyZodProvider) => {+ // Deliberately unauthenticated: the caller is the delegated approval system, which holds no Infisical+ // identity. The per-request token in the header is the credential, checked by the service.+ server.route({+ method: "POST",+ url: "/callback",+ config: {+ rateLimit: externalInboundCallbackLimit+ },+ schema: {+ hide: true,+ operationId: "handleDelegatedApprovalCallback",+ description: "Receive a decision notification from a delegated approval system.",+ headers: z+ .object({+ [DELEGATED_APPROVAL_CALLBACK_TOKEN_HEADER]: z+ .string()+ .trim()+ .max(DELEGATED_APPROVAL_CALLBACK_TOKEN_MAX_LENGTH)+ .optional()+ .describe("The callback token Infisical issued when it sent the request.")+ })+ .passthrough(),+ body: z.object({+ version: z.literal(1).describe("The callback contract version."),+ event: z+ .nativeEnum(DelegatedApprovalCallbackEvent)+ .describe("The event Infisical named when it created the request, returned unchanged."),+ details: z.object({+ externalId: z+ .string()+ .trim()+ .min(1)+ .max(255)+ .describe("The delegated approval system's record ID for the request.")+ })+ }),+ response: {+ 200: z.object({+ message: z.string()+ })+ }+ },+ handler: async (req) => {+ await server.services.delegatedApprovalCallback.handleCallback({+ token: req.headers[DELEGATED_APPROVAL_CALLBACK_TOKEN_HEADER],+ event: req.body.event,+ externalId: req.body.details.externalId+ });++ return {+ message: "Callback accepted. Infisical will read the decision from the delegated approval system."+ };+ }+ });+};diff --git a/backend/src/server/routes/v1/index.ts b/backend/src/server/routes/v1/index.tsindex 11fdfbf596..3af9fa4007 100644--- a/backend/src/server/routes/v1/index.ts+++ b/backend/src/server/routes/v1/index.ts@@ -31,6 +31,7 @@ import { registerCertificateInventoryViewRouter } from "./certificate-inventory-import { registerCertificatePolicyRouter } from "./certificate-policy-router";import { registerCertificateProfilesRouter } from "./certificate-profiles-router";import { registerCertificateRouter } from "./certificate-router";+import { registerDelegatedApprovalCallbackRouter } from "./delegated-approval-callback-router";import { registerDelegatedApprovalRouter } from "./delegated-approval-router";import { DEPRECATED_CERTIFICATE_AUTHORITY_REGISTER_ROUTER_MAP } from "./deprecated-certificate-authority-routers";import { registerDeprecatedCertRouter } from "./deprecated-certificate-router";@@ -377,6 +378,7 @@ export const registerV1Routes = async (server: FastifyZodProvider) => {await server.register(registerEventRouter, { prefix: "/events" });await server.register(registerDelegatedApprovalRouter, { prefix: "/delegated-approvals" });+ await server.register(registerDelegatedApprovalCallbackRouter, { prefix: "/delegated-approvals" });await server.register(async (approvalPolicyRouter) => {// Register policy type-specific endpointsdiff --git a/backend/src/services/delegated-approval-callback/delegated-approval-callback-constants.ts b/backend/src/services/delegated-approval-callback/delegated-approval-callback-constants.tsindex fbe6f2fd9b..9cac38ac7b 100644--- a/backend/src/services/delegated-approval-callback/delegated-approval-callback-constants.ts+++ b/backend/src/services/delegated-approval-callback/delegated-approval-callback-constants.ts@@ -1,3 +1,19 @@export const DELEGATED_APPROVAL_CALLBACK_PATH = "/api/v1/delegated-approvals/callback";export const DELEGATED_APPROVAL_CALLBACK_TOKEN_BYTES = 32;++export const DELEGATED_APPROVAL_CALLBACK_TOKEN_PREFIX = "inf_ext_";++// Lowercase on purpose: Node lowercases incoming header names, and Fastify compiles a Zod headers+// schema as-is, so the key has to match what arrives.+export const DELEGATED_APPROVAL_CALLBACK_TOKEN_HEADER = "infisical-approval-token";++export const DELEGATED_APPROVAL_CALLBACK_TOKEN_MAX_LENGTH = 256;++export const DELEGATED_APPROVAL_CALLBACK_MAX_ATTEMPTS = 5;++export const DELEGATED_APPROVAL_CALLBACK_EVENT_CONSUMER = "delegated-approval-callback";++export const DELEGATED_APPROVAL_CALLBACK_REJECTED_MESSAGE = "Callback rejected.";++export const DELEGATED_APPROVAL_CALLBACK_ATTEMPTS_EXHAUSTED_REASON = `The delegated approval system called back more than ${DELEGATED_APPROVAL_CALLBACK_MAX_ATTEMPTS} times, so Infisical no longer accepts its decision for this request. Create the request again.`;diff --git a/backend/src/services/delegated-approval-callback/delegated-approval-callback-enums.ts b/backend/src/services/delegated-approval-callback/delegated-approval-callback-enums.tsnew file mode 100644index 0000000000..48aa525b7b--- /dev/null+++ b/backend/src/services/delegated-approval-callback/delegated-approval-callback-enums.ts@@ -0,0 +1,3 @@+export enum DelegatedApprovalCallbackEvent {+ SecretsManagementAccessRequest = "secrets_management.access_request"+}diff --git a/backend/src/services/delegated-approval-callback/delegated-approval-callback-event-consumer.test.ts b/backend/src/services/delegated-approval-callback/delegated-approval-callback-event-consumer.test.tsnew file mode 100644index 0000000000..0765afb577--- /dev/null+++ b/backend/src/services/delegated-approval-callback/delegated-approval-callback-event-consumer.test.ts@@ -0,0 +1,67 @@+import { describe, expect, test, vi } from "vitest";++import { EventResultStatus, TEvent } from "@app/services/event-outbox/event-outbox-types";++import { DELEGATED_APPROVAL_CALLBACK_EVENT_CONSUMER } from "./delegated-approval-callback-constants";+import { DelegatedApprovalCallbackEvent } from "./delegated-approval-callback-enums";+import { delegatedApprovalCallbackEventConsumerFactory } from "./delegated-approval-callback-event-consumer";++vi.mock("@app/lib/logger", () => ({+ logger: { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} },+ initLogger: () => {}+}));++const makePayload = (overrides?: Record<string, unknown>) => ({+ delegatedRequestId: "11111111-1111-1111-1111-111111111111",+ approvalRequestId: "22222222-2222-2222-2222-222222222222",+ orgId: "33333333-3333-3333-3333-333333333333",+ event: DelegatedApprovalCallbackEvent.SecretsManagementAccessRequest,+ externalId: "9d41f2a7c3b24e1088f6a05e7b1d4c93",+ ...overrides+});++const makeEvent = (overrides?: Partial<TEvent>): TEvent =>+ ({+ id: 1,+ eventType: DelegatedApprovalCallbackEvent.SecretsManagementAccessRequest,+ payload: makePayload(),+ occurredAt: new Date(),+ ...overrides+ }) as TEvent;++describe("delegatedApprovalCallbackEventConsumer", () => {+ const consumer = delegatedApprovalCallbackEventConsumerFactory();++ test("is registered under the callback consumer name", () => {+ expect(consumer.name).toBe(DELEGATED_APPROVAL_CALLBACK_EVENT_CONSUMER);+ });++ test("subscribes only to the callback events", () => {+ expect(consumer.subscribesTo(DelegatedApprovalCallbackEvent.SecretsManagementAccessRequest)).toBe(true);+ expect(consumer.subscribesTo("approval.workflow.request_opened")).toBe(false);+ });++ test("accepts a valid payload at emit", () => {+ expect(consumer.payloadSchema.safeParse(makePayload()).success).toBe(true);+ expect(consumer.payloadSchema.safeParse(makePayload({ orgId: "not-a-uuid" })).success).toBe(false);+ });++ test("marks a readable event delivered", async () => {+ const [result] = await consumer.handle([makeEvent()]);++ expect(result).toEqual({ id: "1", status: EventResultStatus.Delivered });+ });++ test("fails an unreadable payload instead of retrying it", async () => {+ const [result] = await consumer.handle([makeEvent({ payload: { delegatedRequestId: "nope" } })]);++ expect(result.status).toBe(EventResultStatus.Failed);+ expect(result.error).toContain("Unreadable");+ });++ test("returns one result per event", async () => {+ const results = await consumer.handle([makeEvent({ id: 1 }), makeEvent({ id: 2 } as never)]);++ expect(results.map((result) => result.id)).toEqual(["1", "2"]);+ });+});diff --git a/backend/src/services/delegated-approval-callback/delegated-approval-callback-event-consumer.ts b/backend/src/services/delegated-approval-callback/delegated-approval-callback-event-consumer.tsnew file mode 100644index 0000000000..dc13d44081--- /dev/null+++ b/backend/src/services/delegated-approval-callback/delegated-approval-callback-event-consumer.ts@@ -0,0 +1,64 @@+import { z } from "zod";++import { logger } from "@app/lib/logger";+import {+ EventResultStatus,+ IEventConsumer,+ TEvent,+ TEventConsumerResult+} from "@app/services/event-outbox/event-outbox-types";++import { DELEGATED_APPROVAL_CALLBACK_EVENT_CONSUMER } from "./delegated-approval-callback-constants";+import { DelegatedApprovalCallbackEvent } from "./delegated-approval-callback-enums";++export const DelegatedApprovalCallbackEventPayloadSchema = z.object({+ delegatedRequestId: z.string().uuid(),+ approvalRequestId: z.string().uuid(),+ orgId: z.string().uuid(),+ event: z.nativeEnum(DelegatedApprovalCallbackEvent),+ externalId: z.string().trim().min(1).max(255)+});++type TDelegatedApprovalCallbackEventPayload = z.infer<typeof DelegatedApprovalCallbackEventPayloadSchema>;++const CALLBACK_EVENTS = new Set<string>(Object.values(DelegatedApprovalCallbackEvent));++export const delegatedApprovalCallbackEventConsumerFactory =+ (): IEventConsumer<TDelegatedApprovalCallbackEventPayload> => {+ const subscribesTo = (eventType: string) => CALLBACK_EVENTS.has(eventType);++ // Placeholder until the worker that reads the decision back from the delegated approval system+ // exists. It only has to accept the row so the callback is recorded.+ const $handleEvent = (event: TEvent): TEventConsumerResult => {+ const id = String(event.id);+ const payload = DelegatedApprovalCallbackEventPayloadSchema.safeParse(event.payload);+ if (!payload.success) {+ return { id, status: EventResultStatus.Failed, error: "Unreadable delegated approval callback payload" };+ }++ logger.info(+ `Delegated approval callback event received; processing is not implemented yet [eventId=${id}] [delegatedRequestId=${payload.data.delegatedRequestId}] [event=${payload.data.event}]`+ );+ return { id, status: EventResultStatus.Delivered };+ };++ const handle = async (events: TEvent[]): Promise<TEventConsumerResult[]> =>+ events.map((event) => {+ try {+ return $handleEvent(event);+ } catch (error) {+ return {+ id: String(event.id),+ status: EventResultStatus.Retry,+ error: error instanceof Error ? error.message : "Unknown error"+ };+ }+ });++ return {+ name: DELEGATED_APPROVAL_CALLBACK_EVENT_CONSUMER,+ payloadSchema: DelegatedApprovalCallbackEventPayloadSchema,+ subscribesTo,+ handle+ };+ };diff --git a/backend/src/services/delegated-approval-callback/delegated-approval-callback-fns.test.ts b/backend/src/services/delegated-approval-callback/delegated-approval-callback-fns.test.tsindex 4799c95f89..7535e0f6eb 100644--- a/backend/src/services/delegated-approval-callback/delegated-approval-callback-fns.test.ts+++ b/backend/src/services/delegated-approval-callback/delegated-approval-callback-fns.test.ts@@ -1,13 +1,55 @@-import { describe, expect, test } from "vitest";+import { describe, expect, test, vi } from "vitest";-import { generateDelegatedApprovalCallbackToken } from "./delegated-approval-callback-fns";+vi.mock("@app/lib/logger", () => ({+ logger: { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} },+ initLogger: () => {}+}));++// eslint-disable-next-line import/first+import { ForbiddenRequestError } from "@app/lib/errors";++// eslint-disable-next-line import/first+import {+ DELEGATED_APPROVAL_CALLBACK_REJECTED_MESSAGE,+ DELEGATED_APPROVAL_CALLBACK_TOKEN_PREFIX+} from "./delegated-approval-callback-constants";+// eslint-disable-next-line import/first+import {+ generateDelegatedApprovalCallbackToken,+ isDelegatedApprovalCallbackTokenMatch,+ rejectDelegatedApprovalCallback+} from "./delegated-approval-callback-fns";describe("generateDelegatedApprovalCallbackToken", () => {- test("returns a fresh base64url token of 32 random bytes", () => {+ test("returns a prefixed base64url token of 32 random bytes", () => {const token = generateDelegatedApprovalCallbackToken();- expect(token).toMatch(/^[A-Za-z0-9_-]+$/);- expect(Buffer.from(token, "base64url")).toHaveLength(32);+ expect(token.startsWith(DELEGATED_APPROVAL_CALLBACK_TOKEN_PREFIX)).toBe(true);+ const random = token.slice(DELEGATED_APPROVAL_CALLBACK_TOKEN_PREFIX.length);+ expect(random).toMatch(/^[A-Za-z0-9_-]+$/);+ expect(Buffer.from(random, "base64url")).toHaveLength(32);expect(generateDelegatedApprovalCallbackToken()).not.toBe(token);});});++describe("isDelegatedApprovalCallbackTokenMatch", () => {+ test("matches only the exact stored token", () => {+ const token = generateDelegatedApprovalCallbackToken();++ expect(isDelegatedApprovalCallbackTokenMatch(token, token)).toBe(true);+ expect(isDelegatedApprovalCallbackTokenMatch(`${token}x`, token)).toBe(false);+ expect(isDelegatedApprovalCallbackTokenMatch(token.slice(0, -1), token)).toBe(false);+ expect(isDelegatedApprovalCallbackTokenMatch(generateDelegatedApprovalCallbackToken(), token)).toBe(false);+ });+});++describe("rejectDelegatedApprovalCallback", () => {+ test("returns a 403 whose message never carries the reason", () => {+ const error = rejectDelegatedApprovalCallback("token mismatch", { delegatedRequestId: "delegated-1" });++ expect(error).toBeInstanceOf(ForbiddenRequestError);+ expect(error.message).toBe(DELEGATED_APPROVAL_CALLBACK_REJECTED_MESSAGE);+ expect(error.message).not.toContain("token mismatch");+ expect(error.message).not.toContain("delegated-1");+ });+});diff --git a/backend/src/services/delegated-approval-callback/delegated-approval-callback-fns.ts b/backend/src/services/delegated-approval-callback/delegated-approval-callback-fns.tsindex 90bab219d7..7c2e450c2c 100644--- a/backend/src/services/delegated-approval-callback/delegated-approval-callback-fns.ts+++ b/backend/src/services/delegated-approval-callback/delegated-approval-callback-fns.ts@@ -1,6 +1,56 @@import { crypto } from "@app/lib/crypto/cryptography";+import { ForbiddenRequestError } from "@app/lib/errors";+import { logger } from "@app/lib/logger";+import { ApprovalRequestStatus } from "@app/services/approval-policy/approval-policy-enums";+import { DelegatedApprovalRequestStatus } from "@app/services/delegated-approval/delegated-approval-enums";+import { DELEGATED_APPROVAL_STATUS_REASON_MAX_CHARS } from "@app/services/delegated-approval/dispatch/delegated-approval-dispatch-constants";-import { DELEGATED_APPROVAL_CALLBACK_TOKEN_BYTES } from "./delegated-approval-callback-constants";+import {+ DELEGATED_APPROVAL_CALLBACK_ATTEMPTS_EXHAUSTED_REASON,+ DELEGATED_APPROVAL_CALLBACK_REJECTED_MESSAGE,+ DELEGATED_APPROVAL_CALLBACK_TOKEN_BYTES,+ DELEGATED_APPROVAL_CALLBACK_TOKEN_PREFIX+} from "./delegated-approval-callback-constants";+import { TFailExhaustedDelegatedApprovalRequestDTO } from "./delegated-approval-callback-types";export const generateDelegatedApprovalCallbackToken = () =>- crypto.randomBytes(DELEGATED_APPROVAL_CALLBACK_TOKEN_BYTES).toString("base64url");+ `${DELEGATED_APPROVAL_CALLBACK_TOKEN_PREFIX}${crypto.randomBytes(DELEGATED_APPROVAL_CALLBACK_TOKEN_BYTES).toString("base64url")}`;++export const isDelegatedApprovalCallbackTokenMatch = (presented: string, stored: string) => {+ const presentedBytes = Buffer.from(presented);+ const storedBytes = Buffer.from(stored);+ if (presentedBytes.length !== storedBytes.length) return false;+ return crypto.nativeCrypto.timingSafeEqual(presentedBytes, storedBytes);+};++export const rejectDelegatedApprovalCallback = (reason: string, context: Record<string, string>) => {+ const formatted = Object.entries(context)+ .map(([key, value]) => `[${key}=${value}]`)+ .join(" ");+ logger.warn(`Delegated approval callback rejected: ${reason} ${formatted}`);+ return new ForbiddenRequestError({ message: DELEGATED_APPROVAL_CALLBACK_REJECTED_MESSAGE });+};++export const failExhaustedDelegatedApprovalRequest = ({+ id,+ requestId,+ approvalRequestDAL,+ delegatedApprovalRequestDAL+}: TFailExhaustedDelegatedApprovalRequestDTO) =>+ approvalRequestDAL.transaction(async (tx) => {+ const approvalRequest = await approvalRequestDAL.findByIdForUpdate(requestId, tx);+ if (approvalRequest?.status === ApprovalRequestStatus.Pending) {+ await approvalRequestDAL.updateById(requestId, { status: ApprovalRequestStatus.Cancelled }, tx);+ }+ await delegatedApprovalRequestDAL.update(+ { id, status: DelegatedApprovalRequestStatus.WaitingApproval },+ {+ status: DelegatedApprovalRequestStatus.Failed,+ statusReason: DELEGATED_APPROVAL_CALLBACK_ATTEMPTS_EXHAUSTED_REASON.slice(+ 0,+ DELEGATED_APPROVAL_STATUS_REASON_MAX_CHARS+ )+ },+ tx+ );+ });diff --git a/backend/src/services/delegated-approval-callback/delegated-approval-callback-service.test.ts b/backend/src/services/delegated-approval-callback/delegated-approval-callback-service.test.tsindex 58f77f0c56..13ef232356 100644--- a/backend/src/services/delegated-approval-callback/delegated-approval-callback-service.test.ts+++ b/backend/src/services/delegated-approval-callback/delegated-approval-callback-service.test.ts@@ -4,11 +4,27 @@ vi.mock("@app/lib/config/env", () => ({getConfig: () => ({ SITE_URL: "https://app.infisical.com" })}));+vi.mock("@app/lib/logger", () => ({+ logger: { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} },+ initLogger: () => {}+}));++// eslint-disable-next-line import/first+import { ForbiddenRequestError, NotFoundError } from "@app/lib/errors";+// eslint-disable-next-line import/first+import { ApprovalRequestStatus } from "@app/services/approval-policy/approval-policy-enums";+// eslint-disable-next-line import/first+import { DelegatedApprovalRequestStatus } from "@app/services/delegated-approval/delegated-approval-enums";// eslint-disable-next-line import/firstimport { KmsDataKey } from "@app/services/kms/kms-types";// eslint-disable-next-line import/first-import { DELEGATED_APPROVAL_CALLBACK_PATH } from "./delegated-approval-callback-constants";+import {+ DELEGATED_APPROVAL_CALLBACK_MAX_ATTEMPTS,+ DELEGATED_APPROVAL_CALLBACK_PATH+} from "./delegated-approval-callback-constants";+// eslint-disable-next-line import/first+import { DelegatedApprovalCallbackEvent } from "./delegated-approval-callback-enums";// eslint-disable-next-line import/firstimport { delegatedApprovalCallbackServiceFactory } from "./delegated-approval-callback-service";@@ -17,6 +33,8 @@ const CIPHER_PREFIX = Buffer.from("enc:");const encrypt = (plainText: Buffer) => Buffer.concat([CIPHER_PREFIX, plainText]);const decrypt = (cipherTextBlob: Buffer) => cipherTextBlob.subarray(CIPHER_PREFIX.length);+const TX = { isTx: true };+const makeService = ({stored = true,currentRow = null@@ -24,7 +42,8 @@ const makeService = ({const delegatedApprovalRequestDAL = {update: vi.fn(async () => (stored ? [{ id: "delegated-1" }] : [])),primaryNode: vi.fn(() => ({})),- findById: vi.fn(async () => currentRow)+ findById: vi.fn(async () => currentRow),+ findByProviderRequestId: vi.fn(async (): Promise<unknown> => null)};const kmsService = {createCipherPairWithDataKey: vi.fn(async () => ({@@ -32,13 +51,21 @@ const makeService = ({decryptor: ({ cipherTextBlob }: { cipherTextBlob: Buffer }) => decrypt(cipherTextBlob)}))};+ const approvalRequestDAL = {+ transaction: vi.fn(async (cb: (tx: unknown) => Promise<unknown>) => cb(TX)),+ findByIdForUpdate: vi.fn(async (): Promise<unknown> => null),+ updateById: vi.fn(async () => null)+ };+ const eventEmitter = { emit: vi.fn(async () => {}) };const service = delegatedApprovalCallbackServiceFactory({delegatedApprovalRequestDAL: delegatedApprovalRequestDAL as never,- kmsService: kmsService as never+ approvalRequestDAL: approvalRequestDAL as never,+ kmsService: kmsService as never,+ eventEmitter});- return { service, delegatedApprovalRequestDAL, kmsService };+ return { service, delegatedApprovalRequestDAL, approvalRequestDAL, kmsService, eventEmitter };};describe("getCallbackUrl", () => {@@ -106,3 +133,158 @@ describe("getOrIssueCallbackToken", () => {expect(token).toBeNull();});});++describe("handleCallback", () => {+ const TOKEN = "inf_ext_stored-token";+ const EXTERNAL_ID = "9d41f2a7c3b24e1088f6a05e7b1d4c93";+ const EVENT = DelegatedApprovalCallbackEvent.SecretsManagementAccessRequest;++ const makeDelegatedRequest = (overrides?: Record<string, unknown>) => ({+ id: "delegated-1",+ requestId: "request-1",+ status: DelegatedApprovalRequestStatus.WaitingApproval,+ encryptedCallbackToken: encrypt(Buffer.from(TOKEN)),+ providerRequestId: EXTERNAL_ID,+ callbackAttempts: 0,+ approvalRequestOrganizationId: "org-1",+ approvalRequestStatus: ApprovalRequestStatus.Pending,+ ...overrides+ });++ const makeCallbackService = ({+ delegatedRequest = makeDelegatedRequest(),+ attemptsAfterIncrement = 1,+ lockedApprovalRequest = { id: "request-1", status: ApprovalRequestStatus.Pending }+ }: {+ delegatedRequest?: ReturnType<typeof makeDelegatedRequest> | null;+ attemptsAfterIncrement?: number;+ lockedApprovalRequest?: { id: string; status: ApprovalRequestStatus } | null;+ } = {}) => {+ const built = makeService();+ built.delegatedApprovalRequestDAL.findByProviderRequestId.mockResolvedValue(delegatedRequest);+ built.delegatedApprovalRequestDAL.update.mockResolvedValue([+ { ...delegatedRequest, callbackAttempts: attemptsAfterIncrement }+ ] as never);+ built.approvalRequestDAL.findByIdForUpdate.mockResolvedValue(lockedApprovalRequest);+ return built;+ };++ const callback = (overrides?: Partial<{ token: string | undefined; event: typeof EVENT; externalId: string }>) => ({+ token: TOKEN,+ event: EVENT,+ externalId: EXTERNAL_ID,+ ...overrides+ });++ test("returns 404 when no request has the external ID", async () => {+ const { service, delegatedApprovalRequestDAL, eventEmitter } = makeCallbackService({ delegatedRequest: null });++ await expect(service.handleCallback(callback())).rejects.toBeInstanceOf(NotFoundError);+ expect(delegatedApprovalRequestDAL.findByProviderRequestId).toHaveBeenCalledWith(EXTERNAL_ID);+ expect(delegatedApprovalRequestDAL.update).not.toHaveBeenCalled();+ expect(eventEmitter.emit).not.toHaveBeenCalled();+ });++ test("counts the callback before checking the token", async () => {+ const { service, delegatedApprovalRequestDAL, eventEmitter } = makeCallbackService();++ await expect(service.handleCallback(callback({ token: "inf_ext_wrong" }))).rejects.toBeInstanceOf(+ ForbiddenRequestError+ );+ expect(delegatedApprovalRequestDAL.update).toHaveBeenCalledWith(+ { id: "delegated-1" },+ { $incr: { callbackAttempts: 1 } }+ );+ expect(eventEmitter.emit).not.toHaveBeenCalled();+ });++ test.each([+ ["missing", undefined],+ ["unprefixed", "stored-token"],+ ["mismatched", "inf_ext_other-token"]+ ])("rejects a %s token with 403 and no event", async (_label, token) => {+ const { service, eventEmitter } = makeCallbackService();++ await expect(service.handleCallback(callback({ token }))).rejects.toBeInstanceOf(ForbiddenRequestError);+ expect(eventEmitter.emit).not.toHaveBeenCalled();+ });++ test("rejects a request that is not awaiting a decision", async () => {+ const { service, eventEmitter } = makeCallbackService({+ delegatedRequest: makeDelegatedRequest({ status: DelegatedApprovalRequestStatus.Approved })+ });++ await expect(service.handleCallback(callback())).rejects.toBeInstanceOf(ForbiddenRequestError);+ expect(eventEmitter.emit).not.toHaveBeenCalled();+ });++ test("fails the request and cancels its approval request on the callback past the limit", async () => {+ const { service, delegatedApprovalRequestDAL, approvalRequestDAL, eventEmitter, kmsService } = makeCallbackService({+ attemptsAfterIncrement: DELEGATED_APPROVAL_CALLBACK_MAX_ATTEMPTS + 1+ });++ await expect(service.handleCallback(callback())).rejects.toBeInstanceOf(ForbiddenRequestError);++ expect(approvalRequestDAL.findByIdForUpdate).toHaveBeenCalledWith("request-1", TX);+ expect(approvalRequestDAL.updateById).toHaveBeenCalledWith(+ "request-1",+ { status: ApprovalRequestStatus.Cancelled },+ TX+ );+ const [filter, patch, tx] = delegatedApprovalRequestDAL.update.mock.lastCall as unknown as [+ unknown,+ { status: string; statusReason: string },+ unknown+ ];+ expect(filter).toEqual({ id: "delegated-1", status: DelegatedApprovalRequestStatus.WaitingApproval });+ expect(patch.status).toBe(DelegatedApprovalRequestStatus.Failed);+ expect(patch.statusReason).toContain(`more than ${DELEGATED_APPROVAL_CALLBACK_MAX_ATTEMPTS} times`);+ expect(tx).toBe(TX);+ expect(kmsService.createCipherPairWithDataKey).not.toHaveBeenCalled();+ expect(eventEmitter.emit).not.toHaveBeenCalled();+ });++ test("leaves an approval request that is no longer pending alone when attempts run out", async () => {+ const { service, delegatedApprovalRequestDAL, approvalRequestDAL } = makeCallbackService({+ attemptsAfterIncrement: DELEGATED_APPROVAL_CALLBACK_MAX_ATTEMPTS + 1,+ lockedApprovalRequest: { id: "request-1", status: ApprovalRequestStatus.Expired }+ });++ await expect(service.handleCallback(callback())).rejects.toBeInstanceOf(ForbiddenRequestError);++ expect(approvalRequestDAL.updateById).not.toHaveBeenCalled();+ const [, patch] = delegatedApprovalRequestDAL.update.mock.lastCall as unknown as [unknown, { status: string }];+ expect(patch.status).toBe(DelegatedApprovalRequestStatus.Failed);+ });++ test("still accepts the callback at the limit", async () => {+ const { service, eventEmitter } = makeCallbackService({+ attemptsAfterIncrement: DELEGATED_APPROVAL_CALLBACK_MAX_ATTEMPTS+ });++ await expect(service.handleCallback(callback())).resolves.toEqual({ delegatedRequestId: "delegated-1" });+ expect(eventEmitter.emit).toHaveBeenCalledTimes(1);+ });++ test("emits an outbox event keyed on the delegated request", async () => {+ const { service, eventEmitter, kmsService } = makeCallbackService();++ await expect(service.handleCallback(callback())).resolves.toEqual({ delegatedRequestId: "delegated-1" });++ expect(kmsService.createCipherPairWithDataKey).toHaveBeenCalledWith({+ type: KmsDataKey.Organization,+ orgId: "org-1"+ });+ expect(eventEmitter.emit).toHaveBeenCalledWith({+ eventType: EVENT,+ idempotencyKey: "delegated-1",+ payload: {+ delegatedRequestId: "delegated-1",+ approvalRequestId: "request-1",+ orgId: "org-1",+ event: EVENT,+ externalId: EXTERNAL_ID+ }+ });+ });+});diff --git a/backend/src/services/delegated-approval-callback/delegated-approval-callback-service.ts b/backend/src/services/delegated-approval-callback/delegated-approval-callback-service.tsindex 59b919649e..d2843aa270 100644--- a/backend/src/services/delegated-approval-callback/delegated-approval-callback-service.ts+++ b/backend/src/services/delegated-approval-callback/delegated-approval-callback-service.ts@@ -1,18 +1,34 @@import { getConfig } from "@app/lib/config/env";+import { NotFoundError } from "@app/lib/errors";+import { logger } from "@app/lib/logger";+import { DelegatedApprovalRequestStatus } from "@app/services/delegated-approval/delegated-approval-enums";import { KmsDataKey } from "@app/services/kms/kms-types";-import { DELEGATED_APPROVAL_CALLBACK_PATH } from "./delegated-approval-callback-constants";-import { generateDelegatedApprovalCallbackToken } from "./delegated-approval-callback-fns";import {+ DELEGATED_APPROVAL_CALLBACK_MAX_ATTEMPTS,+ DELEGATED_APPROVAL_CALLBACK_PATH,+ DELEGATED_APPROVAL_CALLBACK_TOKEN_PREFIX+} from "./delegated-approval-callback-constants";+import {+ failExhaustedDelegatedApprovalRequest,+ generateDelegatedApprovalCallbackToken,+ isDelegatedApprovalCallbackTokenMatch,+ rejectDelegatedApprovalCallback+} from "./delegated-approval-callback-fns";+import {+ TDelegatedApprovalCallbackEventPayload,TDelegatedApprovalCallbackServiceFactoryDep,- TGetOrIssueCallbackTokenDTO+ TGetOrIssueCallbackTokenDTO,+ THandleDelegatedApprovalCallbackDTO} from "./delegated-approval-callback-types";export type TDelegatedApprovalCallbackServiceFactory = ReturnType<typeof delegatedApprovalCallbackServiceFactory>;export const delegatedApprovalCallbackServiceFactory = ({delegatedApprovalRequestDAL,- kmsService+ approvalRequestDAL,+ kmsService,+ eventEmitter}: TDelegatedApprovalCallbackServiceFactoryDep) => {const getCallbackUrl = () => {const { SITE_URL } = getConfig();@@ -45,5 +61,76 @@ export const delegatedApprovalCallbackServiceFactory = ({return decryptor({ cipherTextBlob: current.encryptedCallbackToken }).toString();};- return { getCallbackUrl, getOrIssueCallbackToken };+ const handleCallback = async ({ token, event, externalId }: THandleDelegatedApprovalCallbackDTO) => {+ const delegatedRequest = await delegatedApprovalRequestDAL.findByProviderRequestId(externalId);+ if (!delegatedRequest) {+ throw new NotFoundError({+ message: `No delegated approval request matches external ID '${externalId}'`+ });+ }++ const logContext = { delegatedRequestId: delegatedRequest.id, externalId };++ // Counted before the token is checked, so a wrong token for a known external ID still burns the+ // request and the token cannot be brute-forced.+ const [counted] = await delegatedApprovalRequestDAL.update(+ { id: delegatedRequest.id },+ { $incr: { callbackAttempts: 1 } }+ );+ const attempts = counted?.callbackAttempts ?? delegatedRequest.callbackAttempts + 1;+ if (attempts > DELEGATED_APPROVAL_CALLBACK_MAX_ATTEMPTS) {+ await failExhaustedDelegatedApprovalRequest({+ id: delegatedRequest.id,+ requestId: delegatedRequest.requestId,+ approvalRequestDAL,+ delegatedApprovalRequestDAL+ });+ throw rejectDelegatedApprovalCallback("callback attempts exhausted", {+ ...logContext,+ attempts: String(attempts)+ });+ }++ if (!token || !token.startsWith(DELEGATED_APPROVAL_CALLBACK_TOKEN_PREFIX)) {+ throw rejectDelegatedApprovalCallback("missing or malformed token", logContext);+ }+ if (!delegatedRequest.encryptedCallbackToken) {+ throw rejectDelegatedApprovalCallback("request has no callback token", logContext);+ }++ const { decryptor } = await kmsService.createCipherPairWithDataKey({+ type: KmsDataKey.Organization,+ orgId: delegatedRequest.approvalRequestOrganizationId+ });+ const storedToken = decryptor({ cipherTextBlob: delegatedRequest.encryptedCallbackToken }).toString();+ if (!isDelegatedApprovalCallbackTokenMatch(token, storedToken)) {+ throw rejectDelegatedApprovalCallback("token mismatch", logContext);+ }++ if (delegatedRequest.status !== DelegatedApprovalRequestStatus.WaitingApproval) {+ throw rejectDelegatedApprovalCallback("request is not awaiting a decision", {+ ...logContext,+ status: delegatedRequest.status+ });+ }++ const payload: TDelegatedApprovalCallbackEventPayload = {+ delegatedRequestId: delegatedRequest.id,+ approvalRequestId: delegatedRequest.requestId,+ orgId: delegatedRequest.approvalRequestOrganizationId,+ event,+ externalId+ };+ // No tx: the attempt counter is already committed and the outbox's (consumer, idempotencyKey)+ // index drops a repeat callback for the same request.+ await eventEmitter.emit({ eventType: event, idempotencyKey: delegatedRequest.id, payload });++ logger.info(+ `Delegated approval callback accepted [delegatedRequestId=${delegatedRequest.id}] [approvalRequestId=${delegatedRequest.requestId}] [event=${event}] [attempt=${attempts}]`+ );++ return { delegatedRequestId: delegatedRequest.id };+ };++ return { getCallbackUrl, getOrIssueCallbackToken, handleCallback };};diff --git a/backend/src/services/delegated-approval-callback/delegated-approval-callback-types.ts b/backend/src/services/delegated-approval-callback/delegated-approval-callback-types.tsindex 643d2e29c0..128655f4da 100644--- a/backend/src/services/delegated-approval-callback/delegated-approval-callback-types.ts+++ b/backend/src/services/delegated-approval-callback/delegated-approval-callback-types.ts@@ -1,13 +1,39 @@import { TDelegatedApprovalRequests } from "@app/db/schemas";+import { TApprovalRequestDALFactory } from "@app/services/approval-policy/approval-request-dal";import { TDelegatedApprovalRequestDALFactory } from "@app/services/delegated-approval/delegated-approval-request-dal";+import { TEventEmitter } from "@app/services/event-outbox/event-outbox-types";import { TKmsServiceFactory } from "@app/services/kms/kms-service";+import { DelegatedApprovalCallbackEvent } from "./delegated-approval-callback-enums";+export type TDelegatedApprovalCallbackServiceFactoryDep = {- delegatedApprovalRequestDAL: Pick<TDelegatedApprovalRequestDALFactory, "findById" | "primaryNode" | "update">;+ delegatedApprovalRequestDAL: Pick<+ TDelegatedApprovalRequestDALFactory,+ "findById" | "findByProviderRequestId" | "primaryNode" | "update"+ >;+ approvalRequestDAL: Pick<TApprovalRequestDALFactory, "transaction" | "findByIdForUpdate" | "updateById">;kmsService: Pick<TKmsServiceFactory, "createCipherPairWithDataKey">;+ eventEmitter: Pick<TEventEmitter, "emit">;};+export type TFailExhaustedDelegatedApprovalRequestDTO = Pick<TDelegatedApprovalRequests, "id" | "requestId"> &+ Pick<TDelegatedApprovalCallbackServiceFactoryDep, "approvalRequestDAL" | "delegatedApprovalRequestDAL">;+export type TGetOrIssueCallbackTokenDTO = {delegatedRequest: Pick<TDelegatedApprovalRequests, "id" | "encryptedCallbackToken">;orgId: string;};++export type THandleDelegatedApprovalCallbackDTO = {+ token: string | undefined;+ event: DelegatedApprovalCallbackEvent;+ externalId: string;+};++export type TDelegatedApprovalCallbackEventPayload = {+ delegatedRequestId: string;+ approvalRequestId: string;+ orgId: string;+ event: DelegatedApprovalCallbackEvent;+ externalId: string;+};diff --git a/backend/src/services/delegated-approval/delegated-approval-request-dal.ts b/backend/src/services/delegated-approval/delegated-approval-request-dal.tsindex b03168321c..03fc3aa9ab 100644--- a/backend/src/services/delegated-approval/delegated-approval-request-dal.ts+++ b/backend/src/services/delegated-approval/delegated-approval-request-dal.ts@@ -1,13 +1,41 @@import { TDbClient } from "@app/db";-import { TableName } from "@app/db/schemas";-import { ormify } from "@app/lib/knex";+import { TableName, TDelegatedApprovalRequests } from "@app/db/schemas";+import { DatabaseError } from "@app/lib/errors";+import { ormify, selectAllTableCols } from "@app/lib/knex";export type TDelegatedApprovalRequestDALFactory = ReturnType<typeof delegatedApprovalRequestDALFactory>;+export type TDelegatedApprovalRequestWithApprovalRequest = TDelegatedApprovalRequests & {+ approvalRequestOrganizationId: string;+ approvalRequestStatus: string;+};+export const delegatedApprovalRequestDALFactory = (db: TDbClient) => {const orm = ormify(db, TableName.DelegatedApprovalRequests);const primaryNode = () => db.primaryNode();- return { ...orm, primaryNode };+ const findByProviderRequestId = async (providerRequestId: string) => {+ try {+ const row = await db+ .primaryNode()(TableName.DelegatedApprovalRequests)+ .join(+ TableName.ApprovalRequests,+ `${TableName.DelegatedApprovalRequests}.requestId`,+ `${TableName.ApprovalRequests}.id`+ )+ .where(`${TableName.DelegatedApprovalRequests}.providerRequestId`, providerRequestId)+ .select(selectAllTableCols(TableName.DelegatedApprovalRequests))+ .select(+ db.ref("organizationId").withSchema(TableName.ApprovalRequests).as("approvalRequestOrganizationId"),+ db.ref("status").withSchema(TableName.ApprovalRequests).as("approvalRequestStatus")+ )+ .first();+ return (row as TDelegatedApprovalRequestWithApprovalRequest | undefined) ?? null;+ } catch (error) {+ throw new DatabaseError({ error, name: "DelegatedApprovalRequest: findByProviderRequestId" });+ }+ };++ return { ...orm, primaryNode, findByProviderRequestId };};diff --git a/backend/src/services/delegated-approval/dispatch/providers/servicenow/servicenow-fns.ts b/backend/src/services/delegated-approval/dispatch/providers/servicenow/servicenow-fns.tsindex 90a74551cc..d0eb906362 100644--- a/backend/src/services/delegated-approval/dispatch/providers/servicenow/servicenow-fns.ts+++ b/backend/src/services/delegated-approval/dispatch/providers/servicenow/servicenow-fns.ts@@ -8,6 +8,7 @@ import { AppConnection } from "@app/services/app-connection/app-connection-enumsimport { TAppConnection } from "@app/services/app-connection/app-connection-types";import { TServiceNowConnection } from "@app/services/app-connection/servicenow";import { ApprovalPolicyType } from "@app/services/approval-policy/approval-policy-enums";+import { DelegatedApprovalCallbackEvent } from "@app/services/delegated-approval-callback/delegated-approval-callback-enums";import {TDelegatedApprovalDispatchDetails,@@ -47,7 +48,7 @@ const buildRequestTypeFields = (details: TDelegatedApprovalDispatchDetails) => {switch (details.policyType) {case ApprovalPolicyType.SecretAccess:return {- event: "secrets_management.access_request",+ event: DelegatedApprovalCallbackEvent.SecretsManagementAccessRequest,request_type: ServiceNowRequestType.SecretAccess,environment: details.environment,secret_path: details.secretPath,