@starklabs/forge 1.3.25-cors.0 → 2.0.0

package/dist/core/BuiltinCollections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuiltinCollections.js","sourceRoot":"","sources":["../../src/core/BuiltinCollections.ts"],"names":[],"mappings":"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"}

package/dist/core/FeatureModule.d.ts

@@ -0,0 +1,35 @@
+import type { Request, Response, Router } from "express";
+import type { Collection, CollectionType } from "../types/Collection.js";
+import type { AccessLevel, Route } from "../types/Route.js";
+import { RouteContext } from "./RouteContext.js";
+import type { Services } from "./Services.js";
+/** A route handler. Returned promises are awaited by Express 5, so rejections reach the error handler. */
+export type HandlerFn = (req: Request, res: Response, ctx: RouteContext) => Promise<void>;
+/**
+ * One backend feature (crud, auth, account, admin, health).
+ *
+ * Subclass it, declare the handlers it offers, and register it with
+ * `forge.use(new MyModule(services))` to add your own collection types.
+ * The base class owns everything repetitive: route validation, the middleware
+ * chain (rate limit -> auth -> uploads -> handler) and error forwarding.
+ */
+export declare abstract class FeatureModule {
+    protected readonly services: Services;
+    abstract readonly type: CollectionType | (string & {});
+    constructor(services: Services);
+    /** Handler name -> implementation. */
+    protected abstract handlers(): Readonly<Record<string, HandlerFn>>;
+    /** Access level used when a route does not declare `auth`. */
+    protected defaultAuth(_route: Route): AccessLevel;
+    /** Whether the route should use the stricter brute-force limiter. */
+    protected isSensitive(_route: Route): boolean;
+    /** Called before routes are registered: register models, check configuration. */
+    prepare(_collection: Collection): void;
+    /** Checks that apply to every module: `roles`, and anything that needs the user's role to be loaded. */
+    private validateAccess;
+    /** Extra configuration checks. Return one message per problem. */
+    protected validateRoute(_collection: Collection, _route: Route): string[];
+    register(router: Router, collection: Collection): void;
+    private chain;
+}
+//# sourceMappingURL=FeatureModule.d.ts.map

package/dist/core/FeatureModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FeatureModule.d.ts","sourceRoot":"","sources":["../../src/core/FeatureModule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,OAAO,EAAkB,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEvF,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,0GAA0G;AAC1G,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAO1F;;;;;;;GAOG;AACH,8BAAsB,aAAa;IAGrB,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ;IAFjD,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAEvD,YAA+B,QAAQ,EAAE,QAAQ,EAAI;IAErD,sCAAsC;IACtC,SAAS,CAAC,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAEnE,8DAA8D;IAC9D,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,GAAG,WAAW,CAEhD;IAED,qEAAqE;IACrE,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,GAAG,OAAO,CAE5C;IAED,iFAAiF;IACjF,OAAO,CAAC,WAAW,EAAE,UAAU,GAAG,IAAI,CAAG;IAEzC,wGAAwG;IACxG,OAAO,CAAC,cAAc;IAsBtB,kEAAkE;IAClE,SAAS,CAAC,aAAa,CAAC,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,GAAG,MAAM,EAAE,CAExE;IAED,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,CAqDrD;IAED,OAAO,CAAC,KAAK;CAUd"}

package/dist/core/FeatureModule.js

