Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(openapi): keep the auth refusal on operations with their own 403
Yudhi Armyndharis60432aeee99e
diff --git a/src/config/swagger.config.spec.ts b/src/config/swagger.config.spec.tsindex 99164206c..75f889eac 100644--- a/src/config/swagger.config.spec.ts+++ b/src/config/swagger.config.spec.ts@@ -120,11 +120,31 @@ describe('documentErrorResponses', () => {{ description: string; content?: unknown }>;expect(Object.keys(responses)).toEqual(['201', '401', '403', '404']);- expect(responses['403'].description).toBe('Session-scoped keys cannot create sessions');+ expect(responses['403'].description).toBe(+ "Session-scoped keys cannot create sessions. Also returned when the API key's role, session or chat scope, " ++ 'or IP allow-list does not allow this operation.',+ );for (const status of ['401', '403', '404']) expect(responses[status].content).toEqual(ref);expect(responses['201']).toEqual({ description: 'Created' });});+ // The auth guard answers 403 before the handler runs, so an operation's own 403 cannot replace it.+ it('merges the auth refusal into an existing 403 once, however often it runs', () => {+ const doc = documentErrorResponses(documentErrorResponses(fixtureDoc()));+ const description = (doc.paths['/api/sessions'].post!.responses['403'] as { description: string }).description;+ expect(description.match(/IP allow-list/g)).toHaveLength(1);+ expect(description.startsWith('Session-scoped keys cannot create sessions. ')).toBe(true);+ });++ it('adds the plain auth refusal once to an operation without a 403 of its own, however often it runs', () => {+ const doc = fixtureDoc();+ doc.paths['/api/sessions'].get = { responses: { '200': { description: 'ok' } } };+ const twice = documentErrorResponses(documentErrorResponses(doc));+ expect((twice.paths['/api/sessions'].get!.responses['403'] as { description: string }).description).toBe(+ "The API key's role, session or chat scope, or IP allow-list does not allow this operation",+ );+ });+it('leaves operations with their own security as they were', () => {const before = fixtureDoc();const after = documentErrorResponses(fixtureDoc());diff --git a/src/config/swagger.config.ts b/src/config/swagger.config.tsindex 111d50f37..74c2cd0c5 100644--- a/src/config/swagger.config.ts+++ b/src/config/swagger.config.ts@@ -142,11 +142,15 @@ const ERROR_RESPONSE: SchemaObject = {},};+/** The auth guard's 403, answered before any handler runs. */+const AUTH_FORBIDDEN = "API key's role, session or chat scope, or IP allow-list does not allow this operation";+/*** Give every API-key operation its auth refusals and a schema for its error bodies. An operation* with its own `security` (the @Public routes and the metrics scrape) is skipped: those answer- * their own shapes, such as the health probe's 503. Existing responses keep their descriptions;- * only missing ones are added. Idempotent. Mutates and returns the document.+ * their own shapes, such as the health probe's 503. Existing responses keep their descriptions,+ * except that an operation's own 403 also gets the auth refusal, which the guard can answer there+ * too. Idempotent. Mutates and returns the document.*/export function documentErrorResponses(document: OpenAPIObject): OpenAPIObject {document.components ??= {};@@ -157,9 +161,12 @@ export function documentErrorResponses(document: OpenAPIObject): OpenAPIObject {const op = (item as Record<string, OperationObject | undefined>)[method];if (!op || op.security !== undefined) continue;op.responses['401'] ??= { description: 'The API key is missing, unknown, revoked, or expired' };- op.responses['403'] ??= {- description: "The API key's role, session or chat scope, or IP allow-list does not allow this operation",- };+ const forbidden = op.responses['403'];+ if (!forbidden) {+ op.responses['403'] = { description: `The ${AUTH_FORBIDDEN}` };+ } else if (!('$ref' in forbidden) && !forbidden.description.includes(AUTH_FORBIDDEN)) {+ forbidden.description = `${forbidden.description.replace(/\.?$/, '.')} Also returned when the ${AUTH_FORBIDDEN}.`;+ }for (const [status, response] of Object.entries(op.responses) as [string, ResponseObject | ReferenceObject][]) {if (Number(status) >= 400 && !('$ref' in response) && !response.content) {response.content = {