Build a generic policy evaluator (#127)

* Build a generic policy evaluator

currently only used for events

* support multiple hosts in event host restriction

* show in UI

* fix types

Author: devksingh4

src/api/functions/apiKey.ts

@@ -10,7 +10,13 @@ import {
 import { genericConfig } from "common/config.js";
 import { AUTH_DECISION_CACHE_SECONDS as API_KEY_DATA_CACHE_SECONDS } from "./authorization.js";
 import { unmarshall } from "@aws-sdk/util-dynamodb";
-import { ApiKeyDynamoEntry, DecomposedApiKey } from "common/types/apiKey.js";
+import { ApiKeyMaskedEntry, DecomposedApiKey } from "common/types/apiKey.js";
+import { AvailableAuthorizationPolicy } from "api/policies/definition.js";
+
+export type ApiKeyDynamoEntry = ApiKeyMaskedEntry & {
+  keyHash: string;
+  restrictions?: AvailableAuthorizationPolicy[];
+};
 
 function min(a: number, b: number) {
   return a < b ? a : b;

src/api/index.ts

@@ -14,6 +14,7 @@ import cors from "@fastify/cors";
 import { environmentConfig, genericConfig } from "../common/config.js";
 import organizationsPlugin from "./routes/organizations.js";
 import authorizeFromSchemaPlugin from "./plugins/authorizeFromSchema.js";
+import evaluatePoliciesPlugin from "./plugins/evaluatePolicies.js";
 import icalPlugin from "./routes/ics.js";
 import vendingPlugin from "./routes/vending.js";
 import * as dotenv from "dotenv";
@@ -99,6 +100,7 @@ async function init(prettyPrint: boolean = false) {
   await app.register(authorizeFromSchemaPlugin);
   await app.register(fastifyAuthPlugin);
   await app.register(FastifyAuthProvider);
+  await app.register(evaluatePoliciesPlugin);
   await app.register(errorHandlerPlugin);
   await app.register(fastifyZodOpenApiPlugin);
   await app.register(fastifySwagger, {

src/api/plugins/auth.ts

@@ -21,6 +21,8 @@ import {
 } from "@aws-sdk/client-dynamodb";
 import { getApiKeyData, getApiKeyParts } from "api/functions/apiKey.js";
 import { RequestThrottled } from "@aws-sdk/client-sqs";
+import { evaluatePolicy } from "api/policies/evaluator.js";
+import { AuthorizationPoliciesRegistry } from "api/policies/definition.js";
 
 export function intersection<T>(setA: Set<T>, setB: Set<T>): Set<T> {
   const _intersection = new Set<T>();
@@ -120,6 +122,7 @@ const authPlugin: FastifyPluginAsync = async (fastify, _options) => {
     request.username = `acmuiuc_${apikeyId}`;
     request.userRoles = rolesSet;
     request.tokenPayload = undefined; // there's no token data
+    request.policyRestrictions = keyData.restrictions;
     return new Set(keyData.roles);
   };
   fastify.decorate(

src/api/plugins/evaluatePolicies.ts

@@ -0,0 +1,74 @@
+import fp from "fastify-plugin";
+import { FastifyPluginAsync, FastifyRequest } from "fastify";
+import { UnauthorizedError } from "../../common/errors/index.js";
+import {
+  AuthorizationPoliciesRegistry,
+  AvailableAuthorizationPolicies,
+} from "api/policies/definition.js";
+import { evaluatePolicy } from "api/policies/evaluator.js";
+
+/**
+ * Evaluates all policy restrictions for a request
+ * @param {FastifyRequest} request - The Fastify request object
+ * @returns {Promise<boolean>} - True if all policies pass, throws error otherwise
+ */
+export const evaluateAllRequestPolicies = async (
+  request: FastifyRequest,
+): Promise<boolean | string> => {
+  if (!request.policyRestrictions) {
+    return true;
+  }
+
+  for (const restriction of request.policyRestrictions) {
+    if (
+      AuthorizationPoliciesRegistry[
+        restriction.name as keyof AvailableAuthorizationPolicies
+      ] === undefined
+    ) {
+      request.log.warn(`Invalid policy name ${restriction.name}, skipping...`);
+      continue;
+    }
+
+    const policyFunction =
+      AuthorizationPoliciesRegistry[
+        restriction.name as keyof AvailableAuthorizationPolicies
+      ];
+    const policyResult = evaluatePolicy(request, {
+      policy: policyFunction,
+      params: restriction.params,
+    });
+
+    request.log.info(
+      `Policy ${restriction.name} evaluated to ${policyResult.allowed}.`,
+    );
+
+    if (!policyResult.allowed) {
+      return policyResult.message;
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Fastify plugin to evaluate authorization policies after the request body has been parsed
+ */
+const evaluatePoliciesPluginAsync: FastifyPluginAsync = async (
+  fastify,
+  _options,
+) => {
+  // Register a hook that runs after body parsing but before route handler
+  fastify.addHook("preHandler", async (request: FastifyRequest, _reply) => {
+    const result = await evaluateAllRequestPolicies(request);
+    if (typeof result === "string") {
+      throw new UnauthorizedError({
+        message: result,
+      });
+    }
+  });
+};
+
+// Export the plugin as a properly wrapped fastify-plugin
+export default fp(evaluatePoliciesPluginAsync, {
+  name: "evaluatePolicies",
+});

src/api/policies/definition.ts

@@ -0,0 +1,42 @@
+import { FastifyRequest } from "fastify";
+import { hostRestrictionPolicy } from "./events.js";
+import { z } from "zod";
+import { AuthorizationPolicyResult } from "./evaluator.js";
+type Policy<TParamsSchema extends z.ZodObject<any>> = {
+  name: string;
+  paramsSchema: TParamsSchema;
+  evaluator: (
+    request: FastifyRequest,
+    params: z.infer<TParamsSchema>,
+  ) => AuthorizationPolicyResult;
+};
+
+// Type to get parameters type from a policy
+type PolicyParams<T> = T extends Policy<infer U> ? z.infer<U> : never;
+
+// Type for a registry of policies
+type PolicyRegistry = {
+  [key: string]: Policy<any>;
+};
+
+// Type to generate a strongly-typed version of the policy registry
+type TypedPolicyRegistry<T extends PolicyRegistry> = {
+  [K in keyof T]: {
+    name: T[K]["name"];
+    params: PolicyParams<T[K]>;
+  };
+};
+
+export type AvailableAuthorizationPolicies = TypedPolicyRegistry<
+  typeof AuthorizationPoliciesRegistry
+>;
+export const AuthorizationPoliciesRegistry = {
+  EventsHostRestrictionPolicy: hostRestrictionPolicy,
+} as const;
+
+export type AvailableAuthorizationPolicy = {
+  [K in keyof typeof AuthorizationPoliciesRegistry]: {
+    name: K;
+    params: PolicyParams<(typeof AuthorizationPoliciesRegistry)[K]>;
+  };
+}[keyof typeof AuthorizationPoliciesRegistry];

src/api/policies/evaluator.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { FastifyRequest } from "fastify";
+
+export const AuthorizationPolicyResultSchema = z.object({
+  allowed: z.boolean(),
+  message: z.string(),
+  cacheKey: z.string().nullable(),
+});
+export type AuthorizationPolicyResult = z.infer<
+  typeof AuthorizationPolicyResultSchema
+>;
+
+export function createPolicy<TParamsSchema extends z.ZodObject<any>>(
+  name: string,
+  paramsSchema: TParamsSchema,
+  evaluatorFn: (
+    request: FastifyRequest,
+    params: z.infer<TParamsSchema>,
+  ) => AuthorizationPolicyResult,
+) {
+  return {
+    name,
+    paramsSchema,
+    evaluator: evaluatorFn,
+  };
+}
+
+export function applyPolicy<TParamsSchema extends z.ZodObject<any>>(
+  policy: {
+    name: string;
+    paramsSchema: TParamsSchema;
+    evaluator: (
+      request: FastifyRequest,
+      params: z.infer<TParamsSchema>,
+    ) => AuthorizationPolicyResult;
+  },
+  params: Record<string, string>,
+) {
+  // Validate and transform parameters using the schema
+  const validatedParams = policy.paramsSchema.parse(params);
+
+  return {
+    policy,
+    params: validatedParams,
+  };
+}
+
+export function evaluatePolicy<TParamsSchema extends z.ZodObject<any>>(
+  request: FastifyRequest,
+  policyConfig: {
+    policy: {
+      name: string;
+      paramsSchema: TParamsSchema;
+      evaluator: (
+        request: FastifyRequest,
+        params: z.infer<TParamsSchema>,
+      ) => AuthorizationPolicyResult;
+    };
+    params: z.infer<TParamsSchema>;
+  },
+): AuthorizationPolicyResult {
+  try {
+    return policyConfig.policy.evaluator(request, policyConfig.params);
+  } catch (error: any) {
+    return {
+      cacheKey: `error:${policyConfig.policy.name}:${error.message}`,
+      allowed: false,
+      message: `Error evaluating policy ${policyConfig.policy.name}: ${error.message}`,
+    };
+  }
+}

src/api/policies/events.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { createPolicy } from "./evaluator.js";
+import { OrganizationList } from "common/orgs.js";
+import { FastifyRequest } from "fastify";
+import { EventPostRequest } from "api/routes/events.js";
+
+export const hostRestrictionPolicy = createPolicy(
+  "EventsHostRestrictionPolicy",
+  z.object({ host: z.array(z.enum(OrganizationList)) }),
+  (request: FastifyRequest, params) => {
+    if (!request.url.startsWith("/api/v1/events")) {
+      return {
+        allowed: true,
+        message: "Skipped as route not in scope.",
+        cacheKey: null,
+      };
+    }
+    const typedBody = request.body as EventPostRequest;
+    if (!typedBody || !typedBody["host"]) {
+      return {
+        allowed: true,
+        message: "Skipped as no host found.",
+        cacheKey: null,
+      };
+    }
+    if (!params.host.includes(typedBody["host"])) {
+      return {
+        allowed: false,
+        message: `Denied by policy "EventsHostRestrictionPolicy".`,
+        cacheKey: request.username || null,
+      };
+    }
+    return {
+      allowed: true,
+      message: `Policy "EventsHostRestrictionPolicy". evaluated successfully.`,
+      cacheKey: request.username || null,
+    };
+  },
+);

src/api/routes/apiKey.ts

@@ -3,7 +3,7 @@ import rateLimiter from "api/plugins/rateLimiter.js";
 import { withRoles, withTags } from "api/components/index.js";
 import { AppRoles } from "common/roles.js";
 import { FastifyZodOpenApiTypeProvider } from "fastify-zod-openapi";
-import { ApiKeyDynamoEntry, apiKeyPostBody } from "common/types/apiKey.js";
+import { apiKeyPostBody } from "common/types/apiKey.js";
 import { createApiKey } from "api/functions/apiKey.js";
 import { buildAuditLogTransactPut } from "api/functions/auditLog.js";
 import { Modules } from "common/modules.js";
@@ -22,6 +22,7 @@ import {
   ValidationError,
 } from "common/errors/index.js";
 import { z } from "zod";
+import { ApiKeyDynamoEntry } from "api/functions/apiKey.js";
 
 const apiKeyRoute: FastifyPluginAsync = async (fastify, _options) => {
   await fastify.register(rateLimiter, {

src/api/routes/events.ts

@@ -18,8 +18,10 @@ import {
   DatabaseFetchError,
   DatabaseInsertError,
   DiscordEventError,
+  InternalServerError,
   NotFoundError,
   UnauthenticatedError,
+  UnauthorizedError,
   ValidationError,
 } from "../../common/errors/index.js";
 import { randomUUID } from "crypto";
@@ -42,6 +44,8 @@ import {
 } from "fastify-zod-openapi";
 import { ts, withRoles, withTags } from "api/components/index.js";
 import { MAX_METADATA_KEYS, metadataSchema } from "common/types/events.js";
+import { evaluateAllRequestPolicies } from "api/plugins/evaluatePolicies.js";
+import { request } from "http";
 
 const createProjectionParams = (includeMetadata: boolean = false) => {
   // Object mapping attribute names to their expression aliases
@@ -434,6 +438,37 @@ const eventsPlugin: FastifyPluginAsyncZodOpenApi = async (
         }),
       ) satisfies FastifyZodOpenApiSchema,
       onRequest: fastify.authorizeFromSchema,
+      preHandler: async (request, reply) => {
+        if (request.policyRestrictions) {
+          const response = await fastify.dynamoClient.send(
+            new GetItemCommand({
+              TableName: genericConfig.EventsDynamoTableName,
+              Key: marshall({ id: request.params.id }),
+            }),
+          );
+          const item = response.Item ? unmarshall(response.Item) : null;
+          if (!item) {
+            return reply.status(204).send();
+          }
+          const fakeBody = { ...request, body: item, url: request.url };
+          try {
+            const result = await evaluateAllRequestPolicies(fakeBody);
+            if (typeof result === "string") {
+              throw new UnauthorizedError({
+                message: result,
+              });
+            }
+          } catch (err) {
+            if (err instanceof BaseError) {
+              throw err;
+            }
+            fastify.log.error(err);
+            throw new InternalServerError({
+              message: "Failed to evaluate policies.",
+            });
+          }
+        }
+      },
     },
     async (request, reply) => {
       const id = request.params.id;

src/api/types.d.ts

@@ -8,6 +8,7 @@ import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
 import { SQSClient } from "@aws-sdk/client-sqs";
 import { CloudFrontKeyValueStoreClient } from "@aws-sdk/client-cloudfront-keyvaluestore";
+import { AvailableAuthorizationPolicy } from "./policies/definition";
 
 declare module "fastify" {
   interface FastifyInstance {
@@ -38,6 +39,7 @@ declare module "fastify" {
     username?: string;
     userRoles?: Set<AppRoles>;
     tokenPayload?: AadToken;
+    policyRestrictions?: AvailableAuthorizationPolicy[];
   }
 }
 

src/common/types/apiKey.ts

@@ -8,12 +8,9 @@ export type ApiKeyMaskedEntry = {
   description: string;
   createdAt: number;
   expiresAt?: number;
+  restrictions?: Record<string, any>;
 }
 
-export type ApiKeyDynamoEntry = ApiKeyMaskedEntry & {
-  keyHash: string;
-};
-
 export type DecomposedApiKey = {
   prefix: string;
   id: string;