@@ -0,0 +1,116 @@
+import { ConfigurationError, ErrorCode } from "../errors/index.js";
+import { RouteContext } from "./RouteContext.js";
+/** Handlers that read multipart form data. */
+const MULTIPART_HANDLERS = new Set(["create", "update", "addFile", "updateFile"]);
+/** Handlers that take `files` as configuration only (they identify a field but receive no upload). */
+const FILE_CONFIG_HANDLERS = new Set(["deleteFile"]);
+/**
+ * One backend feature (crud, auth, account, admin, health).
+ *
+ * Subclass it, declare the handlers it offers, and register it with
+ * `forge.use(new MyModule(services))` to add your own collection types.
+ * The base class owns everything repetitive: route validation, the middleware
+ * chain (rate limit -> auth -> uploads -> handler) and error forwarding.
+ */
+export class FeatureModule {
+    services;
+    constructor(services) {
+        this.services = services;
+    }
+    /** Access level used when a route does not declare `auth`. */
+    defaultAuth(_route) {
+        return "authenticated";
+    }
+    /** Whether the route should use the stricter brute-force limiter. */
+    isSensitive(_route) {
+        return false;
+    }
+    /** Called before routes are registered: register models, check configuration. */
+    prepare(_collection) { }
+    /** Checks that apply to every module: `roles`, and anything that needs the user's role to be loaded. */
+    validateAccess(route) {
+        const problems = [];
+        const { roles } = route;
+        if (roles !== undefined) {
+            if (!Array.isArray(roles) || roles.length === 0 || roles.some((r) => typeof r !== "string" || r === "")) {
+                problems.push("'roles' must be a non-empty array of role names, e.g. roles: [\"editor\", \"admin\"].");
+            }
+            else if (route.auth === "public") {
+                problems.push("'roles' cannot be used on a 'public' route: nobody is signed in, so nobody has a role. Use auth: 'authenticated'.");
+            }
+            else if (route.auth === "admin") {
+                problems.push("'roles' cannot be combined with auth 'admin' (that already means the roles in `adminRoles`). Use auth: 'authenticated' and list the roles.");
+            }
+        }
+        // A role is read from the user's database record on each request.
+        const needsRole = roles !== undefined || route.auth === "admin" || route.auth === "admin-or-owner";
+        if (needsRole && !this.services.config.auth.verifyAccessUser) {
+            problems.push("this route checks roles, which needs auth.verifyAccessUser: true (otherwise no role is ever loaded and every caller is refused).");
+        }
+        return problems;
+    }
+    /** Extra configuration checks. Return one message per problem. */
+    validateRoute(_collection, _route) {
+        return [];
+    }
+    register(router, collection) {
+        const handlers = this.handlers();
+        const problems = [];
+        const compiled = this.services.compiler.compileValidations(collection.validations, collection.route);
+        for (const original of collection.routes) {
+            const where = `${original.method.toUpperCase()} /${collection.route}${original.path}`;
+            const handler = handlers[original.handler];
+            if (!handler) {
+                problems.push(`${where}: handler '${original.handler}' is not available for collections of type '${collection.type}'. Available: ${Object.keys(handlers).join(", ")}.`);
+                continue;
+            }
+            const route = { ...original, auth: original.auth ?? this.defaultAuth(original) };
+            if (typeof route.validation === "string" && !compiled.has(route.validation)) {
+                problems.push(`${where}: validation '${route.validation}' is not defined in the collection's 'validations'.`);
+                continue;
+            }
+            if (route.validation === true) {
+                problems.push(`${where}: 'validation: true' is ambiguous - use the name of a validation group, or false.`);
+                continue;
+            }
+            if (route.files?.length && !MULTIPART_HANDLERS.has(route.handler) && !FILE_CONFIG_HANDLERS.has(route.handler)) {
+                problems.push(`${where}: 'files' is only supported on create, update, addFile, updateFile and deleteFile.`);
+            }
+            try {
+                this.services.actions.assertValid(route.actions?.before, `${where} → actions.before`);
+                this.services.actions.assertValid(route.actions?.after, `${where} → actions.after`);
+            }
+            catch (error) {
+                problems.push(error.message);
+            }
+            problems.push(...this.validateAccess(route).map((m) => `${where}: ${m}`));
+            problems.push(...this.validateRoute(collection, route).map((m) => `${where}: ${m}`));
+            const validator = typeof route.validation === "string" ? compiled.get(route.validation) : undefined;
+            const repository = collection.model && this.services.data.has(collection.model)
+                ? this.services.data.repository(collection.model)
+                : undefined;
+            const ctx = new RouteContext(this.services, collection, route, validator, repository);
+            router[route.method](route.path, ...this.chain(route, handler, ctx));
+        }
+        if (problems.length > 0) {
+            throw new ConfigurationError({
+                message: `Invalid '${collection.route}' collection:\n - ${problems.join("\n - ")}`,
+                code: ErrorCode.CONFIGURATION_ERROR,
+                details: { problems },
+            });
+        }
+    }
+    chain(route, handler, ctx) {
+        const chain = [];
+        if (this.isSensitive(route))
+            chain.push(this.services.limiters.auth());
+        chain.push(this.services.authenticator.require(route.auth ?? "authenticated", route.roles));
+        if (route.files?.length && MULTIPART_HANDLERS.has(route.handler))
+            chain.push(this.services.uploads.parser(route.files));
+        chain.push((req, res, next) => {
+            handler(req, res, ctx).catch(next);
+        });
+        return chain;
+    }
+}
+//# sourceMappingURL=FeatureModule.js.map

