Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.ts
index 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.ts
index 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 = {