@weaveprotocol/core 0.1.0

package/dist/space/presets.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module space/presets
+ * Starting roles for a space — plain data, and nothing more.
+ *
+ * The protocol takes no position on what roles a space should have: it reads
+ * whatever roles a space's genesis names, and never looks at a preset's name.
+ * These are for app developers who want a sensible start. Pass one when
+ * creating a space, change it, or write your own.
+ *
+ * `*` alone is every permission. `*` + `/` + `*` is every permission a
+ * collection declares — so a moderator here can moderate whatever apps the
+ * space holds, now and later, without managing the space itself.
+ */
+import type { SpaceRole } from '../types.js';
+export interface RolePreset {
+    readonly roles: ReadonlyArray<SpaceRole>;
+    /** Which of them the creator starts with */
+    readonly creatorRole: string;
+}
+/** Just the creator. Invites are view-only: there is no role below theirs. */
+export declare const solo: RolePreset;
+/** A small group working together: everyone invited can write, invite and add collections. */
+export declare const team: RolePreset;
+/** A community: admins run it, moderators keep order in every app, members take part. */
+export declare const community: RolePreset;
+export declare const rolePresets: Readonly<{
+    solo: RolePreset;
+    team: RolePreset;
+    community: RolePreset;
+}>;
+//# sourceMappingURL=presets.d.ts.map

package/dist/space/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../src/space/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACzC,4CAA4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,8EAA8E;AAC9E,eAAO,MAAM,IAAI,EAAE,UAGjB,CAAC;AAEH,8FAA8F;AAC9F,eAAO,MAAM,IAAI,EAAE,UAMjB,CAAC;AAEH,yFAAyF;AACzF,eAAO,MAAM,SAAS,EAAE,UAOtB,CAAC;AAEH,eAAO,MAAM,WAAW;;;;EAA2C,CAAC"}

package/dist/space/presets.js

@@ -0,0 +1,24 @@
+/** Just the creator. Invites are view-only: there is no role below theirs. */
+export const solo = Object.freeze({
+    roles: Object.freeze([{ name: 'owner', title: 'Owner', rank: 100, permissions: ['*'] }]),
+    creatorRole: 'owner',
+});
+/** A small group working together: everyone invited can write, invite and add collections. */
+export const team = Object.freeze({
+    roles: Object.freeze([
+        { name: 'owner', title: 'Owner', rank: 100, permissions: ['*'] },
+        { name: 'editor', title: 'Editor', rank: 10, permissions: ['invite', 'define'] },
+    ]),
+    creatorRole: 'owner',
+});
+/** A community: admins run it, moderators keep order in every app, members take part. */
+export const community = Object.freeze({
+    roles: Object.freeze([
+        { name: 'admin', title: 'Admin', rank: 100, permissions: ['*'] },
+        { name: 'moderator', title: 'Moderator', rank: 50, permissions: ['invite', '*/*'] },
+        { name: 'member', title: 'Member', rank: 0, permissions: [] },
+    ]),
+    creatorRole: 'admin',
+});
+export const rolePresets = Object.freeze({ solo, team, community });
+//# sourceMappingURL=presets.js.map

package/dist/space/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../../src/space/presets.ts"],"names":[],"mappings":"AAqBA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,IAAI,GAAe,MAAM,CAAC,MAAM,CAAC;IAC5C,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxF,WAAW,EAAE,OAAO;CACrB,CAAC,CAAC;AAEH,8FAA8F;AAC9F,MAAM,CAAC,MAAM,IAAI,GAAe,MAAM,CAAC,MAAM,CAAC;IAC5C,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;QACnB,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC,GAAG,CAAC,EAAE;QAChE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE;KACjF,CAAC;IACF,WAAW,EAAE,OAAO;CACrB,CAAC,CAAC;AAEH,yFAAyF;AACzF,MAAM,CAAC,MAAM,SAAS,GAAe,MAAM,CAAC,MAAM,CAAC;IACjD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC;QACnB,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC,GAAG,CAAC,EAAE;QAChE,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE;QACnF,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE;KAC9D,CAAC;IACF,WAAW,EAAE,OAAO;CACrB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC"}