package/dist/core/FeatureModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FeatureModule.js","sourceRoot":"","sources":["../../src/core/FeatureModule.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGnE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAMjD,8CAA8C;AAC9C,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;AAClF,sGAAsG;AACtG,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,OAAgB,aAAa;IAGF,QAAQ;IAAvC,YAA+B,QAAkB;wBAAlB,QAAQ;IAAa,CAAC;IAKrD,8DAA8D;IACpD,WAAW,CAAC,MAAa;QACjC,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,qEAAqE;IAC3D,WAAW,CAAC,MAAa;QACjC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,iFAAiF;IACjF,OAAO,CAAC,WAAuB,IAAS,CAAC;IAEzC,wGAAwG;IAChG,cAAc,CAAC,KAAY;QACjC,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;QAExB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC;gBACxG,QAAQ,CAAC,IAAI,CAAC,uFAAuF,CAAC,CAAC;YACzG,CAAC;iBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACnC,QAAQ,CAAC,IAAI,CAAC,mHAAmH,CAAC,CAAC;YACrI,CAAC;iBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBAClC,QAAQ,CAAC,IAAI,CAAC,4IAA4I,CAAC,CAAC;YAC9J,CAAC;QACH,CAAC;QAED,kEAAkE;QAClE,MAAM,SAAS,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,CAAC;QACnG,IAAI,SAAS,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC7D,QAAQ,CAAC,IAAI,CAAC,kIAAkI,CAAC,CAAC;QACpJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,kEAAkE;IACxD,aAAa,CAAC,WAAuB,EAAE,MAAa;QAC5D,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,QAAQ,CAAC,MAAc,EAAE,UAAsB;QAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,kBAAkB,CAAC,UAAU,CAAC,WAAW,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;QAErG,KAAK,MAAM,QAAQ,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;YACzC,MAAM,KAAK,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,UAAU,CAAC,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;YACtF,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,cAAc,QAAQ,CAAC,OAAO,+CAA+C,UAAU,CAAC,IAAI,iBAAiB,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACxK,SAAS;YACX,CAAC;YAED,MAAM,KAAK,GAAU,EAAE,GAAG,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;YAExF,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC5E,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,iBAAiB,KAAK,CAAC,UAAU,qDAAqD,CAAC,CAAC;gBAC9G,SAAS;YACX,CAAC;YACD,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;gBAC9B,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,mFAAmF,CAAC,CAAC;gBAC3G,SAAS;YACX,CAAC;YACD,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC9G,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,oFAAoF,CAAC,CAAC;YAC9G,CAAC;YAED,IAAI,CAAC;gBACH,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,mBAAmB,CAAC,CAAC;gBACtF,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,KAAK,kBAAkB,CAAC,CAAC;YACtF,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,QAAQ,CAAC,IAAI,CAAE,KAAe,CAAC,OAAO,CAAC,CAAC;YAC1C,CAAC;YAED,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;YAC1E,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;YAErF,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACpG,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC;gBAC7E,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC;gBACjD,CAAC,CAAC,SAAS,CAAC;YACd,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;YAEtF,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;QACvE,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,kBAAkB,CAAC;gBAC3B,OAAO,EAAE,YAAY,UAAU,CAAC,KAAK,qBAAqB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE;gBAClF,IAAI,EAAE,SAAS,CAAC,mBAAmB;gBACnC,OAAO,EAAE,EAAE,QAAQ,EAAE;aACtB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,KAAY,EAAE,OAAkB,EAAE,GAAiB;QAC/D,MAAM,KAAK,GAAqB,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QACvE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,eAAe,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5F,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,IAAI,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QACxH,KAAK,CAAC,IAAI,CAAC,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;YAC7D,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;QACH,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/core/FieldTransformer.d.ts

