@liminalfunctions/framework 1.0.0

package/src/F_Compile.ts

@@ -0,0 +1,368 @@
+import * as z from "zod/v4";
+import { Router, Request, Response } from "express";
+import { isValidObjectId } from "mongoose";
+
+import { F_Collection } from "./F_Collection.js";
+import { F_Security_Model, Authenticated_Request } from "./F_Security_Models/F_Security_Model.js";
+import { query_object_to_mongodb_limits, query_object_to_mongodb_query } from "./utils/query_object_to_mongodb_query.js";
+import { z_mongodb_id } from "./utils/mongoose_from_zod.js";
+
+export function compile<Collection_ID extends string, ZodSchema extends z.ZodObject>(app: Router, collection: F_Collection<Collection_ID, ZodSchema>, api_prefix: string){
+    for(let access_layers of collection.access_layers){
+
+        /*app.use((req, res, next) => {
+            console.log(`${req.method} ${req.originalUrl}`)
+            next();
+        })*/
+
+        let base_layers_path_components = access_layers.layers.flatMap(ele => [ele, ':' + ele]);
+
+        let get_one_path = [
+            api_prefix,
+            ...base_layers_path_components,
+            `${collection.collection_id}/:document_id`
+        ].join('/')
+
+        // get individual document
+        app.get(get_one_path, async (req: Request, res: Response) => {
+            // ensure the the document ID passed in is valid so that mongodb doesn't have a cow
+            if (!isValidObjectId(req.params.document_id)) {
+                res.status(400);
+                res.json({ error: `${req.params.document_id} is not a valid document ID.` });
+                return;
+            }
+
+            let find = { '_id': req.params.document_id } as { [key: string]: any } 
+            for(let layer of access_layers.layers){
+                find[`${layer}_id`] = req.params[layer];
+            }
+
+            let permissive_security_model = await F_Security_Model.model_with_permission(access_layers.security_models, req, res, find, 'get');
+            if (!permissive_security_model) {
+                res.status(403);
+                res.json({ error: `You do not have permission to fetch documents from ${req.params.document_type}.` });
+                return;
+            }
+
+            let document;
+            try {
+                //@ts-expect-error
+                document = await collection.mongoose_model.findOne(find, undefined, { 'lean': true });
+            } catch(err){
+                res.status(500);
+                res.json({ error: `there was a novel error` });
+                console.error(err);
+                return;
+            }
+            
+            if (!document) {
+                let sendable = await permissive_security_model.handle_empty_query_results(req, res, 'get');
+                res.json(sendable);
+            } else {
+                //await req.schema.handle_pre_send(req, document);
+                res.json({ data: document });
+            }
+            //await req.schema.fire_api_event('get', req, [document]);
+        })
+
+
+        let get_multiple_path = [
+            api_prefix,
+            ...base_layers_path_components,
+            collection.collection_id
+        ].join('/')
+
+        app.get(get_multiple_path, async (req: Request, res: Response) => {
+            let validated_query_args: { [key: string]: any } ;
+            try {
+                validated_query_args = collection.query_validator_server.parse(req.query);
+            } catch(err){
+                if(err instanceof z.ZodError){
+                    res.status(400);
+                    res.json({ error: err.issues });
+                    return;
+                } else {
+                    console.error(err);
+                    res.status(500);
+                    res.json({ error: `there was a novel error` });
+                    return;
+                }
+            }
+
+            let find = query_object_to_mongodb_query(validated_query_args) as { [key: string]: any };
+            for(let layer of access_layers.layers){
+                find[`${layer}_id`] = req.params[layer];
+            }
+
+            let permissive_security_model = await F_Security_Model.model_with_permission(access_layers.security_models, req, res, find, 'get');
+            if (!permissive_security_model) {
+                res.status(403);
+                res.json({ error: `You do not have permission to fetch documents from ${req.params.document_type}.` });
+                return;
+            }
+           
+            let documents;
+            try {
+                //@ts-expect-error
+                let query = collection.mongoose_model.find(find, undefined, { 'lean': true });
+                let fetch = query_object_to_mongodb_limits(query, collection.query_validator_server);
+                documents = await fetch;
+            } catch(err){
+                if (err.name == 'CastError') {
+                    res.status(400);
+                    res.json({ error: 'one of the IDs you passed to the query was not a valid MongoDB object ID.' });
+                    return;
+                } else {
+                    res.status(500);
+                    res.send({error: 'there was a novel error'});
+                    console.error(err);
+                    return;
+                }
+            }
+
+            if (!documents) {
+                let sendable = await permissive_security_model.handle_empty_query_results(req, res, 'get');
+                res.json(sendable);
+            } else {
+                //await req.schema.handle_pre_send(req, document);
+                res.json({ data: documents });
+            }
+            //await req.schema.fire_api_event('get', req, [document]);
+        })
+
+        let put_path = [
+            api_prefix,
+            ...base_layers_path_components,
+            `${collection.collection_id}/:document_id`
+        ].join('/')
+
+        app.put(put_path, async (req, res) => {
+            if (!isValidObjectId(req.params.document_id)) {
+                res.status(400);
+                res.json({ error: `${req.params.document_id} is not a valid document ID.` });
+                return;
+            }
+
+            let find = { '_id': req.params.document_id } as { [key: string]: any } ;
+            for(let layer of access_layers.layers){
+                find[`${layer}_id`] = req.params[layer];
+            }
+
+            
+            let permissive_security_model = await F_Security_Model.model_with_permission(access_layers.security_models, req, res, find, 'update');
+            if (!permissive_security_model) {
+                res.status(403);
+                res.json({ error: `You do not have permission to fetch documents from ${req.params.document_type}.` });
+                return;
+            }
+
+            if(collection.mongoose_schema.updated_by?.type === String) {
+                // if the security schema required the user to be logged in, then req.auth.user_id will not be null
+                if((req as Authenticated_Request).auth?.user_id){
+                    req.body.updated_by = (req as Authenticated_Request).auth?.user_id;
+                } else {
+                    req.body.updated_by = null;
+                }
+            }
+
+            if(collection.mongoose_schema.updated_at?.type === Date) {
+                req.body.updated_at = new Date();
+            }
+
+            // TODO: it might be possible to build a validator that matches mongoDB's update
+            // syntax to allow for targeted updating of nested stuff
+            let validated_request_body;
+            try {
+                validated_request_body = await collection.put_validator.parse(req.body);
+            } catch(err){
+                 if(err instanceof z.ZodError){
+                    res.status(400);
+                    res.json({ error: err.issues });
+                    return;
+                } else {
+                    console.error(err);
+                    res.status(500);
+                    res.json({ error: `there was a novel error` });
+                    return;
+                }
+            }
+
+            // if you're accessing the document from /x/:x/y/:y, then you can't change x or y. Note that this does mean if you can access
+            // the document from /x/:x, then you'd be able to change y.
+            for(let layer of access_layers.layers){
+                //@ts-expect-error
+                if(validated_request_body[`${layer}_id`] && validated_request_body[`${layer}_id`] !== req.params[layer]){
+                    res.status(403);
+                    res.json({ error: `The system does not support changing the ${layer}_id of the document with this endpoint.` });
+                    return;
+                }
+            }
+
+            /*let { error: pre_save_error } = await req.schema.handle_pre_save(req, value);
+            if (pre_save_error) {
+                res.status(400);
+                res.json({ error: pre_save_error.message });
+                return;
+            }*/
+            
+            
+            let results;
+            try {
+                //@ts-expect-error
+                results = await collection.mongoose_model.findOneAndUpdate(find, validated_request_body, { returnDocument: 'after', lean: true });
+            } catch(err){
+                res.status(500);
+                res.json({ error: `there was a novel error` });
+                console.error(err);
+                return;
+            }
+
+            if (!results) {
+                let sendable = await permissive_security_model.handle_empty_query_results(req, res, 'update');
+                res.json(sendable);
+            } else {
+                res.json({ data: results });
+            }
+            //await req.schema.fire_api_event('update', req, results);
+        });
+
+        let post_path = [
+            api_prefix,
+            ...base_layers_path_components,
+            `${collection.collection_id}`
+        ].join('/')
+
+        app.post(post_path, async (req, res) => {
+            // I'd like to have a validator here. I think it might need to be a map or record validator?
+            let permissive_security_model = await F_Security_Model.model_with_permission(access_layers.security_models, req, res, undefined, 'create');
+            if (!permissive_security_model) {
+                res.status(403);
+                res.json({ error: `You do not have permission to fetch documents from ${req.params.document_type}.` });
+                return;
+            }
+
+            if(collection.mongoose_schema.updated_by?.type === String) {
+                // if the security schema required the user to be logged in, then req.auth.user_id will not be null
+                if((req as Authenticated_Request).auth?.user_id){
+                    req.body.updated_by = (req as Authenticated_Request).auth?.user_id;
+                } else {
+                    req.body.updated_by = null;
+                }
+            }
+
+            if(collection.mongoose_schema.updated_at?.type === Date) {
+                req.body.updated_at = new Date();
+            }
+
+            if(collection.mongoose_schema.created_by?.type === String) {
+                // if the security schema required the user to be logged in, then req.auth.user_id will not be null
+                if((req as Authenticated_Request).auth?.user_id){
+                    req.body.created_by = (req as Authenticated_Request).auth?.user_id;
+                } else {
+                    req.body.created_by = null;
+                }
+            }
+
+            if(collection.mongoose_schema.created_at?.type === Date) {
+                req.body.created_at = new Date();
+            }
+
+            let validated_request_body;
+            try {
+                validated_request_body = await collection.post_validator.parse(req.body);
+            } catch(err){
+                 if(err instanceof z.ZodError){
+                    res.status(400);
+                    res.json({ error: err.issues });
+                    return;
+                } else {
+                    console.error(err);
+                    res.status(500);
+                    res.json({ error: `there was a novel error` });
+                    return;
+                }
+            }
+
+            // if you're accessing the document from /x/:x/y/:y, then you can't change x or y. Note that this does mean if you can access
+            // the document from /x/:x, then you'd be able to change y.
+            for(let layer of access_layers.layers){
+                //@ts-expect-error
+                if(validated_request_body[`${layer}_id`] && validated_request_body[`${layer}_id`] !== req.params[layer]){
+                    res.status(403);
+                    res.json({ error: `The system does not support changing the ${layer}_id of the document with this endpoint.` });
+                    return;
+                }
+            }
+
+            /*let { error: pre_save_error } = await req.schema.handle_pre_save(req, validated_request_body);
+            if (pre_save_error) {
+                res.status(400);
+                res.json({ error: pre_save_error.message });
+                return;
+            }*/
+
+            let results;
+            try {
+                results = await collection.mongoose_model.create(validated_request_body);
+            } catch(err){
+                res.status(500);
+                res.json({ error: `there was a novel error` });
+                console.error(err);
+                return;
+            }
+
+            if (!results) {
+                let sendable = await permissive_security_model.handle_empty_query_results(req, res, 'create');
+                res.json(sendable);
+            } else {
+                res.json({ data: results });
+            }
+            //await req.schema.fire_api_event('create', req, results);
+        });
+
+        let delete_path = [
+            api_prefix,
+            ...base_layers_path_components,
+            `${collection.collection_id}/:document_id`
+        ].join('/')
+
+        app.delete(delete_path, async (req, res) => {
+            if (!isValidObjectId(req.params.document_id)) {
+                res.status(400);
+                res.json({ error: `${req.params.document_id} is not a valid document ID.` });
+                return;
+            }
+
+            let find = { '_id': req.params.document_id } as { [key: string]: any } ;
+            for(let layer of access_layers.layers){
+                find[`${layer}_id`] = req.params[layer];
+            }
+
+            let permissive_security_model = await F_Security_Model.model_with_permission(access_layers.security_models, req, res, find, 'delete');
+            if (!permissive_security_model) {
+                res.status(403);
+                res.json({ error: `You do not have permission to fetch documents from ${req.params.document_type}.` });
+                return;
+            }
+
+            let results;
+            try {
+                //@ts-expect-error
+                results = await collection.mongoose_model.findOneAndDelete(find, {lean: true });
+            } catch(err){
+                res.status(500);
+                res.json({ error: `there was a novel error` });
+                console.error(err);
+                return;
+            }
+
+            if (!results) {
+                let sendable = await permissive_security_model.handle_empty_query_results(req, res, 'delete');
+                res.json(sendable);
+            } else {
+                res.json({ data: results });
+            }
+            // await req.schema.fire_api_event('delete', req, results);
+        });
+    }
+}

