@procedures/access 0.0.0-stage → 0.12.2

package/dist/access.js

@@ -0,0 +1,159 @@
+/**
+ * The rights of a subject on a scope. A scope is a name of an app, for example `space`,
+ * `board:b1` or `user:u1`. A scope can have an access list: an owner, and entries that give
+ * rights to principals. An entry can have a `when` condition over the document of the check.
+ *
+ * The app gives its own rules as a policy: the rights that hold without a list (the owner of a
+ * personal scope), the parent of a scope without a list, and the rights of a scope without a list
+ * and without a parent. The engine does the rest.
+ */
+/** The default model: `admin` implies `share` and `write`, and each of them implies `read`. */
+export const DEFAULT_RIGHTS = Object.freeze({
+    all: Object.freeze(["read", "write", "share", "admin"]),
+    implies: Object.freeze({ admin: Object.freeze(["share", "write"]), share: Object.freeze(["read"]), write: Object.freeze(["read"]) }),
+});
+const normalEmail = (email) => (email ?? "").trim().toLowerCase();
+/** The engine of the rights of a policy. */
+export class Access {
+    #policy;
+    #model;
+    constructor(policy = {}) {
+        this.#policy = policy;
+        this.#model = policy.rights ?? DEFAULT_RIGHTS;
+    }
+    /** This method gives the rights and each right that they imply. It ignores a right that the model does not know. */
+    implied(rights) {
+        const out = new Set();
+        const add = (right) => {
+            if (out.has(right) || !this.#model.all.includes(right))
+                return;
+            out.add(right);
+            // An own field only: a right named `__proto__` or `constructor` reads nothing of the prototype
+            const next = Object.hasOwn(this.#model.implies, right) ? this.#model.implies[right] : undefined;
+            if (Array.isArray(next))
+                for (const implied of next)
+                    add(implied);
+        };
+        for (const right of rights)
+            add(right);
+        return out;
+    }
+    /** True when an access-list principal names the subject. */
+    names(principal, subject) {
+        const custom = this.#policy.names?.(principal, subject);
+        if (custom !== undefined)
+            return custom;
+        if (principal === "anyone")
+            return true;
+        if (!subject.user)
+            return false;
+        if (principal === "signed-in")
+            return true;
+        return this.#namesOne(principal, subject);
+    }
+    /** True when a principal of one user, one email or one group names the subject (the built-in names only). */
+    #namesOne(principal, subject) {
+        if (!subject.user)
+            return false;
+        if (principal === `user:${subject.user}`)
+            return true;
+        if (principal.startsWith("email:"))
+            return !!subject.email && normalEmail(principal.slice("email:".length)) === normalEmail(subject.email);
+        if (principal.startsWith("group:"))
+            return !!subject.groups?.some((group) => principal === `group:${group.id}`);
+        return false;
+    }
+    /** The variables of a `when` condition for a subject. */
+    #variables(subject, context) {
+        return {
+            principal: { user: subject.user ?? null, email: subject.email ?? null, groups: (subject.groups ?? []).map((group) => group.id), signedIn: !!subject.user },
+            doc: context.doc ?? null,
+            prev: context.prev ?? null,
+            op: context.op,
+        };
+    }
+    /** The rights that an access list gives a subject. */
+    listRights(list, subject, context) {
+        // The owner names one user, one email or one group: never a name of the policy, `anyone` or `signed-in`
+        if (list.owner !== undefined && this.#namesOne(list.owner, subject)) {
+            return new Set(this.#model.all);
+        }
+        const rights = [];
+        for (const entry of list.access ?? []) {
+            if (typeof entry?.principal !== "string" || !this.names(entry.principal, subject))
+                continue;
+            if (entry.when !== undefined) {
+                if (!context || !this.#policy.evaluate)
+                    continue;
+                let passes = false;
+                try {
+                    passes = this.#policy.evaluate(entry.when, this.#variables(subject, context)) === true;
+                }
+                catch {
+                    passes = false;
+                }
+                if (!passes)
+                    continue;
+            }
+            for (const right of entry.rights ?? [])
+                rights.push(right);
+        }
+        return this.implied(rights);
+    }
+    /** The rights of a subject on a scope. */
+    rightsOn(scope, subject, lists, context) {
+        if ((this.#policy.superuser ?? ((s) => s.agent === true && !s.user))(subject))
+            return new Set(this.#model.all);
+        const seen = new Set();
+        for (let current = scope; current !== undefined && !seen.has(current); current = this.#policy.parent?.(current)) {
+            seen.add(current);
+            const implicit = this.#policy.implicit?.(current, subject);
+            if (implicit !== undefined)
+                return this.implied(implicit);
+            const list = lists.get(current);
+            if (list)
+                return this.listRights(list, subject, context);
+            if (this.#policy.parent?.(current) === undefined)
+                return this.implied(this.#policy.fallback?.(current, subject) ?? []);
+        }
+        return new Set();
+    }
+    /** True when the subject has the right on the scope. */
+    can(right, scope, subject, lists, context) {
+        return this.rightsOn(scope, subject, lists, context).has(right);
+    }
+    /**
+     * True when a conditional entry of the list of the scope (or of the first list of its parents) can
+     * give the subject the right on some documents. Then check each document with its context.
+     */
+    conditionalOn(right, scope, subject, lists) {
+        const seen = new Set();
+        let list;
+        for (let current = scope; current !== undefined && !seen.has(current) && !list; current = this.#policy.parent?.(current)) {
+            seen.add(current);
+            list = lists.get(current);
+        }
+        return !!list?.access?.some((entry) => entry?.when !== undefined && typeof entry.principal === "string" && this.names(entry.principal, subject) && this.implied(entry.rights ?? []).has(right));
+    }
+    /** The scopes of a list that the subject can read. */
+    readable(scopes, subject, lists) {
+        return scopes.filter((scope) => this.can("read", scope, subject, lists));
+    }
+}
+/** This function checks a stored access list: it keeps only the known fields and the entries with a principal and rights. */
+export function asAccessList(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const record = raw;
+    const access = Array.isArray(record["access"])
+        ? record["access"]
+            .filter((entry) => typeof entry === "object" && entry !== null && typeof entry["principal"] === "string" && Array.isArray(entry["rights"]))
+            .map((entry) => ({
+            principal: entry["principal"],
+            rights: entry["rights"].filter((right) => typeof right === "string"),
+            ...(entry["when"] !== undefined ? { when: entry["when"] } : {}),
+        }))
+        : undefined;
+    return { ...(typeof record["owner"] === "string" ? { owner: record["owner"] } : {}), ...(access ? { access } : {}) };
+}
+//# sourceMappingURL=access.js.map

package/dist/access.js.map

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

package/dist/admit.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The subject of a principal, and the output filter of a host (`admitItem`) from the access lists.
+ */
+import type { AdmitItem, Invocation, Principal } from "@procedures/client";
+import type { Access, AccessLists, AccessSubject, Right } from "./access.js";
+/** The options of `subjectOf`. */
+export interface SubjectOfOptions {
+    /** The `via` of a principal without a user (default `anonymous`). */
+    readonly anonymousVia?: readonly string[] | undefined;
+    /** The `via` of a service account: an agent without a user (default `agent-token` and the host token `token`). */
+    readonly serviceVia?: readonly string[] | undefined;
+}
+/**
+ * This function gives the subject of a principal of the request hook. The `via` of the principal
+ * decides: a service account, anonymous, or a user with the id of the principal. The id never
+ * decides, so a user with the id `agent` stays a user. The claims give `email`, `groups` and
+ * `agent`. Without a principal (a refused request, or a call from this process), the subject is
+ * anonymous.
+ */
+export declare function subjectOf(principal: Principal | undefined, options?: SubjectOfOptions): AccessSubject;
+/** The options of `accessAdmitItem`. */
+export interface AccessAdmitOptions {
+    readonly access: Access;
+    /** The access lists for an invocation, for example from a cache of the documents of the lists. */
+    readonly lists: (invocation: Invocation) => AccessLists | Promise<AccessLists>;
+    /** The scope of an item. An item without a scope is refused. */
+    readonly scopeOf: (item: unknown) => string | undefined;
+    /** The subject of the principal of the call (default `subjectOf`). */
+    readonly subjectOf?: ((principal: Principal | undefined) => AccessSubject) | undefined;
+    /** The right that an item needs (default `read`). */
+    readonly right?: Right | undefined;
+}
+/**
+ * This function gives the output filter of a host (`admitItem`): it admits an item when the
+ * subject has the right on the scope of the item. A conditional entry sees the item as `doc`.
+ */
+export declare function accessAdmitItem(options: AccessAdmitOptions): AdmitItem;
+//# sourceMappingURL=admit.d.ts.map

package/dist/admit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admit.d.ts","sourceRoot":"","sources":["../src/admit.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAE7E,kCAAkC;AAClC,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACtD,kHAAkH;IAClH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CACrD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,OAAO,GAAE,gBAAqB,GAAG,aAAa,CAiBzG;AAED,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kGAAkG;IAClG,QAAQ,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/E,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;IACxD,sEAAsE;IACtE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,KAAK,aAAa,CAAC,GAAG,SAAS,CAAC;IACvF,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,CAWtE"}

package/dist/admit.js

@@ -0,0 +1,47 @@
+/**
+ * This function gives the subject of a principal of the request hook. The `via` of the principal
+ * decides: a service account, anonymous, or a user with the id of the principal. The id never
+ * decides, so a user with the id `agent` stays a user. The claims give `email`, `groups` and
+ * `agent`. Without a principal (a refused request, or a call from this process), the subject is
+ * anonymous.
+ */
+export function subjectOf(principal, options = {}) {
+    if (!principal)
+        return {};
+    if ((options.serviceVia ?? ["agent-token", "token"]).includes(principal.via))
+        return { agent: true };
+    if ((options.anonymousVia ?? ["anonymous"]).includes(principal.via))
+        return {};
+    const claims = principal.claims ?? {};
+    const email = typeof claims["email"] === "string" && claims["email"] ? claims["email"] : undefined;
+    const groups = Array.isArray(claims["groups"])
+        ? claims["groups"]
+            .filter((group) => typeof group === "object" && group !== null && "id" in group)
+            .map((group) => ({ id: String(group.id), role: typeof group.role === "string" ? group.role : "member" }))
+        : undefined;
+    return {
+        user: principal.id,
+        ...(email ? { email } : {}),
+        ...(groups ? { groups } : {}),
+        ...(claims["agent"] === true ? { agent: true } : {}),
+    };
+}
+/**
+ * This function gives the output filter of a host (`admitItem`): it admits an item when the
+ * subject has the right on the scope of the item. A conditional entry sees the item as `doc`.
+ */
+export function accessAdmitItem(options) {
+    const right = options.right ?? "read";
+    const subjectFor = options.subjectOf ?? ((principal) => subjectOf(principal));
+    return async (item, invocation) => {
+        const scope = options.scopeOf(item);
+        if (scope === undefined)
+            return false;
+        const subject = subjectFor(invocation.principal);
+        const lists = await options.lists(invocation);
+        if (options.access.can(right, scope, subject, lists))
+            return true;
+        return options.access.conditionalOn(right, scope, subject, lists) && options.access.can(right, scope, subject, lists, { op: right, doc: item });
+    };
+}
+//# sourceMappingURL=admit.js.map

package/dist/admit.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./access.js";
+export * from "./admit.js";
+//# 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":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./access.js";
+export * from "./admit.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here.
+ */
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,60 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/access",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.12.2",
+  "description": "The rights of a principal on a scope: access lists, owners, implied rights and conditions over a document, with the rules of the app as a policy, and the output filter of a host.",
+  "keywords": [
+    "procedures",
+    "access-control",
+    "authorization",
+    "acl",
+    "permissions",
+    "rights",
+    "principal"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/access"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "client": null,
+  "dependencies": {
+    "@procedures/client": "0.12.2",
+    "zod": "^4.6.5"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
 }

package/src/access.test.ts

@@ -0,0 +1,243 @@
+import { describe, expect, it } from "vitest";
+import type { Invocation } from "@procedures/client";
+import { Access, accessAdmitItem, asAccessList, DEFAULT_RIGHTS, subjectOf, type AccessList, type AccessPolicy, type AccessSubject } from "./index.js";
+
+const ALL = DEFAULT_RIGHTS.all;
+const norm = (email: string | undefined) => (email ?? "").trim().toLowerCase();
+
+/**
+ * The rules of an app with spaces, boards, groups and personal scopes, as a policy: `user:<id>`
+ * and `member:<board>:<id>` belong to their person, a group gives rights to its members, a board
+ * without a list follows the space, the space owners cannot be locked out, and `link` is anyone.
+ */
+function boardsPolicy(spaceOwners: readonly string[], evaluate?: AccessPolicy["evaluate"]): AccessPolicy {
+  return {
+    evaluate,
+    names: (principal) => (principal === "link" ? true : undefined),
+    implicit: (scope, subject) => {
+      if (scope.startsWith("user:")) return subject.user && scope === `user:${subject.user}` ? ALL : undefined;
+      if (scope.startsWith("member:")) return subject.user && scope.slice(scope.lastIndexOf(":") + 1) === subject.user ? ["read", "write"] : undefined;
+      if (scope.startsWith("group:")) {
+        const group = subject.groups?.find((g) => `group:${g.id}` === scope);
+        return group ? (group.role === "owner" || group.role === "admin" ? ALL : ["read", "write"]) : undefined;
+      }
+      if (scope !== "space" && !scope.startsWith("board:")) return [];
+      return subject.user && subject.email && spaceOwners.map(norm).includes(norm(subject.email)) ? ALL : undefined;
+    },
+    parent: (scope) => (scope.startsWith("board:") ? "space" : undefined),
+    fallback: (scope, subject) => (scope === "space" && subject.user && spaceOwners.length === 0 ? ["read", "write"] : []),
+  };
+}
+
+const lists = (...entries: [string, AccessList][]) => new Map(entries);
+const open = new Access(boardsPolicy([]));
+const owned = new Access(boardsPolicy(["mark@example.com"]));
+const mark: AccessSubject = { user: "u_mark", email: "Mark@Example.com" };
+const ana: AccessSubject = { user: "u_ana", email: "ana@example.com", groups: [{ id: "core", role: "member" }] };
+const anon: AccessSubject = {};
+const sorted = (rights: Set<string>) => [...rights].sort();
+
+describe("the rights of a subject on a scope", () => {
+  it("anonymous: no rights, except an entry for anyone", () => {
+    const pub = lists(["board:pub", { access: [{ principal: "link", rights: ["read"] }] }]);
+    expect(sorted(open.rightsOn("space", anon, lists()))).toEqual([]);
+    expect(owned.can("read", "board:pub", anon, pub)).toBe(true);
+    expect(owned.can("write", "board:pub", anon, pub)).toBe(false);
+    expect(new Access().can("read", "x", anon, lists(["x", { access: [{ principal: "anyone", rights: ["read"] }] }]))).toBe(true);
+  });
+
+  it("a scope without a list: the fallback, or the implicit rights of the owners", () => {
+    expect(open.can("write", "space", ana, lists())).toBe(true);
+    expect(open.can("admin", "space", ana, lists())).toBe(false);
+    expect(owned.can("admin", "space", mark, lists())).toBe(true); // the emails compare without case
+    expect(owned.can("read", "space", ana, lists())).toBe(false);
+  });
+
+  it("a personal scope belongs to its person, and a scope of an unknown kind gives nothing", () => {
+    expect(owned.can("admin", "user:u_ana", ana, lists())).toBe(true);
+    expect(owned.can("read", "user:u_ana", mark, lists())).toBe(false);
+    expect(owned.can("write", "member:roadmap:u_ana", ana, lists())).toBe(true);
+    expect(owned.can("read", "member:roadmap:u_ana", mark, lists())).toBe(false);
+    expect(owned.can("read", "other:x", mark, lists(["other:x", { access: [{ principal: "signed-in", rights: ["read"] }] }]))).toBe(false);
+  });
+
+  it("a scope without a list follows its parent, and a list decides with its owner and its entries", () => {
+    expect(owned.can("write", "board:b1", mark, lists())).toBe(true);
+    expect(owned.can("read", "board:b1", ana, lists())).toBe(false);
+    const board = lists(["board:b1", { owner: "user:u_mark", access: [{ principal: "group:core", rights: ["write"] }, { principal: "email:zoe@example.com", rights: ["read"] }] }]);
+    expect(sorted(owned.rightsOn("board:b1", mark, board))).toEqual(["admin", "read", "share", "write"]);
+    expect(sorted(owned.rightsOn("board:b1", ana, board))).toEqual(["read", "write"]); // write implies read
+    expect(owned.can("read", "board:b1", { user: "u_zoe", email: "ZOE@example.com" }, board)).toBe(true);
+    expect(owned.can("write", "board:b1", { user: "u_zoe", email: "zoe@example.com" }, board)).toBe(false);
+  });
+
+  it("a group: the members read and write, the owners and the admins have each right", () => {
+    expect(sorted(owned.rightsOn("group:core", ana, lists()))).toEqual(["read", "write"]);
+    expect(owned.can("admin", "group:core", { user: "u_x", groups: [{ id: "core", role: "owner" }] }, lists())).toBe(true);
+    expect(owned.can("read", "group:core", mark, lists())).toBe(false);
+  });
+
+  it("a list cannot lock out a subject with implicit rights, and its owner has each right", () => {
+    const locked = lists(["space", { owner: "user:u_ana", access: [] }], ["board:b2", { access: [] }]);
+    expect(owned.can("admin", "space", mark, locked)).toBe(true);
+    expect(owned.can("admin", "board:b2", mark, locked)).toBe(true);
+    expect(owned.can("read", "board:b2", ana, locked)).toBe(false);
+    expect(owned.can("admin", "space", ana, locked)).toBe(true);
+  });
+
+  it("an owner names one user, one email or one group: never anyone, signed-in or a name of the policy", () => {
+    expect(new Access().can("admin", "x", ana, lists(["x", { owner: "signed-in" }]))).toBe(false);
+    expect(new Access().can("admin", "x", ana, lists(["x", { owner: "anyone" }]))).toBe(false);
+    expect(owned.can("admin", "board:o", anon, lists(["board:o", { owner: "link" }]))).toBe(false);
+    expect(owned.can("admin", "board:o", ana, lists(["board:o", { owner: "link" }]))).toBe(false);
+    expect(owned.can("admin", "board:o", ana, lists(["board:o", { owner: "group:core" }]))).toBe(true);
+    expect(owned.can("admin", "board:o", ana, lists(["board:o", { owner: "email:ANA@example.com" }]))).toBe(true);
+  });
+
+  it("the agent alone has each right, and an agent that acts for a user has the rights of the user", () => {
+    expect(owned.can("admin", "user:u_ana", { agent: true }, lists())).toBe(true);
+    expect(owned.can("admin", "space", { agent: true }, lists())).toBe(true);
+    const asAna = { ...ana, agent: true };
+    expect(owned.can("write", "user:u_ana", asAna, lists())).toBe(true);
+    expect(owned.can("read", "user:u_mark", asAna, lists())).toBe(false);
+    expect(owned.can("read", "space", asAna, lists())).toBe(false);
+    expect(new Access({ superuser: () => false }).can("read", "x", { agent: true }, lists())).toBe(false);
+  });
+
+  it("a when condition gives its rights only where it is exactly true, and an error is false", () => {
+    const evaluate = (condition: unknown, vars: Readonly<Record<string, unknown>>) => {
+      const c = condition as Record<string, unknown>;
+      const doc = vars["doc"] as Record<string, unknown> | null;
+      if (c["boom"]) throw new Error("bad");
+      if (c["ownerIsMe"]) return doc?.["owner"] === (vars["principal"] as { user: unknown }).user;
+      if (c["public"]) return doc?.["public"] === true;
+      if (c["truthy"]) return 1 as unknown as boolean;
+      return false;
+    };
+    const access = new Access(boardsPolicy(["mark@example.com"], evaluate));
+    const board = lists([
+      "board:c1",
+      {
+        owner: "user:u_mark",
+        access: [
+          { principal: "email:ana@example.com", rights: ["write"], when: { ownerIsMe: true } },
+          { principal: "email:ana@example.com", rights: ["read"], when: { public: true } },
+          { principal: "signed-in", rights: ["read"], when: { boom: true } },
+          { principal: "signed-in", rights: ["read"], when: { truthy: true } },
+        ],
+      },
+    ]);
+    expect(access.can("read", "board:c1", ana, board)).toBe(false); // no document: no conditional right
+    expect(access.conditionalOn("read", "board:c1", ana, board)).toBe(true);
+    expect(access.conditionalOn("write", "board:c1", ana, board)).toBe(true);
+    expect(access.conditionalOn("admin", "board:c1", ana, board)).toBe(false);
+    expect(access.can("write", "board:c1", ana, board, { op: "write", doc: { owner: "u_ana" } })).toBe(true);
+    expect(access.can("write", "board:c1", ana, board, { op: "write", doc: { owner: "u_mark" } })).toBe(false);
+    expect(access.can("read", "board:c1", ana, board, { op: "read", doc: { public: true } })).toBe(true);
+    expect(access.can("read", "board:c1", { user: "u_zoe" }, board, { op: "read", doc: {} })).toBe(false); // an error and a value that is not true
+    expect(access.can("admin", "board:c1", mark, board)).toBe(true); // the owner is unconditional
+    expect(new Access(boardsPolicy([])).can("read", "board:c1", ana, board, { op: "read", doc: { public: true } })).toBe(false); // no evaluator
+    expect(owned.conditionalOn("read", "board:none", ana, lists(["space", { access: [{ principal: "signed-in", rights: ["read"], when: {} }] }]))).toBe(true); // from the parent
+  });
+
+  it("gives the readable scopes, and stops at a cycle of parents", () => {
+    expect(open.readable(["member:b1:u_ana", "board:b1", "space"], ana, lists())).toEqual(["member:b1:u_ana", "board:b1", "space"]);
+    expect(owned.readable(["member:b1:u_ana", "board:b1", "space"], ana, lists())).toEqual(["member:b1:u_ana"]);
+    const loop = new Access({ parent: (scope) => (scope === "a" ? "b" : "a"), fallback: () => ["read"] });
+    expect(sorted(loop.rightsOn("a", ana, lists()))).toEqual([]);
+    expect(loop.conditionalOn("read", "a", ana, lists())).toBe(false);
+  });
+
+  it("follows the rights model of the policy, and ignores an unknown right", () => {
+    const model = new Access({ rights: { all: ["view", "edit"], implies: { edit: ["view"] } } });
+    expect(sorted(model.implied(["edit", "fly"]))).toEqual(["edit", "view"]);
+    expect(sorted(model.rightsOn("x", ana, lists(["x", { owner: "user:u_ana" }])))).toEqual(["edit", "view"]);
+  });
+
+  it("stops at a cycle of implications, and reads only own implications", () => {
+    const cycle = new Access({ rights: { all: ["a", "b"], implies: { a: ["b"], b: ["a"] } } });
+    expect(sorted(cycle.implied(["a"]))).toEqual(["a", "b"]);
+    const odd = new Access({ rights: { all: ["__proto__", "constructor", "toString"], implies: {} } });
+    expect(sorted(odd.implied(["__proto__", "constructor", "toString"]))).toEqual(["__proto__", "constructor", "toString"]);
+    const hostile = JSON.parse('{"__proto__":{"isAdmin":true},"owner":"user:u_ana","access":[{"principal":"anyone","rights":["read"],"__proto__":{"when":1}}]}');
+    const list = asAccessList(hostile)!;
+    expect(Object.getPrototypeOf(list)).toBe(Object.prototype);
+    expect(list.access?.[0]).toEqual({ principal: "anyone", rights: ["read"] });
+  });
+
+  it("reads a stored access list with care", () => {
+    expect(asAccessList({ _id: "board:b", owner: "user:u", access: [{ principal: "link", rights: ["read", 7] }, { bad: 1 }, null], extra: true })).toEqual({
+      owner: "user:u",
+      access: [{ principal: "link", rights: ["read"] }],
+    });
+    expect(asAccessList({ access: [{ principal: "x", rights: ["read"], when: { a: 1 } }] })?.access?.[0]?.when).toEqual({ a: 1 });
+    expect(asAccessList(null)).toBeUndefined();
+    expect(asAccessList({})).toEqual({});
+  });
+});
+
+describe("the subject of a principal", () => {
+  it("reads the user, the email, the groups and the agent mark", () => {
+    expect(subjectOf(undefined)).toEqual({});
+    expect(subjectOf({ id: "u1", via: "better-auth", claims: { email: "a@b.c", groups: [{ id: "g1", role: "owner" }, { id: 2 }, "bad"] } })).toEqual({
+      user: "u1",
+      email: "a@b.c",
+      groups: [{ id: "g1", role: "owner" }, { id: "2", role: "member" }],
+    });
+    expect(subjectOf({ id: "u1", via: "agent-as", claims: { agent: true } })).toEqual({ user: "u1", agent: true });
+    expect(subjectOf({ id: "agent", via: "agent-token" })).toEqual({ agent: true });
+    expect(subjectOf({ id: "token", via: "token" })).toEqual({ agent: true });
+    expect(subjectOf({ id: "anonymous", via: "anonymous" })).toEqual({});
+  });
+
+  it("decides by via, never by the id: a user with the id agent, token or anonymous is a user", () => {
+    for (const id of ["agent", "token", "anonymous"]) {
+      const subject = subjectOf({ id, via: "better-auth" });
+      expect(subject).toEqual({ user: id });
+      expect(owned.can("admin", "user:someone-else", subject, lists())).toBe(false);
+    }
+  });
+
+  it("a refused or unknown act-as is never a service account", () => {
+    // A refused act-as gives no principal, and an act-as for an unknown user is anonymous
+    for (const principal of [undefined, { id: "anonymous", via: "anonymous", claims: { agent: true, actAs: "ghost" } }]) {
+      const subject = subjectOf(principal);
+      expect(subject).toEqual({});
+      expect(owned.can("read", "space", subject, lists())).toBe(false);
+      expect(owned.can("read", "user:u_ana", subject, lists())).toBe(false);
+    }
+  });
+
+  it("takes other values of via", () => {
+    expect(subjectOf({ id: "g", via: "guest" }, { anonymousVia: ["guest"] })).toEqual({});
+    expect(subjectOf({ id: "token", via: "token" }, { serviceVia: [] })).toEqual({ user: "token" });
+  });
+});
+
+describe("the output filter of a host", () => {
+  const invocation = (principal?: { id: string; via: string; claims?: Record<string, unknown> }) => ({ principal }) as unknown as Invocation;
+  const board = lists(["board:b1", { access: [{ principal: "email:ana@example.com", rights: ["read"] }, { principal: "signed-in", rights: ["read"], when: { mine: true } }] }]);
+  const evaluate = (_c: unknown, vars: Readonly<Record<string, unknown>>) => (vars["doc"] as { by?: unknown } | null)?.by === (vars["principal"] as { user: unknown }).user;
+  const admit = accessAdmitItem({
+    access: new Access(boardsPolicy(["mark@example.com"], evaluate)),
+    lists: async () => board,
+    scopeOf: (item) => (item as { _scope?: string })._scope,
+  });
+
+  it("admits an item of a scope that the subject reads, and refuses an item without a scope", async () => {
+    expect(await admit({ _scope: "board:b1" }, invocation({ id: "u_ana", via: "better-auth", claims: { email: "ana@example.com" } }))).toBe(true);
+    expect(await admit({ _scope: "board:b1" }, invocation({ id: "u_zoe", via: "better-auth" }))).toBe(false);
+    expect(await admit({}, invocation({ id: "agent", via: "agent-token" }))).toBe(false);
+    expect(await admit({ _scope: "board:b1" }, invocation())).toBe(false);
+  });
+
+  it("checks a conditional entry with the item as the document", async () => {
+    expect(await admit({ _scope: "board:b1", by: "u_zoe" }, invocation({ id: "u_zoe", via: "better-auth" }))).toBe(true);
+    expect(await admit({ _scope: "board:b1", by: "u_ana" }, invocation({ id: "u_zoe", via: "better-auth" }))).toBe(false);
+  });
+
+  it("takes another right and another subject function", async () => {
+    const writes = accessAdmitItem({ access: new Access(), lists: () => lists(["x", { access: [{ principal: "anyone", rights: ["read"] }] }]), scopeOf: () => "x", right: "write", subjectOf: () => ({}) });
+    expect(await writes({}, invocation())).toBe(false);
+  });
+});