@@ -0,0 +1,24 @@
+import type { CryptoVault } from "../security/CryptoVault.js";
+import type { PasswordHasher } from "../security/PasswordHasher.js";
+export interface FieldSpec {
+    name: string;
+    optional: boolean;
+}
+/** `"ssn?"` -> `{ name: "ssn", optional: true }`. */
+export declare const parseFieldSpec: (spec: string) => FieldSpec;
+/** Applies the per-route `encryptedFields`, `hashedFields` and `decryptedFields` rules. */
+export declare class FieldTransformer {
+    private readonly vault;
+    private readonly hasher;
+    constructor(vault: CryptoVault, hasher: PasswordHasher);
+    /** Replaces listed body fields with sealed values. Returns a new object. */
+    encrypt(body: Record<string, unknown>, specs: readonly string[] | undefined): Promise<Record<string, unknown>>;
+    /** Replaces listed body fields with Argon2id hashes. Returns a new object. */
+    hash(body: Record<string, unknown>, specs: readonly string[] | undefined): Promise<Record<string, unknown>>;
+    /** Reads plain values of sealed fields from a stored document. */
+    decrypt(doc: Record<string, unknown>, specs: readonly string[] | undefined): Promise<Record<string, string>>;
+    private transform;
+    /** Only a non-empty string can be sealed or hashed. A blank value from a client is a 422, not a crash. */
+    private text;
+}
+//# sourceMappingURL=FieldTransformer.d.ts.map

package/dist/core/FieldTransformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldTransformer.d.ts","sourceRoot":"","sources":["../../src/core/FieldTransformer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qDAAqD;AACrD,eAAO,MAAM,cAAc,SAAU,MAAM,KAAG,SACsD,CAAC;AAErG,2FAA2F;AAC3F,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFzB,YACmB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,cAAc,EACrC;IAEJ,4EAA4E;IACtE,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEnH;IAED,8EAA8E;IACxE,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEhH;IAED,kEAAkE;IAC5D,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAajH;YAEa,SAAS;IAqBvB,0GAA0G;IAC1G,OAAO,CAAC,IAAI;CASb"}

package/dist/core/FieldTransformer.js

