@tekki-forge/runtime-permissions 0.1.0

package/README.md

@@ -0,0 +1,5 @@
+# @tekki-forge/runtime-permissions
+
+Forge RBAC/ownership permission evaluation (shared by API and UI).
+
+Part of [Tekki Forge](https://www.npmjs.com/package/tekki-forge), which turns a `forge.config.ts` into a production-ready full-stack app. Apps created with `forge new` install this package for you; see the [tekki-forge](https://www.npmjs.com/package/tekki-forge) package for the documentation.

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import type { EntityIR, Operation, PermissionIR } from "@tekki-forge/compiler";
+/** The authenticated caller as seen by the authorization layer. */
+export interface Principal {
+    id: string;
+    roles: string[];
+    organizationId?: string | null;
+    /** Teams of the active organization the caller belongs to ("team" rules). */
+    teamIds?: string[];
+    /**
+     * Set for API keys: what the key may touch ("invoices:read", "invoices:write", "*:read", "*").
+     * Applied on top of the roles. Undefined for people signed in with a session (no restriction).
+     */
+    scopes?: string[];
+    /** Set when the caller is an API key (a service principal, not a user). */
+    apiKeyId?: string;
+}
+export type Decision = {
+    allowed: false;
+    reason: "unauthenticated" | "forbidden";
+} | {
+    allowed: true;
+    scope: "all";
+}
+/** Allowed only for records matching the owner/team/policy conditions. */
+ | {
+    allowed: true;
+    scope: "conditional";
+    owner: boolean;
+    team?: boolean;
+    policies: string[];
+};
+/**
+ * Merge the global user role (Better Auth admin plugin, comma separated) with the
+ * member role in the active organization. Organization owners count as admins.
+ */
+export declare function effectiveRoles(userRole: string | null | undefined, memberRole?: string | null, tenancy?: boolean): string[];
+export declare function evaluate(rule: PermissionIR, principal: Principal | null): Decision;
+/**
+ * Does an API key scope list allow `op` on the resource at `path`? Scopes are `<path>:read`, `<path>:write`
+ * (create, update, delete, actions, transitions, import), `<path>:*`, `*:read`, `*:write` and `*`.
+ */
+export declare function scopeAllows(scopes: readonly string[], path: string, op: Operation | "read" | "write"): boolean;
+export declare function authorize(entity: EntityIR, op: Operation, principal: Principal | null): Decision;
+export type PolicyCheck = (name: string, record: Record<string, unknown>) => boolean | Promise<boolean>;
+/** Foreign key of the team relation (`teamId`), if the entity has features.teams. */
+export declare function teamKey(entity: EntityIR): string | undefined;
+/** Decide whether `principal` may apply `decision` to one concrete record. */
+export declare function allowsRecord(entity: EntityIR, decision: Decision, principal: Principal | null, record: Record<string, unknown>, checkPolicy?: PolicyCheck): Promise<boolean>;
+/** UI helper: may the user *possibly* perform `op` (ignoring record-level conditions)? */
+export declare function can(entity: EntityIR, op: Operation, principal: Principal | null): boolean;
+/** UI helper: may the user perform `op` on this specific record (owner and team rules only)? */
+export declare function canOnRecord(entity: EntityIR, op: Operation, principal: Principal | null, record: Record<string, unknown>): boolean;
+/** UI helper: may the user change `field` of this record (entity update permission + field write permission)? */
+export declare function canWriteField(entity: EntityIR, field: string, principal: Principal | null, record: Record<string, unknown>): boolean;
+/** UI helper: does `rule` (e.g. a workflow transition permission) allow the user on this record? */
+export declare function ruleAllowsRecord(entity: EntityIR, rule: PermissionIR, principal: Principal | null, record: Record<string, unknown>): boolean;

package/dist/index.js

@@ -0,0 +1,110 @@
+/**
+ * Merge the global user role (Better Auth admin plugin, comma separated) with the
+ * member role in the active organization. Organization owners count as admins.
+ */
+export function effectiveRoles(userRole, memberRole, tenancy = false) {
+    const roles = new Set();
+    for (const r of (userRole ?? "").split(",").map((s) => s.trim()).filter(Boolean))
+        roles.add(r);
+    if (tenancy && memberRole) {
+        for (const r of memberRole.split(",").map((s) => s.trim()).filter(Boolean))
+            roles.add(r === "owner" ? "admin" : r);
+        roles.add("member");
+    }
+    if (!tenancy)
+        roles.add("user");
+    return [...roles];
+}
+export function evaluate(rule, principal) {
+    if (rule.public)
+        return { allowed: true, scope: "all" };
+    if (!principal)
+        return { allowed: false, reason: "unauthenticated" };
+    if (rule.authenticated || rule.roles.some((r) => principal.roles.includes(r)))
+        return { allowed: true, scope: "all" };
+    if (rule.owner || rule.team || rule.policies.length > 0)
+        return { allowed: true, scope: "conditional", owner: rule.owner, ...(rule.team ? { team: true } : {}), policies: rule.policies };
+    return { allowed: false, reason: "forbidden" };
+}
+/**
+ * Does an API key scope list allow `op` on the resource at `path`? Scopes are `<path>:read`, `<path>:write`
+ * (create, update, delete, actions, transitions, import), `<path>:*`, `*:read`, `*:write` and `*`.
+ */
+export function scopeAllows(scopes, path, op) {
+    const kind = op === "read" ? "read" : "write";
+    return scopes.some((s) => s === "*" || s === "*:*" || s === `*:${kind}` || s === `${path}:*` || s === `${path}:${kind}`);
+}
+export function authorize(entity, op, principal) {
+    if (principal?.scopes && !scopeAllows(principal.scopes, entity.path, op))
+        return { allowed: false, reason: "forbidden" };
+    return evaluate(entity.permissions[op], principal);
+}
+/** Foreign key of the owner relation (`ownerId`), if the entity has one. */
+function ownerKey(entity) {
+    return entity.ownerField ? entity.fields.find((f) => f.name === entity.ownerField)?.relation?.foreignKey : undefined;
+}
+/** Foreign key of the team relation (`teamId`), if the entity has features.teams. */
+export function teamKey(entity) {
+    return entity.teamField ? entity.fields.find((f) => f.name === entity.teamField)?.relation?.foreignKey : undefined;
+}
+/** Owner or team condition satisfied by this record (policies aside). */
+function matchesScope(entity, decision, principal, record) {
+    if (!principal)
+        return false;
+    if (decision.owner) {
+        const fk = ownerKey(entity);
+        if (fk && record[fk] === principal.id)
+            return true;
+    }
+    if (decision.team) {
+        const fk = teamKey(entity);
+        const team = fk ? record[fk] : undefined;
+        if (typeof team === "string" && (principal.teamIds ?? []).includes(team))
+            return true;
+    }
+    return false;
+}
+/** Decide whether `principal` may apply `decision` to one concrete record. */
+export async function allowsRecord(entity, decision, principal, record, checkPolicy) {
+    if (!decision.allowed)
+        return false;
+    if (decision.scope === "all")
+        return true;
+    if (matchesScope(entity, decision, principal, record))
+        return true;
+    for (const policy of decision.policies) {
+        if (checkPolicy && (await checkPolicy(policy, record)))
+            return true;
+    }
+    return false;
+}
+/** UI helper: may the user *possibly* perform `op` (ignoring record-level conditions)? */
+export function can(entity, op, principal) {
+    return authorize(entity, op, principal).allowed;
+}
+/** UI helper: may the user perform `op` on this specific record (owner and team rules only)? */
+export function canOnRecord(entity, op, principal, record) {
+    return decidesRecord(entity, authorize(entity, op, principal), principal, record);
+}
+/** UI helper: may the user change `field` of this record (entity update permission + field write permission)? */
+export function canWriteField(entity, field, principal, record) {
+    if (!canOnRecord(entity, "update", principal, record))
+        return false;
+    const rule = entity.fields.find((f) => f.name === field)?.access?.write;
+    return !rule || decidesRecord(entity, evaluate(rule, principal), principal, record);
+}
+/** UI helper: does `rule` (e.g. a workflow transition permission) allow the user on this record? */
+export function ruleAllowsRecord(entity, rule, principal, record) {
+    return decidesRecord(entity, evaluate(rule, principal), principal, record);
+}
+function decidesRecord(entity, decision, principal, record) {
+    if (!decision.allowed)
+        return false;
+    if (decision.scope === "all")
+        return true;
+    if (matchesScope(entity, decision, principal, record))
+        return true;
+    // Policies are only known server-side; optimistically show the control and let the API decide.
+    return decision.policies.length > 0;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwBA;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,QAAmC,EAAE,UAA0B,EAAE,OAAO,GAAG,KAAK;IAC7G,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC/F,IAAI,OAAO,IAAI,UAAU,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACnH,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACtB,CAAC;IACD,IAAI,CAAC,OAAO;QAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAChC,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAkB,EAAE,SAA2B;IACtE,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACxD,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACrE,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACtH,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;IAC1L,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAAyB,EAAE,IAAY,EAAE,EAAgC;IACnG,MAAM,IAAI,GAAG,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAC9C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC;AAC3H,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,MAAgB,EAAE,EAAa,EAAE,SAA2B;IACpF,IAAI,SAAS,EAAE,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACzH,OAAO,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;AACrD,CAAC;AAID,4EAA4E;AAC5E,SAAS,QAAQ,CAAC,MAAgB;IAChC,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;AACvH,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,OAAO,CAAC,MAAgB;IACtC,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;AACrH,CAAC;AAED,yEAAyE;AACzE,SAAS,YAAY,CAAC,MAAgB,EAAE,QAAqD,EAAE,SAA2B,EAAE,MAA+B;IACzJ,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7B,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,EAAE,IAAI,MAAM,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;IACrD,CAAC;IACD,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;QAClB,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAC3B,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;IACxF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAgB,EAChB,QAAkB,EAClB,SAA2B,EAC3B,MAA+B,EAC/B,WAAyB;IAEzB,IAAI,CAAC,QAAQ,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,QAAQ,CAAC,KAAK,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACnE,KAAK,MAAM,MAAM,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACvC,IAAI,WAAW,IAAI,CAAC,MAAM,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;IACtE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,GAAG,CAAC,MAAgB,EAAE,EAAa,EAAE,SAA2B;IAC9E,OAAO,SAAS,CAAC,MAAM,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC,OAAO,CAAC;AAClD,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,WAAW,CAAC,MAAgB,EAAE,EAAa,EAAE,SAA2B,EAAE,MAA+B;IACvH,OAAO,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AACpF,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,aAAa,CAAC,MAAgB,EAAE,KAAa,EAAE,SAA2B,EAAE,MAA+B;IACzH,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IACpE,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC;IACxE,OAAO,CAAC,IAAI,IAAI,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AACtF,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,gBAAgB,CAAC,MAAgB,EAAE,IAAkB,EAAE,SAA2B,EAAE,MAA+B;IACjI,OAAO,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AAC7E,CAAC;AAED,SAAS,aAAa,CAAC,MAAgB,EAAE,QAAkB,EAAE,SAA2B,EAAE,MAA+B;IACvH,IAAI,CAAC,QAAQ,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,QAAQ,CAAC,KAAK,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACnE,+FAA+F;IAC/F,OAAO,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AACtC,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@tekki-forge/runtime-permissions",
+  "version": "0.1.0",
+  "description": "Forge RBAC/ownership permission evaluation (shared by API and UI)",
+  "keywords": [
+    "code-generator",
+    "forge",
+    "full-stack",
+    "tekki-forge"
+  ],
+  "author": "Mahy KANE",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tekki-forge/compiler": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}