package/src/F_Security_Models/F_SM_Open_Access.ts

@@ -0,0 +1,21 @@
+import * as z from "zod/v4";
+import { Request, Response } from "express";
+import { Empty_Query_Possibilities, F_Security_Model, Operation } from "./F_Security_Model.js";
+import { F_Collection } from "../F_Collection.js";
+
+export class F_SM_Open_Access<Collection_ID extends string, ZodSchema extends z.ZodObject> extends F_Security_Model<Collection_ID, ZodSchema> {
+
+    constructor(collection: F_Collection<Collection_ID, ZodSchema>){
+        super(collection);
+        this.needs_auth_user = false;
+    }
+
+    async has_permission(req: Request, res: Response, find: {[key: string]: any}, operation: Operation): Promise<boolean> {
+        return true;
+    }
+
+    async handle_empty_query_results(req: Request, res: Response, operation: Operation): Promise<Empty_Query_Possibilities> {
+        return { data: null }
+    }
+    
+}

package/src/F_Security_Models/F_SM_Ownership.ts

@@ -0,0 +1,72 @@
+import * as z from "zod/v4";
+import { Request, Response } from "express";
+import { F_Collection } from "../F_Collection.js";
+import { Authenticated_Request, Empty_Query_Possibilities, F_Security_Model, Operation } from "./F_Security_Model.js";
+
+export class F_SM_Ownership<Collection_ID extends string, ZodSchema extends z.ZodObject> extends F_Security_Model<Collection_ID, ZodSchema> {
+    user_id_field: string;
+
+    constructor(collection: F_Collection<Collection_ID, ZodSchema>, user_id_field = 'user_id'){
+        super(collection);
+        this.needs_auth_user = true;
+        this.user_id_field = user_id_field;
+    }
+
+    async has_permission(req: Authenticated_Request, res: Response, find: {[key: string]: any}, operation: Operation): Promise<boolean> {
+        let user_id = '' + req.auth.user_id;
+        
+        if (operation === 'get') {
+            // if we're fetching a specific document by its ID, it's valid to get
+            // it as long as we modify the find so that it only returns documents
+            // owned by the current user
+            if (req.params.document_id) {
+                find[this.user_id_field] = user_id;
+
+                return true;
+            }
+
+            // if we're fetching a document and filtering by the user's ID already,
+            // then this security model is satisfied
+            if (find[this.user_id_field] === user_id) {
+                return true;
+            }
+        }
+
+        // if we're updating a specific document, it's valid as long as we modify the
+        // find so that it only modifies documents owned by the current user
+        if (operation === 'update') {
+            find[this.user_id_field] = user_id;
+            return true;
+        }
+
+        // if we're creating a document, it's valid as long as it's owned by the current
+        // user.
+        if (operation === 'create') {
+            if (req.body[this.user_id_field] === user_id) {
+                return true;
+            }
+        }
+
+        // if we're deleting a specific document, it's valid as long as we modify the
+        // find so that it only deletes documents owned by the current user
+        if (operation === 'delete') {
+            find[this.user_id_field] = user_id;
+            return true;
+        }
+
+        return false;
+    }
+    
+    async handle_empty_query_results(req: Request, res: Response, operation: Operation): Promise<Empty_Query_Possibilities> {
+        if (req.params.document_id) {
+            let document_result = await this.collection.mongoose_model.findById(req.params.document_id);
+
+            if (document_result) {
+                res.status(403);
+                return { error: `You do not have permission to ${operation} documents from ${req.params.document_type}.` };
+            }
+        }
+
+        return { data: null };
+    }
+}