@@ -0,0 +1,66 @@
+import { ErrorCode, ValidationError } from "../errors/index.js";
+import { isSealedValue } from "../security/CryptoVault.js";
+/** `"ssn?"` -> `{ name: "ssn", optional: true }`. */
+export const parseFieldSpec = (spec) => spec.endsWith("?") ? { name: spec.slice(0, -1), optional: true } : { name: spec, optional: false };
+/** Applies the per-route `encryptedFields`, `hashedFields` and `decryptedFields` rules. */
+export class FieldTransformer {
+    vault;
+    hasher;
+    constructor(vault, hasher) {
+        this.vault = vault;
+        this.hasher = hasher;
+    }
+    /** Replaces listed body fields with sealed values. Returns a new object. */
+    async encrypt(body, specs) {
+        return this.transform(body, specs, async (value, name) => this.vault.seal(this.text(value, name)));
+    }
+    /** Replaces listed body fields with Argon2id hashes. Returns a new object. */
+    async hash(body, specs) {
+        return this.transform(body, specs, async (value, name) => this.hasher.hash(this.text(value, name)));
+    }
+    /** Reads plain values of sealed fields from a stored document. */
+    async decrypt(doc, specs) {
+        const out = {};
+        for (const spec of specs ?? []) {
+            const { name, optional } = parseFieldSpec(spec);
+            const stored = doc[name];
+            if (stored === undefined || stored === null) {
+                if (optional)
+                    continue;
+                throw new ValidationError({ message: `'${name}' has no stored value to decrypt.`, code: ErrorCode.FIELD_MISSING });
+            }
+            if (!isSealedValue(stored))
+                continue;
+            out[name] = await this.vault.unseal(stored);
+        }
+        return out;
+    }
+    async transform(body, specs, apply) {
+        const result = { ...body };
+        for (const spec of specs ?? []) {
+            const { name, optional } = parseFieldSpec(spec);
+            if (!Object.hasOwn(body, name) || body[name] === undefined) {
+                if (optional)
+                    continue;
+                throw new ValidationError({
+                    message: `'${name}' is required.`,
+                    code: ErrorCode.FIELD_MISSING,
+                    hint: `Add '${name}' to the route's validation, or mark it optional as '${name}?'.`,
+                });
+            }
+            result[name] = await apply(body[name], name);
+        }
+        return result;
+    }
+    /** Only a non-empty string can be sealed or hashed. A blank value from a client is a 422, not a crash. */
+    text(value, name) {
+        if (typeof value !== "string") {
+            throw new ValidationError({ message: `'${name}' must be a string.`, code: ErrorCode.VALIDATION_FAILED });
+        }
+        if (value === "") {
+            throw new ValidationError({ message: `'${name}' must not be empty.`, code: ErrorCode.VALIDATION_FAILED });
+        }
+        return value;
+    }
+}
+//# sourceMappingURL=FieldTransformer.js.map

package/dist/core/FieldTransformer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldTransformer.js","sourceRoot":"","sources":["../../src/core/FieldTransformer.ts"],"names":[],"mappings":"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"}

package/dist/core/Forge.d.ts

@@ -0,0 +1,47 @@
+import { type Express } from "express";
+import type { Server } from "node:http";
+import { ForgeConfig } from "../config/ForgeConfig.js";
+import type { ForgeOptions } from "../config/ForgeOptions.js";
+import type { Collection } from "../types/Collection.js";
+import "../types/express.js";
+import type { FeatureModule } from "./FeatureModule.js";
+import type { Services } from "./Services.js";
+import { type ForgeDependencies } from "./ServiceFactory.js";
+/**
+ * The framework.
+ *
+ * ```ts
+ * const forge = new Forge({ jwtSecret, mongoDBURI, collections: [...] });
+ * await forge.start();
+ * ```
+ *
+ * `build()` returns the configured Express app without opening any
+ * connection, which is what you want in tests (`supertest`, `fetch`...).
+ */
+export declare class Forge {
+    readonly config: ForgeConfig;
+    readonly services: Services;
+    readonly app: Express;
+    private readonly modules;
+    private readonly allCollections;
+    private server;
+    private built;
+    private signalHandlers;
+    constructor(options?: ForgeOptions, dependencies?: ForgeDependencies);
+    /** The most recently created instance (used by the deprecated `startServer()` shortcut). */
+    static lastCreated: Forge | undefined;
+    /** Add a custom collection type, or replace a built-in module. */
+    use(module: FeatureModule): this;
+    get collections(): readonly Collection[];
+    /** Assembles the middleware stack and mounts every collection. Safe to call more than once. */
+    build(): Express;
+    start(): Promise<Server>;
+    /** Stops accepting connections, waits for in-flight requests, then closes the database. */
+    stop(): Promise<void>;
+    private mountCollections;
+    private moduleFor;
+    private corsOptions;
+    private allowedOrigins;
+    private installSignalHandlers;
+}
+//# sourceMappingURL=Forge.d.ts.map

