@nebutra/permissions 0.1.3 → 2.0.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { createPermissions, getPermissions, PermissionsManager, resetPermissions, } from "./factory";
 export { attachPermissionContext, type RequirePermissionOptions, requirePermission, } from "./middleware";
+export { canPlatform, isPlatformStaffRole, normalizePlatformStaffRole, PLATFORM_STAFF_ROLES, type PlatformAbility, type PlatformAction, type PlatformResource, type PlatformStaffRole, platformAbilityFor, platformRoleHierarchy, } from "./platform";
 export { buildAbilityFor, CASLProvider, createCASLProvider, createPrismaAbility, getPrismaQuery, } from "./providers/casl";
 export { createOpenFGAProvider, type OpenFGACheckRequest, type OpenFGACheckResponse, type OpenFGAListObjectsRequest, OpenFGAProvider, type OpenFGAProviderConfig, type OpenFGATuple, type OpenFGAWriteRequest, } from "./providers/openfga";
 export { Can, Cannot, type CannotProps, type CanProps, PermissionProvider as PermissionProviderComponent, type PermissionProviderProps, type UsePermissionOptions, usePermission, usePermissionContext, } from "./react";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,uBAAuB,EACvB,KAAK,wBAAwB,EAC7B,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,GAAG,EACH,MAAM,EACN,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,kBAAkB,IAAI,2BAA2B,EACjD,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,aAAa,EACb,oBAAoB,GACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,MAAM,EACX,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,IAAI,EACT,KAAK,cAAc,GACpB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,uBAAuB,EACvB,KAAK,wBAAwB,EAC7B,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,GAAG,EACH,MAAM,EACN,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,kBAAkB,IAAI,2BAA2B,EACjD,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,aAAa,EACb,oBAAoB,GACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,MAAM,EACX,cAAc,EACd,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,IAAI,EACT,KAAK,cAAc,GACpB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export { createPermissions, getPermissions, PermissionsManager, resetPermissions, } from "./factory";
 export { attachPermissionContext, requirePermission, } from "./middleware";
+export { canPlatform, isPlatformStaffRole, normalizePlatformStaffRole, PLATFORM_STAFF_ROLES, platformAbilityFor, platformRoleHierarchy, } from "./platform";
 export { buildAbilityFor, CASLProvider, createCASLProvider, createPrismaAbility, getPrismaQuery, } from "./providers/casl";
 export { createOpenFGAProvider, OpenFGAProvider, } from "./providers/openfga";
 export { Can, Cannot, PermissionProvider as PermissionProviderComponent, usePermission, usePermissionContext, } from "./react";

package/dist/platform.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Platform staff authorization — for the ecosystem control plane (the `admin`
+ * host in the brand domain SSOT).
+ *
+ * Deliberately separate from `DEFAULT_ROLES` in `./roles`. Tenant roles
+ * (owner / admin / member / viewer / billing_admin) answer "what may this
+ * member do inside their workspace"; platform staff roles answer "what may a
+ * platform operator do ACROSS every tenant". Merging the two maps is how a
+ * staff capability leaks into a tenant session, so they never share a registry:
+ * `platformAbilityFor` builds its ability from scratch instead of going through
+ * `CASLProvider`, which always seeds itself with the tenant roles.
+ *
+ * See docs/plans/2026-07-28-nebutra-admin-control-plane-design.md §6.
+ */
+import { type Ability } from "@casl/ability";
+/** Ordered least → most senior. Seniority is linear and inclusive. */
+export declare const PLATFORM_STAFF_ROLES: readonly ["platform_readonly", "platform_support", "platform_operator", "platform_owner"];
+export type PlatformStaffRole = (typeof PLATFORM_STAFF_ROLES)[number];
+export type PlatformAction = "read" | "impersonate" | "invite" | "suspend" | "unsuspend" | "replay" | "override" | "grant" | "revoke";
+export type PlatformResource = "Fleet" | "Tenant" | "RouterSupply" | "ForgeJob" | "FeatureFlag" | "PlatformStaff" | "AuditLog";
+export type PlatformAbility = Ability<[PlatformAction, PlatformResource]>;
+export declare function isPlatformStaffRole(role: string): role is PlatformStaffRole;
+/**
+ * Accepts either the TypeScript role string (`platform_owner`) or the Prisma
+ * enum spelling (`PLATFORM_OWNER`). Returns null for anything unrecognized —
+ * an unknown role must degrade to "no access", never to a default.
+ */
+export declare function normalizePlatformStaffRole(role: string | null | undefined): PlatformStaffRole | null;
+/** Roles at or below `role` in seniority, including `role` itself. */
+export declare function platformRoleHierarchy(role: PlatformStaffRole): PlatformStaffRole[];
+export declare function platformAbilityFor(role: PlatformStaffRole): PlatformAbility;
+/**
+ * Convenience guard for route handlers. Takes the raw role so callers can pass
+ * whatever came out of the `PlatformStaff` row without pre-validating it; an
+ * unknown or revoked role simply cannot do anything.
+ */
+export declare function canPlatform(role: string | null | undefined, action: PlatformAction, resource: PlatformResource): boolean;
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAsC,MAAM,eAAe,CAAC;AAEjF,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,2FAKvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,aAAa,GACb,QAAQ,GACR,SAAS,GACT,WAAW,GACX,QAAQ,GACR,UAAU,GACV,OAAO,GACP,QAAQ,CAAC;AAEb,MAAM,MAAM,gBAAgB,GACxB,OAAO,GACP,QAAQ,GACR,cAAc,GACd,UAAU,GACV,aAAa,GACb,eAAe,GACf,UAAU,CAAC;AAEf,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAmC1E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,iBAAiB,CAE3E;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B,iBAAiB,GAAG,IAAI,CAI1B;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,EAAE,CAGlF;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,eAAe,CAU3E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAIT"}

