@north-light/sdk 0.3.548 → 0.3.550

package/dist/testing/permissions.js

@@ -0,0 +1,261 @@
+// The permission semantics FakeCloud's space shares with the daemon (`src/core/permissions`): the built-in definitions, schema validation, fact
+// validation and an in-memory evaluator over the same parsed schemas. The daemon compiles one permission to SQL (`compile.ts`); this walks the
+// same expressions over facts in memory, so `sdk-fake-conformance.test.ts` can hold both to one set of cases. Refusals carry the daemon's codes.
+import { parseSchema, SchemaParseError } from './schema-parser.js';
+import { refuse } from './wire.js';
+export const BUILTIN_SOURCE = `
+definition user {}
+definition app {}
+definition crtr/group {
+  relation member: user | crtr/group#member
+}
+definition crtr/object {
+  relation parent: crtr/object
+  relation acts_for: user
+  relation reader: user | user:* | crtr/group#member
+  relation editor: user | crtr/group#member
+  relation messenger: user | crtr/group#member
+  relation user_of: user | crtr/group#member
+  permission read = reader + editor + messenger + user_of + acts_for + parent->read
+  permission edit = editor + acts_for + parent->edit
+  permission message = messenger + acts_for + parent->message
+  permission use = user_of + acts_for + parent->use
+  permission share = acts_for + parent->share
+}
+`;
+const BUILTIN_DEFINITIONS = parseSchema(BUILTIN_SOURCE);
+export const OBJECT_TYPE = 'crtr/object';
+const NAMESPACE = /^[a-z][a-z0-9_-]{0,63}$/;
+const MAX_DEPTH = 8;
+const has = (record, key) => Object.hasOwn(record, key);
+export const formatSubject = (s) => `${s.type}:${s.id}${s.relation === '' ? '' : `#${s.relation}`}`;
+export const factKey = (f) => `${f.resourceType}\u0000${f.resourceId}\u0000${f.relation}\u0000${formatSubject(f.subject)}`;
+/** `<type>:<id>[#<relation>]`; the type may contain `/`. */
+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 refuse(400, 'subject_invalid', `${JSON.stringify(text)} is not a subject (<type>:<id>[#<relation>])`);
+    return { type: m[1], id: m[2], relation: m[3] ?? '' };
+}
+/** `<type>:<id>` 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);
+    return m === null ? { type: OBJECT_TYPE, id: text } : { type: m[1], id: m[2] };
+}
+export const builtinDefinitions = () => new Map(BUILTIN_DEFINITIONS.map((d) => [d.name, d]));
+/** 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. */
+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));
+            }
+        }
+    }
+}
+/** Parse `source` as the schema of `namespace`: every definition must live in the namespace and every subject type must be declared. */
+export function validateSchema(namespace, source) {
+    if (!NAMESPACE.test(namespace) || namespace === 'crtr')
+        throw refuse(403, 'namespace_taken', `namespace ${JSON.stringify(namespace)} is reserved or malformed`);
+    let defs;
+    try {
+        defs = parseSchema(source);
+    }
+    catch (e) {
+        if (e instanceof SchemaParseError)
+            throw refuse(400, 'schema_invalid', e.message, { details: { line: e.line, message: e.message } });
+        throw e;
+    }
+    const all = [...BUILTIN_DEFINITIONS, ...defs];
+    try {
+        assertNoUnsupportedRecursion(all, defs);
+    }
+    catch (e) {
+        if (e instanceof SchemaParseError)
+            throw refuse(400, 'schema_invalid', e.message, { details: { line: e.line, message: e.message } });
+        throw e;
+    }
+    const known = new Set(all.map((d) => d.name));
+    const invalidSchema = (message, detail) => refuse(400, 'schema_invalid', message, { details: { line: 1, message: detail } });
+    for (const d of defs) {
+        if (!d.name.startsWith(`${namespace}/`))
+            throw invalidSchema(`definition ${d.name} must be named ${namespace}/<name>`, `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 invalidSchema(`${d.name}#${rel}: unknown subject type ${s.type}`, `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 invalidSchema(`${d.name}#${rel}: ${s.type} has no ${s.relation}`, `${s.type} has no ${s.relation}`);
+                }
+            }
+    }
+    return defs;
+}
+/** The relations `previous` declares that `next` drops: `{ name: '<definition>#<relation>' }` for each. */
+export function droppedRelations(previous, next) {
+    const kept = new Map(next.map((d) => [d.name, d]));
+    return previous.flatMap((old) => Object.keys(old.relations).filter((rel) => kept.get(old.name)?.relations[rel] === undefined).map((relation) => ({ definition: old.name, relation })));
+}
+/** A fact must name a defined type, a relation that type declares, and a subject the relation lists (so `editor @ user:*` fails like any unlisted subject). */
+export function validateFact(defs, fact) {
+    const def = defs.get(fact.resourceType);
+    if (def === undefined)
+        throw refuse(400, 'unknown_type', `no schema defines ${fact.resourceType}`);
+    if (fact.resourceType === OBJECT_TYPE && fact.relation === 'parent')
+        throw refuse(400, 'unknown_relation', 'parent is the object owner, never stored');
+    const listed = has(def.relations, fact.relation) ? def.relations[fact.relation] : undefined;
+    if (listed === undefined)
+        throw refuse(400, 'unknown_relation', `${fact.resourceType} has no relation ${fact.relation}`, { details: { 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 refuse(400, 'subject_not_allowed', `${fact.resourceType}#${fact.relation} does not accept ${formatSubject(s)}`, { details: { relation: fact.relation, subject: formatSubject(s) } });
+}
+/** Does `userId` hold `permission` on the resource? An unknown type or permission is false, as in the daemon. A person reaches no `crtr/group`:
+ *  an app cannot write group facts, so no group is ever reached here. */
+export function holds(defs, facts, userId, resourceType, resourceId, permission) {
+    return new Evaluator(defs, [...facts], [userId, '*']).permission(resourceType, permission, resourceId);
+}
+class Evaluator {
+    defs;
+    facts;
+    userIds;
+    constructor(defs, facts, userIds) {
+        this.defs = defs;
+        this.facts = facts;
+        this.userIds = userIds;
+    }
+    subjectsOf(type, id, relation) {
+        return this.facts.filter((f) => f.resourceType === type && f.resourceId === id && f.relation === relation).map((f) => f.subject);
+    }
+    permission(typeName, name, id, depth = 0) {
+        const def = this.defs.get(typeName);
+        if (def === undefined || depth > MAX_DEPTH)
+            return false;
+        if (has(def.relations, name))
+            return this.relation(def, name, id, depth);
+        const expr = has(def.permissions, name) ? def.permissions[name] : undefined;
+        if (expr === undefined)
+            return false;
+        return this.closure(def, name, expr, id, depth) ?? this.expr(def, expr, id, depth);
+    }
+    /** `x->name` among the top-level union terms of `name` itself, with `x` pointing back at `def`: the other terms hold at some ancestor, however far up. */
+    closure(def, name, expr, id, depth) {
+        const terms = [];
+        const flatten = (e) => { if (e.op === 'union') {
+            flatten(e.l);
+            flatten(e.r);
+        }
+        else
+            terms.push(e); };
+        flatten(expr);
+        const self = terms.find((t) => t.op === 'arrow' && t.right === name && def.relations[t.left]?.some((s) => s.type === def.name && s.relation === undefined));
+        if (self === undefined || self.op !== 'arrow')
+            return null;
+        const local = terms.filter((t) => t !== self);
+        const seen = new Set();
+        for (let queue = [id]; queue.length > 0;) {
+            const at = queue.pop();
+            if (seen.has(at))
+                continue;
+            seen.add(at);
+            if (local.some((t) => this.expr(def, t, at, depth)))
+                return true;
+            queue = [...queue, ...this.subjectsOf(def.name, at, self.left).map((s) => s.id)];
+        }
+        return false;
+    }
+    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 this.expr(def, e.l, id, depth) || this.expr(def, e.r, id, depth);
+            case 'inter': return this.expr(def, e.l, id, depth) && this.expr(def, e.r, id, depth);
+            case 'excl': return this.expr(def, e.l, id, depth) && !this.expr(def, e.r, id, depth);
+        }
+    }
+    relation(def, name, id, depth) {
+        const facts = this.subjectsOf(def.name, id, name);
+        return def.relations[name].some((s) => facts.some((f) => {
+            if (s.type === 'user')
+                return s.relation === undefined && f.type === 'user' && this.userIds.includes(f.id);
+            if (s.relation === undefined || s.type === 'crtr/group')
+                return false; // a plain object subject is reached only through an arrow
+            return f.type === s.type && f.relation === s.relation && this.permission(s.type, s.relation, f.id, depth + 1);
+        }));
+    }
+    arrow(def, left, right, id, depth) {
+        const facts = this.subjectsOf(def.name, id, left);
+        return (def.relations[left] ?? []).some((s) => {
+            if (s.type === 'user' || s.relation !== undefined)
+                return false;
+            const target = this.defs.get(s.type);
+            if (target === undefined || !(right in target.permissions || right in target.relations))
+                return false;
+            return facts.some((f) => f.type === s.type && this.permission(s.type, right, f.id, depth + 1));
+        });
+    }
+}

package/dist/testing/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/testing/schema-parser.js

@@ -0,0 +1,153 @@
+// A copy of the daemon's `src/core/permissions/schema-parser.ts`: the published SDK cannot import daemon source, and FakeCloud must
+// accept and refuse exactly the schemas the real API does. `sdk-fake-conformance.test.ts` runs the same schema cases against both.
+// 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/testing/space.d.ts

@@ -0,0 +1,42 @@
+export type SpaceOp = 'schema.register' | 'relations.write' | 'relations.replace' | 'relations.list' | 'check' | 'doc.write' | 'doc.edit' | 'doc.delete' | 'object.list' | 'object.search' | 'object.get';
+export declare const SPACE_OPS: ReadonlySet<string>;
+export declare class FakeSpace {
+    private readonly clientId;
+    private readonly userId;
+    private readonly now;
+    private readonly schemas;
+    private facts;
+    private readonly docs;
+    private serial;
+    constructor(clientId: string, userId: string, now: () => string);
+    clear(): void;
+    /** The built-in definitions plus every registered app definition. */
+    private definitions;
+    handle(op: SpaceOp, id: string | undefined, query: URLSearchParams, rawBody: unknown): {
+        status: number;
+        body: unknown;
+    };
+    private json;
+    private ownerHandle;
+    private canonical;
+    private byRef;
+    /** A resource type `<namespace>/<name>` must live in a namespace this app registered. */
+    private owned;
+    private register;
+    private factList;
+    private fact;
+    /** Validate and apply facts to `into`, in order; false when the fact was already there. */
+    private put;
+    private change;
+    private replace;
+    private list;
+    /** The schema's permission over the facts, for the person `subject`: unknown types and permissions are false, as in the daemon. */
+    private check;
+    private write;
+    private edit;
+    private remove;
+    private item;
+    private filter;
+    private search;
+    private read;
+}