@north-light/api 0.3.580 → 0.3.587

package/dist/core/permissions/ceiling.js

@@ -0,0 +1,319 @@
+// The ceiling: what one of a person's agents may reach, computed in TypeScript from the reader's grant scopes and node row before the query,
+// then applied inside the same query as the schema check (`ceilingFrag`). A person reader has no ceiling. Privacy (`private` per root), run
+// confinement (`place`) and the launched own-memory narrowing are all rules here; none of them is schema text.
+import { covers } from '@north-light/identity';
+import { fileRoot } from '../spaces/file-root.js';
+import { FALSE, TRUE, and, f, or, raw } from './sql.js';
+const empty = (ownApp) => ({ ownApp, roots: [], namespaces: [], place: null, predicates: { allNodes: false, spaces: false }, authorApps: [] });
+async function externalId(db, objectId) {
+    const row = await db.prepare('SELECT external_id FROM identities WHERE object = ? ORDER BY scheme LIMIT 1').get(objectId);
+    return row?.external_id ?? null;
+}
+async function objectOf(db, scheme, ext) {
+    const row = await db.prepare('SELECT o.id FROM identities i JOIN objects o ON o.id = i.object WHERE i.scheme = ? AND i.external_id = ? AND o.deleted_at IS NULL').get(scheme, ext);
+    return row?.id ?? null;
+}
+/** Every live local person object. The ceiling reaches a person's tree through the scope the reader holds; which person's documents the reader's user may
+ *  actually read is the schema's decision (`acts_for` on the reader's own person, a share on anyone else's), so a document shared with the reader is in reach. */
+export async function personObjectIds(db) {
+    const rows = await db.prepare("SELECT id FROM objects WHERE type = 'person' AND home_machine IS NULL AND deleted_at IS NULL ORDER BY created_at").all();
+    return rows.map((r) => r.id);
+}
+/** Apps whose grant (any status) holds `crtr:memory:manage:user` with mode `always`: first-party apps, whose person documents a covering rw scope may change. */
+async function firstPartyApps(db) {
+    const rows = await db.prepare(`SELECT DISTINCT i.object AS id FROM grants g JOIN identities i ON i.external_id = g.grantee AND i.scheme = 'app'
+    WHERE g.resolved_scopes_json::jsonb @> '[{"scope":"crtr:memory:manage:user","mode":"always"}]'::jsonb`).all();
+    return rows.map((r) => r.id);
+}
+/** Whether `scopes` hold a provider-group scope `<provider>:<group>` of the app whose external id is `appExt`: what lets a run read that app's private objects. */
+export function holdsProviderGroup(scopes, appExt) {
+    return providerGroupHolders(scopes).has(appExt.replace(/^app:/, ''));
+}
+// A grant can hold thousands of scopes and a ceiling asks once per app: index each scope list once.
+const providerGroups = new WeakMap();
+function providerGroupHolders(scopes) {
+    let providers = providerGroups.get(scopes);
+    if (providers === undefined) {
+        providers = new Set();
+        for (const s of scopes) {
+            const colon = s.indexOf(':');
+            if (colon >= 0 && !s.includes(':', colon + 1))
+                providers.add(s.slice(0, colon));
+        }
+        providerGroups.set(scopes, providers);
+    }
+    return providers;
+}
+/** The repo objects whose files the reader's checkouts reach for `access`. */
+async function repoRoots(db, reader, access) {
+    if (reader.class === 'object')
+        return reader.repos.map((r) => r.id);
+    if (reader.class !== 'node')
+        return [];
+    const appExt = await externalId(db, reader.app.id);
+    if (appExt === null)
+        return [];
+    const caller = { app: appExt, resolved: reader.scopes ?? [], launched: null };
+    const ids = new Set();
+    for (const c of [...reader.checkouts, ...reader.projectCheckouts])
+        if ('root' in fileRoot(caller, c.root, access))
+            ids.add(c.repo.id);
+    return [...ids];
+}
+/** The ceiling of `reader` for `access`; null for a person reader (no ceiling). */
+export async function resolveCeiling(db, reader, access, options = {}) {
+    if (reader.class === 'person')
+        return null;
+    const c = empty(reader.app.id);
+    const held = reader.scopes;
+    const has = (scope) => held !== null && held.some((s) => covers(s, scope));
+    const ownExt = await externalId(db, reader.app.id);
+    const place = reader.class === 'node' ? await nodePlace(db, reader.node.id) : (reader.place ?? null);
+    c.place = place;
+    c.authorApps = [reader.app.id];
+    // ---- the reader's own app
+    const verbAccess = access === 'write' ? 'rw' : 'read';
+    const launched = reader.launched;
+    const own = (id, match, priv = true) => { c.roots.push({ id, private: priv, match }); };
+    if (access === 'message' || launched === undefined || launched === null || ownExt === null || launched.some((l) => covers(l, `crtr:memory:${verbAccess}:${ownExt}`))) {
+        own(reader.app.id, 'any');
+        if (ownExt !== null)
+            c.namespaces = await ownNamespaces(db, ownExt);
+    }
+    else {
+        // A launched list that lacks the app-wide memory scope gates documents only: every other object stays open.
+        own(reader.app.id, 'non-document');
+        if (access === 'read' && place !== null)
+            own(reader.app.id, 'run-report');
+        for (const p of await db.prepare("SELECT o.id, i.external_id FROM objects o JOIN identities i ON i.object = o.id AND i.scheme = 'profile' WHERE o.owner = ? AND o.type = 'profile' AND o.deleted_at IS NULL").all(reader.app.id)) {
+            if (launched.some((l) => covers(l, `crtr:memory:${verbAccess}:${ownExt}:profile:${p.external_id}`)))
+                own(p.id, 'no-node');
+        }
+    }
+    if (held === null)
+        return c; // a revoked grant reaches only its own app
+    c.predicates.spaces = true;
+    // ---- the person
+    const persons = await personObjectIds(db);
+    const manage = has('crtr:memory:manage:user');
+    const personPrivate = manage || has('crtr:memory:read_private:user');
+    const addPerson = (match, priv) => { for (const id of persons)
+        if (id !== reader.app.id)
+            c.roots.push({ id, private: priv, match }); };
+    if (access === 'write') {
+        if (manage)
+            addPerson('any', true);
+        else {
+            if (has('crtr:memory:rw:user')) {
+                addPerson('self', true);
+                addPerson('authored:*', true);
+            }
+            for (const s of held) {
+                const m = /^crtr:memory:rw:user:(.+)$/.exec(s);
+                if (m !== null)
+                    addPerson(`authored:${m[1]}`, true);
+            }
+            if (has('crtr:objects:write:user'))
+                addPerson('any', true);
+            if (c.roots.some((r) => r.match.startsWith('authored:')))
+                c.authorApps.push(...await firstPartyApps(db));
+        }
+    }
+    else if (access === 'read') {
+        if (manage)
+            addPerson('any', true);
+        else
+            addPerson('direct-doc', personPrivate);
+        if (has(`crtr:objects:${options.verb ?? 'read'}:user`))
+            addPerson('any', personPrivate);
+    }
+    // ---- other apps and profiles: memory and objects scopes, conversations, message
+    const objVerb = access === 'write' ? 'write' : options.verb ?? 'read';
+    const watching = reader.class === 'object' && reader.object.type.includes('.');
+    const appRoot = async (ext, match) => {
+        const id = await objectOf(db, 'app', ext);
+        if (id === null || id === reader.app.id)
+            return;
+        c.roots.push({ id, private: holdsProviderGroup(held, ext), match });
+    };
+    for (const s of held) {
+        if (!s.startsWith('crtr:'))
+            continue;
+        let m = /^crtr:memory:(read|rw):app:([A-Za-z0-9_-]{1,64})(?::profile:([A-Za-z0-9_-]{1,64}))?$/.exec(s);
+        if (m !== null && (access === 'read' || (access === 'write' && m[1] === 'rw'))) {
+            if (m[3] === undefined)
+                await appRoot(`app:${m[2]}`, 'no-node');
+            else {
+                const pid = await objectOf(db, 'profile', m[3]);
+                if (pid !== null)
+                    c.roots.push({ id: pid, private: false, match: 'no-node' });
+            }
+            continue;
+        }
+        m = /^crtr:objects:(read|watch|link|write):(user|node|profile:[A-Za-z0-9_-]+|app:[A-Za-z0-9_-]+)$/.exec(s);
+        if (m !== null && access !== 'message' && (m[1] === objVerb || (access === 'read' && watching && m[1] === 'watch'))) {
+            const target = m[2];
+            if (target === 'node')
+                c.predicates.allNodes = true;
+            else if (target.startsWith('profile:')) {
+                const pid = await objectOf(db, 'profile', target.slice(8));
+                if (pid !== null)
+                    c.roots.push({ id: pid, private: false, match: 'below' });
+            }
+            else if (target.startsWith('app:'))
+                await appRoot(target, 'objects-app');
+            continue;
+        }
+        m = /^crtr:conversations:read:(app:[A-Za-z0-9_-]+)$/.exec(s);
+        if (m !== null && access === 'read') {
+            await appRoot(m[1], 'node-report');
+            await appRoot(m[1], 'run-node');
+            continue;
+        }
+        m = /^crtr:objects:message:(app:[A-Za-z0-9_-]+)$/.exec(s);
+        if (m !== null && access === 'message')
+            await appRoot(m[1], 'node-tree');
+    }
+    // ---- tool-usable apps (read): their shipped documents and custom objects
+    if (access === 'read') {
+        const apps = await db.prepare(`SELECT a.id FROM objects a WHERE a.type = 'app' AND a.deleted_at IS NULL AND EXISTS (
+      SELECT 1 FROM objects o JOIN documents d ON d.object = o.id WHERE o.owner = a.id AND o.type = 'document' AND o.deleted_at IS NULL AND d.source_path IS NOT NULL)`).all();
+        for (const a of apps)
+            if (a.id !== reader.app.id)
+                c.roots.push({ id: a.id, private: false, match: 'shipped' });
+        for (const a of await db.prepare("SELECT o.id, i.external_id FROM objects o JOIN identities i ON i.object = o.id AND i.scheme = 'app' WHERE o.type = 'app' AND o.deleted_at IS NULL").all()) {
+            if (a.id !== reader.app.id)
+                c.roots.push({ id: a.id, private: holdsProviderGroup(held, a.external_id), match: 'custom' });
+        }
+    }
+    // ---- repos the reader's checkouts reach
+    if (access !== 'message')
+        for (const id of await repoRoots(db, reader, access === 'write' ? 'rw' : 'read'))
+            c.roots.push({ id, private: access === 'read', match: 'any' });
+    return c;
+}
+async function ownNamespaces(db, ownExt) {
+    return (await db.prepare('SELECT namespace FROM schemas WHERE app = ?').all(ownExt)).map((r) => r.namespace);
+}
+/** A node's run and whether it is isolated (its own flag: isolation is sticky). A deleted node of an isolated run keeps its run in `deleted_isolated_nodes`. */
+export async function nodePlace(db, nodeId) {
+    const row = await db.prepare('SELECT run_id, isolated FROM nodes WHERE node_id = ?').get(nodeId);
+    if (row !== undefined)
+        return { run: row.run_id ?? nodeId, isolated: row.isolated === 1 };
+    const gone = await db.prepare('SELECT run_id FROM deleted_isolated_nodes WHERE node_id = ?').get(nodeId);
+    return gone ? { run: gone.run_id, isolated: true } : null;
+}
+/** Record, before a node's row is deleted, the run of a node of an isolated run. */
+export async function rememberDeletedIsolated(nodeId, db) {
+    const place = await nodePlace(db, nodeId);
+    if (place?.isolated)
+        await db.prepare('INSERT INTO deleted_isolated_nodes (node_id, run_id) VALUES (?, ?) ON CONFLICT (node_id) DO UPDATE SET run_id = excluded.run_id').run(nodeId, place.run);
+}
+// ---- the launched own-memory narrowing, for the error message a refused write names
+/** The reader with its launched list lifted, for the runtime's own writes inside a narrowed run (a `crtr push` report, a promoted node's scaffolded roadmap). */
+export function asRuntimeWriter(reader) {
+    return reader.class === 'person' ? reader : { ...reader, launched: null };
+}
+/** The own-app memory scope a narrowed run lacks to `read` or `rw` the document `objectId` (or a document about to be created under `objectId` when `creating`), or null.
+ *  A run with no launched list, the app's server and a person are never narrowed. Only documents are gated. */
+export async function missingMemoryScope(db, reader, objectId, access, creating = false) {
+    if (reader.class === 'person' || reader.launched === undefined || reader.launched === null)
+        return null;
+    const chain = await db.prepare(`WITH RECURSIVE c(id, owner, type, kind, depth) AS (
+      SELECT id, owner, type, kind, 0 FROM objects WHERE id = ? UNION ALL
+      SELECT p.id, p.owner, p.type, p.kind, c.depth + 1 FROM c JOIN objects p ON p.id = c.owner WHERE c.depth < 12)
+    SELECT c.id, c.type, c.kind FROM c ORDER BY c.depth`).all(objectId);
+    if (chain[chain.length - 1]?.id !== reader.app.id)
+        return null;
+    const ext = await externalId(db, reader.app.id);
+    if (ext === null)
+        return null;
+    // Creating directly under the reader's own app needs the app-wide scope.
+    if (chain.length === 1)
+        return creating ? (reader.launched.some((l) => covers(l, `crtr:memory:${access}:${ext}`)) ? null : `crtr:memory:${access}:${ext}`) : null;
+    if (!creating && chain[0].type !== 'document')
+        return null;
+    const below = chain.slice(0, -1).reverse(); // top first, below the app
+    if (access === 'read' && !creating && chain[0].kind === 'report' && below[0].type === 'node' && reader.class !== 'object') {
+        const own = reader.class === 'node' ? await nodePlace(db, reader.node.id) : reader.place ?? null;
+        const target = await nodePlace(db, below[0].id);
+        if (own !== null && target !== null && own.run === target.run)
+            return null;
+    }
+    const top = below[0];
+    const scope = top.type === 'profile' ? `crtr:memory:${access}:${ext}:profile:${await externalId(db, top.id)}` : `crtr:memory:${access}:${ext}`;
+    return reader.launched.some((l) => covers(l, scope)) ? null : scope;
+}
+// ---- SQL
+/** The ceiling as a condition on the candidate `o` (an alias of `objects`). */
+export function ceilingFrag(c, o) {
+    const parts = [];
+    if (c.roots.length > 0)
+        parts.push(rootsFrag(c, o));
+    if (c.namespaces.length > 0)
+        parts.push(f `split_part(${raw(o)}.schema_type, '/', 1) = ANY(${c.namespaces}::text[])`);
+    if (c.predicates.allNodes)
+        parts.push(raw(`(${o}.type = 'node' AND ${o}.privacy = 'public')`));
+    if (c.predicates.spaces)
+        parts.push(raw(`(${o}.owner IS NULL AND ${o}.type IN ('app','person','repo'))`));
+    return and([or(parts), placeFrag(c, o)]);
+}
+/** Run confinement, for every object below the reader's own app regardless of the alternative that passed it (a root, an own namespace, `objects:read:node`):
+ *  the nearest node of the object (below the app) must be in the reader's run, or neither it nor the reader's run is isolated. An object not
+ *  below the app, or with no node between it and the app, is not confined. */
+function placeFrag(c, o) {
+    if (c.place === null)
+        return TRUE;
+    const iso = c.place.isolated ? 1 : 0;
+    return f `NOT EXISTS (WITH RECURSIVE ca(id, owner, depth, near_node) AS (
+      SELECT ${raw(o)}.id, ${raw(o)}.owner, 0, CASE WHEN ${raw(o)}.type = 'node' THEN ${raw(o)}.id END
+      UNION ALL
+      SELECT p.id, p.owner, ca.depth + 1, COALESCE(ca.near_node, CASE WHEN p.type = 'node' THEN p.id END)
+        FROM ca JOIN objects p ON p.id = ca.owner WHERE ca.depth < 12)
+    SELECT 1 FROM ca LEFT JOIN nodes cn ON cn.node_id = ca.near_node LEFT JOIN deleted_isolated_nodes cd ON cd.node_id = ca.near_node
+     WHERE ca.id = ${c.ownApp} AND ca.depth > 0 AND ca.near_node IS NOT NULL
+       AND NOT (CASE WHEN cn.node_id IS NOT NULL THEN COALESCE(cn.run_id, cn.node_id) = ${c.place.run} OR (cn.isolated = 0 AND ${iso} = 0)
+                     WHEN cd.node_id IS NOT NULL THEN cd.run_id = ${c.place.run} ELSE ${iso} = 0 END))`;
+}
+function rootsFrag(c, o) {
+    const ids = c.roots.map((r) => r.id);
+    const priv = c.roots.map((r) => (r.private ? 1 : 0));
+    const match = c.roots.map((r) => r.match);
+    const used = new Set(c.roots.map((r) => r.match));
+    const O = (col) => `${o}.${col}`;
+    const terms = [];
+    const t = (m, cond) => { if (used.has(m))
+        terms.push(f `(r.match = ${m} AND ${typeof cond === 'string' ? raw(cond) : cond})`); };
+    t('any', 'TRUE');
+    t('below', 'ca.depth > 0');
+    t('direct-doc', `(ca.depth = 0 OR (ca.depth = 1 AND ${O('type')} = 'document'))`);
+    t('no-node', 'NOT ca.node_below');
+    t('node-tree', 'ca.node_below');
+    t('objects-app', `(ca.node_below OR ${O('type')} LIKE '%.%')`);
+    t('node-report', `(ca.node_below AND ${O('type')} = 'document' AND ${O('kind')} = 'report')`);
+    t('run-node', `(${O('type')} = 'node' AND EXISTS (SELECT 1 FROM nodes rn WHERE rn.node_id = ${O('id')} AND rn.run_id IS NOT NULL))`);
+    t('custom', `${O('type')} LIKE '%.%'`);
+    t('shipped', `(ca.depth > 0 AND EXISTS (SELECT 1 FROM documents sd WHERE sd.object = ${O('id')} AND sd.source_path IS NOT NULL))`);
+    t('non-document', `(${O('type')} <> 'document')`);
+    t('self', 'ca.depth = 0');
+    if (used.has('run-report')) {
+        terms.push(c.place === null ? FALSE
+            : f `(r.match = 'run-report' AND ${raw(O('type'))} = 'document' AND ${raw(O('kind'))} = 'report' AND EXISTS (SELECT 1 FROM nodes rn WHERE rn.node_id = ca.near_node AND COALESCE(rn.run_id, rn.node_id) = ${c.place.run}))`);
+    }
+    for (const m of used) {
+        if (m.startsWith('authored:')) {
+            const name = m.slice(9);
+            terms.push(f `(r.match = ${m} AND ca.depth = 1 AND ${raw(O('type'))} = 'document' AND ${name === '*' ? raw('TRUE') : f `${raw(O('name'))} = ${name}`} AND EXISTS (SELECT 1 FROM revisions rv JOIN objects au ON au.id = rv.author
+        WHERE rv.document = ${raw(O('id'))} AND rv.number = (SELECT min(number) FROM revisions WHERE document = ${raw(O('id'))})
+        AND (au.type = 'person' OR COALESCE((SELECT app FROM nodes WHERE node_id = au.id), au.owner) = ANY(${c.authorApps}::text[]))))`);
+        }
+    }
+    const matchSql = or(terms);
+    return f `EXISTS (WITH RECURSIVE ca(id, owner, type, depth, node_below, near_node) AS (
+      SELECT ${raw(O('id'))}, ${raw(O('owner'))}, ${raw(O('type'))}, 0, FALSE, CASE WHEN ${raw(O('type'))} = 'node' THEN ${raw(O('id'))} END
+      UNION ALL
+      SELECT p.id, p.owner, p.type, ca.depth + 1, ca.node_below OR ca.type = 'node', COALESCE(ca.near_node, CASE WHEN p.type = 'node' THEN p.id END)
+        FROM ca JOIN objects p ON p.id = ca.owner WHERE ca.depth < 12)
+    SELECT 1 FROM ca JOIN unnest(${ids}::text[], ${priv}::int[], ${match}::text[]) AS r(id, priv, match) ON r.id = ca.id
+     WHERE (${raw(O('privacy'))} = 'public' OR r.priv = 1) AND ${matchSql})`;
+}

