@webtypen/webframez-core 0.3.108 → 0.3.109

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/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.109",
     "description": "The core package of the typescript based webframez (web-framework) by webtypen.de",
     "homepage": "https://webtypen.de/",
     "license": "MIT",