package/dist/core/Forge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Forge.d.ts","sourceRoot":"","sources":["../../src/core/Forge.ts"],"names":[],"mappings":"AAGA,OAAgB,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAEhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAMxC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAS9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAI7E;;;;;;;;;;GAUG;AACH,qBAAa,KAAK;IAChB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAa;IAElC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAe;IAC9C,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,cAAc,CAA2C;IAEjE,YAAY,OAAO,GAAE,YAAiB,EAAE,YAAY,GAAE,iBAAsB,EAqB3E;IAED,4FAA4F;IAC5F,MAAM,CAAC,WAAW,EAAE,KAAK,GAAG,SAAS,CAAC;IAEtC,kEAAkE;IAClE,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAI/B;IAED,IAAI,WAAW,IAAI,SAAS,UAAU,EAAE,CAEvC;IAED,+FAA+F;IAC/F,KAAK,IAAI,OAAO,CA8Bf;IAEK,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAiB7B;IAED,2FAA2F;IACrF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAa1B;IAED,OAAO,CAAC,gBAAgB;IAwBxB,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,WAAW;IAQnB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,qBAAqB;CAgB9B"}

package/dist/core/Forge.js

@@ -0,0 +1,196 @@
+import compression from "compression";
+import cookieParser from "cookie-parser";
+import cors, {} from "cors";
+import express, {} from "express";
+import helmet from "helmet";
+import morgan from "morgan";
+import { AccountModule } from "../account/AccountModule.js";
+import { AdminModule } from "../admin/AdminModule.js";
+import { AuthModule } from "../auth/AuthModule.js";
+import { ForgeConfig } from "../config/ForgeConfig.js";
+import { CrudModule } from "../crud/CrudModule.js";
+import { ConfigurationError, ErrorCode } from "../errors/index.js";
+import { HealthModule } from "../health/HealthModule.js";
+import { ErrorHandler } from "../http/middleware/ErrorHandler.js";
+import { inputSanitizer } from "../http/middleware/InputSanitizer.js";
+import { originGuard } from "../http/middleware/OriginGuard.js";
+import { requestContext } from "../http/middleware/RequestContext.js";
+import { BannerPrinter } from "../terminal/BannerPrinter.js";
+import "../types/express.js";
+import { BuiltinCollections } from "./BuiltinCollections.js";
+import { ServiceFactory } from "./ServiceFactory.js";
+const ROUTE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9/_-]*$/;
+/**
+ * The framework.
+ *
+ * ```ts
+ * const forge = new Forge({ jwtSecret, mongoDBURI, collections: [...] });
+ * await forge.start();
+ * ```
+ *
+ * `build()` returns the configured Express app without opening any
+ * connection, which is what you want in tests (`supertest`, `fetch`...).
+ */
+export class Forge {
+    config;
+    services;
+    app = express();
+    modules = new Map();
+    allCollections;
+    server;
+    built = false;
+    signalHandlers = [];
+    constructor(options = {}, dependencies = {}) {
+        this.config = new ForgeConfig(options);
+        this.services = new ServiceFactory().create(this.config, dependencies);
+        for (const warning of this.config.warnings)
+            this.services.logger.warn(warning);
+        for (const module of [
+            new CrudModule(this.services),
+            new AuthModule(this.services),
+            new AccountModule(this.services),
+            new AdminModule(this.services),
+            new HealthModule(this.services),
+        ]) {
+            this.modules.set(module.type, module);
+        }
+        this.allCollections = [
+            ...new BuiltinCollections(this.config, this.services.compiler).build(),
+            ...this.config.collections,
+        ];
+        Forge.lastCreated = this;
+    }
+    /** The most recently created instance (used by the deprecated `startServer()` shortcut). */
+    static lastCreated;
+    /** Add a custom collection type, or replace a built-in module. */
+    use(module) {
+        if (this.built)
+            throw new ConfigurationError({ message: "Call use() before build() / start()." });
+        this.modules.set(module.type, module);
+        return this;
+    }
+    get collections() {
+        return this.allCollections;
+    }
+    /** Assembles the middleware stack and mounts every collection. Safe to call more than once. */
+    build() {
+        if (this.built)
+            return this.app;
+        const { app, config, services } = this;
+        app.disable("x-powered-by");
+        app.set("trust proxy", config.trustProxy);
+        const errors = new ErrorHandler(config, services.logger);
+        app.use(requestContext());
+        app.use(helmet());
+        app.use(cors(this.corsOptions()));
+        if (config.logRequests) {
+            app.use(morgan("tiny", { stream: { write: (line) => services.logger.info(line.trim()) } }));
+        }
+        app.use(compression());
+        app.use(services.limiters.global());
+        app.use(express.json({ limit: config.bodyLimit }));
+        app.use(express.urlencoded({ extended: false, limit: config.bodyLimit }));
+        app.use(cookieParser());
+        app.use(inputSanitizer());
+        app.use(originGuard(this.allowedOrigins()));
+        this.mountCollections();
+        app.use(errors.notFound());
+        app.use(errors.handler());
+        this.built = true;
+        return app;
+    }
+    async start() {
+        if (this.server)
+            return this.server;
+        this.build();
+        await this.services.data.connect();
+        // Express 5 hands listen errors (EADDRINUSE...) to this callback instead of throwing.
+        const server = await new Promise((resolve, reject) => {
+            const s = this.app.listen(this.config.port, (error) => (error ? reject(error) : resolve(s)));
+        });
+        this.server = server;
+        if (this.config.logRequests) {
+            new BannerPrinter(this.config).print(this.allCollections, "Connected", server.address().port);
+        }
+        if (!this.config.isTest)
+            this.installSignalHandlers();
+        return server;
+    }
+    /** Stops accepting connections, waits for in-flight requests, then closes the database. */
+    async stop() {
+        for (const [signal, handler] of this.signalHandlers)
+            process.off(signal, handler);
+        this.signalHandlers = [];
+        const server = this.server;
+        this.server = undefined;
+        if (server) {
+            await new Promise((resolve, reject) => {
+                server.close((error) => (error ? reject(error) : resolve()));
+                server.closeIdleConnections?.();
+            });
+        }
+        await this.services.data.disconnect();
+    }
+    mountCollections() {
+        const { config, services } = this;
+        const seen = new Set();
+        // Prepare every collection first (registers models), then mount routes.
+        for (const collection of this.allCollections) {
+            if (!ROUTE_SEGMENT.test(collection.route)) {
+                throw new ConfigurationError({
+                    message: `Invalid collection route '${collection.route}'. Use letters, digits, '-', '_' and '/'.`,
+                    code: ErrorCode.CONFIGURATION_ERROR,
+                });
+            }
+            this.moduleFor(collection).prepare(collection);
+        }
+        for (const collection of this.allCollections) {
+            const router = express.Router({ mergeParams: true });
+            this.moduleFor(collection).register(router, collection);
+            this.app.use(`${config.apiPrefix}/${collection.route}`, router);
+            seen.add(collection.route);
+        }
+        services.logger.debug(`Mounted ${seen.size} collections under ${config.apiPrefix}.`);
+    }
+    moduleFor(collection) {
+        const module = this.modules.get(collection.type);
+        if (!module) {
+            throw new ConfigurationError({
+                message: `Unknown collection type '${collection.type}' for '${collection.route}'.`,
+                hint: `Known types: ${[...this.modules.keys()].join(", ")}. Add your own with forge.use(new MyModule(forge.services)).`,
+            });
+        }
+        return module;
+    }
+    corsOptions() {
+        const { config } = this;
+        if (config.corsConfig)
+            return config.corsConfig;
+        const origins = config.frontendOrigins;
+        // Without configured front-end origins, cross-origin browser access is not allowed.
+        return origins.length > 0 ? { origin: [...origins], credentials: true } : { origin: false };
+    }
+    allowedOrigins() {
+        const configured = this.config.corsConfig?.origin;
+        const fromCors = Array.isArray(configured)
+            ? configured.filter((o) => typeof o === "string")
+            : typeof configured === "string" && configured !== "*"
+                ? [configured]
+                : [];
+        return [...this.config.frontendOrigins, ...fromCors];
+    }
+    installSignalHandlers() {
+        for (const signal of ["SIGINT", "SIGTERM"]) {
+            const handler = () => {
+                this.services.logger.info(`${signal} received: shutting down.`);
+                this.stop().then(() => process.exit(0), (error) => {
+                    this.services.logger.error("Shutdown failed.", { error: String(error) });
+                    process.exit(1);
+                });
+            };
+            process.once(signal, handler);
+            this.signalHandlers.push([signal, handler]);
+        }
+    }
+}
+//# sourceMappingURL=Forge.js.map

