@ultimabase/acl 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @ultimabase/acl
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies
+  - ultimabase@0.1.1
+  - @ultimabase/roles@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/roles@0.1.0
+  - ultimabase@0.1.0

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @ultimabase/acl
 
-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.
+Per-row rights for UltimaBase. Each row stores who reads it and who writes it: by user, by role, or for the public. A query sees only the rows its caller may read, and writes only those it may write.
+
+Documentation: [ACL](https://ultimabase.dev/docs/acl).

package/dist/acl.d.ts

@@ -0,0 +1,59 @@
+import type { Caller } from 'ultimabase';
+/** `write` is update and delete (D-124). */
+export type Permission = 'read' | 'write';
+/** What a client reads, and may send: the subjects of each permission. */
+export type AclJson = {
+    readonly read: readonly string[];
+    readonly write: readonly string[];
+};
+/**
+ * The ACL a value is, or what it lacks: an `ACL`, or `{ read, write }`
+ * listing subjects `*`, `user:<id>` or `role:<id>`.
+ */
+export declare function parsed(value: unknown): ACL | string;
+/** Who may read and who may write one row; empty, only Master (D-124). */
+export declare class ACL {
+    #private;
+    /** Its entries as stored, as `['read:*', 'write:user:u_1']`. */
+    static fromEntries(entries: Iterable<string>): ACL;
+    /** What `toJSON` gives, or a client sends. */
+    static fromJSON(json: unknown): ACL;
+    allowPublic(...perms: readonly Permission[]): ACL;
+    allowUser(user: {
+        readonly id: string;
+    }, ...perms: readonly Permission[]): ACL;
+    allowRole(role: {
+        readonly id: string;
+    }, ...perms: readonly Permission[]): ACL;
+    denyPublic(...perms: readonly Permission[]): ACL;
+    denyUser(user: {
+        readonly id: string;
+    }, ...perms: readonly Permission[]): ACL;
+    denyRole(role: {
+        readonly id: string;
+    }, ...perms: readonly Permission[]): ACL;
+    publicCan(permission: Permission): boolean;
+    userCan(user: {
+        readonly id: string;
+    }, permission: Permission): boolean;
+    roleCan(role: {
+        readonly id: string;
+    }, permission: Permission): boolean;
+    /** The ids of the users having the permission. */
+    users(permission: Permission): readonly string[];
+    /** The ids of the roles having the permission. */
+    roles(permission: Permission): readonly string[];
+    /**
+     * Whether the caller has the permission, through the public, its user or
+     * one of its roles; a write needs the read too, as the queries do. True
+     * for Master.
+     */
+    allows(caller: Caller, permission: Permission): boolean;
+    /** Its entries as stored, sorted. */
+    entries(): readonly string[];
+    /** What a client reads: `{ read: ['*'], write: ['user:u_1'] }`. */
+    toJSON(): AclJson;
+}
+/** The subjects a caller other than Master is: `*`, its user, its roles. */
+export declare function subjectsOf(caller: Caller): readonly string[];
+//# sourceMappingURL=acl.d.ts.map

package/dist/acl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acl.d.ts","sourceRoot":"","sources":["../src/acl.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,4CAA4C;AAC5C,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAA;AAEzC,0EAA0E;AAC1E,MAAM,MAAM,OAAO,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CACjC,CAAA;AAkBD;;;GAGG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,GAAG,MAAM,CAmBnD;AAED,0EAA0E;AAC1E,qBAAa,GAAG;;IASf,gEAAgE;IAChE,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,GAAG,CASjD;IAED,8CAA8C;IAC9C,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,GAAG,CAIlC;IAYD,WAAW,CAAC,GAAG,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,GAAG,CAEhD;IAED,SAAS,CACR,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAC7B,GAAG,KAAK,EAAE,SAAS,UAAU,EAAE,GAC7B,GAAG,CAEL;IAED,SAAS,CACR,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAC7B,GAAG,KAAK,EAAE,SAAS,UAAU,EAAE,GAC7B,GAAG,CAEL;IAED,UAAU,CAAC,GAAG,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,GAAG,CAE/C;IAED,QAAQ,CACP,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAC7B,GAAG,KAAK,EAAE,SAAS,UAAU,EAAE,GAC7B,GAAG,CAEL;IAED,QAAQ,CACP,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAC7B,GAAG,KAAK,EAAE,SAAS,UAAU,EAAE,GAC7B,GAAG,CAEL;IAED,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAEzC;IAED,OAAO,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAEtE;IAED,OAAO,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAEtE;IAED,kDAAkD;IAClD,KAAK,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,CAE/C;IAED,kDAAkD;IAClD,KAAK,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,CAE/C;IAQD;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAMtD;IAED,qCAAqC;IACrC,OAAO,IAAI,SAAS,MAAM,EAAE,CAE3B;IAED,mEAAmE;IACnE,MAAM,IAAI,OAAO,CAMhB;CACD;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAO5D"}

package/dist/acl.js

@@ -0,0 +1,155 @@
+var _a;
+// The `ACL` class (D-124): who may read and who may write one row, as
+// entries `read:*`, `read:user:<id>` and `write:role:<id>`. Each method
+// returns a new ACL.
+import { rolesOf } from '@ultimabase/roles';
+const permissions = ['read', 'write'];
+const isSubject = (subject) => subject === '*' || /^(?:user|role):.+$/u.test(subject);
+/** The entry's permission, or `undefined` when it is not an entry. */
+function permissionOf(entry) {
+    const permission = permissions.find((each) => entry.startsWith(`${each}:`));
+    if (permission === undefined)
+        return undefined;
+    return isSubject(entry.slice(permission.length + 1)) ? permission : undefined;
+}
+/** The permissions given, or both when none is. */
+const given = (perms) => perms.length === 0 ? permissions : perms;
+/**
+ * The ACL a value is, or what it lacks: an `ACL`, or `{ read, write }`
+ * listing subjects `*`, `user:<id>` or `role:<id>`.
+ */
+export function parsed(value) {
+    if (value instanceof ACL)
+        return value;
+    if (typeof value !== 'object' || value === null) {
+        return 'An ACL is an ACL or { read, write }.';
+    }
+    const entries = [];
+    for (const key of Object.keys(value)) {
+        const permission = permissions.find((each) => each === key);
+        if (permission === undefined)
+            return `${key} is not a permission.`;
+        const subjects = Reflect.get(value, key);
+        if (!Array.isArray(subjects))
+            return `${key} is a list of subjects.`;
+        for (const [index, subject] of subjects.entries()) {
+            if (typeof subject !== 'string' || !isSubject(subject)) {
+                return `${key}[${index}]: a subject is *, user:<id> or role:<id>.`;
+            }
+            entries.push(`${permission}:${subject}`);
+        }
+    }
+    return ACL.fromEntries(entries);
+}
+/** Who may read and who may write one row; empty, only Master (D-124). */
+export class ACL {
+    #entries = new Set();
+    static #of(entries) {
+        const acl = new _a();
+        acl.#entries = entries;
+        return acl;
+    }
+    /** Its entries as stored, as `['read:*', 'write:user:u_1']`. */
+    static fromEntries(entries) {
+        const kept = new Set();
+        for (const entry of entries) {
+            if (permissionOf(entry) === undefined) {
+                throw new TypeError(`${entry} is not an ACL entry.`);
+            }
+            kept.add(entry);
+        }
+        return _a.#of(kept);
+    }
+    /** What `toJSON` gives, or a client sends. */
+    static fromJSON(json) {
+        const acl = parsed(json);
+        if (typeof acl === 'string')
+            throw new TypeError(acl);
+        return acl;
+    }
+    #changed(subject, perms, add) {
+        const entries = new Set(this.#entries);
+        for (const permission of given(perms)) {
+            const entry = `${permission}:${subject}`;
+            if (add)
+                entries.add(entry);
+            else
+                entries.delete(entry);
+        }
+        return _a.#of(entries);
+    }
+    allowPublic(...perms) {
+        return this.#changed('*', perms, true);
+    }
+    allowUser(user, ...perms) {
+        return this.#changed(`user:${user.id}`, perms, true);
+    }
+    allowRole(role, ...perms) {
+        return this.#changed(`role:${role.id}`, perms, true);
+    }
+    denyPublic(...perms) {
+        return this.#changed('*', perms, false);
+    }
+    denyUser(user, ...perms) {
+        return this.#changed(`user:${user.id}`, perms, false);
+    }
+    denyRole(role, ...perms) {
+        return this.#changed(`role:${role.id}`, perms, false);
+    }
+    publicCan(permission) {
+        return this.#entries.has(`${permission}:*`);
+    }
+    userCan(user, permission) {
+        return this.#entries.has(`${permission}:user:${user.id}`);
+    }
+    roleCan(role, permission) {
+        return this.#entries.has(`${permission}:role:${role.id}`);
+    }
+    /** The ids of the users having the permission. */
+    users(permission) {
+        return this.#ids(`${permission}:user:`);
+    }
+    /** The ids of the roles having the permission. */
+    roles(permission) {
+        return this.#ids(`${permission}:role:`);
+    }
+    #ids(prefix) {
+        return this.entries()
+            .filter((entry) => entry.startsWith(prefix))
+            .map((entry) => entry.slice(prefix.length));
+    }
+    /**
+     * Whether the caller has the permission, through the public, its user or
+     * one of its roles; a write needs the read too, as the queries do. True
+     * for Master.
+     */
+    allows(caller, permission) {
+        if (caller.kind === 'master')
+            return true;
+        const keys = subjectsOf(caller);
+        const has = (wanted) => keys.some((key) => this.#entries.has(`${wanted}:${key}`));
+        return has('read') && (permission === 'read' || has('write'));
+    }
+    /** Its entries as stored, sorted. */
+    entries() {
+        return [...this.#entries].toSorted();
+    }
+    /** What a client reads: `{ read: ['*'], write: ['user:u_1'] }`. */
+    toJSON() {
+        const subjects = (permission) => this.entries()
+            .filter((entry) => permissionOf(entry) === permission)
+            .map((entry) => entry.slice(permission.length + 1));
+        return { read: subjects('read'), write: subjects('write') };
+    }
+}
+_a = ACL;
+/** The subjects a caller other than Master is: `*`, its user, its roles. */
+export function subjectsOf(caller) {
+    if (caller.kind !== 'user')
+        return ['*'];
+    return [
+        '*',
+        `user:${caller.user.id}`,
+        ...rolesOf(caller).map(({ id }) => `role:${id}`),
+    ];
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { AclJson, Permission } from './acl.ts';
+export { ACL } from './acl.ts';
+export type { Acl, AclDefault, AclField, AclInput, AclOptions, } from './plugin.ts';
+export { acl, aclPlugin } 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,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAC9B,YAAY,EACX,GAAG,EACH,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,UAAU,GACV,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { ACL } from './acl.js';
+export { acl, aclPlugin } from './plugin.js';

package/dist/plugin.d.ts

@@ -0,0 +1,39 @@
+import type { Caller, Field, ModelUse, PluginOf, PluginTypes } from 'ultimabase';
+import type { AclJson } from './acl.ts';
+import { ACL } from './acl.ts';
+/** What an `acl` field takes: an `ACL`, or its JSON. */
+export type AclInput = ACL | AclJson;
+/** The ACL of a row created without one, from the caller (D-124). */
+export type AclDefault = (facts: {
+    readonly caller: Caller;
+}) => ACL;
+export type AclOptions = {
+    readonly default: AclDefault;
+};
+type Stored = Field<readonly string[], {
+    readonly list: true;
+}>;
+/** The `acl` field a model that uses the plugin gets. */
+export type AclField = Field<ACL, {
+    readonly list: true;
+    readonly default: AclDefault;
+}, 'acl', never, AclInput, true, Stored>;
+/** The ACL plugin's types (D-57). */
+export interface Acl extends PluginTypes {
+    readonly name: 'acl';
+    readonly options: AclOptions;
+    readonly addedFields: {
+        readonly acl: AclField;
+    };
+}
+/** The ACL plugin, which `plugins` lists. */
+export declare const aclPlugin: PluginOf<Acl>;
+/**
+ * A model's per-row rights: an `acl` field, `default` giving the ACL of a
+ * row created without one (D-124).
+ */
+export declare function acl(options: AclOptions): ModelUse<'acl', Acl & {
+    readonly options: AclOptions;
+}>;
+export {};
+//# 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,KAAK,EAEL,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,MAAM,YAAY,CAAA;AAGnB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,EAAE,GAAG,EAAsB,MAAM,UAAU,CAAA;AAElD,wDAAwD;AACxD,MAAM,MAAM,QAAQ,GAAG,GAAG,GAAG,OAAO,CAAA;AAEpC,qEAAqE;AACrE,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAK,GAAG,CAAA;AAEpE,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAA;AAEzD,KAAK,MAAM,GAAG,KAAK,CAAC,SAAS,MAAM,EAAE,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAA;AAE/D,yDAAyD;AACzD,MAAM,MAAM,QAAQ,GAAG,KAAK,CAC3B,GAAG,EACH;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAE,EACrD,KAAK,EACL,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,MAAM,CACN,CAAA;AAED,qCAAqC;AACrC,MAAM,WAAW,GAAI,SAAQ,WAAW;IACvC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAA;KAAE,CAAA;CAChD;AAqED,6CAA6C;AAC7C,eAAO,MAAM,SAAS,EAAE,QAAQ,CAAC,GAAG,CAAqB,CAAA;AAEzD;;;GAGG;AACH,wBAAgB,GAAG,CAClB,OAAO,EAAE,UAAU,GACjB,QAAQ,CAAC,KAAK,EAAE,GAAG,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC,CAEzD"}

package/dist/plugin.js

@@ -0,0 +1,63 @@
+import { defineFieldType, definePlugin, Refused } from 'ultimabase';
+import manifest from '../package.json' with { type: 'json' };
+import { ACL, parsed, subjectsOf } from './acl.js';
+/** A Standard Schema taking an `ACL` or `{ read, write }`. */
+const schema = {
+    '~standard': {
+        version: 1,
+        vendor: 'ultimabase-acl',
+        validate: (value) => {
+            const given = parsed(value);
+            return typeof given === 'string'
+                ? { issues: [{ message: given }] }
+                : { value: given };
+        },
+    },
+};
+const aclType = defineFieldType({
+    plugin: 'acl',
+    stored: (f) => f.string({ list: true }),
+    decode: (stored) => ACL.fromEntries(stored),
+    encode: (rights) => rights.entries(),
+    schema,
+    toJSON: (rights) => rights.toJSON(),
+});
+/** The keys the caller's subjects give for a permission. */
+const keys = (caller, permission) => subjectsOf(caller).map((subject) => `${permission}:${subject}`);
+const definition = definePlugin({
+    name: 'acl',
+    manifest,
+    addedFields: (_f, options) => {
+        const fallback = Reflect.get(Object(options), 'default');
+        if (typeof fallback !== 'function') {
+            throw new Refused('acl() takes default: the ACL of a row created without one.');
+        }
+        // Only Master writes an ACL: sharing is a function's (D-124).
+        return {
+            acl: aclType({ default: options.default }).with({
+                access: { create: () => false, update: () => false },
+            }),
+        };
+    },
+    addedIndexes: [{ fields: ['acl'] }],
+    hooks: {
+        beforeFind: ({ caller, operation, where }) => {
+            if (caller.kind === 'master')
+                return undefined;
+            const read = { acl: { hasSome: keys(caller, 'read') } };
+            if (operation === 'read')
+                return where(read);
+            // A caller writes the rows it reads.
+            return where({ AND: [read, { acl: { hasSome: keys(caller, 'write') } }] });
+        },
+    },
+});
+/** The ACL plugin, which `plugins` lists. */
+export const aclPlugin = definition.plugin;
+/**
+ * A model's per-row rights: an `acl` field, `default` giving the ACL of a
+ * row created without one (D-124).
+ */
+export function acl(options) {
+    return definition.use(options);
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@ultimabase/acl",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Per-row rights for UltimaBase: who may read and write each row, as Parse's ACL.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://ultimabase.dev/docs/acl",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrEkinox/ultimabase.git",
+    "directory": "packages/acl"
+  },
+  "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/roles": "^0.1.1",
+    "ultimabase": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/pg": "8.23.1",
+    "@ultimabase/postgres": "0.1.1",
+    "@ultimabase/roles": "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/acl.ts

@@ -0,0 +1,196 @@
+// The `ACL` class (D-124): who may read and who may write one row, as
+// entries `read:*`, `read:user:<id>` and `write:role:<id>`. Each method
+// returns a new ACL.
+import { rolesOf } from '@ultimabase/roles'
+import type { Caller } from 'ultimabase'
+
+/** `write` is update and delete (D-124). */
+export type Permission = 'read' | 'write'
+
+/** What a client reads, and may send: the subjects of each permission. */
+export type AclJson = {
+	readonly read: readonly string[]
+	readonly write: readonly string[]
+}
+
+const permissions: readonly Permission[] = ['read', 'write']
+
+const isSubject = (subject: string): boolean =>
+	subject === '*' || /^(?:user|role):.+$/u.test(subject)
+
+/** The entry's permission, or `undefined` when it is not an entry. */
+function permissionOf(entry: string): Permission | undefined {
+	const permission = permissions.find((each) => entry.startsWith(`${each}:`))
+	if (permission === undefined) return undefined
+	return isSubject(entry.slice(permission.length + 1)) ? permission : undefined
+}
+
+/** The permissions given, or both when none is. */
+const given = (perms: readonly Permission[]): readonly Permission[] =>
+	perms.length === 0 ? permissions : perms
+
+/**
+ * The ACL a value is, or what it lacks: an `ACL`, or `{ read, write }`
+ * listing subjects `*`, `user:<id>` or `role:<id>`.
+ */
+export function parsed(value: unknown): ACL | string {
+	if (value instanceof ACL) return value
+	if (typeof value !== 'object' || value === null) {
+		return 'An ACL is an ACL or { read, write }.'
+	}
+	const entries: string[] = []
+	for (const key of Object.keys(value)) {
+		const permission = permissions.find((each) => each === key)
+		if (permission === undefined) return `${key} is not a permission.`
+		const subjects: unknown = Reflect.get(value, key)
+		if (!Array.isArray(subjects)) return `${key} is a list of subjects.`
+		for (const [index, subject] of subjects.entries()) {
+			if (typeof subject !== 'string' || !isSubject(subject)) {
+				return `${key}[${index}]: a subject is *, user:<id> or role:<id>.`
+			}
+			entries.push(`${permission}:${subject}`)
+		}
+	}
+	return ACL.fromEntries(entries)
+}
+
+/** Who may read and who may write one row; empty, only Master (D-124). */
+export class ACL {
+	#entries: ReadonlySet<string> = new Set()
+
+	static #of(entries: ReadonlySet<string>): ACL {
+		const acl = new ACL()
+		acl.#entries = entries
+		return acl
+	}
+
+	/** Its entries as stored, as `['read:*', 'write:user:u_1']`. */
+	static fromEntries(entries: Iterable<string>): ACL {
+		const kept = new Set<string>()
+		for (const entry of entries) {
+			if (permissionOf(entry) === undefined) {
+				throw new TypeError(`${entry} is not an ACL entry.`)
+			}
+			kept.add(entry)
+		}
+		return ACL.#of(kept)
+	}
+
+	/** What `toJSON` gives, or a client sends. */
+	static fromJSON(json: unknown): ACL {
+		const acl = parsed(json)
+		if (typeof acl === 'string') throw new TypeError(acl)
+		return acl
+	}
+
+	#changed(subject: string, perms: readonly Permission[], add: boolean): ACL {
+		const entries = new Set(this.#entries)
+		for (const permission of given(perms)) {
+			const entry = `${permission}:${subject}`
+			if (add) entries.add(entry)
+			else entries.delete(entry)
+		}
+		return ACL.#of(entries)
+	}
+
+	allowPublic(...perms: readonly Permission[]): ACL {
+		return this.#changed('*', perms, true)
+	}
+
+	allowUser(
+		user: { readonly id: string },
+		...perms: readonly Permission[]
+	): ACL {
+		return this.#changed(`user:${user.id}`, perms, true)
+	}
+
+	allowRole(
+		role: { readonly id: string },
+		...perms: readonly Permission[]
+	): ACL {
+		return this.#changed(`role:${role.id}`, perms, true)
+	}
+
+	denyPublic(...perms: readonly Permission[]): ACL {
+		return this.#changed('*', perms, false)
+	}
+
+	denyUser(
+		user: { readonly id: string },
+		...perms: readonly Permission[]
+	): ACL {
+		return this.#changed(`user:${user.id}`, perms, false)
+	}
+
+	denyRole(
+		role: { readonly id: string },
+		...perms: readonly Permission[]
+	): ACL {
+		return this.#changed(`role:${role.id}`, perms, false)
+	}
+
+	publicCan(permission: Permission): boolean {
+		return this.#entries.has(`${permission}:*`)
+	}
+
+	userCan(user: { readonly id: string }, permission: Permission): boolean {
+		return this.#entries.has(`${permission}:user:${user.id}`)
+	}
+
+	roleCan(role: { readonly id: string }, permission: Permission): boolean {
+		return this.#entries.has(`${permission}:role:${role.id}`)
+	}
+
+	/** The ids of the users having the permission. */
+	users(permission: Permission): readonly string[] {
+		return this.#ids(`${permission}:user:`)
+	}
+
+	/** The ids of the roles having the permission. */
+	roles(permission: Permission): readonly string[] {
+		return this.#ids(`${permission}:role:`)
+	}
+
+	#ids(prefix: string): readonly string[] {
+		return this.entries()
+			.filter((entry) => entry.startsWith(prefix))
+			.map((entry) => entry.slice(prefix.length))
+	}
+
+	/**
+	 * Whether the caller has the permission, through the public, its user or
+	 * one of its roles; a write needs the read too, as the queries do. True
+	 * for Master.
+	 */
+	allows(caller: Caller, permission: Permission): boolean {
+		if (caller.kind === 'master') return true
+		const keys = subjectsOf(caller)
+		const has = (wanted: Permission) =>
+			keys.some((key) => this.#entries.has(`${wanted}:${key}`))
+		return has('read') && (permission === 'read' || has('write'))
+	}
+
+	/** Its entries as stored, sorted. */
+	entries(): readonly string[] {
+		return [...this.#entries].toSorted()
+	}
+
+	/** What a client reads: `{ read: ['*'], write: ['user:u_1'] }`. */
+	toJSON(): AclJson {
+		const subjects = (permission: Permission) =>
+			this.entries()
+				.filter((entry) => permissionOf(entry) === permission)
+				.map((entry) => entry.slice(permission.length + 1))
+		return { read: subjects('read'), write: subjects('write') }
+	}
+}
+
+/** The subjects a caller other than Master is: `*`, its user, its roles. */
+export function subjectsOf(caller: Caller): readonly string[] {
+	if (caller.kind !== 'user') return ['*']
+	return [
+		'*',
+		`user:${caller.user.id}`,
+		...rolesOf(caller).map(({ id }) => `role:${id}`),
+	]
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+// `@ultimabase/acl` (D-124): who may read and who may write each row, stored
+// in the row and filtered in its query.
+export type { AclJson, Permission } from './acl.ts'
+export { ACL } from './acl.ts'
+export type {
+	Acl,
+	AclDefault,
+	AclField,
+	AclInput,
+	AclOptions,
+} from './plugin.ts'
+export { acl, aclPlugin } from './plugin.ts'

package/src/plugin.ts

@@ -0,0 +1,123 @@
+// `aclPlugin()` and `acl({ default })` (D-124): an `acl` field on each model
+// that uses it, which only Master writes, and a beforeFind keeping the rows
+// the caller may read, or write too for the rows a write targets.
+import type {
+	Caller,
+	Field,
+	FieldType,
+	ModelUse,
+	PluginOf,
+	PluginTypes,
+} from 'ultimabase'
+import { defineFieldType, definePlugin, Refused } from 'ultimabase'
+import manifest from '../package.json' with { type: 'json' }
+import type { AclJson } from './acl.ts'
+import { ACL, parsed, subjectsOf } from './acl.ts'
+
+/** What an `acl` field takes: an `ACL`, or its JSON. */
+export type AclInput = ACL | AclJson
+
+/** The ACL of a row created without one, from the caller (D-124). */
+export type AclDefault = (facts: { readonly caller: Caller }) => ACL
+
+export type AclOptions = { readonly default: AclDefault }
+
+type Stored = Field<readonly string[], { readonly list: true }>
+
+/** The `acl` field a model that uses the plugin gets. */
+export type AclField = Field<
+	ACL,
+	{ readonly list: true; readonly default: AclDefault },
+	'acl',
+	never,
+	AclInput,
+	true,
+	Stored
+>
+
+/** The ACL plugin's types (D-57). */
+export interface Acl extends PluginTypes {
+	readonly name: 'acl'
+	readonly options: AclOptions
+	readonly addedFields: { readonly acl: AclField }
+}
+
+type Result =
+	| { readonly value: ACL }
+	| { readonly issues: readonly { readonly message: string }[] }
+
+/** A Standard Schema taking an `ACL` or `{ read, write }`. */
+const schema: {
+	readonly '~standard': {
+		readonly version: 1
+		readonly vendor: string
+		readonly validate: (value: unknown) => Result
+		readonly types?: { readonly input: AclInput; readonly output: ACL }
+	}
+} = {
+	'~standard': {
+		version: 1,
+		vendor: 'ultimabase-acl',
+		validate: (value) => {
+			const given = parsed(value)
+			return typeof given === 'string'
+				? { issues: [{ message: given }] }
+				: { value: given }
+		},
+	},
+}
+
+const aclType: FieldType<'acl', Stored, ACL, AclInput> = defineFieldType({
+	plugin: 'acl',
+	stored: (f) => f.string({ list: true }),
+	decode: (stored) => ACL.fromEntries(stored),
+	encode: (rights) => rights.entries(),
+	schema,
+	toJSON: (rights) => rights.toJSON(),
+})
+
+/** The keys the caller's subjects give for a permission. */
+const keys = (caller: Caller, permission: 'read' | 'write') =>
+	subjectsOf(caller).map((subject) => `${permission}:${subject}`)
+
+const definition = definePlugin<Acl>({
+	name: 'acl',
+	manifest,
+	addedFields: (_f, options) => {
+		const fallback: unknown = Reflect.get(Object(options), 'default')
+		if (typeof fallback !== 'function') {
+			throw new Refused(
+				'acl() takes default: the ACL of a row created without one.',
+			)
+		}
+		// Only Master writes an ACL: sharing is a function's (D-124).
+		return {
+			acl: aclType({ default: options.default }).with({
+				access: { create: () => false, update: () => false },
+			}),
+		}
+	},
+	addedIndexes: [{ fields: ['acl'] }],
+	hooks: {
+		beforeFind: ({ caller, operation, where }) => {
+			if (caller.kind === 'master') return undefined
+			const read = { acl: { hasSome: keys(caller, 'read') } }
+			if (operation === 'read') return where(read)
+			// A caller writes the rows it reads.
+			return where({ AND: [read, { acl: { hasSome: keys(caller, 'write') } }] })
+		},
+	},
+})
+
+/** The ACL plugin, which `plugins` lists. */
+export const aclPlugin: PluginOf<Acl> = definition.plugin
+
+/**
+ * A model's per-row rights: an `acl` field, `default` giving the ACL of a
+ * row created without one (D-124).
+ */
+export function acl(
+	options: AclOptions,
+): ModelUse<'acl', Acl & { readonly options: AclOptions }> {
+	return definition.use(options)
+}