143 lines
6.8 KiB
TypeScript
143 lines
6.8 KiB
TypeScript
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<string, unknown>;
|
|
"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<typeof method, unknown>)[method];
|
|
expect(operation, `${method.toUpperCase()} ${path} must exist in openApiDocument.paths`).toBeDefined();
|
|
|
|
return operation as DocumentedOperation;
|
|
}
|
|
|
|
function collectPermissionOperations(permission: NonNullable<DocumentedOperation["x-api-key-permissions"]>) {
|
|
const operations = new Set<unknown>();
|
|
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<string>(API_KEY_SCOPE_OPERATIONS);
|
|
const documentedOperations = new Set<string>();
|
|
|
|
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<OpenApiPath>(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<OpenApiPath>(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<OpenApiPath>(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();
|
|
});
|
|
});
|