package/dist/core/permissions/compile.d.ts

@@ -0,0 +1,14 @@
+import { type Definition } from './schema-parser.js';
+import { type Frag } from './sql.js';
+/** The subjects a reader stands for: its user ids (including `*`) and every group it reaches, directly or through nested groups. */
+export interface SubjectSet {
+    userIds: string[];
+    groupIds: string[];
+}
+export type Defs = ReadonlyMap<string, Definition>;
+/** Refuse a schema whose evaluation would recurse past the closure: a permission that reaches itself other than through top-level self-arrows
+ *  (inside `&`/`-`, through another permission, or through a `type#relation` subject). Such a rule would be cut off at MAX_DEPTH, so its meaning
+ *  would depend on a hidden depth. `defs` is every definition the schema can reach (the built-ins and the new ones); the error names the line. */
+export declare function assertNoUnsupportedRecursion(defs: readonly Definition[], own: readonly Definition[]): void;
+/** SQL true when the subjects hold `name` on the resource of type `typeName` whose id is the expression `id`. */
+export declare function compilePermission(defs: Defs, subjects: SubjectSet, typeName: string, name: string, id: Frag): Frag;

package/dist/core/permissions/compile.js

@@ -0,0 +1,175 @@
+// Compiles a permission of a definition to a SQL fragment over `relation_source` for a resource id expression. Every relation and every
+// arrow reads that one source; a `parent` arrow into the same definition becomes an ancestor closure (one recursive CTE).
+import { SchemaParseError } from './schema-parser.js';
+import { FALSE, TRUE, and, f, or, raw } from './sql.js';
+const MAX_DEPTH = 8;
+class Compiler {
+    defs;
+    subjects;
+    n = 0;
+    constructor(defs, subjects) {
+        this.defs = defs;
+        this.subjects = subjects;
+    }
+    alias(prefix) { return `${prefix}${++this.n}`; }
+    permission(typeName, name, id, depth = 0) {
+        const def = this.defs.get(typeName);
+        if (def === undefined || depth > MAX_DEPTH)
+            return FALSE;
+        if (name in def.relations)
+            return this.relation(def, name, id, depth);
+        const expr = def.permissions[name];
+        if (expr === undefined)
+            return FALSE;
+        const closure = this.closure(def, name, expr, id, depth);
+        return closure ?? this.expr(def, expr, id, depth);
+    }
+    /** Every `x->name` among the top-level union terms of `name` itself, with `x` pointing back at `def`: the ancestor closure over all of those `x`. */
+    closure(def, name, expr, id, depth) {
+        const { terms, selfs } = selfArrows(def, name, expr);
+        if (selfs.length === 0)
+            return null;
+        const lefts = [...new Set(selfs.map((t) => t.left))];
+        // A self-arrow's `left` may also admit other types: those subjects stay an ordinary arrow at each ancestor.
+        const local = terms.filter((t) => !selfs.includes(t)).map((t) => ({ t, skip: undefined }))
+            .concat(selfs.map((t) => ({ t, skip: def.name })));
+        // The step is a LATERAL lookup per ancestor, with OFFSET 0 so it is not flattened: as a plain join the planner hash-joins the whole
+        // `relation_source` view (a seq scan of `objects` for every candidate row).
+        const up = this.alias('anc');
+        const a = this.alias('a');
+        const rs = this.alias('rs');
+        const localAtAnc = or(local.map(({ t, skip }) => t.op === 'arrow' && skip !== undefined ? this.arrow(def, t.left, t.right, raw(`${a}.id`), depth, skip) : this.expr(def, t, raw(`${a}.id`), depth)));
+        return f `EXISTS (WITH RECURSIVE ${raw(up)}(id) AS (SELECT ${id}::text UNION SELECT ${raw(rs)}.subject_id FROM ${raw(up)}, LATERAL (SELECT s.subject_id FROM relation_source s WHERE s.resource_type = ${def.name} AND s.resource_id = ${raw(up)}.id AND s.relation = ANY(${lefts}::text[]) AND s.subject_type = ${def.name} AND s.subject_relation = '' OFFSET 0) ${raw(rs)}) SELECT 1 FROM ${raw(up)} ${raw(a)} WHERE ${localAtAnc})`;
+    }
+    expr(def, e, id, depth) {
+        switch (e.op) {
+            case 'ref': return this.permission(def.name, e.name, id, depth + 1);
+            case 'arrow': return this.arrow(def, e.left, e.right, id, depth);
+            case 'union': return or([this.expr(def, e.l, id, depth), this.expr(def, e.r, id, depth)]);
+            case 'inter': return and([this.expr(def, e.l, id, depth), this.expr(def, e.r, id, depth)]);
+            case 'excl': return and([this.expr(def, e.l, id, depth), notFrag(this.expr(def, e.r, id, depth))]);
+        }
+    }
+    subjectMatch(rs, s, depth) {
+        const col = (c) => raw(`${rs}.${c}`);
+        if (s.type === 'user') {
+            if (s.relation !== undefined)
+                return FALSE;
+            return f `(${col('subject_type')} = 'user' AND ${col('subject_id')} = ANY(${this.subjects.userIds}::text[]))`;
+        }
+        if (s.relation === undefined)
+            return FALSE; // a plain object subject is reached only through an arrow
+        if (s.type === 'crtr/group' && s.relation === 'member') {
+            return f `(${col('subject_type')} = 'crtr/group' AND ${col('subject_relation')} = 'member' AND ${col('subject_id')} = ANY(${this.subjects.groupIds}::text[]))`;
+        }
+        const inner = this.permission(s.type, s.relation, col('subject_id'), depth + 1);
+        return and([f `${col('subject_type')} = ${s.type}`, f `${col('subject_relation')} = ${s.relation}`, inner]);
+    }
+    relation(def, name, id, depth) {
+        const rs = this.alias('rs');
+        const match = or(def.relations[name].map((s) => this.subjectMatch(rs, s, depth)));
+        if (match === FALSE)
+            return FALSE;
+        return f `EXISTS (SELECT 1 FROM relation_source ${raw(rs)} WHERE ${raw(rs)}.resource_type = ${def.name} AND ${raw(rs)}.resource_id = ${id} AND ${raw(rs)}.relation = ${name} AND ${match})`;
+    }
+    /** `left->right`; `skipType` leaves out the subjects of that type (the ones an ancestor closure already walks). */
+    arrow(def, left, right, id, depth, skipType) {
+        const subjects = def.relations[left];
+        if (subjects === undefined)
+            return FALSE;
+        const parts = [];
+        for (const s of subjects) {
+            if (s.type === 'user' || s.relation !== undefined || s.type === skipType)
+                continue;
+            const target = this.defs.get(s.type);
+            if (target === undefined || !(right in target.permissions || right in target.relations))
+                continue;
+            const rs = this.alias('rs');
+            const inner = this.permission(s.type, right, raw(`${rs}.subject_id`), depth + 1);
+            parts.push(f `EXISTS (SELECT 1 FROM relation_source ${raw(rs)} WHERE ${raw(rs)}.resource_type = ${def.name} AND ${raw(rs)}.resource_id = ${id} AND ${raw(rs)}.relation = ${left} AND ${raw(rs)}.subject_type = ${s.type} AND ${inner})`);
+        }
+        return or(parts);
+    }
+}
+/** The top-level union terms of permission `name` and, among them, its self-arrows: `x->name` with `x` a relation that can point back at `def`.
+ *  Those are the one recursion the compiler evaluates exactly, as an ancestor closure at any depth. */
+function selfArrows(def, name, expr) {
+    const terms = [];
+    const flatten = (e) => { if (e.op === 'union') {
+        flatten(e.l);
+        flatten(e.r);
+    }
+    else
+        terms.push(e); };
+    flatten(expr);
+    const selfs = terms.filter((t) => t.op === 'arrow' && t.right === name && (def.relations[t.left]?.some((s) => s.type === def.name && s.relation === undefined) ?? false));
+    return { terms, selfs };
+}
+/** Refuse a schema whose evaluation would recurse past the closure: a permission that reaches itself other than through top-level self-arrows
+ *  (inside `&`/`-`, through another permission, or through a `type#relation` subject). Such a rule would be cut off at MAX_DEPTH, so its meaning
+ *  would depend on a hidden depth. `defs` is every definition the schema can reach (the built-ins and the new ones); the error names the line. */
+export function assertNoUnsupportedRecursion(defs, own) {
+    const byName = new Map(defs.map((d) => [d.name, d]));
+    const key = (t, n) => `${t}\u0000${n}`;
+    const edges = (def, name) => {
+        const out = [];
+        if (name in def.relations) {
+            for (const s of def.relations[name])
+                if (s.relation !== undefined && s.type !== 'user' && !(s.type === 'crtr/group' && s.relation === 'member'))
+                    out.push([s.type, s.relation]);
+            return out;
+        }
+        const expr = def.permissions[name];
+        if (expr === undefined)
+            return out;
+        const { selfs } = selfArrows(def, name, expr);
+        const walk = (e) => {
+            if (e.op === 'ref')
+                out.push([def.name, e.name]);
+            else if (e.op === 'arrow') {
+                const handled = selfs.includes(e);
+                for (const s of def.relations[e.left] ?? []) {
+                    if (s.type === 'user' || s.relation !== undefined || (handled && s.type === def.name))
+                        continue;
+                    const target = byName.get(s.type);
+                    if (target !== undefined && (e.right in target.permissions || e.right in target.relations))
+                        out.push([s.type, e.right]);
+                }
+            }
+            else {
+                walk(e.l);
+                walk(e.r);
+            }
+        };
+        walk(expr);
+        return out;
+    };
+    for (const def of own) {
+        for (const name of [...Object.keys(def.relations), ...Object.keys(def.permissions)]) {
+            const seen = new Set();
+            const stack = edges(def, name);
+            while (stack.length > 0) {
+                const [t, n] = stack.pop();
+                if (t === def.name && n === name)
+                    throw new SchemaParseError(def.lines?.[name] ?? 1, `${def.name}#${name} reaches itself; only top-level \`relation->${name}\` terms of a permission may recurse`);
+                if (seen.has(key(t, n)))
+                    continue;
+                seen.add(key(t, n));
+                const d = byName.get(t);
+                if (d !== undefined)
+                    stack.push(...edges(d, n));
+            }
+        }
+    }
+}
+function notFrag(p) {
+    if (p === TRUE)
+        return FALSE;
+    if (p === FALSE)
+        return TRUE;
+    return { sql: `NOT (${p.sql})`, params: p.params };
+}
+/** SQL true when the subjects hold `name` on the resource of type `typeName` whose id is the expression `id`. */
+export function compilePermission(defs, subjects, typeName, name, id) {
+    return new Compiler(defs, subjects).permission(typeName, name, id);
+}