package/src/F_Security_Models/F_SM_Role_Membership.ts

@@ -0,0 +1,87 @@
+import * as z from "zod/v4";
+import { Request, Response } from "express";
+import { F_Collection } from "../F_Collection.js";
+import { Cache } from "../utils/cache.js";
+import { Authenticated_Request, Empty_Query_Possibilities, F_Security_Model, Operation } from "./F_Security_Model.js";
+import mongoose from "mongoose";
+
+let operation_permission_map = {
+    'get': 'read',
+    'create': 'create',
+    'update': 'update',
+    'delete': 'delete'
+}
+
+export class F_SM_Role_Membership<Collection_ID extends string, ZodSchema extends z.ZodObject> extends F_Security_Model<Collection_ID, ZodSchema> {
+    user_id_field: string;
+    role_id_field: string;
+    layer_collection_id: string;
+    role_membership_collection: F_Collection<string, any>;
+    role_membership_cache: Cache<any>;
+    role_collection: F_Collection<string, any>;
+    role_cache: Cache<any>;
+
+    constructor(collection: F_Collection<Collection_ID, ZodSchema>,
+        layer_collection: F_Collection<string, any>,
+        role_membership_collection: F_Collection<string, any>,
+        role_collection: F_Collection<string, any>,
+        role_membership_cache?: Cache<any>,
+        role_cache?: Cache<any>,
+        user_id_field = 'user_id',
+        role_id_field = 'role_id',
+    ){
+        super(collection);
+        this.needs_auth_user = true;
+        this.user_id_field = user_id_field;
+        this.role_id_field = role_id_field;
+        this.layer_collection_id = layer_collection.collection_id;
+        this.role_membership_collection = role_membership_collection;
+        this.role_membership_cache = role_membership_cache ?? new Cache(60);
+        this.role_collection = role_collection;
+        this.role_cache = role_cache ?? new Cache(60);
+
+        if(!this.role_collection.mongoose_schema.permissions){
+            throw new Error(`could not find field "permissions" on role collection. Permissions should be an object of the format {[key: collection_id]: ('read'| 'create'| 'update'| 'delete')[]}`)
+        }
+    }
+
+    async has_permission(req: Authenticated_Request, res: Response, find: {[key: string]: any}, operation: Operation): Promise<boolean> {
+        let user_id = req.auth.user_id;
+        let layer_id = req.params[this.layer_collection_id];
+
+        // return the role membership associated with the layer. This uses the cache heavily, so it should be
+        // a cheap operation even though it makes an extra database query. Use the cache's first_fetch_then_refresh
+        // method so that we aren't keeping out-of-date auth data in the cache.
+        let role_membership = await this.role_membership_cache.first_fetch_then_refresh(`${user_id}-${layer_id}`, async () => {
+            let role_memberships = await this.role_membership_collection.mongoose_model.find({ 
+                [this.user_id_field]: user_id,
+                [`${this.layer_collection_id}_id`]: new mongoose.Types.ObjectId(layer_id)
+            })
+
+            if(role_memberships.length > 1){
+                console.warn(`in F_SM_Role_Membership, more than one role membership for user ${user_id} at layer ${this.layer_collection_id} found.`)
+            }
+            return role_memberships[0];
+        })
+
+        if(!role_membership){ return false; }
+        if(!role_membership[this.role_id_field]){ console.warn(`role membership collection ${this.role_membership_collection.collection_id} did not have role ID filed ${this.role_id_field}`); return false;}
+
+        // return the role associated with the role membership. This uses the cache heavily, so it should be
+        // a cheap operation even though it makes an extra database query. Use the cache's first_fetch_then_refresh
+        // method so that we aren't keeping out-of-date auth data in the cache.
+        let role = await this.role_cache.first_fetch_then_refresh(role_membership[this.role_id_field], async () => {
+            let role = await this.role_collection.mongoose_model.findById(role_membership[this.role_id_field]);
+            return role;
+        })
+        
+        if(!role){ return false; }
+        if(!role.permissions){ console.warn(`role collection ${this.role_collection.collection_id} was missing its permissions field`); return false; }
+        if(!role.permissions[this.collection.collection_id]){ console.warn(`role collection ${this.role_collection.collection_id} was missing its permissions.${this.collection.collection_id} field`); return false; }
+        return role.permissions[this.collection.collection_id].includes(operation_permission_map[operation]);
+    }
+    
+    async handle_empty_query_results(req: Request, res: Response, operation: Operation): Promise<Empty_Query_Possibilities> {
+        return { data: null };
+    }
+}