package/dist/space/roles.d.ts

@@ -0,0 +1,186 @@
+/**
+ * @module space/roles
+ * Who may do what in a space: its roles, its members, its invites, and the
+ * history of changes to them — replayed the same way on every peer.
+ *
+ * This module knows people and permissions. It knows nothing about polls or
+ * todos: a collection's rules name a permission (`can:moderate`), and this
+ * module answers one question about it — *does this account hold that
+ * permission here, as of this point in the space's history?*
+ *
+ * **Roles.** A role is a name, a rank and a list of permissions. Permissions
+ * are plain strings: three the protocol checks itself (`manage`, `invite`,
+ * `define`) and whatever the collections in the space declare
+ * (`app.poll/moderate`). A `*` in a role's permission matches any run of
+ * characters, so `*` alone is every permission.
+ *
+ * **Rank.** You may change people and roles ranked below you, and give out
+ * roles up to your own rank. Two people at the same rank can never remove each
+ * other — only themselves.
+ *
+ * **The access history.** Every change to a role, a member, an invite, a
+ * revoked note or a collection definition is a record whose `seen` names the
+ * latest changes its author knew of. That makes a small graph. Replaying it:
+ *
+ * 1. A change comes after everything it saw.
+ * 2. Changes that did not see each other go in this order: ones that take
+ *    something away first — counting everything on the way to one, so a
+ *    removal that also saw something else still comes first — then the
+ *    author with the higher rank, then the lower id.
+ * 3. A change counts only if its author had the power — both as of what they
+ *    had seen, and at its turn in the replay. Of two changes to the same thing
+ *    that did not see each other, the first in the replay wins.
+ *
+ * Everything here is pure and synchronous: the runtime checks signatures,
+ * opens bodies and verifies invite signatures, and hands over plain events.
+ */
+import type { SpaceRole } from '../types.js';
+/** A role, as a space defines it */
+export type Role = SpaceRole;
+/** The permissions the protocol checks itself. Every other one belongs to a collection. */
+export declare const MANAGE = "manage";
+export declare const INVITE = "invite";
+export declare const DEFINE = "define";
+export declare const ROLE_COLLECTION = "sys.role";
+export declare const MEMBER_COLLECTION = "sys.member";
+export declare const INVITE_COLLECTION = "sys.invite";
+export declare const REVOKE_COLLECTION = "sys.revoke";
+/** Collection definitions are part of the access history too: they decide what a rule asks for */
+export declare const DEFINITION_COLLECTION = "sys.collection";
+/** Every collection whose records are part of the access history */
+export declare const ACCESS_COLLECTIONS: ReadonlySet<string>;
+export declare const ROLE_NAME_PATTERN: RegExp;
+/** Why a role is malformed, or null */
+export declare function checkRole(role: unknown): string | null;
+/** Whether a role's permission (which may hold `*`) matches a permission */
+export declare function permissionMatches(pattern: string, permission: string): boolean;
+/** Whether a role holds a permission */
+export declare function roleHolds(role: Role | null | undefined, permission: string): boolean;
+interface EventBase {
+    readonly id: string;
+    /** The record key it changes: `role:moderator`, `member:…`, `invite:…`, `revoke:…`, `collection:…` */
+    readonly key: string;
+    /** The account behind the key that signed it */
+    readonly root: string;
+    /** The latest access changes its author knew of */
+    readonly seen: ReadonlyArray<string>;
+    /** Records by the people this takes power from, that the author had seen and that stay */
+    readonly keep: ReadonlyArray<string>;
+}
+export type AccessEvent = EventBase & ({
+    readonly kind: 'role';
+    readonly name: string; /** Null: the role is removed */
+    readonly role: Role | null;
+} | {
+    readonly kind: 'member';
+    readonly did: string;
+    /** Null: they are no longer a member */
+    readonly role: string | null;
+    /** The invite's public key, when the runtime checked the invite's signature on this record */
+    readonly viaInvite?: string;
+} | {
+    readonly kind: 'invite';
+    readonly inviteKey: string;
+    readonly role: string;
+    readonly open: boolean;
+} | {
+    readonly kind: 'revoke'; /** The note's CID */
+    readonly note: string; /** Who signed the note */
+    readonly issuer: string;
+} | {
+    readonly kind: 'definition';
+    readonly name: string;
+    readonly deleted: boolean;
+});
+/** Who holds what, at one point in the history */
+export interface AccessState {
+    readonly roles: ReadonlyMap<string, Role>;
+    /** Account DID → role name */
+    readonly members: ReadonlyMap<string, string>;
+    /** Invite public key → its role, and whether it is open */
+    readonly invites: ReadonlyMap<string, {
+        readonly role: string;
+        readonly open: boolean;
+        readonly event: string;
+    }>;
+    /** Collection name → the id of the definition in force, and who first defined it */
+    readonly definitions: ReadonlyMap<string, {
+        readonly event: string;
+        readonly definedBy: string;
+    }>;
+}
+/** What a space starts with, from its genesis */
+export interface AccessGenesis {
+    /** The space id — also the id every change implicitly comes after */
+    readonly id: string;
+    readonly creator: string;
+    readonly roles: ReadonlyArray<Role>;
+    readonly creatorRole: string;
+}
+export type EventStatus = {
+    readonly status: 'applied';
+    readonly index: number;
+} | {
+    readonly status: 'dropped';
+    readonly reason: string;
+} | {
+    readonly status: 'waiting';
+};
+export type RecordVerdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly later?: boolean;
+};
+export interface AccessHistory {
+    /** Who holds what once everything held is replayed */
+    readonly current: AccessState;
+    /** What became of one change */
+    status(id: string): EventStatus | null;
+    /** The latest changes — what a new record's `seen` names */
+    heads(): ReadonlyArray<string>;
+    /** The state as of what `seen` names, or null when some of it is not here */
+    at(seen: ReadonlyArray<string>): AccessState | null;
+    /**
+     * Whether a record stands: its author's standing, as of what it saw, must
+     * satisfy `needs`; and no later change it had not seen took that away —
+     * unless that change kept it.
+     * @param record The record's id, its account, what it saw, and the note it was written under
+     * @param needs What the record requires of its author's role
+     */
+    judge(record: {
+        readonly id: string;
+        readonly root: string;
+        readonly seen: ReadonlyArray<string>;
+        readonly note?: string;
+    }, needs: (role: Role | null, state: AccessState) => boolean): RecordVerdict;
+    /** The applied change that revoked a note, if any */
+    revoked(note: string): {
+        readonly event: string;
+        readonly keep: ReadonlySet<string>;
+    } | null;
+    /**
+     * Whether an account appears anywhere in the history — the creator, or
+     * named by any member change, whatever became of it. Only grows as changes
+     * arrive, so it can decide what to store without two peers ever disagreeing
+     * for good.
+     */
+    named(did: string): boolean;
+    /** Whether any change held opens an invite with this key */
+    knownInvite(inviteKey: string): boolean;
+}
+/** Whether an account holds a permission in a state */
+export declare function holds(state: AccessState, did: string, permission: string): boolean;
+/** The role an account holds in a state, or null */
+export declare function standing(state: AccessState, did: string): Role | null;
+/**
+ * Replays a space's access history.
+ * @param genesis What the space started with
+ * @param events Every change held, in any order; duplicates are ignored
+ */
+export declare function replayAccess(genesis: AccessGenesis, events: ReadonlyArray<AccessEvent>): AccessHistory;
+/** Freezes a state for handing out */
+export declare function snapshot(state: AccessState): AccessState;
+export {};
+//# sourceMappingURL=roles.d.ts.map

package/dist/space/roles.d.ts.map

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