@north-light/api 0.3.580 → 0.3.587

package/dist/core/permissions/evaluator.js

@@ -0,0 +1,96 @@
+import { isCloudRole, personIdAsync } from '../canvas/person.js';
+import { OBJECT_TYPE, GROUP_TYPE } from './builtin.js';
+import { ceilingFrag, resolveCeiling } from './ceiling.js';
+import { compilePermission } from './compile.js';
+import { PermissionError } from './errors.js';
+import { loadDefinitions } from './schemas.js';
+import { TRUE, and, f, or, raw } from './sql.js';
+export const PERMISSIONS = ['read', 'edit', 'message', 'use', 'share'];
+/** The ceiling access class a permission asks: read/use → read, edit/share → write, message → message. */
+const ACCESS = { read: 'read', use: 'read', edit: 'write', share: 'write', message: 'message' };
+const bareUser = (principal) => principal.replace(/^user:/, '');
+/** 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 async function userOf(db, reader) {
+    if (reader.class === 'person') {
+        const row = await db.prepare("SELECT external_id FROM identities WHERE object = ? AND scheme = 'user'").get(reader.person.id);
+        return bareUser(row?.external_id ?? await personIdAsync());
+    }
+    if (reader.class === 'app')
+        return bareUser(reader.sub ?? await personIdAsync());
+    const nodeId = reader.class === 'node' ? reader.node.id : reader.object.id;
+    const row = await db.prepare('SELECT sub FROM nodes WHERE node_id = ?').get(nodeId);
+    return bareUser(row?.sub ?? await personIdAsync());
+}
+/** 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 async function readerUser(db, reader) {
+    if (reader.class === 'app' && reader.sub === undefined && isCloudRole())
+        return null;
+    return await userOf(db, reader);
+}
+/** The user ids a subject stands for (the user and `*`) and every group it reaches, directly or through nested groups. */
+export async function subjectSet(db, userId) {
+    const userIds = [userId, '*'];
+    const rows = await db.prepareUncached(`WITH RECURSIVE g(id) AS (
+      SELECT resource_id FROM relations WHERE resource_type = ? AND relation = 'member' AND subject_type = 'user' AND subject_id = ANY(?::text[])
+      UNION
+      SELECT r.resource_id FROM relations r JOIN g ON r.subject_type = ? AND r.subject_id = g.id AND r.subject_relation = 'member'
+       WHERE r.resource_type = ? AND r.relation = 'member')
+    SELECT id FROM g`).all(GROUP_TYPE, userIds, GROUP_TYPE, GROUP_TYPE);
+    return { userIds, groupIds: rows.map((r) => r.id) };
+}
+export async function resolveReader(db, reader) {
+    const userId = await readerUser(db, reader);
+    return { reader, userId, subjects: userId === null ? { userIds: ['*'], groupIds: [] } : await subjectSet(db, userId) };
+}
+const isEval = (r) => 'subjects' in r;
+/** 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 async function permits(db, reader, permission, alias = 'o', options = {}) {
+    if (!PERMISSIONS.includes(permission))
+        throw new PermissionError(400, 'unknown_permission', `unknown permission ${permission}`);
+    const ev = isEval(reader) ? reader : await resolveReader(db, reader);
+    const defs = await loadDefinitions(db);
+    const id = raw(`${alias}.id`);
+    // Apps are the roots of every tree and are shared by every account: any reader sees that an app exists. Nothing below an app inherits this
+    // (a fact `reader @ user:*` on the app would), so it is the one type-level rule in the evaluator.
+    const compiled = compilePermission(defs, ev.subjects, OBJECT_TYPE, permission, id);
+    const builtin = permission === 'read' ? or([compiled, raw(`${alias}.type = 'app'`)]) : compiled;
+    const ownApp = ev.reader.class === 'person' ? null : ev.reader.app.id;
+    const server = ev.reader.class === 'app' && ev.reader.place === undefined;
+    const ownNs = server && ownApp !== null ? await ownNamespaceTypes(db, ownApp) : new Set();
+    const cases = [];
+    for (const [name, def] of defs) {
+        if (name.startsWith('crtr/') || name === 'user' || name === 'app')
+            continue;
+        if (!(permission in def.permissions) && !(permission in def.relations))
+            continue;
+        const ns = name.split('/')[0];
+        cases.push(f `WHEN ${raw(alias)}.schema_type = ${name} THEN ${ownNs.has(ns) ? TRUE : compilePermission(defs, ev.subjects, name, permission, id)}`);
+    }
+    const schemaPart = cases.length === 0 ? f `(CASE WHEN ${raw(alias)}.schema_type IS NULL THEN ${builtin} ELSE FALSE END)`
+        : f `(CASE WHEN ${raw(alias)}.schema_type IS NULL THEN ${builtin} ${{ sql: cases.map((c) => c.sql).join(' '), params: cases.flatMap((c) => c.params) }} ELSE FALSE END)`;
+    const ceiling = await resolveCeiling(db, ev.reader, ACCESS[permission], options);
+    if (ceiling === null)
+        return schemaPart;
+    return and([ceilingFrag(ceiling, alias), schemaPart]);
+}
+async function ownNamespaceTypes(db, appObjectId) {
+    const rows = await db.prepare(`SELECT s.namespace FROM schemas s JOIN identities i ON i.external_id = s.app AND i.scheme = 'app' WHERE i.object = ?`).all(appObjectId);
+    return new Set(rows.map((r) => r.namespace));
+}
+/** May `reader` do `permission` on the object `objectId`? A missing object is false. */
+export async function check(db, reader, permission, objectId, options = {}) {
+    const p = await permits(db, reader, permission, 'o', options);
+    const row = await db.prepareUncached(`SELECT ${p.sql} AS ok FROM objects o WHERE o.id = ?`).get(...p.params, objectId);
+    return row?.ok === true;
+}
+/** `check` for a subject that is not a Reader: a person's user id with no ceiling (the SDK's `POST /v1/check`). */
+export async function checkUser(db, userId, permission, resource) {
+    const subjects = await subjectSet(db, bareUser(userId));
+    const defs = await loadDefinitions(db);
+    const frag = compilePermission(defs, subjects, resource.type, permission, f `${resource.id}::text`);
+    const row = await db.prepareUncached(`SELECT ${frag.sql} AS ok`).get(...frag.params);
+    return row?.ok === true;
+}

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

