@m5kdev/backend 0.5.0 → 0.7.0

package/dist/src/modules/base/base.procedure.js

@@ -0,0 +1,301 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServiceProcedureBuilder = createServiceProcedureBuilder;
+exports.createPermissionServiceProcedureBuilder = createPermissionServiceProcedureBuilder;
+const neverthrow_1 = require("neverthrow");
+const base_actor_1 = require("./base.actor");
+const DEFAULT_CONTEXT_FILTER_INCLUDE = [
+    "user",
+];
+function isServerResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "isErr" in value &&
+        typeof value.isErr === "function" &&
+        "isOk" in value &&
+        typeof value.isOk === "function");
+}
+async function normalizeProcedureResult(result) {
+    const resolved = await result;
+    return isServerResult(resolved) ? resolved : (0, neverthrow_1.ok)(resolved);
+}
+function assertUniqueStepName(steps, stepName) {
+    if (steps.some((step) => step.stepName === stepName)) {
+        throw new Error(`Duplicate service procedure step name: ${stepName}`);
+    }
+}
+function hasStepName(steps, stepName) {
+    return steps.some((step) => step.stepName === stepName);
+}
+function getContextFilterInclude(include = DEFAULT_CONTEXT_FILTER_INCLUDE) {
+    return {
+        user: include.includes("user"),
+        organization: include.includes("organization"),
+        team: include.includes("team"),
+    };
+}
+function getFailureStage(code) {
+    return code === "FORBIDDEN" || code === "UNAUTHORIZED" ? "forbidden" : "error";
+}
+function logProcedureStage(host, procedureName, ctx, stage, { stepName, durationMs, errorCode, } = {}) {
+    host.logger.debug({
+        procedureName,
+        stage,
+        stepName,
+        durationMs,
+        errorCode,
+        hasActor: Boolean(ctx.actor),
+    });
+}
+function requireProcedureActor(host, ctx, scope) {
+    if (!ctx.actor) {
+        return host.error("UNAUTHORIZED", "Unauthorized");
+    }
+    if (!(0, base_actor_1.validateActor)(ctx.actor, scope)) {
+        return host.error("FORBIDDEN", "Forbidden");
+    }
+    return (0, neverthrow_1.ok)(ctx.actor);
+}
+function createRequireAuthStep(host, scope = "user") {
+    return {
+        stage: "auth",
+        stepName: "auth",
+        run: async ({ ctx }) => {
+            return requireProcedureActor(host, ctx, scope);
+        },
+    };
+}
+function createUseStep(stepName, step) {
+    return {
+        stage: "use",
+        stepName,
+        run: async (args) => normalizeProcedureResult(step(args)),
+    };
+}
+function createInputStep(stepName, step) {
+    return {
+        stage: "input",
+        stepName,
+        run: async (args) => normalizeProcedureResult(step(args)),
+    };
+}
+function createContextFilterStep(host, include) {
+    const contextInclude = getContextFilterInclude(include);
+    const requiredScope = contextInclude.team
+        ? "team"
+        : contextInclude.organization
+            ? "organization"
+            : "user";
+    return {
+        stage: "input",
+        stepName: "contextFilter",
+        run: async ({ input, ctx }) => {
+            const actor = requireProcedureActor(host, ctx, requiredScope);
+            if (actor.isErr())
+                return actor;
+            return (0, neverthrow_1.ok)(host.addContextFilter(actor.value, contextInclude, input));
+        },
+    };
+}
+function createAccessStep(host, config) {
+    return {
+        stage: "access",
+        stepName: "access",
+        run: async (args) => {
+            const typedArgs = args;
+            const actor = requireProcedureActor(host, typedArgs.ctx, "user");
+            if (actor.isErr())
+                return actor;
+            if ("entityStep" in config && typeof config.entityStep === "string") {
+                const entities = typedArgs.state[config.entityStep];
+                const hasPermission = host.checkPermission(actor.value, config.action, entities, config.grants);
+                if (!hasPermission) {
+                    return host.error("FORBIDDEN");
+                }
+                return (0, neverthrow_1.ok)(entities);
+            }
+            if (typeof config.entities === "function") {
+                const resolveEntities = config.entities;
+                let loadedEntities;
+                const permission = await host.checkPermissionAsync(actor.value, config.action, async () => {
+                    const entityResult = await normalizeProcedureResult(resolveEntities(typedArgs));
+                    if (entityResult.isOk()) {
+                        loadedEntities = entityResult.value;
+                    }
+                    return entityResult;
+                }, config.grants);
+                if (permission.isErr()) {
+                    return permission;
+                }
+                if (!permission.value) {
+                    return host.error("FORBIDDEN");
+                }
+                return (0, neverthrow_1.ok)(loadedEntities);
+            }
+            const entities = config.entities;
+            const hasPermission = host.checkPermission(actor.value, config.action, entities, config.grants);
+            if (!hasPermission) {
+                return host.error("FORBIDDEN");
+            }
+            return (0, neverthrow_1.ok)(entities);
+        },
+    };
+}
+function createProcedureHandler(host, config, handler) {
+    return async (input, ctx) => host.throwableAsync(async () => {
+        const state = {};
+        const startTime = Date.now();
+        const typedCtx = ctx;
+        let currentInput = input;
+        logProcedureStage(host, config.name, typedCtx, "start");
+        try {
+            for (const step of config.steps) {
+                const stepResult = await step.run({
+                    input: currentInput,
+                    ctx: typedCtx,
+                    state,
+                    repository: host.repository,
+                    service: host.service,
+                    logger: host.logger,
+                });
+                if (stepResult.isErr()) {
+                    logProcedureStage(host, config.name, typedCtx, getFailureStage(stepResult.error.code), {
+                        stepName: step.stepName,
+                        durationMs: Date.now() - startTime,
+                        errorCode: stepResult.error.code,
+                    });
+                    return stepResult;
+                }
+                state[step.stepName] = stepResult.value;
+                if (step.stage === "input") {
+                    currentInput = stepResult.value;
+                }
+                if (step.stage === "auth") {
+                    logProcedureStage(host, config.name, typedCtx, "auth_passed", {
+                        stepName: step.stepName,
+                    });
+                }
+                if (step.stage === "access") {
+                    logProcedureStage(host, config.name, typedCtx, "access_passed", {
+                        stepName: step.stepName,
+                    });
+                }
+            }
+            const handlerResult = await normalizeProcedureResult(handler({
+                input: currentInput,
+                ctx: ctx,
+                state: state,
+                repository: host.repository,
+                service: host.service,
+                logger: host.logger,
+            }));
+            if (handlerResult.isErr()) {
+                logProcedureStage(host, config.name, typedCtx, getFailureStage(handlerResult.error.code), {
+                    durationMs: Date.now() - startTime,
+                    errorCode: handlerResult.error.code,
+                });
+                return handlerResult;
+            }
+            logProcedureStage(host, config.name, typedCtx, "success", {
+                durationMs: Date.now() - startTime,
+            });
+            return handlerResult;
+        }
+        catch (error) {
+            const serverError = host.handleUnknownError(error);
+            logProcedureStage(host, config.name, typedCtx, getFailureStage(serverError.code), {
+                durationMs: Date.now() - startTime,
+                errorCode: serverError.code,
+            });
+            throw error;
+        }
+    });
+}
+function createServiceProcedureBuilder(host, config) {
+    function addContextFilter(include) {
+        const steps = hasStepName(config.steps, "auth")
+            ? config.steps
+            : [...config.steps, createRequireAuthStep(host, "user")];
+        assertUniqueStepName(steps, "contextFilter");
+        return createServiceProcedureBuilder(host, {
+            ...config,
+            steps: [...steps, createContextFilterStep(host, include)],
+        });
+    }
+    const builder = {
+        use(stepName, step) {
+            assertUniqueStepName(config.steps, stepName);
+            return createServiceProcedureBuilder(host, {
+                ...config,
+                steps: [...config.steps, createUseStep(stepName, step)],
+            });
+        },
+        mapInput(stepName, step) {
+            assertUniqueStepName(config.steps, stepName);
+            return createServiceProcedureBuilder(host, {
+                ...config,
+                steps: [...config.steps, createInputStep(stepName, step)],
+            });
+        },
+        addContextFilter,
+        requireAuth(scope) {
+            assertUniqueStepName(config.steps, "auth");
+            return createServiceProcedureBuilder(host, {
+                ...config,
+                steps: [...config.steps, createRequireAuthStep(host, scope ?? "user")],
+            });
+        },
+        handle(handler) {
+            return createProcedureHandler(host, config, handler);
+        },
+    };
+    return builder;
+}
+function createPermissionServiceProcedureBuilder(host, config) {
+    function addContextFilter(include) {
+        const steps = hasStepName(config.steps, "auth")
+            ? config.steps
+            : [...config.steps, createRequireAuthStep(host, "user")];
+        assertUniqueStepName(steps, "contextFilter");
+        return createPermissionServiceProcedureBuilder(host, {
+            ...config,
+            steps: [...steps, createContextFilterStep(host, include)],
+        });
+    }
+    function access(accessConfig) {
+        assertUniqueStepName(config.steps, "access");
+        return createPermissionServiceProcedureBuilder(host, {
+            ...config,
+            steps: [...config.steps, createAccessStep(host, accessConfig)],
+        });
+    }
+    const builder = {
+        use(stepName, step) {
+            assertUniqueStepName(config.steps, stepName);
+            return createPermissionServiceProcedureBuilder(host, {
+                ...config,
+                steps: [...config.steps, createUseStep(stepName, step)],
+            });
+        },
+        mapInput(stepName, step) {
+            assertUniqueStepName(config.steps, stepName);
+            return createPermissionServiceProcedureBuilder(host, {
+                ...config,
+                steps: [...config.steps, createInputStep(stepName, step)],
+            });
+        },
+        addContextFilter,
+        requireAuth(scope) {
+            assertUniqueStepName(config.steps, "auth");
+            return createPermissionServiceProcedureBuilder(host, {
+                ...config,
+                steps: [...config.steps, createRequireAuthStep(host, scope ?? "user")],
+            });
+        },
+        access,
+        handle(handler) {
+            return createProcedureHandler(host, config, handler);
+        },
+    };
+    return builder;
+}

