fix:ccp-4138

usingtechnology · RyanBirtch-aot · commit ae93bf249787 · 2026-06-08T19:55:58.000Z
enforce checks on apikey and form pairs, update docs.
diff --git a/app/frontend/public/embed/README.md b/app/frontend/public/embed/README.md
@@ -69,8 +69,20 @@ These files are **not in source control** and are created by the build process:
 
 ### Authentication
 
+#### Obtaining a gateway token (server-side only)
+
+Your backend must fetch the JWT before passing it to the embed. Call this endpoint from your server — never expose the form API key to the browser.
+
+- **Endpoint**: `POST {basePath}/gateway/v1/auth/token/forms/{formId}`
+- **Authorization**: `Basic base64(formId:apiKey)` (required)
+- **Response**: `201 { "token": "<jwt>" }`
+
+The `formId` in the URL must match the `formId` in the Basic auth credentials.
+
+#### Using the token in the webcomponent
+
 The webcomponent uses the `X-Chefs-Gateway-Token` header for authentication when making requests to CHEFS backend endpoints. This custom header allows host applications to use the `Authorization: Bearer` header for their own authentication needs.
 
 - **Header name**: `X-Chefs-Gateway-Token`
-- **Value**: JWT token obtained from the gateway token endpoint
+- **Value**: JWT token obtained from the gateway token endpoint above
 - **Usage**: Automatically added to all requests to CHEFS backend URLs (URLs matching the component's `baseUrl`)
diff --git a/app/frontend/public/embed/chefs-form-viewer-embed.js b/app/frontend/public/embed/chefs-form-viewer-embed.js
@@ -172,7 +172,7 @@
  * **Required:**
  * - `form-id`: CHEFS form UUID
  * - `auth-token`: JWT authentication token (preferred)
- *   - The auth-token should be fetched by your backend server using the protected api-key and form-id via POST /app/gateway/v1/auth/token/forms/<form-id>.
+ *   - The auth-token should be fetched by your backend server via POST /app/gateway/v1/auth/token/forms/<form-id> with required Authorization: Basic base64(formId:apiKey).
  *   - The backend should return the short-lived, refreshable token to the frontend for embedding and authenticating form access.
  * - `api-key`: API access key (fallback, only if auth-token is not available)
 
diff --git a/app/frontend/public/embed/chefs-form-viewer.js b/app/frontend/public/embed/chefs-form-viewer.js
@@ -499,7 +499,7 @@
    * Configuration via attributes
    * - form-id (string): required. The CHEFS/Form.io form identifier.
    * - auth-token (string): JWT authentication token (preferred).
-   *   - The auth-token should be fetched by your backend server using the protected api-key and form-id via POST /app/gateway/v1/auth/token/forms/<form-id>.
+   *   - The auth-token should be fetched by your backend server via POST /app/gateway/v1/auth/token/forms/<form-id> with required Authorization: Basic base64(formId:apiKey).
    *   - The backend should return the short-lived, refreshable token to the frontend for embedding and authenticating form access.
    *   - Enables automatic token refresh based on expiry time. Refreshed 60 seconds before expiry.
    * - api-key (string): API access key (fallback, only if auth-token is not available).
diff --git a/app/src/gateway/v1/auth/controller.js b/app/src/gateway/v1/auth/controller.js
@@ -6,8 +6,7 @@ module.exports = {
    */
   issueFormToken: async (req, res, next) => {
     try {
-      // You may want to validate input here
-      const payload = { ...req.body, formId: req.params.formId };
+      const payload = { formId: req.params.formId };
       const token = await tokenService.createToken(payload);
       res.status(201).json({ token });
     } catch (error) {
diff --git a/app/src/gateway/v1/auth/middleware/requireApiKeyBasic.js b/app/src/gateway/v1/auth/middleware/requireApiKeyBasic.js
@@ -0,0 +1,45 @@
+const Problem = require('api-problem');
+const { validate: uuidValidate } = require('uuid');
+
+const formService = require('../../../../forms/form/service');
+const { parseBasicPair } = require('../../../../runtime-auth/security/auth/utils/basicAuth');
+const { validateApiKey } = require('../../../../runtime-auth/security/auth/utils/apiKeyValidation');
+
+const HTTP_401_DETAIL = 'Invalid authorization credentials.';
+
+module.exports = async (req, res, next) => {
+  try {
+    const authz = req.headers?.authorization || '';
+    if (!/^Basic\s+/i.test(authz)) {
+      throw new Problem(401, { detail: HTTP_401_DETAIL });
+    }
+
+    const formIdParam = req.params.formId;
+    if (!uuidValidate(formIdParam)) {
+      throw new Problem(400, { detail: `Bad formId "${formIdParam}".` });
+    }
+
+    const pair = parseBasicPair(authz);
+    if (!pair) {
+      throw new Problem(401, { detail: HTTP_401_DETAIL });
+    }
+
+    const { formId, apiKey } = pair;
+    if (formId !== formIdParam) {
+      throw new Problem(401, { detail: HTTP_401_DETAIL });
+    }
+
+    const apiKeyRecord = await formService.readApiKey(formId);
+    validateApiKey(apiKey, apiKeyRecord);
+
+    req.apiUser = true;
+    next();
+  } catch (error) {
+    if (error.status === 400) {
+      next(error);
+      return;
+    }
+
+    next(new Problem(401, { detail: HTTP_401_DETAIL }));
+  }
+};
diff --git a/app/src/gateway/v1/auth/routes.js b/app/src/gateway/v1/auth/routes.js
@@ -1,13 +1,12 @@
 const express = require('express');
 const router = express.Router();
 
-// just reusing this for now...
-const apiAccess = require('../../../forms/auth/middleware/apiAccess');
+const requireApiKeyBasic = require('./middleware/requireApiKeyBasic');
 
 const controller = require('./controller');
 
 // Issue a new token for a specific form
-router.post('/token/forms/:formId', apiAccess, controller.issueFormToken);
+router.post('/token/forms/:formId', requireApiKeyBasic, controller.issueFormToken);
 
 // Refresh an existing token
 router.post('/refresh', controller.refreshToken);
diff --git a/app/src/runtime-auth/README.md b/app/src/runtime-auth/README.md
@@ -161,6 +161,15 @@ Different authentication strategies use different HTTP headers:
 - **gatewayBearer**: Uses `X-Chefs-Gateway-Token: <token>` (for webcomponent routes only)
   - This custom header allows host applications to use `Authorization: Bearer` for their own authentication
 
+### Gateway token issuance
+
+Webcomponent embeds obtain a short-lived JWT from the gateway auth endpoint before making API calls:
+
+- **Endpoint**: `POST /gateway/v1/auth/token/forms/:formId`
+- **Authentication**: `apiKeyBasic`-style `Authorization: Basic base64(formId:apiKey)` (required; the URL `formId` must match the Basic auth `formId`)
+- **Response**: `201 { "token": "<jwt>" }` with a server-signed payload containing `formId` only
+- **Consumption**: The returned token is sent on webcomponent API requests via `X-Chefs-Gateway-Token`, validated by the `gatewayBearer` strategy
+
 ## Resource Specs
 
 Resources tell the middleware what entity the request is operating on. The middleware uses this to fetch permissions from RBAC.
diff --git a/app/src/runtime-auth/security/auth/strategies/apiKeyBasic.js b/app/src/runtime-auth/security/auth/strategies/apiKeyBasic.js
@@ -4,6 +4,7 @@
  */
 
 const ERRORS = require('../../errorMessages');
+const { parseBasicPair } = require('../utils/basicAuth');
 const { validateApiKey } = require('../utils/apiKeyValidation');
 const { createApiKeyAuthResult } = require('../utils/authResult');
 
@@ -12,18 +13,6 @@ function canHandle(req) {
   return /^Basic\s+/i.test(h);
 }
 
-function parseBasicPair(header) {
-  try {
-    const base64 = header.replace(/^Basic\s+/i, '');
-    const decoded = Buffer.from(base64, 'base64').toString('utf8');
-    const idx = decoded.indexOf(':');
-    if (idx === -1) return null;
-    return { formId: decoded.slice(0, idx), apiKey: decoded.slice(idx + 1) };
-  } catch {
-    return null;
-  }
-}
-
 module.exports = function apiKeyBasicFactory({ deps }) {
   const { formService, authService } = deps.services || {};
 
diff --git a/app/src/runtime-auth/security/auth/utils/basicAuth.js b/app/src/runtime-auth/security/auth/utils/basicAuth.js
@@ -0,0 +1,19 @@
+/**
+ * Shared Basic auth parsing for formId:apiKey credentials.
+ */
+
+function parseBasicPair(header) {
+  try {
+    const base64 = header.replace(/^Basic\s+/i, '');
+    const decoded = Buffer.from(base64, 'base64').toString('utf8');
+    const idx = decoded.indexOf(':');
+    if (idx === -1) return null;
+    return { formId: decoded.slice(0, idx), apiKey: decoded.slice(idx + 1) };
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  parseBasicPair,
+};
diff --git a/app/tests/unit/gateway/auth/controller.spec.js b/app/tests/unit/gateway/auth/controller.spec.js
@@ -27,11 +27,18 @@ describe('gateway/v1/auth/controller', () => {
     req.body = { userId: 'u1' };
     req.params.formId = 'abc';
     await controller.issueFormToken(req, res, next);
-    expect(tokenService.createToken).toHaveBeenCalledWith({ userId: 'u1', formId: 'abc' });
+    expect(tokenService.createToken).toHaveBeenCalledWith({ formId: 'abc' });
     expect(res.status).toHaveBeenCalledWith(201);
     expect(res.json).toHaveBeenCalledWith({ token: 'mocked-token' });
   });
 
+  test('issueFormToken does not forward request body fields into token payload', async () => {
+    req.body = { userId: 'u1', role: 'admin', formId: 'other' };
+    req.params.formId = 'abc';
+    await controller.issueFormToken(req, res, next);
+    expect(tokenService.createToken).toHaveBeenCalledWith({ formId: 'abc' });
+  });
+
   test('issueFormToken calls next on error', async () => {
     tokenService.createToken.mockImplementationOnce(() => {
       throw new Error('fail');
diff --git a/app/tests/unit/gateway/auth/middleware/requireApiKeyBasic.spec.js b/app/tests/unit/gateway/auth/middleware/requireApiKeyBasic.spec.js
@@ -0,0 +1,137 @@
+const { getMockReq, getMockRes } = require('@jest-mock/express');
+const uuid = require('uuid');
+
+jest.mock('../../../../../src/forms/form/service', () => ({
+  readApiKey: jest.fn(),
+}));
+
+const requireApiKeyBasic = require('../../../../../src/gateway/v1/auth/middleware/requireApiKeyBasic');
+const formService = require('../../../../../src/forms/form/service');
+
+function createBasicAuthHeader(formId, apiKey) {
+  const credentials = Buffer.from(`${formId}:${apiKey}`).toString('base64');
+  return `Basic ${credentials}`;
+}
+
+describe('requireApiKeyBasic', () => {
+  const formId = uuid.v4();
+  const secret = uuid.v4();
+  const authHeader = createBasicAuthHeader(formId, secret);
+
+  beforeEach(() => {
+    formService.readApiKey.mockReset();
+    formService.readApiKey.mockResolvedValue({ secret, filesApiAccess: true });
+  });
+
+  it('should return 401 when there is no auth header', async () => {
+    const req = getMockReq({ headers: {}, params: { formId } });
+    const { res, next } = getMockRes();
+
+    await requireApiKeyBasic(req, res, next);
+
+    expect(formService.readApiKey).toBeCalledTimes(0);
+    expect(req.apiUser).toBeFalsy();
+    expect(next).toBeCalledTimes(1);
+    expect(next).toBeCalledWith(expect.objectContaining({ status: 401 }));
+  });
+
+  it('should return 401 with bearer authorization', async () => {
+    const req = getMockReq({
+      headers: { authorization: 'Bearer JWT' },
+      params: { formId },
+    });
+    const { res, next } = getMockRes();
+
+    await requireApiKeyBasic(req, res, next);
+
+    expect(formService.readApiKey).toBeCalledTimes(0);
+    expect(req.apiUser).toBeFalsy();
+    expect(next).toBeCalledTimes(1);
+    expect(next).toBeCalledWith(expect.objectContaining({ status: 401 }));
+  });
+
+  it('should return 401 with malformed Basic auth', async () => {
+    const malformed = `Basic ${Buffer.from('nocolonseparator').toString('base64')}`;
+    const req = getMockReq({
+      headers: { authorization: malformed },
+      params: { formId },
+    });
+    const { res, next } = getMockRes();
+
+    await requireApiKeyBasic(req, res, next);
+
+    expect(formService.readApiKey).toBeCalledTimes(0);
+    expect(next).toBeCalledWith(expect.objectContaining({ status: 401 }));
+  });
+
+  it('should return 400 with non-uuid form id param', async () => {
+    const req = getMockReq({
+      headers: { authorization: authHeader },
+      params: { formId: 'invalidFormId' },
+    });
+    const { res, next } = getMockRes();
+
+    await requireApiKeyBasic(req, res, next);
+
+    expect(formService.readApiKey).toBeCalledTimes(0);
+    expect(next).toBeCalledWith(expect.objectContaining({ status: 400 }));
+  });
+
+  it('should return 401 when Basic auth formId does not match route param', async () => {
+    const otherFormId = uuid.v4();
+    const req = getMockReq({
+      headers: { authorization: createBasicAuthHeader(otherFormId, secret) },
+      params: { formId },
+    });
+    const { res, next } = getMockRes();
+
+    await requireApiKeyBasic(req, res, next);
+
+    expect(formService.readApiKey).toBeCalledTimes(0);
+    expect(next).toBeCalledWith(expect.objectContaining({ status: 401 }));
+  });
+
+  it('should return 401 when db api key result is missing', async () => {
+    formService.readApiKey.mockResolvedValue();
+    const req = getMockReq({
+      headers: { authorization: authHeader },
+      params: { formId },
+    });
+    const { res, next } = getMockRes();
+
+    await requireApiKeyBasic(req, res, next);
+
+    expect(formService.readApiKey).toBeCalledTimes(1);
+    expect(next).toBeCalledWith(expect.objectContaining({ status: 401 }));
+  });
+
+  it('should return 401 when api key secret does not match', async () => {
+    formService.readApiKey.mockResolvedValue({ secret: uuid.v4(), filesApiAccess: true });
+    const req = getMockReq({
+      headers: { authorization: authHeader },
+      params: { formId },
+    });
+    const { res, next } = getMockRes();
+
+    await requireApiKeyBasic(req, res, next);
+
+    expect(formService.readApiKey).toBeCalledTimes(1);
+    expect(next).toBeCalledWith(expect.objectContaining({ status: 401 }));
+  });
+
+  it('should pass through with valid credentials', async () => {
+    const req = getMockReq({
+      headers: { authorization: authHeader },
+      params: { formId },
+    });
+    const { res, next } = getMockRes();
+
+    await requireApiKeyBasic(req, res, next);
+
+    expect(formService.readApiKey).toBeCalledTimes(1);
+    expect(formService.readApiKey).toBeCalledWith(formId);
+    expect(req.apiUser).toBe(true);
+    expect(next).toBeCalledTimes(1);
+    expect(next).toBeCalledWith();
+  });
+});
diff --git a/app/tests/unit/gateway/auth/routes.spec.js b/app/tests/unit/gateway/auth/routes.spec.js
@@ -1,10 +1,10 @@
 const express = require('express');
 const request = require('supertest');
 const controller = require('../../../../src/gateway/v1/auth/controller');
-const apiAccess = require('../../../../src/forms/auth/middleware/apiAccess');
+const requireApiKeyBasic = require('../../../../src/gateway/v1/auth/middleware/requireApiKeyBasic');
 
 // Mock middleware
-jest.mock('../../../../src/forms/auth/middleware/apiAccess', () => jest.fn((req, res, next) => next()));
+jest.mock('../../../../src/gateway/v1/auth/middleware/requireApiKeyBasic', () => jest.fn((req, res, next) => next()));
 
 // Mock controller methods
 jest.mock('../../../../src/gateway/v1/auth/controller', () => ({
@@ -26,13 +26,13 @@ describe('gateway/v1/auth routes', () => {
     app.use('/gateway/v1/auth', routes);
   });
 
-  it('POST /token/forms/:formId should route to controller.issueFormToken with apiAccess middleware', async () => {
+  it('POST /token/forms/:formId should route to controller.issueFormToken with requireApiKeyBasic middleware', async () => {
     controller.issueFormToken.mockImplementation(async (_req, res) => res.status(201).json({ token: 'abc' }));
     const res = await request(app).post('/gateway/v1/auth/token/forms/123').send({ formId: '123' });
     expect(res.statusCode).toBe(201);
     expect(res.body).toEqual({ token: 'abc' });
     expect(controller.issueFormToken).toHaveBeenCalled();
-    expect(apiAccess).toHaveBeenCalled();
+    expect(requireApiKeyBasic).toHaveBeenCalled();
   });
 
   it('POST /refresh should route to controller.refreshToken without middleware', async () => {
diff --git a/app/tests/unit/runtime-auth/security/auth/utils/basicAuth.spec.js b/app/tests/unit/runtime-auth/security/auth/utils/basicAuth.spec.js
@@ -0,0 +1,30 @@
+/* eslint-env jest */
+
+const { parseBasicPair } = require('../../../../../../src/runtime-auth/security/auth/utils/basicAuth');
+
+describe('auth/utils/basicAuth', () => {
+  it('should parse valid Basic auth header', () => {
+    const credentials = Buffer.from('form-id:secret-key').toString('base64');
+    expect(parseBasicPair(`Basic ${credentials}`)).toEqual({
+      formId: 'form-id',
+      apiKey: 'secret-key',
+    });
+  });
+
+  it('should parse Basic auth header case-insensitively', () => {
+    const credentials = Buffer.from('form-id:secret-key').toString('base64');
+    expect(parseBasicPair(`basic ${credentials}`)).toEqual({
+      formId: 'form-id',
+      apiKey: 'secret-key',
+    });
+  });
+
+  it('should return null when credentials have no colon separator', () => {
+    const credentials = Buffer.from('invalidcredentials').toString('base64');
+    expect(parseBasicPair(`Basic ${credentials}`)).toBeNull();
+  });
+
+  it('should return null for invalid base64', () => {
+    expect(parseBasicPair('Basic !!!')).toBeNull();
+  });
+});
