feat: status api with key auth (#8035)

Author: gao-sun

.github/workflows/integration-test.yml

@@ -41,9 +41,11 @@ jobs:
     env:
       INTEGRATION_TEST: true
       DEV_FEATURES_ENABLED: ${{ matrix.dev-features-enabled }}
-      # Key encryption key (KEK) for the secret vault. (For integration tests use only)
+      # Key encryption key (KEK) for the secret vault used in integration tests
       SECRET_VAULT_KEK: DtPWS09unRXGuRScB60qXqCSsrjd22dUlXt/0oZgxSo=
       DB_URL: postgres://postgres:postgres@localhost:5432/postgres
+      # Mock key for authorized status API access during integration tests
+      STATUS_API_KEY: test-status-api-key
 
     steps:
       - uses: logto-io/actions-run-logto-integration-tests@v4

packages/core/src/routes/status.test.ts

@@ -1,10 +1,59 @@
 import { createRequester } from '#src/utils/test-utils.js';
 
+import { EnvSet } from '../env-set/index.js';
+
 import statusRoutes from './status.js';
 
 describe('status router', () => {
   const requester = createRequester({ anonymousRoutes: statusRoutes });
-  it('GET /status', async () => {
-    await expect(requester.get('/status')).resolves.toHaveProperty('status', 204);
+
+  it('should respond with status 204', async () => {
+    const response = await requester.get('/status');
+
+    expect(response.status).toBe(204);
+    expect(response.headers).not.toHaveProperty('logto-tenant-id');
+  });
+
+  it('should not respond with tenant ID when no API key is set', async () => {
+    const response = await requester.get('/status').set('logto-status-api-key', 'any-key');
+
+    expect(response.status).toBe(204);
+    expect(response.headers).not.toHaveProperty('logto-tenant-id');
+  });
+});
+
+describe('status router with API key set', () => {
+  const testApiKey = 'test-status-api-key';
+  const originalApiKey = EnvSet.values.statusApiKey;
+
+  beforeEach(() => {
+    // eslint-disable-next-line @silverhand/fp/no-mutating-methods
+    Object.defineProperty(EnvSet.values, 'statusApiKey', {
+      value: testApiKey,
+    });
+  });
+
+  afterEach(() => {
+    // Restore original API key
+    // eslint-disable-next-line @silverhand/fp/no-mutating-methods
+    Object.defineProperty(EnvSet.values, 'statusApiKey', {
+      value: originalApiKey,
+    });
+  });
+
+  it('should respond with tenant ID when valid API key is provided', async () => {
+    const requester = createRequester({ anonymousRoutes: statusRoutes });
+
+    const response = await requester.get('/status').set('logto-status-api-key', testApiKey);
+    expect(response.headers).toHaveProperty('logto-tenant-id', 'mock_id');
+  });
+
+  it('should not respond with tenant ID when invalid API key is provided', async () => {
+    const requester = createRequester({ anonymousRoutes: statusRoutes });
+
+    const response = await requester.get('/status').set('logto-status-api-key', 'invalid-api-key');
+
+    expect(response.status).toBe(204);
+    expect(response.headers).not.toHaveProperty('logto-tenant-id');
   });
 });

packages/core/src/routes/status.ts

@@ -1,11 +1,33 @@
+import { timingSafeEqual } from 'node:crypto';
+
+import { trySafe } from '@silverhand/essentials';
+
 import koaGuard from '#src/middleware/koa-guard.js';
 
+import { EnvSet } from '../env-set/index.js';
+
 import type { AnonymousRouter, RouterInitArgs } from './types.js';
 
-export default function statusRoutes<T extends AnonymousRouter>(...[router]: RouterInitArgs<T>) {
+const getSingleHeader = (value: string | string[] | undefined): string | undefined =>
+  Array.isArray(value) || value === undefined ? undefined : value;
+
+export default function statusRoutes<T extends AnonymousRouter>(
+  ...[router, tenant]: RouterInitArgs<T>
+) {
   router.get('/status', koaGuard({ status: 204 }), async (ctx, next) => {
     ctx.status = 204;
 
+    const statusApiKeyHeader = getSingleHeader(ctx.request.headers['logto-status-api-key']);
+    if (
+      EnvSet.values.statusApiKey &&
+      statusApiKeyHeader &&
+      trySafe(() =>
+        timingSafeEqual(Buffer.from(EnvSet.values.statusApiKey), Buffer.from(statusApiKeyHeader))
+      )
+    ) {
+      ctx.set('logto-tenant-id', tenant.id);
+    }
+
     return next();
   });
 }

packages/integration-tests/src/tests/api/status.test.ts

@@ -0,0 +1,29 @@
+import { adminTenantApi } from '#src/api/api.js';
+
+describe('status API', () => {
+  it('should respond with status 204', async () => {
+    const response = await adminTenantApi.get('status');
+    expect(response.status).toBe(204);
+    expect(response.headers).not.toHaveProperty('logto-tenant-id');
+  });
+
+  it('should respond with tenant ID when valid API key is provided', async () => {
+    const response = await adminTenantApi.get('status', {
+      headers: {
+        'logto-status-api-key': 'test-status-api-key',
+      },
+    });
+    expect(response.status).toBe(204);
+    expect(response.headers.get('logto-tenant-id')?.length).toBeGreaterThan(0);
+  });
+
+  it('should not respond with tenant ID when invalid API key is provided', async () => {
+    const response = await adminTenantApi.get('status', {
+      headers: {
+        'logto-status-api-key': 'invalid-api-key',
+      },
+    });
+    expect(response.status).toBe(204);
+    expect(response.headers).not.toHaveProperty('logto-tenant-id');
+  });
+});

packages/shared/src/node/env/GlobalValues.ts

@@ -119,6 +119,14 @@ export default class GlobalValues {
   /** Global switch for enabling/disabling case-sensitive usernames. */
   public readonly isCaseSensitiveUsername = yes(getEnv('CASE_SENSITIVE_USERNAME', 'true'));
 
+  /**
+   * The API key for status endpoint protection. If it's set, requests to the status endpoint may
+   * supply the key in the header for receiving response with additional details.
+   *
+   * @optional
+   */
+  public readonly statusApiKey = getEnv('STATUS_API_KEY');
+
   /** The write-only key for PostHog integration. */
   public readonly posthogPublicKey = process.env.POSTHOG_PUBLIC_KEY;
   /** The PostHog host URL for SDK to send events to. */