package/dist/src/modules/base/base.repository.d.ts

@@ -32,6 +32,7 @@ export declare class BaseRepository<O extends LibSQLDatabase<any>, S extends Rec
     getConditionBuilder(): ConditionBuilder;
     getConditionBuilder(table: undefined): ConditionBuilder;
     getConditionBuilder<TTable extends SQLiteTableWithColumns<any>>(table: TTable): TableConditionBuilder<TTable>;
+    throwableQuery<T>(fn: () => Promise<T>): ServerResultAsync<T>;
     withPagination<TQuery>(query: TQuery, { page, limit }: Pick<QueryInput, "page" | "limit">): TQuery;
     withSorting<TTable extends SQLiteTableWithColumns<any>, TQuery>(query: TQuery, { sort, order }: Pick<QueryInput, "sort" | "order">, table?: TTable): TQuery;
     withSortingAndPagination<TTable extends SQLiteTableWithColumns<any>, TQuery>(query: TQuery, { sort, order, page, limit }: Pick<QueryInput, "sort" | "order" | "page" | "limit">, table?: TTable): TQuery;

package/dist/src/modules/base/base.repository.js

@@ -3,11 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseExternaRepository = exports.BaseTableRepository = exports.BaseRepository = exports.arrayContains = exports.TableConditionBuilder = exports.ConditionBuilder = void 0;
 const drizzle_orm_1 = require("drizzle-orm");
 const neverthrow_1 = require("neverthrow");