package/dist/core/Forge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Forge.js","sourceRoot":"","sources":["../../src/core/Forge.ts"],"names":[],"mappings":"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"}

package/dist/core/Pagination.d.ts

@@ -0,0 +1,19 @@
+import type { Request } from "express";
+import type { ForgeConfig } from "../config/ForgeConfig.js";
+import type { PageMeta } from "../http/ResponseWriter.js";
+export interface PageRequest {
+    page: number;
+    limit: number;
+    skip: number;
+    sort: Record<string, 1 | -1>;
+}
+/** Parses `?page=&limit=&sort=` safely (bounded size, whitelisted sort fields). */
+export declare class Pagination {
+    private readonly config;
+    constructor(config: ForgeConfig);
+    parse(req: Request, sortable: readonly string[]): PageRequest;
+    meta(request: PageRequest, total: number): PageMeta;
+    private positiveInt;
+    private parseSort;
+}
+//# sourceMappingURL=Pagination.d.ts.map

package/dist/core/Pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pagination.d.ts","sourceRoot":"","sources":["../../src/core/Pagination.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAC9B;AAKD,mFAAmF;AACnF,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAnC,YAA6B,MAAM,EAAE,WAAW,EAAI;IAEpD,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CAK5D;IAED,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAElD;IAED,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,SAAS;CAoBlB"}