@@ -0,0 +1,56 @@
+import type { CanvasDb } from '../canvas/db.js';
+export interface FactSubject {
+    type: string;
+    id: string;
+    relation: string;
+}
+export interface Fact {
+    resourceType: string;
+    resourceId: string;
+    relation: string;
+    subject: FactSubject;
+    writtenBy: string;
+}
+export interface FactRow {
+    resource_type: string;
+    resource_id: string;
+    relation: string;
+    subject_type: string;
+    subject_id: string;
+    subject_relation: string;
+    written_by: string;
+    created_at: string;
+}
+/** `user:<id>` | `user:*` | `<type>:<id>` | `<type>:<id>#<relation>`; the type may contain `/`. The text of a person's principal (`user:abc`) is the subject user `abc`. */
+export declare function parseSubject(text: string): FactSubject;
+export declare function formatSubject(s: FactSubject): string;
+/** `<type>:<id>` of a resource in an app namespace, or a bare crouter object id. */
+export declare function parseResource(text: string): {
+    type: string;
+    id: string;
+};
+export declare function validateFact(db: CanvasDb, fact: Omit<Fact, 'writtenBy'>): Promise<void>;
+export declare function writeFact(db: CanvasDb, fact: Fact): Promise<boolean>;
+export declare function deleteFact(db: CanvasDb, fact: Omit<Fact, 'writtenBy'>): Promise<boolean>;
+/** Make the facts `(resource, relation, *)` exactly `subjects`, in the caller's transaction. */
+export declare function replaceSet(db: CanvasDb, resourceType: string, resourceId: string, relation: string, subjects: FactSubject[], writtenBy: string): Promise<{
+    written: number;
+    deleted: number;
+}>;
+export declare function listFacts(db: CanvasDb, resourceType: string, resourceId: string): Promise<FactRow[]>;
+/** Replace every fact of `relation` on `resourceType` written by `writtenBy` with `facts` (grant sync's team members: `crtr/group` `member`, `directory`). */
+export declare function replaceWrittenBy(db: CanvasDb, writtenBy: string, resourceType: string, relation: string, facts: Array<{
+    resourceId: string;
+    subject: FactSubject;
+}>): Promise<{
+    written: number;
+    deleted: number;
+}>;
+/** The user subject of a person principal (`user:abc` → user `abc`). */
+export declare const userSubject: (principal: string) => FactSubject;
+export declare const EVERYONE: FactSubject;
+/** `acts_for @ user:<userId>` on a crouter object: the person it is kept for. Idempotent. */
+export declare function writeActsFor(db: CanvasDb, objectId: string, userId: string, writtenBy?: string): Promise<boolean>;
+/** The shipped-document fact: `reader @ user:*`, `written_by = 'package'`; the package reconciler writes it with the document and removes it with it. */
+export declare function writeShippedReader(db: CanvasDb, objectId: string): Promise<boolean>;
+export declare function deleteShippedReader(db: CanvasDb, objectId: string): Promise<boolean>;