-const base_abstract_1 = require("./base.abstract");
-const base_dto_1 = require("./base.dto");
+const errors_1 = require("../../utils/errors");
 const applyPagination_1 = require("../utils/applyPagination");
 const applySorting_1 = require("../utils/applySorting");
 const getConditionsFromFilters_1 = require("../utils/getConditionsFromFilters");
+const base_abstract_1 = require("./base.abstract");
+const base_dto_1 = require("./base.dto");
 class ConditionBuilder {
     conditions;
     constructor(conditions = []) {
@@ -66,6 +67,15 @@ class BaseRepository extends base_abstract_1.Base {
         }
         return new TableConditionBuilder(table);
     }
+    throwableQuery(fn) {
+        return this.throwablePromise(() => fn(), (error) => new errors_1.ServerError({
+            code: "INTERNAL_SERVER_ERROR",
+            layer: "repository",
+            layerName: this.constructor.name,
+            message: "Database query failed",
+            cause: error,
+        }));
+    }
     withPagination(query, { page, limit }) {
         return (0, applyPagination_1.applyPagination)(query, limit, page);
     }

package/dist/src/modules/base/base.service.d.ts

@@ -1,40 +1,40 @@
 import type { QueryFilter, QueryInput } from "@m5kdev/commons/modules/schemas/query.schema";
-import type { Context, Session, User } from "../auth/auth.lib";
 import { Base } from "./base.abstract";
+import { type AuthenticatedActor } from "./base.actor";
 import type { ServerResult, ServerResultAsync } from "./base.dto";
 import { type Entity, type ResourceActionGrant, type ResourceGrant } from "./base.grants";
-import type { BaseExternaRepository, BaseRepository } from "./base.repository";
-export declare class BaseService<Repositories extends Record<string, BaseRepository<any, any, any> | BaseExternaRepository>, Services extends Record<string, BaseService<any, any>>> extends Base {
+import { type PermissionServiceProcedureBuilder, type ServiceProcedureBuilder, type ServiceProcedureContext } from "./base.procedure";
+export type { PermissionServiceProcedureBuilder, ServiceProcedure, ServiceProcedureAccessConfig, ServiceProcedureAccessEntitiesConfig, ServiceProcedureAccessStateConfig, ServiceProcedureArgs, ServiceProcedureBuilder, ServiceProcedureContext, ServiceProcedureContextFilteredInput, ServiceProcedureContextFilterScope, ServiceProcedureEntityStepName, ServiceProcedureInputMapper, } from "./base.procedure";
+export declare class BaseService<Repositories extends Record<string, Base>, Services extends Record<string, Base>, DefaultContext extends ServiceProcedureContext = ServiceProcedureContext> extends Base {
     repository: Repositories;
     service: Services;
     constructor(repository?: Repositories, service?: Services);
-    addUserFilter(value: string, query?: QueryInput, columnId?: string, method?: QueryFilter["method"]): QueryInput;
-    addContextFilter(ctx: Context, include?: {
+    addUserFilter(value: string, query?: undefined, columnId?: string, method?: QueryFilter["method"]): QueryInput;
+    addUserFilter<TQuery extends QueryInput>(value: string, query: TQuery, columnId?: string, method?: QueryFilter["method"]): TQuery;
+    protected procedure<TInput, TCtx extends ServiceProcedureContext = DefaultContext>(name: string): ServiceProcedureBuilder<TInput, TCtx, Repositories, Services>;
+    addContextFilter(actor: AuthenticatedActor, include?: {
         user?: boolean;
         organization?: boolean;
         team?: boolean;
-    }, query?: QueryInput, map?: Record<string, {
+    }, query?: undefined, map?: Record<string, {
         columnId: string;
         method: QueryFilter["method"];
     }>): QueryInput;
+    addContextFilter<TQuery extends QueryInput>(actor: AuthenticatedActor, include: {
+        user?: boolean;
+        organization?: boolean;
+        team?: boolean;
+    } | undefined, query: TQuery, map?: Record<string, {
+        columnId: string;
+        method: QueryFilter["method"];
+    }>): TQuery;
 }
-export declare class BasePermissionService<Repositories extends Record<string, BaseRepository<any, any, any> | BaseExternaRepository>, Services extends Record<string, BaseService<any, any>>> extends BaseService<Repositories, Services> {
+export declare class BasePermissionService<Repositories extends Record<string, Base>, Services extends Record<string, Base>, DefaultContext extends ServiceProcedureContext = ServiceProcedureContext> extends BaseService<Repositories, Services, DefaultContext> {
     grants: ResourceGrant[];
     constructor(repository: Repositories, service: Services, grants?: ResourceGrant[]);
-    accessGuard<T extends Entity>(ctx: {
-        session: Session;
-        user: User;
-    }, action: string, entities?: T | T[], grants?: ResourceActionGrant[]): ServerResult<true>;
-    accessGuardAsync<T extends Entity>(ctx: {
-        session: Session;
-        user: User;
-    }, action: string, getEntities: () => ServerResultAsync<T | T[] | undefined>, grants?: ResourceActionGrant[]): ServerResultAsync<true>;
-    checkPermission<T extends Entity>(ctx: {
-        session: Session;
-        user: User;
-    }, action: string, entities?: T | T[], grants?: ResourceActionGrant[]): boolean;
-    checkPermissionAsync<T extends Entity>(ctx: {
-        session: Session;
-        user: User;
-    }, action: string, getEntities: () => ServerResultAsync<T | T[] | undefined>, grants?: ResourceActionGrant[]): ServerResultAsync<boolean>;
+    accessGuard<T extends Entity>(actor: AuthenticatedActor, action: string, entities?: T | T[], grants?: ResourceActionGrant[]): ServerResult<true>;
+    accessGuardAsync<T extends Entity>(actor: AuthenticatedActor, action: string, getEntities: () => ServerResultAsync<T | T[] | undefined>, grants?: ResourceActionGrant[]): ServerResultAsync<true>;
+    protected procedure<TInput, TCtx extends ServiceProcedureContext = DefaultContext>(name: string): PermissionServiceProcedureBuilder<TInput, TCtx, Repositories, Services>;
+    checkPermission<T extends Entity>(actor: AuthenticatedActor, action: string, entities?: T | T[], grants?: ResourceActionGrant[]): boolean;
+    checkPermissionAsync<T extends Entity>(actor: AuthenticatedActor, action: string, getEntities: () => ServerResultAsync<T | T[] | undefined>, grants?: ResourceActionGrant[]): ServerResultAsync<boolean>;
 }

package/dist/src/modules/base/base.service.js

@@ -3,7 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BasePermissionService = exports.BaseService = void 0;
 const neverthrow_1 = require("neverthrow");
 const base_abstract_1 = require("./base.abstract");
+const base_actor_1 = require("./base.actor");
 const base_grants_1 = require("./base.grants");
+const base_procedure_1 = require("./base.procedure");
 class BaseService extends base_abstract_1.Base {
     repository;
     service;
@@ -25,7 +27,10 @@ class BaseService extends base_abstract_1.Base {
             ? { ...query, filters: [...(query?.filters ?? []), userFilter] }
             : { filters: [userFilter] };
     }
-    addContextFilter(ctx, include = {
+    procedure(name) {
+        return (0, base_procedure_1.createServiceProcedureBuilder)(this, { name, steps: [] });
+    }
+    addContextFilter(actor, include = {
         user: true,
         organization: false,
         team: false,
@@ -49,23 +54,29 @@ class BaseService extends base_abstract_1.Base {
                 columnId: map.userId.columnId,
                 type: "string",
                 method: map.userId.method,
-                value: ctx.user.id,
+                value: actor.userId,
             });
         }
         if (include.organization) {
+            if (!(0, base_actor_1.validateActor)(actor, "organization")) {
+                throw new Error("Organization-scoped context filter requires an organization actor");
+            }
             filters.push({
                 columnId: map.organizationId.columnId,
                 type: "string",
                 method: map.organizationId.method,
-                value: ctx.session.activeOrganizationId ?? "",
+                value: actor.organizationId,
             });
         }
         if (include.team) {
+            if (!(0, base_actor_1.validateActor)(actor, "team")) {
+                throw new Error("Team-scoped context filter requires a team actor");
+            }
             filters.push({
                 columnId: map.teamId.columnId,
                 type: "string",
                 method: map.teamId.method,
-                value: ctx.session.activeTeamId ?? "",
+                value: actor.teamId,
             });
         }
         return query ? { ...query, filters: [...(query?.filters ?? []), ...filters] } : { filters };
@@ -78,27 +89,30 @@ class BasePermissionService extends BaseService {
         super(repository, service);
         this.grants = grants;
     }
-    accessGuard(ctx, action, entities, grants) {
-        const hasPermission = this.checkPermission(ctx, action, entities, grants);
+    accessGuard(actor, action, entities, grants) {
+        const hasPermission = this.checkPermission(actor, action, entities, grants);
         if (!hasPermission)
             return this.error("FORBIDDEN");
         return (0, neverthrow_1.ok)(true);
     }
-    async accessGuardAsync(ctx, action, getEntities, grants) {
-        const hasPermission = await this.checkPermissionAsync(ctx, action, getEntities, grants);
+    async accessGuardAsync(actor, action, getEntities, grants) {
+        const hasPermission = await this.checkPermissionAsync(actor, action, getEntities, grants);
         if (hasPermission.isErr())
             return (0, neverthrow_1.err)(hasPermission.error);
         if (!hasPermission.value)
             return this.error("FORBIDDEN");
         return (0, neverthrow_1.ok)(true);
     }
-    checkPermission(ctx, action, entities, grants) {
+    procedure(name) {
+        return (0, base_procedure_1.createPermissionServiceProcedureBuilder)(this, { name, steps: [] });
+    }
+    checkPermission(actor, action, entities, grants) {
         const actionGrants = grants ?? this.grants.filter((grant) => grant.action === action);
-        return (0, base_grants_1.checkPermissionSync)(ctx, actionGrants, entities);
+        return (0, base_grants_1.checkPermissionSync)(actor, actionGrants, entities);
     }
-    async checkPermissionAsync(ctx, action, getEntities, grants) {
+    async checkPermissionAsync(actor, action, getEntities, grants) {
         const actionGrants = grants ?? this.grants.filter((grant) => grant.action === action);
-        const permission = await (0, base_grants_1.checkPermissionAsync)(ctx, actionGrants, getEntities);
+        const permission = await (0, base_grants_1.checkPermissionAsync)(actor, actionGrants, getEntities);
         if (permission.isErr())
             return this.error("INTERNAL_SERVER_ERROR", "Failed to check permission", {
                 cause: permission.error,

package/dist/src/modules/base/base.service.test.d.ts

@@ -0,0 +1 @@
+export {};