import { describe, expect, test } from "vitest"; import { API_KEY_SCOPE_OPERATIONS } from "./auth/scope.js"; import { openApiDocument } from "./openapi.js"; const scopedPermissionMatrix = [ { path: "/v1/entities/{entity}/rows", method: "get", operation: "read" }, { path: "/v1/entities/{entity}/rows", method: "post", operation: "create" }, { path: "/v1/entities/{entity}/rows/{rowId}", method: "get", operation: "read" }, { path: "/v1/entities/{entity}/rows/{rowId}", method: "patch", operation: "update" }, { path: "/v1/entities/{entity}/rows/{rowId}", method: "delete", operation: "delete" }, { path: "/v1/relationships", method: "post", operation: "create" }, { path: "/v1/relationships/{id}", method: "get", operation: "read" }, { path: "/v1/relationships/{id}", method: "delete", operation: "delete" }, ] as const; const unscopedPublicOrLegacyPaths = [ "/healthz", "/readyz", "/v1/api-keys/validate", "/v1/analytics/public", ] as const; const serviceCredentialMatrix = [ { path: "/v1/exports/{exportJobId}/download-url", method: "get" }, ] as const; const serviceTokenOnlyMatrix = [ { path: "/v1/entities/{entity}", method: "get" }, ] as const; const expectedSecurity = [{ bearerAuth: [] }, { apiKeyHeader: [] }]; const expectedServiceTokenOnlySecurity = [{ bearerAuth: [] }]; const expectedRuntimeCrudOperations = ["read", "create", "update", "delete"] as const; type OpenApiPath = keyof typeof openApiDocument.paths; type ScopedMatrixEntry = (typeof scopedPermissionMatrix)[number]; type ServiceCredentialMatrixEntry = (typeof serviceCredentialMatrix)[number] | (typeof serviceTokenOnlyMatrix)[number]; type DocumentedOperation = { security?: unknown; responses?: Record; "x-api-key-permissions"?: { operation?: unknown; entityPermissions?: Array<{ operation?: unknown }>; }; }; function getDocumentedOperation({ path, method }: ScopedMatrixEntry | ServiceCredentialMatrixEntry): DocumentedOperation { const pathItem = openApiDocument.paths[path]; expect(pathItem, `${path} must exist in openApiDocument.paths`).toBeDefined(); const operation = (pathItem as Record)[method]; expect(operation, `${method.toUpperCase()} ${path} must exist in openApiDocument.paths`).toBeDefined(); return operation as DocumentedOperation; } function collectPermissionOperations(permission: NonNullable) { const operations = new Set(); if (permission.operation !== undefined) { operations.add(permission.operation); } for (const entityPermission of permission.entityPermissions ?? []) { operations.add(entityPermission.operation); } return [...operations]; } describe("scoped API-key permission matrix", () => { test.each(scopedPermissionMatrix)("documents $method $path as requiring $operation scope", (entry) => { const operation = getDocumentedOperation(entry); expect(operation.security).toEqual(expectedSecurity); expect(operation.responses).toHaveProperty("403"); expect(operation["x-api-key-permissions"], `${entry.method.toUpperCase()} ${entry.path} must document API-key permissions`).toBeDefined(); const permission = operation["x-api-key-permissions"]; expect(permission?.operation ?? permission?.entityPermissions?.[0]?.operation).toBe(entry.operation); expect(collectPermissionOperations(permission ?? {})).toEqual([entry.operation]); }); test("uses only supported scope operations and represents every runtime CRUD operation", () => { const supportedOperations = new Set(API_KEY_SCOPE_OPERATIONS); const documentedOperations = new Set(); for (const entry of scopedPermissionMatrix) { const permission = getDocumentedOperation(entry)["x-api-key-permissions"]; expect(permission).toBeDefined(); for (const operation of collectPermissionOperations(permission ?? {})) { expect(typeof operation, `${entry.method.toUpperCase()} ${entry.path} operation must be a string`).toBe("string"); expect(supportedOperations.has(operation as string), `${entry.method.toUpperCase()} ${entry.path} uses unsupported operation ${String(operation)}`).toBe(true); documentedOperations.add(operation as string); } } expect([...documentedOperations].sort()).toEqual([...expectedRuntimeCrudOperations].sort()); expect([...documentedOperations].sort()).toEqual([...API_KEY_SCOPE_OPERATIONS].sort()); }); test("covers exactly the scoped OpenAPI operations that publish API-key permissions", () => { const expectedEntries = scopedPermissionMatrix.map(({ method, path }) => `${method.toUpperCase()} ${path}`).sort(); const documentedEntries = Object.entries(openApiDocument.paths) .flatMap(([path, pathItem]) => Object.entries(pathItem) .filter(([, operation]) => typeof operation === "object" && operation !== null && "x-api-key-permissions" in operation) .map(([method]) => `${method.toUpperCase()} ${path}`) ) .sort(); expect(documentedEntries).toEqual(expectedEntries); }); test.each(unscopedPublicOrLegacyPaths)("keeps %s out of the scoped permission matrix", (path) => { const scopedMatrixPaths = new Set(scopedPermissionMatrix.map((entry) => entry.path)); expect(scopedMatrixPaths.has(path)).toBe(false); const pathItem = openApiDocument.paths[path]; expect(pathItem, `${path} should remain documented as an unscoped public endpoint`).toBeDefined(); expect(Object.values(pathItem).some((operation) => typeof operation === "object" && operation !== null && "x-api-key-permissions" in operation)).toBe(false); }); test.each(serviceCredentialMatrix)("documents $method $path as service-credential protected but not CRUD scoped", (entry) => { const scopedMatrixPaths = new Set(scopedPermissionMatrix.map(({ path }) => path)); expect(scopedMatrixPaths.has(entry.path)).toBe(false); const operation = getDocumentedOperation(entry); expect(operation.security).toEqual(expectedSecurity); expect(operation.responses).toHaveProperty("401"); expect(operation["x-api-key-permissions"], `${entry.method.toUpperCase()} ${entry.path} must not publish CRUD scope claims`).toBeUndefined(); }); test.each(serviceTokenOnlyMatrix)("documents $method $path as bearer service-token protected but not CRUD scoped", (entry) => { const scopedMatrixPaths = new Set(scopedPermissionMatrix.map(({ path }) => path)); expect(scopedMatrixPaths.has(entry.path)).toBe(false); const operation = getDocumentedOperation(entry); expect(operation.security).toEqual(expectedServiceTokenOnlySecurity); expect(operation.responses).toHaveProperty("401"); expect(operation["x-api-key-permissions"], `${entry.method.toUpperCase()} ${entry.path} must not publish CRUD scope claims`).toBeUndefined(); }); });