Skip to content

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

feat: define new endpoint to receive callbacks from the external deleagated service

adilson6b32f9ddd8a4
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 a
builder in `DELEGATED_APPROVAL_DISPATCH_DETAILS_BUILDER_MAP` rather than branching in a provider. The worker
reads 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 own
module, `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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 endpoints
diff --git a/backend/src/services/delegated-approval-callback/delegated-approval-callback-constants.ts b/backend/src/services/delegated-approval-callback/delegated-approval-callback-constants.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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/first
import { 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/first
import { 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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-enums
import { 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,