package/src/F_Security_Models/F_Security_Model.ts

@@ -0,0 +1,85 @@
+
+import * as z from "zod/v4";
+import { Router, Request, Response } from "express";
+import { F_Collection } from "../F_Collection.js";
+
+export type Operation = 'get' | 'update' | 'create' | 'delete';
+
+export abstract class F_Security_Model<Collection_ID extends string, ZodSchema extends z.ZodObject> {
+    collection: F_Collection<Collection_ID, ZodSchema>;
+    needs_auth_user: boolean
+    static auth_fetcher: (req: Request) => Promise<Auth_Data | undefined>
+
+    constructor(collection: F_Collection<Collection_ID, ZodSchema>) {
+        this.collection = collection;
+    }
+
+    /**
+     * Returns true if this security model can grant permission to perform the operation.
+     * This may be accomplished by modifying the mongodb filter that will be applied during
+     * the fetch/update: for example, a security model that allows modifying only members of
+     * a certain institution might add { institution_id: xxxxx } to the find.
+     * @param req 
+     * @param res 
+     * @param find 
+     * @param operation 
+     */
+    abstract has_permission(req: Request, res: Response, find: {[key: string]: any}, operation: Operation): Promise<boolean>;
+    
+    /**
+     * In the event that no documents are returned by the mongodb operation, it's necessary to find
+     * out if this was caused by modifications to the mongodb filter, or if it was caused by a lack
+     * of documents to operate on.
+     * 
+     * In the event that there are documents but the user lacks permission to act on them, this method
+     * is expected to set the response status to 403.
+     * 
+     * @param req 
+     * @param res 
+     * @param operation 
+     */
+    abstract handle_empty_query_results(req: Request, res: Response, operation: Operation): Promise<Empty_Query_Possibilities>;
+
+    static set_auth_fetcher(fetcher: (req: Request) => Promise<Auth_Data | undefined>){
+        F_Security_Model.auth_fetcher = fetcher;
+    }
+
+    static async has_permission(models: F_Security_Model<string, any>[], req: Request, res: Response, find: {[key: string]: any}, operation: Operation){ console.error(`F_Security_Model.has_permission is deprecated in favor of F_Security_Model.model_with_permission.`); return await F_Security_Model.model_with_permission(models, req, res, find, operation); }
+    static async model_with_permission(models: F_Security_Model<string, any>[], req: Request, res: Response, find: {[key: string]: any}, operation: Operation): Promise<F_Security_Model<string, any>> {
+        let has_attempted_authenticating_user = false;
+        
+        for (let security_model of models) {
+            // if the security model needs user auth data, fetch it.
+            if (security_model.needs_auth_user && !has_attempted_authenticating_user) {
+                has_attempted_authenticating_user = true;
+                (req as Authenticated_Request).auth = await F_Security_Model.auth_fetcher(req);
+            }
+
+            // if the user auth data fetch failed, and the security model needs that data, don't bother using the security model.
+            if (security_model.needs_auth_user && !(req as Authenticated_Request).auth) {
+                continue;
+            }
+
+            // if the security model is a good candidate, return it.
+            if (await security_model.has_permission(req, res, find, operation)) {
+                return security_model;
+            }
+        }
+        return undefined;
+    }
+}
+
+export type Auth_Data = {
+    user_id: string,
+    layers: {
+        layer_id: string,
+        permissions: {[key: string]: Operation[]},
+        special_permissions: {[key: string]: string[]}
+    }[]
+}
+
+export type Authenticated_Request = Request & {
+    auth: Auth_Data
+}
+
+export type Empty_Query_Possibilities = { data: null} | { error: string };