package/dist/platform.js

@@ -0,0 +1,92 @@
+/**
+ * Platform staff authorization — for the ecosystem control plane (the `admin`
+ * host in the brand domain SSOT).
+ *
+ * Deliberately separate from `DEFAULT_ROLES` in `./roles`. Tenant roles
+ * (owner / admin / member / viewer / billing_admin) answer "what may this
+ * member do inside their workspace"; platform staff roles answer "what may a
+ * platform operator do ACROSS every tenant". Merging the two maps is how a
+ * staff capability leaks into a tenant session, so they never share a registry:
+ * `platformAbilityFor` builds its ability from scratch instead of going through
+ * `CASLProvider`, which always seeds itself with the tenant roles.
+ *
+ * See docs/plans/2026-07-28-nebutra-admin-control-plane-design.md §6.
+ */
+import { AbilityBuilder, createMongoAbility } from "@casl/ability";
+/** Ordered least → most senior. Seniority is linear and inclusive. */
+export const PLATFORM_STAFF_ROLES = [
+    "platform_readonly",
+    "platform_support",
+    "platform_operator",
+    "platform_owner",
+];
+const ALL_RESOURCES = [
+    "Fleet",
+    "Tenant",
+    "RouterSupply",
+    "ForgeJob",
+    "FeatureFlag",
+    "PlatformStaff",
+    "AuditLog",
+];
+/**
+ * Capabilities a role adds on top of everything the role below it already has.
+ * `platform_readonly` is the floor: read everything, change nothing.
+ */
+const CAPABILITIES = {
+    platform_readonly: ALL_RESOURCES.map((resource) => ["read", resource]),
+    platform_support: [
+        ["impersonate", "Tenant"],
+        ["invite", "Tenant"],
+    ],
+    platform_operator: [
+        ["suspend", "Tenant"],
+        ["unsuspend", "Tenant"],
+        ["replay", "ForgeJob"],
+        ["override", "FeatureFlag"],
+    ],
+    // Staff grants are the privilege-escalation edge: only the owner tier moves it.
+    platform_owner: [
+        ["grant", "PlatformStaff"],
+        ["revoke", "PlatformStaff"],
+    ],
+};
+export function isPlatformStaffRole(role) {
+    return PLATFORM_STAFF_ROLES.includes(role);
+}
+/**
+ * Accepts either the TypeScript role string (`platform_owner`) or the Prisma
+ * enum spelling (`PLATFORM_OWNER`). Returns null for anything unrecognized —
+ * an unknown role must degrade to "no access", never to a default.
+ */
+export function normalizePlatformStaffRole(role) {
+    if (!role)
+        return null;
+    const normalized = role.toLowerCase();
+    return isPlatformStaffRole(normalized) ? normalized : null;
+}
+/** Roles at or below `role` in seniority, including `role` itself. */
+export function platformRoleHierarchy(role) {
+    const ceiling = PLATFORM_STAFF_ROLES.indexOf(role);
+    return PLATFORM_STAFF_ROLES.slice(0, ceiling + 1);
+}
+export function platformAbilityFor(role) {
+    const { can, build } = new AbilityBuilder(createMongoAbility);
+    for (const inherited of platformRoleHierarchy(role)) {
+        for (const [action, resource] of CAPABILITIES[inherited]) {
+            can(action, resource);
+        }
+    }
+    return build();
+}
+/**
+ * Convenience guard for route handlers. Takes the raw role so callers can pass
+ * whatever came out of the `PlatformStaff` row without pre-validating it; an
+ * unknown or revoked role simply cannot do anything.
+ */
+export function canPlatform(role, action, resource) {
+    const normalized = normalizePlatformStaffRole(role);
+    if (!normalized)
+        return false;
+    return platformAbilityFor(normalized).can(action, resource);
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@nebutra/permissions",
-  "version": "0.1.3",
+  "version": "2.0.0",
   "private": false,
   "license": "MIT",
   "type": "module",
   "nebutra": {
+    "graph": "core",
     "status": "foundation",
     "productionReady": false,
     "requires": [
@@ -54,13 +55,14 @@
     "@casl/ability": "^6.7.0",
     "@casl/prisma": "^1.5.1",
     "zod": "^4.3.6",
-    "@nebutra/logger": "0.1.2"
+    "@nebutra/logger": "2.0.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "hono": "^4.0.0"
   },
   "devDependencies": {
+    "@types/react": "^19.0.0",
     "react": "^19.0.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.4"