Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/api/src/permission-matrix.test.ts
T

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();
});
});