package/dist/core/permissions/errors.d.ts

@@ -0,0 +1,7 @@
+/** A refusal the daemon maps to its HTTP status and error code. */
+export declare class PermissionError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown> | undefined);
+}

package/dist/core/permissions/errors.js

@@ -0,0 +1,13 @@
+/** A refusal the daemon maps to its HTTP status and error code. */
+export class PermissionError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = 'PermissionError';
+    }
+}

package/dist/core/permissions/evaluator.d.ts

@@ -0,0 +1,33 @@
+import type { CanvasDb } from '../canvas/db.js';
+import type { Reader } from '../graph/types.js';
+import { type CeilingOptions } from './ceiling.js';
+import { type SubjectSet } from './compile.js';
+import { type Frag } from './sql.js';
+export type Permission = 'read' | 'edit' | 'message' | 'use' | 'share';
+export declare const PERMISSIONS: readonly Permission[];
+/** A reader with its user and subject set resolved: build once, pass to many `permits`/`check` calls. `userId` is null for a reader
+ *  that acts for no person (see `readerUser`): its subjects are `*` alone. */
+export interface EvalReader {
+    reader: Reader;
+    userId: string | null;
+    subjects: SubjectSet;
+}
+/** The user a reader acts for: a person's own identity; an app call's `sub`; a node's `sub`; otherwise the install's person. */
+export declare function userOf(db: CanvasDb, reader: Reader): Promise<string>;
+/** The user a reader reads as: `userOf`, except that on a cloud role an app reader with no `sub` (a runtime-owned call, such as
+ *  package link derivation at boot) acts for no person and answers null. `userOf` itself keeps throwing there, so no write path
+ *  records an object as kept for a person that is not there. */
+export declare function readerUser(db: CanvasDb, reader: Reader): Promise<string | null>;
+/** The user ids a subject stands for (the user and `*`) and every group it reaches, directly or through nested groups. */
+export declare function subjectSet(db: CanvasDb, userId: string): Promise<SubjectSet>;
+export declare function resolveReader(db: CanvasDb, reader: Reader): Promise<EvalReader>;
+/** SQL true when `reader` holds `permission` on the object `alias` (a row of `objects` in the caller's SELECT): schema within the ceiling.
+ *  Bare `?` placeholders in textual order: embed `sql` and append `params` at the same position in the caller's parameter list. */
+export declare function permits(db: CanvasDb, reader: Reader | EvalReader, permission: Permission, alias?: string, options?: CeilingOptions): Promise<Frag>;
+/** May `reader` do `permission` on the object `objectId`? A missing object is false. */
+export declare function check(db: CanvasDb, reader: Reader | EvalReader, permission: Permission, objectId: string, options?: CeilingOptions): Promise<boolean>;
+/** `check` for a subject that is not a Reader: a person's user id with no ceiling (the SDK's `POST /v1/check`). */
+export declare function checkUser(db: CanvasDb, userId: string, permission: Permission | string, resource: {
+    type: string;
+    id: string;
+}): Promise<boolean>;