package/dist/core/permissions/facts.js

@@ -0,0 +1,102 @@
+import { OBJECT_TYPE } from './builtin.js';
+import { PermissionError } from './errors.js';
+import { loadDefinitions } from './schemas.js';
+/** `user:<id>` | `user:*` | `<type>:<id>` | `<type>:<id>#<relation>`; the type may contain `/`. The text of a person's principal (`user:abc`) is the subject user `abc`. */
+export function parseSubject(text) {
+    const m = /^([A-Za-z][A-Za-z0-9_/]*):([^#\s]+)(?:#([A-Za-z_][A-Za-z0-9_]*))?$/.exec(text);
+    if (m === null)
+        throw new PermissionError(400, 'subject_invalid', `${JSON.stringify(text)} is not a subject (<type>:<id>[#<relation>])`);
+    return { type: m[1], id: m[2], relation: m[3] ?? '' };
+}
+export function formatSubject(s) { return `${s.type}:${s.id}${s.relation === '' ? '' : `#${s.relation}`}`; }
+/** `<type>:<id>` of a resource in an app namespace, or a bare crouter object id. */
+export function parseResource(text) {
+    const m = /^([A-Za-z][A-Za-z0-9_/]*):(\S+)$/.exec(text);
+    if (m === null)
+        return { type: OBJECT_TYPE, id: text };
+    return { type: m[1], id: m[2] };
+}
+export async function validateFact(db, fact) {
+    const defs = await loadDefinitions(db);
+    const def = defs.get(fact.resourceType);
+    if (def === undefined)
+        throw new PermissionError(400, 'unknown_type', `no schema defines ${fact.resourceType}`);
+    if (fact.resourceType === OBJECT_TYPE && fact.relation === 'parent')
+        throw new PermissionError(400, 'unknown_relation', 'parent is the object owner, never stored');
+    const listed = def.relations[fact.relation];
+    if (listed === undefined)
+        throw new PermissionError(400, 'unknown_relation', `${fact.resourceType} has no relation ${fact.relation}`, { relation: fact.relation });
+    const s = fact.subject;
+    const ok = listed.some((t) => t.type === s.type && (s.id === '*' ? t.wildcard === true : s.relation === '' ? t.relation === undefined && t.wildcard !== true : t.relation === s.relation));
+    if (!ok)
+        throw new PermissionError(400, 'subject_not_allowed', `${fact.resourceType}#${fact.relation} does not accept ${formatSubject(s)}`, { relation: fact.relation, subject: formatSubject(s) });
+}
+export async function writeFact(db, fact) {
+    await validateFact(db, fact);
+    const s = fact.subject;
+    const r = await db.prepare(`INSERT INTO relations (resource_type, resource_id, relation, subject_type, subject_id, subject_relation, written_by, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT DO NOTHING`).run(fact.resourceType, fact.resourceId, fact.relation, s.type, s.id, s.relation, fact.writtenBy, new Date().toISOString());
+    return r.changes > 0;
+}
+export async function deleteFact(db, fact) {
+    const s = fact.subject;
+    const r = await db.prepare(`DELETE FROM relations WHERE resource_type = ? AND resource_id = ? AND relation = ? AND subject_type = ? AND subject_id = ? AND subject_relation = ?`)
+        .run(fact.resourceType, fact.resourceId, fact.relation, s.type, s.id, s.relation);
+    return r.changes > 0;
+}
+/** Make the facts `(resource, relation, *)` exactly `subjects`, in the caller's transaction. */
+export async function replaceSet(db, resourceType, resourceId, relation, subjects, writtenBy) {
+    const want = new Map(subjects.map((s) => [formatSubject(s), s]));
+    const have = await db.prepare('SELECT subject_type, subject_id, subject_relation FROM relations WHERE resource_type = ? AND resource_id = ? AND relation = ?')
+        .all(resourceType, resourceId, relation);
+    let deleted = 0;
+    let written = 0;
+    const haveKeys = new Set();
+    for (const h of have) {
+        const s = { type: h.subject_type, id: h.subject_id, relation: h.subject_relation };
+        haveKeys.add(formatSubject(s));
+        if (!want.has(formatSubject(s)) && await deleteFact(db, { resourceType, resourceId, relation, subject: s }))
+            deleted++;
+    }
+    for (const [key, s] of want)
+        if (!haveKeys.has(key) && await writeFact(db, { resourceType, resourceId, relation, subject: s, writtenBy }))
+            written++;
+    return { written, deleted };
+}
+export async function listFacts(db, resourceType, resourceId) {
+    return await db.prepare('SELECT * FROM relations WHERE resource_type = ? AND resource_id = ? ORDER BY relation, subject_type, subject_id').all(resourceType, resourceId);
+}
+/** Replace every fact of `relation` on `resourceType` written by `writtenBy` with `facts` (grant sync's team members: `crtr/group` `member`, `directory`). */
+export async function replaceWrittenBy(db, writtenBy, resourceType, relation, facts) {
+    const key = (id, s) => `${id}\0${formatSubject(s)}`;
+    const want = new Map(facts.map((x) => [key(x.resourceId, x.subject), x]));
+    const have = await db.prepare('SELECT resource_id, subject_type, subject_id, subject_relation FROM relations WHERE written_by = ? AND resource_type = ? AND relation = ?')
+        .all(writtenBy, resourceType, relation);
+    let deleted = 0;
+    let written = 0;
+    const haveKeys = new Set();
+    for (const h of have) {
+        const s = { type: h.subject_type, id: h.subject_id, relation: h.subject_relation };
+        haveKeys.add(key(h.resource_id, s));
+        if (!want.has(key(h.resource_id, s)) && await deleteFact(db, { resourceType, resourceId: h.resource_id, relation, subject: s }))
+            deleted++;
+    }
+    for (const [k, x] of want)
+        if (!haveKeys.has(k) && await writeFact(db, { resourceType, resourceId: x.resourceId, relation, subject: x.subject, writtenBy }))
+            written++;
+    return { written, deleted };
+}
+/** The user subject of a person principal (`user:abc` → user `abc`). */
+export const userSubject = (principal) => ({ type: 'user', id: principal.replace(/^user:/, ''), relation: '' });
+export const EVERYONE = { type: 'user', id: '*', relation: '' };
+/** `acts_for @ user:<userId>` on a crouter object: the person it is kept for. Idempotent. */
+export async function writeActsFor(db, objectId, userId, writtenBy = 'crtr') {
+    return await writeFact(db, { resourceType: OBJECT_TYPE, resourceId: objectId, relation: 'acts_for', subject: userSubject(userId), writtenBy });
+}
+/** The shipped-document fact: `reader @ user:*`, `written_by = 'package'`; the package reconciler writes it with the document and removes it with it. */
+export async function writeShippedReader(db, objectId) {
+    return await writeFact(db, { resourceType: OBJECT_TYPE, resourceId: objectId, relation: 'reader', subject: EVERYONE, writtenBy: 'package' });
+}
+export async function deleteShippedReader(db, objectId) {
+    return await deleteFact(db, { resourceType: OBJECT_TYPE, resourceId: objectId, relation: 'reader', subject: EVERYONE });
+}

package/dist/core/permissions/schema-parser.d.ts

@@ -0,0 +1,29 @@
+export interface SubjectType {
+    type: string;
+    relation?: string;
+    wildcard?: boolean;
+}
+export type Expr = {
+    op: 'ref';
+    name: string;
+} | {
+    op: 'arrow';
+    left: string;
+    right: string;
+} | {
+    op: 'union' | 'inter' | 'excl';
+    l: Expr;
+    r: Expr;
+};
+export interface Definition {
+    name: string;
+    relations: Record<string, SubjectType[]>;
+    permissions: Record<string, Expr>;
+    /** Source line of each relation and permission name (set by `parseSchema`; absent in a definition stored by an older build). */
+    lines?: Record<string, number>;
+}
+export declare class SchemaParseError extends Error {
+    readonly line: number;
+    constructor(line: number, message: string);
+}
+export declare function parseSchema(source: string): Definition[];

package/dist/core/permissions/schema-parser.js

@@ -0,0 +1,151 @@
+// Parser for the SpiceDB schema subset the permission model uses: `definition`, `relation` (subject types, `type:*`, `type#rel`),
+// `permission` with `+` union, `&` intersection, `-` exclusion, `->` arrow, parentheses. Anything else is a SchemaParseError with the line.
+export class SchemaParseError extends Error {
+    line;
+    constructor(line, message) {
+        super(`line ${line}: ${message}`);
+        this.line = line;
+        this.name = 'SchemaParseError';
+    }
+}
+function tokenize(source) {
+    const tokens = [];
+    const lines = source.split('\n');
+    const re = /\s*(->|[{}():|+&\-=#*]|[A-Za-z_][A-Za-z0-9_/]*)/y;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].replace(/\/\/.*$/, '').replace(/\/\*.*?\*\//g, '');
+        re.lastIndex = 0;
+        let pos = 0;
+        while (pos < line.length) {
+            if (/^\s*$/.test(line.slice(pos)))
+                break;
+            re.lastIndex = pos;
+            const m = re.exec(line);
+            if (m === null)
+                throw new SchemaParseError(i + 1, `unexpected character ${JSON.stringify(line.slice(pos).trim()[0])}`);
+            tokens.push({ text: m[1], line: i + 1 });
+            pos = re.lastIndex;
+        }
+    }
+    return tokens;
+}
+const IDENT = /^[A-Za-z_][A-Za-z0-9_/]*$/;
+export function parseSchema(source) {
+    const tokens = tokenize(source);
+    let i = 0;
+    const lastLine = () => tokens[Math.min(i, tokens.length - 1)]?.line ?? 1;
+    const peek = () => tokens[i]?.text;
+    const next = () => {
+        const t = tokens[i++];
+        if (t === undefined)
+            throw new SchemaParseError(lastLine(), 'unexpected end of schema');
+        return t;
+    };
+    const expect = (text) => {
+        const t = next();
+        if (t.text !== text)
+            throw new SchemaParseError(t.line, `expected "${text}", found "${t.text}"`);
+    };
+    const ident = (what) => {
+        const t = next();
+        if (!IDENT.test(t.text))
+            throw new SchemaParseError(t.line, `expected ${what}, found "${t.text}"`);
+        return t.text;
+    };
+    function primary() {
+        if (peek() === '(') {
+            next();
+            const e = expression();
+            expect(')');
+            return e;
+        }
+        const name = ident('a relation or permission name');
+        if (peek() === '->') {
+            next();
+            return { op: 'arrow', left: name, right: ident('a permission name') };
+        }
+        return { op: 'ref', name };
+    }
+    function expression() {
+        let left = primary();
+        for (;;) {
+            const op = peek();
+            const kind = op === '+' ? 'union' : op === '&' ? 'inter' : op === '-' ? 'excl' : null;
+            if (kind === null)
+                return left;
+            next();
+            left = { op: kind, l: left, r: primary() };
+        }
+    }
+    const defs = [];
+    while (i < tokens.length) {
+        const head = next();
+        if (head.text !== 'definition')
+            throw new SchemaParseError(head.line, `expected "definition", found "${head.text}"`);
+        const def = { name: ident('a definition name'), relations: {}, permissions: {}, lines: {} };
+        if (defs.some((d) => d.name === def.name))
+            throw new SchemaParseError(head.line, `definition ${def.name} is declared twice`);
+        expect('{');
+        while (peek() !== '}') {
+            const t = next();
+            if (t.text === 'relation') {
+                const name = ident('a relation name');
+                if (name in def.relations || name in def.permissions)
+                    throw new SchemaParseError(t.line, `${name} is declared twice in ${def.name}`);
+                expect(':');
+                const subjects = [];
+                for (;;) {
+                    const type = ident('a subject type');
+                    if (peek() === ':') {
+                        next();
+                        expect('*');
+                        subjects.push({ type, wildcard: true });
+                    }
+                    else if (peek() === '#') {
+                        next();
+                        subjects.push({ type, relation: ident('a relation name') });
+                    }
+                    else
+                        subjects.push({ type });
+                    if (peek() !== '|')
+                        break;
+                    next();
+                }
+                def.relations[name] = subjects;
+                def.lines[name] = t.line;
+            }
+            else if (t.text === 'permission') {
+                const name = ident('a permission name');
+                if (name in def.relations || name in def.permissions)
+                    throw new SchemaParseError(t.line, `${name} is declared twice in ${def.name}`);
+                expect('=');
+                def.permissions[name] = expression();
+                def.lines[name] = t.line;
+            }
+            else
+                throw new SchemaParseError(t.line, `expected "relation", "permission" or "}", found "${t.text}"`);
+        }
+        next();
+        defs.push(def);
+    }
+    // Every reference must name something declared in its own definition; an arrow's left must be a relation.
+    for (const def of defs) {
+        const check = (e, line) => {
+            if (e.op === 'ref') {
+                if (!(e.name in def.relations) && !(e.name in def.permissions))
+                    throw new SchemaParseError(line, `${def.name} has no relation or permission "${e.name}"`);
+            }
+            else if (e.op === 'arrow') {
+                if (!(e.left in def.relations))
+                    throw new SchemaParseError(line, `${def.name} has no relation "${e.left}" to follow with ->`);
+            }
+            else {
+                check(e.l, line);
+                check(e.r, line);
+            }
+        };
+        for (const e of Object.values(def.permissions))
+            check(e, tokens.find((t) => t.text === def.name)?.line ?? 1);
+    }
+    return defs;
+}

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

@@ -0,0 +1,21 @@
+import type { CanvasDb } from '../canvas/db.js';
+import { type Definition } from './schema-parser.js';
+export interface Registered {
+    namespace: string;
+    version: number;
+    changed: boolean;
+}
+/** Built-ins plus every registered app definition. */
+export declare function loadDefinitions(db: CanvasDb): Promise<Map<string, Definition>>;
+export interface SchemaRow {
+    namespace: string;
+    app: string;
+    version: number;
+    source: string;
+}
+export declare function schemaOf(db: CanvasDb, namespace: string): Promise<SchemaRow | null>;
+/** Validate `source` as the schema of `namespace`: parse it, require every definition to live in the namespace and every subject type to be declared. */
+export declare function validateSchema(namespace: string, source: string): Definition[];
+/** Register or change an app's schema. Same source: no-op. A new source bumps the version; removing a relation that still holds facts is refused
+ *  `409 relation_in_use`. A namespace belongs to the app that registered it first (`403 namespace_taken`). Facts are never rewritten. */
+export declare function registerSchema(db: CanvasDb, app: string, namespace: string, source: string): Promise<Registered>;

package/dist/core/permissions/schemas.js

@@ -0,0 +1,83 @@
+import { BUILTIN_DEFINITIONS } from './builtin.js';
+import { PermissionError } from './errors.js';
+import { assertNoUnsupportedRecursion } from './compile.js';
+import { parseSchema, SchemaParseError } from './schema-parser.js';
+const NAMESPACE = /^[a-z][a-z0-9_-]{0,63}$/;
+/** Built-ins plus every registered app definition. */
+export async function loadDefinitions(db) {
+    const defs = new Map(BUILTIN_DEFINITIONS.map((d) => [d.name, d]));
+    for (const row of await db.prepareUncached('SELECT compiled_json FROM schemas').all()) {
+        for (const d of JSON.parse(row.compiled_json))
+            defs.set(d.name, d);
+    }
+    return defs;
+}
+export async function schemaOf(db, namespace) {
+    return await db.prepare('SELECT namespace, app, version, source FROM schemas WHERE namespace = ?').get(namespace) ?? null;
+}
+/** Validate `source` as the schema of `namespace`: parse it, require every definition to live in the namespace and every subject type to be declared. */
+export function validateSchema(namespace, source) {
+    if (!NAMESPACE.test(namespace) || namespace === 'crtr')
+        throw new PermissionError(403, 'namespace_taken', `namespace ${JSON.stringify(namespace)} is reserved or malformed`);
+    let defs;
+    try {
+        defs = parseSchema(source);
+    }
+    catch (e) {
+        if (e instanceof SchemaParseError)
+            throw new PermissionError(400, 'schema_invalid', e.message, { line: e.line, message: e.message });
+        throw e;
+    }
+    const all = [...BUILTIN_DEFINITIONS, ...defs];
+    try {
+        assertNoUnsupportedRecursion(all, defs);
+    }
+    catch (e) {
+        if (e instanceof SchemaParseError)
+            throw new PermissionError(400, 'schema_invalid', e.message, { line: e.line, message: e.message });
+        throw e;
+    }
+    const known = new Set(all.map((d) => d.name));
+    for (const d of defs) {
+        if (!d.name.startsWith(`${namespace}/`))
+            throw new PermissionError(400, 'schema_invalid', `definition ${d.name} must be named ${namespace}/<name>`, { line: 1, message: `definition ${d.name} must be named ${namespace}/<name>` });
+        for (const [rel, subjects] of Object.entries(d.relations))
+            for (const s of subjects) {
+                if (!known.has(s.type))
+                    throw new PermissionError(400, 'schema_invalid', `${d.name}#${rel}: unknown subject type ${s.type}`, { line: 1, message: `unknown subject type ${s.type}` });
+                if (s.relation !== undefined) {
+                    const target = all.find((x) => x.name === s.type);
+                    if (!(s.relation in target.relations) && !(s.relation in target.permissions))
+                        throw new PermissionError(400, 'schema_invalid', `${d.name}#${rel}: ${s.type} has no ${s.relation}`, { line: 1, message: `${s.type} has no ${s.relation}` });
+                }
+            }
+    }
+    return defs;
+}
+/** Register or change an app's schema. Same source: no-op. A new source bumps the version; removing a relation that still holds facts is refused
+ *  `409 relation_in_use`. A namespace belongs to the app that registered it first (`403 namespace_taken`). Facts are never rewritten. */
+export async function registerSchema(db, app, namespace, source) {
+    const defs = validateSchema(namespace, source);
+    const existing = await schemaOf(db, namespace);
+    if (existing !== null && existing.app !== app)
+        throw new PermissionError(403, 'namespace_taken', `namespace ${namespace} belongs to ${existing.app}`);
+    if (existing !== null && existing.source === source)
+        return { namespace, version: existing.version, changed: false };
+    if (existing !== null) {
+        const next = new Map(defs.map((d) => [d.name, d]));
+        for (const old of parseSchema(existing.source)) {
+            for (const rel of Object.keys(old.relations)) {
+                if (next.get(old.name)?.relations[rel] !== undefined)
+                    continue;
+                const n = await db.prepare('SELECT count(*) AS n FROM relations WHERE resource_type = ? AND relation = ?').get(old.name, rel);
+                if (n.n > 0)
+                    throw new PermissionError(409, 'relation_in_use', `${old.name}#${rel} still holds ${n.n} facts; delete them first`, { relation: `${old.name}#${rel}`, facts: n.n });
+            }
+        }
+    }
+    const version = (existing?.version ?? 0) + 1;
+    await db.prepare(`INSERT INTO schemas (namespace, app, version, source, compiled_json, registered_at) VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT (namespace) DO UPDATE SET version = excluded.version, source = excluded.source, compiled_json = excluded.compiled_json, registered_at = excluded.registered_at`)
+        .run(namespace, app, version, source, JSON.stringify(defs), new Date().toISOString());
+    return { namespace, version, changed: true };
+}

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

@@ -0,0 +1,16 @@
+import type { CanvasValue } from '../canvas/db.js';
+/** A SQL fragment with bare `?` placeholders and its parameters in textual order: concatenating fragments in order keeps them aligned. */
+export interface Frag {
+    sql: string;
+    params: CanvasValue[];
+}
+export declare const TRUE: Frag;
+export declare const FALSE: Frag;
+/** Tagged template: a `Frag` value is inlined with its parameters, any other value becomes one `?` parameter (arrays included). */
+export declare function f(strings: TemplateStringsArray, ...values: unknown[]): Frag;
+export declare const raw: (sql: string) => Frag;
+export declare const isFrag: (v: unknown) => v is Frag;
+/** Join fragments with a separator, e.g. ` OR `. An empty list is `empty`. */
+export declare function joinFrags(parts: Frag[], sep: string, empty: Frag): Frag;
+export declare const or: (parts: Frag[]) => Frag;
+export declare const and: (parts: Frag[]) => Frag;

package/dist/core/permissions/sql.js

@@ -0,0 +1,31 @@
+export const TRUE = { sql: 'TRUE', params: [] };
+export const FALSE = { sql: 'FALSE', params: [] };
+/** Tagged template: a `Frag` value is inlined with its parameters, any other value becomes one `?` parameter (arrays included). */
+export function f(strings, ...values) {
+    let sql = strings[0];
+    const params = [];
+    values.forEach((v, i) => {
+        if (isFrag(v)) {
+            sql += v.sql;
+            params.push(...v.params);
+        }
+        else {
+            sql += '?';
+            params.push(v);
+        }
+        sql += strings[i + 1];
+    });
+    return { sql, params };
+}
+export const raw = (sql) => ({ sql, params: [] });
+export const isFrag = (v) => typeof v === 'object' && v !== null && 'sql' in v && 'params' in v && Array.isArray(v.params);
+/** Join fragments with a separator, e.g. ` OR `. An empty list is `empty`. */
+export function joinFrags(parts, sep, empty) {
+    if (parts.length === 0)
+        return empty;
+    if (parts.length === 1)
+        return parts[0];
+    return { sql: `(${parts.map((p) => p.sql).join(sep)})`, params: parts.flatMap((p) => p.params) };
+}
+export const or = (parts) => joinFrags(parts.filter((p) => p.sql !== 'FALSE'), ' OR ', FALSE);
+export const and = (parts) => joinFrags(parts.filter((p) => p.sql !== 'TRUE'), ' AND ', TRUE);

package/dist/core/plugin-app.d.ts

@@ -0,0 +1,31 @@
+import type { InstalledPlugin } from '../types.js';
+export interface InvalidAppPlugin {
+    plugin: InstalledPlugin;
+    error: string;
+}
+export interface PluginAppCredential {
+    plugin: InstalledPlugin;
+    token: string;
+    socket: string;
+    /** The endpoint of the installed manifest's http transport, or null for an exec plugin. */
+    endpoint: string | null;
+}
+/** The space-joined path of every leaf below the plugin's root command, with the command-validation issues. */
+export declare function pluginLeafPaths(plugin: InstalledPlugin): {
+    leafPaths: Set<string>;
+    streamingLeafPaths: Set<string>;
+    issues: string[];
+};
+/** Enabled user plugins that hold an app token: not a provider, declaring kinds or scopes or serving over HTTP, with a clean manifest. */
+export declare function appPlugins(): InstalledPlugin[];
+/** Enabled user plugins and provider bundles with a clean manifest that declare `object_kinds`, whether or not they hold a token. */
+export declare function kindPlugins(): InstalledPlugin[];
+/** The enabled plugins and provider bundles that would hold a token or declare object blocks but whose manifest or commands are invalid, with why. */
+export declare function invalidAppPlugins(): InvalidAppPlugin[];
+/** The environment an exec leaf of `plugin` gets, or null when it holds no token. */
+export declare function pluginAppEnv(plugin: string): {
+    CRTR_APP_TOKEN: string;
+    CRTR_DAEMON_SOCKET: string;
+} | null;
+/** The credential of an app plugin, or null when it is not in `appPlugins()` or holds no token. */
+export declare function pluginAppCredential(name: string): PluginAppCredential | null;