@teamkeel/functions-runtime 0.285.0 → 0.287.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamkeel/functions-runtime",
-  "version": "0.285.0",
+  "version": "0.287.0",
   "description": "Internal package used by @teamkeel/sdk",
   "main": "src/index.js",
   "scripts": {

package/src/errors.js

@@ -1,4 +1,5 @@
 const { createJSONRPCErrorResponse } = require("json-rpc-2.0");
+const { PermissionError } = require("./permissions");
 
 const RuntimeErrors = {
   // Catchall error type for unhandled execution errors during custom function
@@ -12,11 +13,22 @@ const RuntimeErrors = {
   ForeignKeyConstraintError: -32005,
   NotNullConstraintError: -32006,
   UniqueConstraintError: -32007,
+  PermissionError: -32008,
 };
 
 // errorToJSONRPCResponse transforms a JavaScript Error instance (or derivative) into a valid JSONRPC response object to pass back to the Keel runtime.
 function errorToJSONRPCResponse(request, e) {
   if (!e.error) {
+    // it isnt wrapped
+
+    if (e instanceof PermissionError) {
+      return createJSONRPCErrorResponse(
+        request.id,
+        RuntimeErrors.PermissionError,
+        e.message
+      );
+    }
+
     return createJSONRPCErrorResponse(
       request.id,
       RuntimeErrors.UnknownError,
@@ -24,9 +36,6 @@ function errorToJSONRPCResponse(request, e) {
     );
   }
   // we want to switch on instanceof but there is no way to do that in js, so best to check the constructor class of the error
-
-  // todo: fuzzy matching on postgres errors from both rds-data-api and pg-protocol
-
   switch (e.error.constructor.name) {
     // Any error thrown in the ModelAPI class is
     // wrapped in a DatabaseError in order to differentiate 'our code' vs the user's own code.

package/src/handleRequest.js

@@ -4,6 +4,9 @@ const {
   JSONRPCErrorCode,
 } = require("json-rpc-2.0");
 
+const { getDatabase } = require("./database");
+const { PERMISSION_STATE, PermissionError } = require("./permissions");
+
 const { errorToJSONRPCResponse, RuntimeErrors } = require("./errors");
 
 // Generic handler function that is agnostic to runtime environment (local or lambda)
@@ -24,11 +27,36 @@ async function handleRequest(request, config) {
     // headers reference passed to custom function where object data can be modified
     const headers = new Headers();
 
-    const result = await functions[request.method](
-      request.params,
-      createFunctionAPI(headers),
-      createContextAPI(request.meta)
-    );
+    const db = getDatabase();
+
+    // We want to wrap the execution of the custom function in a transaction so that any call the user makes
+    // to any of the model apis we provide to the custom function is processed in a transaction.
+    // This is useful for permissions where we want to only proceed with database writes if all permission rules
+    // have been validated.
+    const result = await db.transaction().execute(async (trx) => {
+      const api = createFunctionAPI({ headers, db: trx });
+      const ctx = createContextAPI(request.meta);
+
+      // Call the user's custom function!
+      const fnResult = await functions[request.method](
+        request.params,
+        api,
+        ctx
+      );
+
+      // api.permissions maintains an internal state of whether the current operation has been permitted either by the user or by built-in permission rules
+      // we need to check that the final state is permitted. if it's not, then we want to rollback
+      // the transaction
+      if (api.permissions.getState() !== PERMISSION_STATE.PERMITTED) {
+        // Any error thrown inside of Kysely's transaction execute() will cause the transaction to be rolled back.
+        // PermissionError is handled by our JSONRPC error serialisation code
+        throw new PermissionError(`Not permitted to access ${request.method}`);
+      } else {
+        // otherwise, if everything is permitted, then we just return the function result from
+        // the transaction closure.
+        return fnResult;
+      }
+    });
 
     if (result === undefined) {
       // no result returned from custom function

package/src/handleRequest.test.js

@@ -4,19 +4,29 @@ import { handleRequest, RuntimeErrors } from "./handleRequest";
 import { test, expect, beforeEach, describe } from "vitest";
 import { ModelAPI } from "./ModelAPI";
 import { getDatabase } from "./database";
+import { Permissions } from "./permissions";
+
 import KSUID from "ksuid";
 
+process.env.KEEL_DB_CONN_TYPE = "pg";
+process.env.KEEL_DB_CONN = `postgresql://postgres:postgres@localhost:5432/functions-runtime`;
+
 test("when the custom function returns expected value", async () => {
   const config = {
     functions: {
-      createPost: async () => {
+      createPost: async (inputs, api, ctx) => {
+        api.permissions.allow();
         return {
           title: "a post",
           id: "abcde",
         };
       },
     },
-    createFunctionAPI: () => {},
+    createFunctionAPI: ({ headers, db }) => {
+      return {
+        permissions: new Permissions(),
+      };
+    },
     createContextAPI: () => {},
   };
 
@@ -38,9 +48,15 @@ test("when the custom function returns expected value", async () => {
 test("when the custom function doesnt return a value", async () => {
   const config = {
     functions: {
-      createPost: async () => {},
+      createPost: async (inputs, api, ctx) => {
+        api.permissions.allow();
+      },
+    },
+    createFunctionAPI: ({ headers, db }) => {
+      return {
+        permissions: new Permissions(),
+      };
     },
-    createFunctionAPI: () => {},
     createContextAPI: () => {},
   };
 
@@ -59,9 +75,13 @@ test("when the custom function doesnt return a value", async () => {
 test("when there is no matching function for the path", async () => {
   const config = {
     functions: {
-      createPost: async () => {},
+      createPost: async (inputs, api, ctx) => {},
+    },
+    createFunctionAPI: ({ headers, db }) => {
+      return {
+        permissions: new Permissions(),
+      };
     },
-    createFunctionAPI: () => {},
     createContextAPI: () => {},
   };
 
@@ -80,11 +100,17 @@ test("when there is no matching function for the path", async () => {
 test("when there is an unexpected error in the custom function", async () => {
   const config = {
     functions: {
-      createPost: () => {
+      createPost: (inputs, api, ctx) => {
+        api.permissions.allow();
+
         throw new Error("oopsie daisy");
       },
     },
-    createFunctionAPI: () => {},
+    createFunctionAPI: ({ headers, db }) => {
+      return {
+        permissions: new Permissions(),
+      };
+    },
     createContextAPI: () => {},
   };
 
@@ -103,11 +129,17 @@ test("when there is an unexpected error in the custom function", async () => {
 test("when there is an unexpected object thrown in the custom function", async () => {
   const config = {
     functions: {
-      createPost: () => {
+      createPost: (inputs, api, ctx) => {
+        api.permissions.allow();
+
         throw { err: "oopsie daisy" };
       },
     },
-    createFunctionAPI: () => {},
+    createFunctionAPI: ({ headers, db }) => {
+      return {
+        permissions: new Permissions(),
+      };
+    },
     createContextAPI: () => {},
   };
 
@@ -159,17 +191,22 @@ describe("ModelAPI error handling", () => {
     functionConfig = {
       functions: {
         createPost: async (inputs, api, ctx) => {
+          api.permissions.allow();
+
           const post = await api.models.post.create(inputs);
 
           return post;
         },
         deletePost: async (inputs, api, ctx) => {
+          api.permissions.allow();
+
           const deleted = await api.models.post.delete(inputs);
 
           return deleted;
         },
       },
-      createFunctionAPI: () => ({
+      createFunctionAPI: ({ headers, db }) => ({
+        permissions: new Permissions(),
         models: {
           post: new ModelAPI(
             "post",

package/src/index.d.ts

@@ -64,3 +64,16 @@ export type RequestHeaders = {
   get(name: string): string;
   has(name: string): boolean;
 };
+
+export declare class Permissions {
+  constructor();
+
+  // check() can be used to check the given row(s) against the permission rules defined in the schema
+  async check(rows: any | any[]): Promise<void>;
+
+  // allow() can be used to explicitly permit access to an action
+  allow(): void;
+
+  // deny() can be used to explicitly deny access to an action
+  deny(): void;
+}

package/src/index.js

@@ -3,12 +3,15 @@ const { RequestHeaders } = require("./RequestHeaders");
 const { handleRequest } = require("./handleRequest");
 const KSUID = require("ksuid");
 const { getDatabase } = require("./database");
+const { Permissions, PERMISSION_STATE } = require("./permissions");
 
 module.exports = {
   ModelAPI,
   RequestHeaders,
   handleRequest,
   getDatabase,
+  Permissions,
+  PERMISSION_STATE,
   ksuid() {
     return KSUID.randomSync().string;
   },

package/src/permissions.js

@@ -0,0 +1,46 @@
+class PermissionError extends Error {}
+
+const PERMISSION_STATE = {
+  PERMITTED: "permitted",
+  UNPERMITTED: "unpermitted",
+};
+
+class Permissions {
+  constructor() {
+    this.state = {
+      // permitted starts off as null to indicate that the end user
+      // hasn't explicitly marked a function execution as permitted yet
+      permitted: null,
+    };
+  }
+
+  async check(rows) {
+    throw new Error("Not implemented");
+  }
+
+  allow() {
+    this.state.permitted = true;
+  }
+
+  deny() {
+    // if a user is explicitly calling deny() then we want to throw an error
+    // so that any further execution of the custom function stops abruptly
+    // we don't need to explicitly set pending to false as the error will have been thrown
+    // so we know an action has been taken
+    throw new PermissionError();
+  }
+
+  getState() {
+    switch (true) {
+      // this will cover both permitted being false, and null (initial state)
+      case !this.state.permitted:
+        return PERMISSION_STATE.UNPERMITTED;
+      default:
+        return PERMISSION_STATE.PERMITTED;
+    }
+  }
+}
+
+module.exports.PermissionError = PermissionError;
+module.exports.PERMISSION_STATE = PERMISSION_STATE;
+module.exports.Permissions = Permissions;

package/src/permissions.test.js

@@ -0,0 +1,31 @@
+import { Permissions, PERMISSION_STATE, PermissionError } from "./permissions";
+
+import { beforeEach, expect, test } from "vitest";
+
+let permissions;
+
+beforeEach(() => {
+  permissions = new Permissions();
+});
+
+test("explicitly allowing execution", () => {
+  expect(permissions.getState()).toEqual(PERMISSION_STATE.UNPERMITTED);
+
+  permissions.allow();
+
+  expect(permissions.getState()).toEqual(PERMISSION_STATE.PERMITTED);
+});
+
+test("explicitly denying execution", () => {
+  expect(permissions.getState()).toEqual(PERMISSION_STATE.UNPERMITTED);
+
+  expect(() => permissions.deny()).toThrowError(PermissionError);
+
+  expect(permissions.getState()).toEqual(PERMISSION_STATE.UNPERMITTED);
+});
+
+test("check", async () => {
+  await expect(() => permissions.check()).rejects.toThrowError(
+    "Not implemented"
+  );
+});