package/dist/core/Pagination.js

@@ -0,0 +1,51 @@
+import { BadRequestError, ErrorCode } from "../errors/index.js";
+const SORTABLE_ALWAYS = ["_id", "createdAt", "updatedAt"];
+const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Parses `?page=&limit=&sort=` safely (bounded size, whitelisted sort fields). */
+export class Pagination {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    parse(req, sortable) {
+        const { defaultSize, maxSize } = this.config.pagination;
+        const page = this.positiveInt(req.query.page, "page", 1);
+        const limit = Math.min(this.positiveInt(req.query.limit, "limit", defaultSize), maxSize);
+        return { page, limit, skip: (page - 1) * limit, sort: this.parseSort(req.query.sort, sortable) };
+    }
+    meta(request, total) {
+        return { page: request.page, limit: request.limit, total, pages: Math.max(1, Math.ceil(total / request.limit)) };
+    }
+    positiveInt(raw, name, fallback) {
+        if (raw === undefined || raw === "")
+            return fallback;
+        // Digits only: rejects "2e3", "0x10", "1.5", "-1" and arrays/objects from `?limit[]=`.
+        const value = typeof raw === "string" && /^\d{1,7}$/.test(raw) ? Number(raw) : NaN;
+        if (!Number.isInteger(value) || value < 1 || value > 1_000_000) {
+            throw new BadRequestError({ message: `'${name}' must be a positive integer.`, code: ErrorCode.INVALID_QUERY });
+        }
+        return value;
+    }
+    parseSort(raw, sortable) {
+        if (raw === undefined || raw === "")
+            return { createdAt: -1, _id: -1 };
+        if (typeof raw !== "string")
+            throw new BadRequestError({ message: "'sort' must be a string.", code: ErrorCode.INVALID_QUERY });
+        const allowed = new Set([...SORTABLE_ALWAYS, ...sortable]);
+        const sort = {};
+        for (const part of raw.split(",").slice(0, 5)) {
+            const direction = part.startsWith("-") ? -1 : 1;
+            const field = part.replace(/^[-+]/, "");
+            if (!FIELD_NAME.test(field) || !allowed.has(field)) {
+                throw new BadRequestError({
+                    message: `Cannot sort by '${field}'.`,
+                    code: ErrorCode.INVALID_QUERY,
+                    hint: `Sortable fields: ${[...allowed].join(", ")}.`,
+                });
+            }
+            sort[field] = direction;
+        }
+        return sort;
+    }
+}
+//# sourceMappingURL=Pagination.js.map