@rdlabo/workers-hono-kit 0.6.17 → 0.6.18

package/README.md

@@ -616,6 +616,40 @@ The package ships three `bin` commands (run via `npx` or an npm script in the co
 | `workers-hono-kit-check-subrequest-fanout [dir…]` | CI gate that greps for per-item external-call fan-outs (`runWithConcurrency(` / `PromisePool` / `.withConcurrency(`) that would eventually exceed the Workers subrequest cap. Annotate a genuinely-safe site with `subrequest-ok`. Scans `src` by default; exits 1 on an un-annotated marker. |
 | `workers-hono-kit-db-baseline [--migrations ./drizzle]` | Brownfield first-deploy helper: record the baseline `0000` migration as *already applied* on an existing MySQL DB without running its DDL (the CLI wrapper around `baselineMigrations` / `readBaselineEntry`). Reads DB credentials from `DB_SECRET` (AWS RDS managed secret) or the individual `DB_*` env vars. |
 
+## Storage-agnostic role policies
+
+`createRolePolicy` builds pure RBAC checks without coupling the policy to a database schema. The
+application can resolve roles from a membership table, a `users.role` column, token claims, or any
+other source.
+
+```ts
+import { createRolePolicy } from '@rdlabo/workers-hono-kit';
+
+type Role = 'owner' | 'admin' | 'member' | 'read';
+type Permission = 'organization.manage' | 'resource.write' | 'resource.read';
+
+const policy = createRolePolicy<Role, Permission>({
+  permissions: {
+    owner: ['organization.manage', 'resource.write', 'resource.read'],
+    admin: ['resource.write', 'resource.read'],
+    member: ['resource.write', 'resource.read'],
+    read: ['resource.read'],
+  },
+  assignableRoles: {
+    owner: ['admin', 'member', 'read'],
+    admin: ['member', 'read'],
+    member: [],
+    read: [],
+  },
+  manageableRoles: {
+    owner: ['admin', 'member', 'read'],
+    admin: ['member', 'read'],
+    member: [],
+    read: [],
+  },
+});
+```
+
 ## Development
 
 ```bash

package/dist/authorization/role-policy.d.ts

@@ -0,0 +1,32 @@
+/** A role-to-permissions lookup used by {@link createRolePolicy}. */
+export type RolePermissionMap<Role extends string, Permission extends string> = Readonly<Record<Role, readonly Permission[]>>;
+/** A role-to-roles lookup used for assignment and management boundaries. */
+export type RoleRelationMap<Role extends string> = Readonly<Record<Role, readonly Role[]>>;
+/** Configuration for a storage-agnostic role policy. */
+export interface RolePolicyConfig<Role extends string, Permission extends string> {
+    /** Permissions granted to each role. */
+    permissions: RolePermissionMap<Role, Permission>;
+    /** Roles that each actor role may assign to another subject. */
+    assignableRoles: RoleRelationMap<Role>;
+    /** Existing subject roles that each actor role may manage. */
+    manageableRoles: RoleRelationMap<Role>;
+}
+/** Pure authorization checks produced from a role policy configuration. */
+export interface RolePolicy<Role extends string, Permission extends string> {
+    /** Returns whether `role` grants `permission`. */
+    hasPermission(role: Role, permission: Permission): boolean;
+    /** Returns whether `actorRole` may assign `nextRole`. */
+    canAssignRole(actorRole: Role, nextRole: Role): boolean;
+    /** Returns whether `actorRole` may manage a subject with `targetRole`. */
+    canManageRole(actorRole: Role, targetRole: Role): boolean;
+    /** Returns whether an actor may change a subject from one role to another. */
+    canChangeRole(actorRole: Role, currentRole: Role, nextRole: Role): boolean;
+}
+/**
+ * Creates pure, schema-independent RBAC checks.
+ *
+ * The caller resolves a role from any persistence model (for example `group_users.role`,
+ * `users.role`, a token claim, or an external identity provider) and passes that role into these
+ * checks. Keeping lookup and policy separate makes the same policy reusable across applications.
+ */
+export declare function createRolePolicy<Role extends string, Permission extends string>(config: RolePolicyConfig<Role, Permission>): RolePolicy<Role, Permission>;

package/dist/authorization/role-policy.js

@@ -0,0 +1,25 @@
+function ownListIncludes(record, key, value) {
+    if (!Object.prototype.hasOwnProperty.call(record, key)) {
+        return false;
+    }
+    return record[key]?.includes(value) ?? false;
+}
+/**
+ * Creates pure, schema-independent RBAC checks.
+ *
+ * The caller resolves a role from any persistence model (for example `group_users.role`,
+ * `users.role`, a token claim, or an external identity provider) and passes that role into these
+ * checks. Keeping lookup and policy separate makes the same policy reusable across applications.
+ */
+export function createRolePolicy(config) {
+    // Keep the public config strongly typed while treating runtime values as untrusted input.
+    const permissions = config.permissions;
+    const assignableRoles = config.assignableRoles;
+    const manageableRoles = config.manageableRoles;
+    return {
+        hasPermission: (role, permission) => ownListIncludes(permissions, role, permission),
+        canAssignRole: (actorRole, nextRole) => ownListIncludes(assignableRoles, actorRole, nextRole),
+        canManageRole: (actorRole, targetRole) => ownListIncludes(manageableRoles, actorRole, targetRole),
+        canChangeRole: (actorRole, currentRole, nextRole) => ownListIncludes(manageableRoles, actorRole, currentRole) && ownListIncludes(assignableRoles, actorRole, nextRole),
+    };
+}

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export { createIsolateMemo } from './container/isolate-memo.js';
 export type { IsolateMemo } from './container/isolate-memo.js';
 export { createContainerRuntime } from './container/middleware.js';
 export type { ContainerBuildContext, ContainerRuntime, ContainerRuntimeOptions } from './container/middleware.js';
+export { createRolePolicy } from './authorization/role-policy.js';
+export type { RolePermissionMap, RolePolicy, RolePolicyConfig, RoleRelationMap } from './authorization/role-policy.js';
 export { getUserProtocol } from './http/user-protocol.js';
 export type { IUserProtocol } from './http/user-protocol.js';
 export { getAppInfo } from './http/app-info.js';

package/dist/index.js

@@ -21,6 +21,8 @@ export { perfLog } from './middleware/perf-log.js';
 export { createMaintenanceMiddleware, createMaintenanceWaitHandler, isMaintenanceEnabled, MAINTENANCE_BODY, MAINTENANCE_CODE, MAINTENANCE_WAIT_PATH, } from './middleware/maintenance.js';
 export { createIsolateMemo } from './container/isolate-memo.js';
 export { createContainerRuntime } from './container/middleware.js';
+// authorization
+export { createRolePolicy } from './authorization/role-policy.js';
 // http
 export { getUserProtocol } from './http/user-protocol.js';
 export { getAppInfo } from './http/app-info.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/workers-hono-kit",
-  "version": "0.6.17",
+  "version": "0.6.18",
   "private": false,
   "publishConfig": {
     "access": "public"