@ultimabase/roles 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @ultimabase/roles
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies
+  - ultimabase@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- 0e885c4: The first release: the kernel, its adapters, transports and plugins, the testing helpers and the starter.
+
+### Patch Changes
+
+- Updated dependencies [0e885c4]
+  - ultimabase@0.1.0

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @ultimabase/roles
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Roles for UltimaBase: users get roles, such as `writer` or `team`, roles hold other roles, and the access rule `hasRole` asks whether a caller has one.
+
+Documentation: [Roles](https://ultimabase.dev/docs/roles).

package/dist/define-role.d.ts

@@ -0,0 +1,42 @@
+import type { Field, FieldShapes, IndexShape, Many, ModelFields, ModelIndexes, ModelOf, ModelUse, PluginTypes } from 'ultimabase';
+import type { Roles } from './plugin.ts';
+type Uses = readonly ModelUse<string, PluginTypes>[];
+/** The role model's `use`: roles first, then the developer's plugins. */
+type WithRoles<U extends Uses> = readonly [ModelUse<'roles', Roles>, ...U];
+/** The fields `defineRole` adds; `R` is the role model's own thunk. */
+export type RoleFields<M, R> = {
+    readonly name: Field<string, {
+        readonly unique: true;
+    }>;
+    readonly members: Many<M, {
+        readonly inverse?: string;
+    }>;
+    readonly inherits: Many<R, {
+        readonly inverse: 'inheritedBy';
+    }>;
+    readonly inheritedBy: Many<R, {
+        readonly inverse: 'inherits';
+    }>;
+};
+/** The role model, typed through an interface: it refers to itself. */
+export interface RoleThunk<N extends string, F, M, U extends Uses, X extends readonly IndexShape[]> {
+    (): ModelOf<N, F & RoleFields<M, RoleThunk<N, F, M, U, X>>, WithRoles<U>, X>;
+}
+/** What every role model declares; `F` types `indexes` only. */
+type RoleDefinition<N, M, F, U extends Uses, X> = {
+    readonly name: N;
+    /** The stored table's or collection's name (D-63). */
+    readonly dbName?: string;
+    /** The user model, `() => User`. */
+    readonly members: M;
+    readonly use?: U;
+    readonly indexes?: ModelIndexes<X, F & RoleFields<M, () => object>, WithRoles<U>>;
+};
+/** The application's one role model, with its own fields (D-123). */
+export declare function defineRole<const N extends string, const M extends () => object, const F extends FieldShapes, const U extends Uses = [], const X extends readonly IndexShape[] = []>(definition: RoleDefinition<N, M, F, U, X> & {
+    readonly fields: ModelFields<F, WithRoles<U>>;
+}): ReturnType<RoleThunk<N, F, M, U, X>>;
+/** The application's one role model, without fields of its own (D-123). */
+export declare function defineRole<const N extends string, const M extends () => object, const U extends Uses = [], const X extends readonly IndexShape[] = []>(definition: RoleDefinition<N, M, {}, U, X>): ReturnType<RoleThunk<N, {}, M, U, X>>;
+export {};
+//# sourceMappingURL=define-role.d.ts.map

package/dist/define-role.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-role.d.ts","sourceRoot":"","sources":["../src/define-role.ts"],"names":[],"mappings":"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"}

package/dist/define-role.js

@@ -0,0 +1,36 @@
+import { defineModel, Refused } from 'ultimabase';
+import { roleModels, rolesUse } from './plugin.js';
+const reserved = ['name', 'members', 'inherits', 'inheritedBy'];
+export function defineRole(definition) {
+    const { name, members, fields } = definition;
+    if (typeof members !== 'function') {
+        throw new Refused(`defineRole(${name}): members is () => the user model.`);
+    }
+    const self = () => model;
+    const model = defineModel({
+        name,
+        ...(definition.dbName === undefined ? {} : { dbName: definition.dbName }),
+        use: [rolesUse(), ...(definition.use ?? [])],
+        fields: (f) => {
+            // The developer's fields, typed by its own `use`.
+            const own = fields === undefined ? {} : Reflect.apply(fields, undefined, [f]);
+            if (typeof own !== 'object' || own === null) {
+                throw new Refused(`defineRole(${name}): fields returns an object.`);
+            }
+            const taken = reserved.find((key) => Object.hasOwn(own, key));
+            if (taken !== undefined) {
+                throw new Refused(`defineRole(${name}): ${taken} is a field defineRole adds.`);
+            }
+            return {
+                ...own,
+                name: f.string({ unique: true }),
+                members: f.many(members),
+                inherits: f.many(self, { inverse: 'inheritedBy' }),
+                inheritedBy: f.many(self, { inverse: 'inherits' }),
+            };
+        },
+        indexes: definition.indexes ?? [],
+    });
+    roleModels.add(model);
+    return model;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { RoleFields, RoleThunk } from './define-role.ts';
+export { defineRole } from './define-role.ts';
+export type { Roles } from './plugin.ts';
+export { hasRole, rolesOf, rolesPlugin } from './plugin.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,YAAY,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { defineRole } from './define-role.js';
+export { hasRole, rolesOf, rolesPlugin } from './plugin.js';

package/dist/plugin.d.ts

@@ -0,0 +1,27 @@
+import type { Caller, CallerRule, PluginOf, PluginTypes, UseOf } from 'ultimabase';
+/** The roles plugin's types (D-57). */
+export interface Roles extends PluginTypes {
+    readonly name: 'roles';
+}
+/** The models `defineRole` returned. */
+export declare const roleModels: WeakSet<object>;
+/** Each user caller's roles, read once per caller (D-123). */
+export declare const rolesPlugin: PluginOf<Roles>;
+/** The roles plugin's entry in the role model's `use`, which `defineRole` adds. */
+export declare const rolesUse: UseOf<Roles>;
+/**
+ * The caller's roles, each `{ id, name }`, inherited ones included; `[]` for
+ * a caller the roles plugin did not complete (D-126).
+ */
+export declare function rolesOf(caller: Caller): readonly {
+    readonly id: string;
+    readonly name: string;
+}[];
+/**
+ * Whether the caller has one of the roles, inherited ones included; false
+ * for an anonymous or Master caller (D-126). Without the caller, the rule
+ * asking it (D-10).
+ */
+export declare function hasRole(...names: readonly [string, ...string[]]): CallerRule;
+export declare function hasRole(caller: Caller, ...names: readonly [string, ...string[]]): boolean;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,MAAM,EACN,UAAU,EAGV,QAAQ,EACR,WAAW,EACX,KAAK,EACL,MAAM,YAAY,CAAA;AAInB,uCAAuC;AACvC,MAAM,WAAW,KAAM,SAAQ,WAAW;IACzC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACtB;AAID,wCAAwC;AACxC,eAAO,MAAM,UAAU,EAAE,OAAO,CAAC,MAAM,CAAiB,CAAA;AAwGxD,8DAA8D;AAC9D,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAgB,CAAA;AACxD,mFAAmF;AACnF,eAAO,MAAM,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAa,CAAA;AAE/C;;;GAGG;AACH,wBAAgB,OAAO,CACtB,MAAM,EAAE,MAAM,GACZ,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAG3D;AAaD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,GAAG,UAAU,CAAA;AAC7E,wBAAgB,OAAO,CACtB,MAAM,EAAE,MAAM,EACd,GAAG,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,GACtC,OAAO,CAAA"}

package/dist/plugin.js

@@ -0,0 +1,115 @@
+import { definePlugin, master, Refused } from 'ultimabase';
+import manifest from '../package.json' with { type: 'json' };
+/** The models `defineRole` returned. */
+export const roleModels = new WeakSet();
+/** The caller's key holding its roles, which `@ultimabase/roles` keeps (D-126). */
+const rolesKey = Symbol('roles');
+/** The lists of roles this plugin gave a caller. */
+const given = new WeakSet();
+const M = { as: master };
+/** The one role model among the application's models (D-123). */
+function rolesModelOf(models) {
+    const [first, second] = models.filter(({ queries }) => roleModels.has(queries));
+    if (first === undefined) {
+        throw new Refused('rolesPlugin() needs a role model: declare it with defineRole.');
+    }
+    if (second !== undefined) {
+        throw new Refused('models lists two models defineRole returned: an application has one role model.');
+    }
+    return first.queries;
+}
+/** The levels of inheritance one read follows (D-123). */
+const depth = 5;
+/** A role's id and name, and its inherited roles `left` levels deep. */
+const level = (left) => ({
+    id: true,
+    name: true,
+    inherits: { select: left === 0 ? { id: true } : level(left - 1) },
+});
+/**
+ * Adds a read role and the roles it inherits to `held`; a role read past
+ * the last level, its id alone, goes to `missing`. A role already held was
+ * followed, which ends a cycle.
+ */
+function follow(row, held, missing) {
+    const id = Reflect.get(Object(row), 'id');
+    const name = Reflect.get(Object(row), 'name');
+    if (typeof id !== 'string' || held.has(id))
+        return;
+    if (typeof name !== 'string') {
+        missing.add(id);
+        return;
+    }
+    held.set(id, Object.freeze({ id, name }));
+    const parents = Reflect.get(Object(row), 'inherits');
+    for (const parent of Array.isArray(parents) ? parents : []) {
+        follow(parent, held, missing);
+    }
+}
+/**
+ * Every role of a user: the roles it is a member of and those they inherit,
+ * five levels per query (D-123).
+ */
+async function rolesOfUser(id, queries) {
+    const held = new Map();
+    const select = level(depth);
+    let where = { members: { some: { id } } };
+    for (;;) {
+        const missing = new Set();
+        for (const row of await queries.findMany({ where, select }, M)) {
+            follow(row, held, missing);
+        }
+        const next = [...missing].filter((role) => !held.has(role));
+        if (next.length === 0)
+            break;
+        where = { id: { in: next } };
+    }
+    const roles = Object.freeze([...held.values()]);
+    given.add(roles);
+    return roles;
+}
+const isHeld = (value) => typeof value === 'object' && value !== null && given.has(value);
+const roles = definePlugin({
+    name: 'roles',
+    manifest,
+    start: ({ models }) => {
+        rolesModelOf(models);
+    },
+    caller: async ({ user }, { models }) => {
+        // Built apart: a key no interface declares is not an excess one.
+        const keys = {
+            [rolesKey]: await rolesOfUser(user.id, rolesModelOf(models)),
+        };
+        return keys;
+    },
+});
+/** Each user caller's roles, read once per caller (D-123). */
+export const rolesPlugin = roles.plugin;
+/** The roles plugin's entry in the role model's `use`, which `defineRole` adds. */
+export const rolesUse = roles.use;
+/**
+ * The caller's roles, each `{ id, name }`, inherited ones included; `[]` for
+ * a caller the roles plugin did not complete (D-126).
+ */
+export function rolesOf(caller) {
+    const held = Reflect.get(caller, rolesKey);
+    return isHeld(held) ? held : [];
+}
+function holds(caller, names) {
+    if (caller.kind !== 'user')
+        return false;
+    const held = Reflect.get(caller, rolesKey);
+    if (!isHeld(held)) {
+        throw new Error('hasRole reads the roles rolesPlugin() gives a caller: add rolesPlugin() to plugins.');
+    }
+    return held.some(({ name }) => names.includes(name));
+}
+export function hasRole(first, ...names) {
+    if (typeof first !== 'string') {
+        if (names.length === 0)
+            throw new TypeError('hasRole takes a role name.');
+        return holds(first, names);
+    }
+    const wanted = [first, ...names];
+    return ({ caller }) => holds(caller, wanted);
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@ultimabase/roles",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Roles for UltimaBase: a role model, roles inside roles, and the rule asking a caller's role.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://ultimabase.dev/docs/roles",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrEkinox/ultimabase.git",
+    "directory": "packages/roles"
+  },
+  "engines": {
+    "node": ">=24.7.0"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test"
+  ],
+  "scripts": {
+    "prepack": "rm -rf dist && yarn run -T tsc --project tsconfig.build.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "ultimabase": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/pg": "8.23.1",
+    "@ultimabase/postgres": "0.1.1",
+    "@ultimabase/testing": "0.1.1",
+    "pg": "8.23.1",
+    "ultimabase": "0.1.1",
+    "vite": "8.3.4",
+    "vitest": "5.0.5"
+  }
 }

package/src/define-role.ts

@@ -0,0 +1,128 @@
+// `defineRole` (D-13, D-123): the application's one role model, an ordinary
+// model with a unique name, its members, and the roles it inherits.
+import type {
+	Field,
+	FieldShapes,
+	IndexShape,
+	Many,
+	ModelFields,
+	ModelIndexes,
+	ModelOf,
+	ModelUse,
+	PluginTypes,
+} from 'ultimabase'
+import { defineModel, Refused } from 'ultimabase'
+import type { Roles } from './plugin.ts'
+import { roleModels, rolesUse } from './plugin.ts'
+
+type Uses = readonly ModelUse<string, PluginTypes>[]
+/** The role model's `use`: roles first, then the developer's plugins. */
+type WithRoles<U extends Uses> = readonly [ModelUse<'roles', Roles>, ...U]
+
+/** The fields `defineRole` adds; `R` is the role model's own thunk. */
+export type RoleFields<M, R> = {
+	readonly name: Field<string, { readonly unique: true }>
+	readonly members: Many<M, { readonly inverse?: string }>
+	readonly inherits: Many<R, { readonly inverse: 'inheritedBy' }>
+	readonly inheritedBy: Many<R, { readonly inverse: 'inherits' }>
+}
+
+/** The role model, typed through an interface: it refers to itself. */
+export interface RoleThunk<
+	N extends string,
+	F,
+	M,
+	U extends Uses,
+	X extends readonly IndexShape[],
+> {
+	(): ModelOf<N, F & RoleFields<M, RoleThunk<N, F, M, U, X>>, WithRoles<U>, X>
+}
+
+const reserved = ['name', 'members', 'inherits', 'inheritedBy']
+
+/** What every role model declares; `F` types `indexes` only. */
+type RoleDefinition<N, M, F, U extends Uses, X> = {
+	readonly name: N
+	/** The stored table's or collection's name (D-63). */
+	readonly dbName?: string
+	/** The user model, `() => User`. */
+	readonly members: M
+	readonly use?: U
+	// Checked on the scalar fields only: the role model's own type would
+	// infer `X` from itself.
+	readonly indexes?: ModelIndexes<
+		X,
+		F & RoleFields<M, () => object>,
+		WithRoles<U>
+	>
+}
+
+/** The application's one role model, with its own fields (D-123). */
+export function defineRole<
+	const N extends string,
+	const M extends () => object,
+	const F extends FieldShapes,
+	const U extends Uses = [],
+	const X extends readonly IndexShape[] = [],
+>(
+	definition: RoleDefinition<N, M, F, U, X> & {
+		readonly fields: ModelFields<F, WithRoles<U>>
+	},
+): ReturnType<RoleThunk<N, F, M, U, X>>
+/** The application's one role model, without fields of its own (D-123). */
+export function defineRole<
+	const N extends string,
+	const M extends () => object,
+	const U extends Uses = [],
+	const X extends readonly IndexShape[] = [],
+>(
+	definition: RoleDefinition<N, M, {}, U, X>,
+): ReturnType<RoleThunk<N, {}, M, U, X>>
+export function defineRole(definition: {
+	readonly name: string
+	readonly dbName?: string
+	readonly members: unknown
+	readonly use?: Uses
+	readonly fields?: Function
+	readonly indexes?: readonly IndexShape[]
+}): object {
+	const { name, members, fields } = definition
+	if (typeof members !== 'function') {
+		throw new Refused(`defineRole(${name}): members is () => the user model.`)
+	}
+	const self = (): object => model
+	const model: object = defineModel<
+		string,
+		FieldShapes,
+		Uses,
+		readonly IndexShape[]
+	>({
+		name,
+		...(definition.dbName === undefined ? {} : { dbName: definition.dbName }),
+		use: [rolesUse(), ...(definition.use ?? [])],
+		fields: (f) => {
+			// The developer's fields, typed by its own `use`.
+			const own: unknown =
+				fields === undefined ? {} : Reflect.apply(fields, undefined, [f])
+			if (typeof own !== 'object' || own === null) {
+				throw new Refused(`defineRole(${name}): fields returns an object.`)
+			}
+			const taken = reserved.find((key) => Object.hasOwn(own, key))
+			if (taken !== undefined) {
+				throw new Refused(
+					`defineRole(${name}): ${taken} is a field defineRole adds.`,
+				)
+			}
+			return {
+				...own,
+				name: f.string({ unique: true }),
+				members: f.many(members),
+				inherits: f.many(self, { inverse: 'inheritedBy' }),
+				inheritedBy: f.many(self, { inverse: 'inherits' }),
+			}
+		},
+		indexes: definition.indexes ?? [],
+	})
+	roleModels.add(model)
+	return model
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// `@ultimabase/roles` (D-123, D-126): the role model, roles inside roles, and
+// the question whether a caller has a role.
+export type { RoleFields, RoleThunk } from './define-role.ts'
+export { defineRole } from './define-role.ts'
+export type { Roles } from './plugin.ts'
+export { hasRole, rolesOf, rolesPlugin } from './plugin.ts'

package/src/plugin.ts

@@ -0,0 +1,175 @@
+// `rolesPlugin()` (D-123, D-126): each user caller completed with every role
+// the user has, inherited ones included, under a key no other code names;
+// `hasRole` asks it, `rolesOf` lists it.
+import type {
+	Caller,
+	CallerRule,
+	ExposedModel,
+	ModelQueries,
+	PluginOf,
+	PluginTypes,
+	UseOf,
+} from 'ultimabase'
+import { definePlugin, master, Refused } from 'ultimabase'
+import manifest from '../package.json' with { type: 'json' }
+
+/** The roles plugin's types (D-57). */
+export interface Roles extends PluginTypes {
+	readonly name: 'roles'
+}
+
+type Held = { readonly id: string; readonly name: string }
+
+/** The models `defineRole` returned. */
+export const roleModels: WeakSet<object> = new WeakSet()
+
+/** The caller's key holding its roles, which `@ultimabase/roles` keeps (D-126). */
+const rolesKey = Symbol('roles')
+/** The lists of roles this plugin gave a caller. */
+const given = new WeakSet<object>()
+
+const M = { as: master }
+
+/** The one role model among the application's models (D-123). */
+function rolesModelOf(models: readonly ExposedModel[]): ModelQueries {
+	const [first, second] = models.filter(({ queries }) =>
+		roleModels.has(queries),
+	)
+	if (first === undefined) {
+		throw new Refused(
+			'rolesPlugin() needs a role model: declare it with defineRole.',
+		)
+	}
+	if (second !== undefined) {
+		throw new Refused(
+			'models lists two models defineRole returned: an application has one role model.',
+		)
+	}
+	return first.queries
+}
+
+/** The levels of inheritance one read follows (D-123). */
+const depth = 5
+
+/** A role's id and name, and its inherited roles `left` levels deep. */
+const level = (left: number): object => ({
+	id: true,
+	name: true,
+	inherits: { select: left === 0 ? { id: true } : level(left - 1) },
+})
+
+/**
+ * Adds a read role and the roles it inherits to `held`; a role read past
+ * the last level, its id alone, goes to `missing`. A role already held was
+ * followed, which ends a cycle.
+ */
+function follow(
+	row: unknown,
+	held: Map<string, Held>,
+	missing: Set<string>,
+): void {
+	const id: unknown = Reflect.get(Object(row), 'id')
+	const name: unknown = Reflect.get(Object(row), 'name')
+	if (typeof id !== 'string' || held.has(id)) return
+	if (typeof name !== 'string') {
+		missing.add(id)
+		return
+	}
+	held.set(id, Object.freeze({ id, name }))
+	const parents: unknown = Reflect.get(Object(row), 'inherits')
+	for (const parent of Array.isArray(parents) ? parents : []) {
+		follow(parent, held, missing)
+	}
+}
+
+/**
+ * Every role of a user: the roles it is a member of and those they inherit,
+ * five levels per query (D-123).
+ */
+async function rolesOfUser(
+	id: string,
+	queries: ModelQueries,
+): Promise<readonly Held[]> {
+	const held = new Map<string, Held>()
+	const select = level(depth)
+	let where: object = { members: { some: { id } } }
+	for (;;) {
+		const missing = new Set<string>()
+		for (const row of await queries.findMany({ where, select }, M)) {
+			follow(row, held, missing)
+		}
+		const next = [...missing].filter((role) => !held.has(role))
+		if (next.length === 0) break
+		where = { id: { in: next } }
+	}
+	const roles = Object.freeze([...held.values()])
+	given.add(roles)
+	return roles
+}
+
+const isHeld = (value: unknown): value is readonly Held[] =>
+	typeof value === 'object' && value !== null && given.has(value)
+
+const roles = definePlugin<Roles>({
+	name: 'roles',
+	manifest,
+	start: ({ models }) => {
+		rolesModelOf(models)
+	},
+	caller: async ({ user }, { models }) => {
+		// Built apart: a key no interface declares is not an excess one.
+		const keys = {
+			[rolesKey]: await rolesOfUser(user.id, rolesModelOf(models)),
+		}
+		return keys
+	},
+})
+
+/** Each user caller's roles, read once per caller (D-123). */
+export const rolesPlugin: PluginOf<Roles> = roles.plugin
+/** The roles plugin's entry in the role model's `use`, which `defineRole` adds. */
+export const rolesUse: UseOf<Roles> = roles.use
+
+/**
+ * The caller's roles, each `{ id, name }`, inherited ones included; `[]` for
+ * a caller the roles plugin did not complete (D-126).
+ */
+export function rolesOf(
+	caller: Caller,
+): readonly { readonly id: string; readonly name: string }[] {
+	const held: unknown = Reflect.get(caller, rolesKey)
+	return isHeld(held) ? held : []
+}
+
+function holds(caller: Caller, names: readonly string[]): boolean {
+	if (caller.kind !== 'user') return false
+	const held: unknown = Reflect.get(caller, rolesKey)
+	if (!isHeld(held)) {
+		throw new Error(
+			'hasRole reads the roles rolesPlugin() gives a caller: add rolesPlugin() to plugins.',
+		)
+	}
+	return held.some(({ name }) => names.includes(name))
+}
+
+/**
+ * Whether the caller has one of the roles, inherited ones included; false
+ * for an anonymous or Master caller (D-126). Without the caller, the rule
+ * asking it (D-10).
+ */
+export function hasRole(...names: readonly [string, ...string[]]): CallerRule
+export function hasRole(
+	caller: Caller,
+	...names: readonly [string, ...string[]]
+): boolean
+export function hasRole(
+	first: Caller | string,
+	...names: readonly string[]
+): CallerRule | boolean {
+	if (typeof first !== 'string') {
+		if (names.length === 0) throw new TypeError('hasRole takes a role name.')
+		return holds(first, names)
+	}
+	const wanted = [first, ...names]
+	return ({ caller }) => holds(caller, wanted)
+}