@webtypen/webframez-core 0.3.108 → 0.3.110

package/README.md

@@ -23,6 +23,24 @@ This README reflects the current API in this repository and focuses on:
 npm i @webtypen/webframez-core
 ```
 
+## Optional server extensions
+
+`WebApplication.boot({ extensions: [...] })` accepts `WebServerExtension` instances.
+Their synchronous `attach({ server, basename, kernel, modulesLoader })` method runs
+after routes are registered and before the HTTP server listens. This allows optional
+transports such as `@webtypen/webframez-sockets` to share the application's port
+without adding their dependencies to Core.
+
+Call `await application.close()` to release extensions in reverse order before
+closing HTTP. Cleanup continues if an extension fails, and the returned promise
+reports the failure. Partially attached extensions are also closed after startup
+failure. Application instances boot once; create a new instance after shutdown.
+`port: 0` selects an ephemeral port, and `onBoot(port)` receives the actual port.
+
+Socket integrations can report `socket.event.start`, `socket.event.end` and
+`socket.event.error` through `WebframezHooks` using the same operation context as
+HTTP and queue execution.
+
 ## Authentication
 
 New integrations can use `SessionAuth` for hashed, revocable device sessions,

package/dist/Auth/AuthResourceAccess.d.ts

@@ -0,0 +1,30 @@
+import { Model } from "../Database/Model";
+import { AuthMembershipCondition } from "./AuthMembership";
+export type AuthResourceGrants = {
+    all?: boolean;
+    own?: boolean;
+    assigned?: boolean;
+};
+export type AuthResourceAccessOptions = {
+    model: typeof Model;
+    /** Immutable creator reference on the resource. */
+    ownerField?: string;
+    /** Array of explicitly assigned user references (also supports paths such as members.user). */
+    membersField?: string;
+    userKey?: string;
+    userConditions?: readonly AuthMembershipCondition[];
+    resourceConditions?: readonly AuthMembershipCondition[];
+};
+/** Document-query authorization for all, owned and explicitly assigned resources.
+ * Callers must supply authenticated, server-loaded users and server-derived grants.
+ * Use the same filter before pagination/counts/exports and for individual mutations.
+ */
+export declare class AuthResourceAccess {
+    private readonly options;
+    private readonly primaryKey;
+    private readonly userKey;
+    constructor(options: AuthResourceAccessOptions);
+    filter(user: Model, grants: AuthResourceGrants): Record<string, any>;
+    /** The returned model is freshly read; missing/invalid IDs never create an unbounded query. */
+    find<TResource extends Model = Model>(user: Model, id: unknown, grants: AuthResourceGrants): Promise<TResource | null>;
+}

package/dist/Auth/AuthResourceAccess.js

@@ -0,0 +1,70 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthResourceAccess = void 0;
+const Model_1 = require("../Database/Model");
+/** Document-query authorization for all, owned and explicitly assigned resources.
+ * Callers must supply authenticated, server-loaded users and server-derived grants.
+ * Use the same filter before pagination/counts/exports and for individual mutations.
+ */
+class AuthResourceAccess {
+    constructor(options) {
+        this.options = options;
+        this.primaryKey = new options.model().__primaryKey;
+        this.userKey = options.userKey || "_id";
+        for (const field of [this.primaryKey, this.userKey, options.ownerField, options.membersField,
+            ...(options.userConditions || []).map(condition => condition.field),
+            ...(options.resourceConditions || []).map(condition => condition.field)]) {
+            if (field !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(field))
+                throw new Error("Invalid resource access field.");
+        }
+        if (options.ownerField && options.ownerField === options.membersField)
+            throw new Error("Owner and membership fields must be separate.");
+    }
+    filter(user, grants) {
+        const deny = { [this.primaryKey]: { $in: [] } };
+        if (!(user instanceof Model_1.Model))
+            return deny;
+        const userId = user[this.userKey];
+        if (userId === null || userId === undefined || userId === "")
+            return deny;
+        if (!(this.options.userConditions || []).every(condition => condition.operator === "="
+            ? user[condition.field] === condition.value : user[condition.field] !== condition.value))
+            return deny;
+        const alternatives = [];
+        if (grants.own === true && this.options.ownerField)
+            alternatives.push({ [this.options.ownerField]: { $eq: userId } });
+        if (grants.assigned === true && this.options.membersField)
+            alternatives.push({ [this.options.membersField]: { $eq: userId } });
+        if (grants.all !== true && !alternatives.length)
+            return deny;
+        const conditions = (this.options.resourceConditions || []).map(condition => ({
+            [condition.field]: { [condition.operator === "=" ? "$eq" : "$ne"]: condition.value },
+        }));
+        if (grants.all !== true)
+            conditions.push({ $or: alternatives });
+        return conditions.length ? { $and: conditions } : {};
+    }
+    /** The returned model is freshly read; missing/invalid IDs never create an unbounded query. */
+    find(user, id, grants) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (id === null || id === undefined || id === "" || !(user instanceof Model_1.Model))
+                return null;
+            const resourceId = yield this.options.model.objectId(id, { noExceptions: true });
+            if (resourceId === null || resourceId === undefined)
+                return null;
+            return yield this.options.model.where("$and", "=", [
+                { [this.primaryKey]: { $eq: resourceId } }, this.filter(user, grants),
+            ]).first();
+        });
+    }
+}
+exports.AuthResourceAccess = AuthResourceAccess;

package/dist/Auth/index.d.ts

@@ -9,3 +9,4 @@ export * from "./Auth";
 export * from "./PasswordReset";
 export * from "./AuthMembership";
 export * from "./AuthHandoff";
+export * from "./AuthResourceAccess";

package/dist/Auth/index.js

@@ -25,3 +25,4 @@ __exportStar(require("./Auth"), exports);
 __exportStar(require("./PasswordReset"), exports);
 __exportStar(require("./AuthMembership"), exports);
 __exportStar(require("./AuthHandoff"), exports);
+__exportStar(require("./AuthResourceAccess"), exports);

package/dist/Hooks/WebframezHooks.d.ts

@@ -1,4 +1,4 @@
-export type WebframezHookOperation = "http.request" | "route.handler" | "console.command" | "queue.job" | "queue.worker" | "app.boot" | "lambda.invoke";
+export type WebframezHookOperation = "http.request" | "route.handler" | "console.command" | "queue.job" | "queue.worker" | "app.boot" | "lambda.invoke" | "socket.event";
 export type WebframezHookPhase = "start" | "end" | "error";
 export type WebframezHookEventName = `${WebframezHookOperation}.${WebframezHookPhase}`;
 export type WebframezHookAttributeValue = string | number | boolean | null;

package/dist/Http/WebServerExtension.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="node" />
+import type { Server } from "http";
+import type { ModulesLoader } from "../Modules/ModulesLoader";
+export type WebServerExtensionContext = {
+    server: Server;
+    basename: string | null;
+    kernel: any;
+    modulesLoader: ModulesLoader;
+};
+/** Optional transports attach before listen; close must release their connections. */
+export interface WebServerExtension {
+    attach(context: WebServerExtensionContext): void;
+    close(): void | Promise<void>;
+}

package/dist/Http/WebServerExtension.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/WebApplication.d.ts

@@ -4,6 +4,10 @@ import { ModulesLoader } from "./Modules/ModulesLoader";
 export declare class WebApplication {
     private server;
     modulesLoader: ModulesLoader | null;
+    private serverExtensions;
+    private closing;
+    /** Close optional transports before waiting for the HTTP server to stop. */
+    close(): Promise<void>;
     /**
      * Init the routes and start the http-server
      */

package/dist/WebApplication.js

@@ -30,6 +30,35 @@ const NotificationService_1 = require("./Notifications/NotificationService");
 class WebApplication {
     constructor() {
         this.modulesLoader = null;
+        this.serverExtensions = [];
+        this.closing = null;
+    }
+    /** Close optional transports before waiting for the HTTP server to stop. */
+    close() {
+        if (this.closing)
+            return this.closing;
+        this.closing = (() => __awaiter(this, void 0, void 0, function* () {
+            let failure;
+            for (const extension of this.serverExtensions.splice(0).reverse()) {
+                try {
+                    yield extension.close();
+                }
+                catch (error) {
+                    failure = failure || error;
+                }
+            }
+            if (this.server) {
+                yield new Promise((resolve, reject) => this.server.close((error) => {
+                    if (error && error.code !== "ERR_SERVER_NOT_RUNNING")
+                        reject(error);
+                    else
+                        resolve();
+                }));
+            }
+            if (failure)
+                throw failure;
+        }))();
+        return this.closing;
     }
     /**
      * Init the routes and start the http-server
@@ -46,6 +75,12 @@ class WebApplication {
         });
     }
     bootScoped(options) {
+        if (this.server || this.closing)
+            throw new Error("WebApplication instances can only boot once.");
+        const extensions = (options === null || options === void 0 ? void 0 : options.extensions) || [];
+        if (!Array.isArray(extensions) || extensions.some(extension => !extension || typeof extension.attach !== "function" || typeof extension.close !== "function")) {
+            throw new Error("WebApplication extensions must implement attach(context) and close().");
+        }
         const bootOperationId = WebframezHooks_1.WebframezHooks.createOperationId("app");
         void WebframezHooks_1.WebframezHooks.emit("app.boot.start", {
             operationId: bootOperationId,
@@ -99,7 +134,7 @@ class WebApplication {
         if (options.jobs && options.jobs.length > 0) {
             QueueJobsRegisty_1.QueueJobsRegisty.registerJob(options.jobs);
         }
-        const port = options && options.port ? options.port : 3000;
+        const port = (options === null || options === void 0 ? void 0 : options.port) !== undefined ? options.port : 3000;
         this.server = http_1.default.createServer((req, res) => ErrorHandler_1.ErrorHandler.withContext({ applicationType: "WebApplication", scope: "controller", operationId: WebframezHooks_1.WebframezHooks.createOperationId("http") }, () => __awaiter(this, void 0, void 0, function* () {
             try {
                 const handled = yield HttpKernelHandlerRegistry_1.HttpKernelHandlerRegistry.handle({
@@ -131,6 +166,7 @@ class WebApplication {
             }
         })));
         this.server.on("error", (error) => {
+            void this.close().catch(closeError => ErrorHandler_1.ErrorHandler.report(closeError, { source: "http.server.close" }));
             void ErrorHandler_1.ErrorHandler.report(error, { applicationType: "WebApplication", scope: "boot", source: "http.server" });
             void WebframezHooks_1.WebframezHooks.emit("app.boot.error", {
                 operationId: bootOperationId,
@@ -149,26 +185,45 @@ class WebApplication {
         // this.server.on("close", () => {
         //     void SigNozTelemetry.shutdown();
         // });
-        this.server.listen(port, () => {
-            void WebframezHooks_1.WebframezHooks.emit("app.boot.end", {
-                operationId: bootOperationId,
-                name: "web",
-                status: "ok",
-                attributes: {
-                    "server.port": port,
-                    "webframez.mode": options && options.mode ? options.mode : "web",
-                },
-            });
-            const runtimeConsole = typeof globalThis !== "undefined" ? globalThis.console : undefined;
-            if (runtimeConsole && typeof runtimeConsole.log === "function") {
-                runtimeConsole.log("Server started and listening on port " +
-                    port +
-                    (Router_1.Router.basename ? " (Basename: " + Router_1.Router.basename + ")" : ""));
-            }
-            if (options && options.onBoot) {
-                options.onBoot(port);
+        try {
+            for (const extension of extensions) {
+                this.serverExtensions.push(extension);
+                extension.attach({ server: this.server, basename: Router_1.Router.basename,
+                    kernel: (options === null || options === void 0 ? void 0 : options.kernel) || null, modulesLoader: this.modulesLoader });
             }
-        });
+        }
+        catch (error) {
+            void this.close().catch(closeError => ErrorHandler_1.ErrorHandler.report(closeError, { source: "http.server.close" }));
+            throw error;
+        }
+        try {
+            this.server.listen(port, () => {
+                const address = this.server.address();
+                const listeningPort = address && typeof address === "object" ? address.port : port;
+                void WebframezHooks_1.WebframezHooks.emit("app.boot.end", {
+                    operationId: bootOperationId,
+                    name: "web",
+                    status: "ok",
+                    attributes: {
+                        "server.port": listeningPort,
+                        "webframez.mode": options && options.mode ? options.mode : "web",
+                    },
+                });
+                const runtimeConsole = typeof globalThis !== "undefined" ? globalThis.console : undefined;
+                if (runtimeConsole && typeof runtimeConsole.log === "function") {
+                    runtimeConsole.log("Server started and listening on port " +
+                        listeningPort +
+                        (Router_1.Router.basename ? " (Basename: " + Router_1.Router.basename + ")" : ""));
+                }
+                if (options && options.onBoot) {
+                    options.onBoot(listeningPort);
+                }
+            });
+        }
+        catch (error) {
+            void this.close().catch(closeError => ErrorHandler_1.ErrorHandler.report(closeError, { source: "http.server.close" }));
+            throw error;
+        }
         return this.server;
     }
 }

package/dist/index.d.ts

@@ -61,6 +61,7 @@ export * from "./Api/ApiScopeRegistry";
 export * from "./Ai/AiTypes";
 export * from "./Mcp/McpTypes";
 export * from "./Http/HttpKernelHandlerRegistry";
+export * from "./Http/WebServerExtension";
 export * from "./Auth";
 export * from "./Notifications/Notification";
 export * from "./Notifications/BaseNotificationsController";

package/dist/index.js

@@ -78,6 +78,7 @@ __exportStar(require("./Api/ApiScopeRegistry"), exports);
 __exportStar(require("./Ai/AiTypes"), exports);
 __exportStar(require("./Mcp/McpTypes"), exports);
 __exportStar(require("./Http/HttpKernelHandlerRegistry"), exports);
+__exportStar(require("./Http/WebServerExtension"), exports);
 __exportStar(require("./Auth"), exports);
 __exportStar(require("./Notifications/Notification"), exports);
 __exportStar(require("./Notifications/BaseNotificationsController"), exports);

package/docs/authentication.md

@@ -584,3 +584,43 @@ checked by `isSessionAllowed` on every authentication/refresh. To enforce logout
 request, do not cache positive introspection results. This requires one authority round trip
 per check and fails closed when the authority is unavailable. No browser push is implied;
 clients detect logout when making their next authenticated request.
+
+
+## Owned and assigned resource scopes
+
+`AuthResourceAccess` composes document filters for global, creator-owned and
+explicitly assigned records. It complements `AuthMembership` (separate membership
+models) with embedded administrator assignments and list/detail query parity.
+
+```ts
+const access = new AuthResourceAccess({
+    model: Project,
+    ownerField: "created_by",
+    membersField: "administrators.user",
+    userConditions: [{ field: "is_active", operator: "!=", value: false }],
+    resourceConditions: [{ field: "is_deleted", operator: "!=", value: true }],
+});
+const grants = {
+    all: user.can("projects.read"),
+    own: user.can("projects.own.read"),
+    assigned: user.can("projects.assigned.read"),
+};
+const rows = await Project.aggregate([{ $match: access.filter(user, grants) }]);
+const project = await access.find(user, req.params.id, grants);
+if (!project) return res.status(403).send({ code: "forbidden" });
+```
+
+Grants are server-derived booleans; own and assigned are a union. Missing identity,
+missing references and invalid resource IDs fail closed. `all` still respects the
+configured status conditions. `filter` must run before pagination, counts, exports,
+selectors and lookups that could expose other records. `find` performs a fresh
+lookup, so revoked assignments take effect on the next request. Neither method
+caches authorization or authenticates a supplied model. User identity fields are
+scalar model fields; resource mappings may use document paths.
+
+Set creator references server-side on creation and keep them immutable. Protect
+assignment changes separately from scoped editing, and never derive grants from
+submitted form values. Use the filter in conditional writes where concurrent
+revocation must also constrain an already running operation. Existing records
+without a creator or assignment gain no scoped access. Scope membership itself
+does not grant another application's login or tenant membership.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtypen/webframez-core",
-    "version": "0.3.108",
+    "version": "0.3.110",
     "description": "The core package of the typescript based webframez (web-framework) by webtypen.de",
     "homepage": "https://webtypen.de/",
     "license": "MIT",