@kubun/plugin-p2p 0.10.1 → 0.12.0

package/lib/groups/access-default-token.js

@@ -0,0 +1,103 @@
+import { isVerifiedToken, normalizeDID, stringifyToken, verifyToken } from '@kokuin/token';
+export async function signAccessDefaultSet(identity, claim) {
+    const signed = await identity.signToken({
+        op: 'set',
+        ...claim
+    }, {
+        embedLongForm: true
+    });
+    return stringifyToken(signed);
+}
+export async function signAccessDefaultRemove(identity, claim) {
+    const signed = await identity.signToken({
+        op: 'remove',
+        ...claim
+    }, {
+        embedLongForm: true
+    });
+    return stringifyToken(signed);
+}
+function isPermissionType(value) {
+    return value === 'read' || value === 'write';
+}
+/** The levels the store's read predicate is written for, and no others. */ const ACCESS_LEVELS = new Set([
+    'only_owner',
+    'anyone',
+    'restricted'
+]);
+function isDIDList(value) {
+    return value == null || Array.isArray(value) && value.every((entry)=>typeof entry === 'string');
+}
+/**
+ * Every field, not just `level`.
+ *
+ * This is the only gate between the wire and `setUserModelAccessDefault`: the
+ * applier writes the rule verbatim. Checking `level` alone let a member land an
+ * arbitrary string as an access level, and non-array values in the allow-lists,
+ * in its own rows on every peer — shapes the receiving device's SQL read
+ * predicate was never written for. The blast radius is the sender's own rows
+ * (the applier is sender-bound), which is a reason it is not urgent, not a
+ * reason to accept the shape.
+ */ function isRule(value) {
+    if (value == null || typeof value !== 'object') {
+        return false;
+    }
+    const rule = value;
+    return ACCESS_LEVELS.has(rule.level) && isDIDList(rule.allowedDIDs) && isDIDList(rule.allowedCircles) && // Accepted from the wire but never minted locally: `setModelAccessDefaults`
+    // exposes circles only. Refusing it here would drop a frame a peer on an
+    // older build can still legitimately send, so it is validated and kept.
+    isDIDList(rule.allowedGroups);
+}
+/**
+ * Verify a signed access-default token and extract its claim. Returns `null`
+ * (never throws) when the token is unparseable, unsigned (`alg: 'none'`), or
+ * structurally malformed — an attacker cannot forge an `iss` this way. The
+ * issuer is the normalized verified `iss`.
+ */ export async function verifyAccessDefault(token) {
+    let verified;
+    try {
+        verified = await verifyToken(token);
+    } catch  {
+        return null;
+    }
+    if (!isVerifiedToken(verified)) {
+        return null;
+    }
+    const { iss, op, modelID, hlc } = verified.payload;
+    if (typeof modelID !== 'string' || typeof hlc !== 'string') {
+        return null;
+    }
+    const issuer = normalizeDID(iss);
+    if (op === 'set') {
+        const { permissionType, rule } = verified.payload;
+        if (!isPermissionType(permissionType) || !isRule(rule)) {
+            return null;
+        }
+        return {
+            issuer,
+            claim: {
+                op: 'set',
+                modelID,
+                permissionType,
+                rule,
+                hlc
+            }
+        };
+    }
+    if (op === 'remove') {
+        const { permissionTypes } = verified.payload;
+        if (!Array.isArray(permissionTypes) || !permissionTypes.every(isPermissionType)) {
+            return null;
+        }
+        return {
+            issuer,
+            claim: {
+                op: 'remove',
+                modelID,
+                permissionTypes,
+                hlc
+            }
+        };
+    }
+    return null;
+}

package/lib/groups/admin-roster.d.ts

@@ -0,0 +1,55 @@
+import { type GroupAnchor, type LedgerLogEntry, type RoleValue } from '@kumiai/mls';
+import type { PositionedFoldInput } from './ledger.js';
+/**
+ * Ledger entry `type` for a role grant or demotion. This is `@kumiai/mls`'s own
+ * interpreted type: the same signed entry the library folds into the roster its
+ * commit policy enforces, so kubun's projection and the MLS authority that
+ * accepts or refuses a commit can never disagree about who is an admin.
+ */
+export declare const ADMIN_ROLE_ENTRY_TYPE = "kumiai.role";
+/**
+ * The claim carried by a role entry: the permission the subject holds. Demotion
+ * is `member`, not a distinct "revoked" value — the library's roster is a
+ * DID→permission map, and an absent admin is simply a member.
+ */
+export type AdminRoleValue = RoleValue;
+/** Folded admin set: the normalized DIDs currently holding the admin role. */
+export type AdminRosterState = {
+    admins: Set<string>;
+};
+/**
+ * Fold the role ledger into the admin set.
+ *
+ * With `throughPosition`, only entries enacted at or before that ledger slot are
+ * folded — the roster as it stood at that point in the group's history. That is
+ * the was-admin-then answer the current-only `role` column cannot express, and
+ * unlike the HLC it used to be keyed on, a position is assigned by the commit
+ * chain rather than asserted by the signer, so it cannot be backdated.
+ *
+ * The entries are folded in the order given, which is the order the handle's log
+ * holds them. Authority is rooted at the genesis anchor (the creator is the
+ * epoch-0 admin) and grows only through admins-so-far — `foldRoster` also drops
+ * an entry signed for another group and one that would leave the roster with
+ * zero admins.
+ */
+export declare function foldAdminRoster(entries: Array<PositionedFoldInput<RoleValue>>, anchor: GroupAnchor, groupID: string, throughPosition?: number): AdminRosterState;
+/**
+ * Select the role entries out of a group's control ledger, as fold inputs
+ * carrying the ledger slot each one occupies.
+ *
+ * Every entry is already verified: the log is the handle's own, and each of its
+ * doors — `GroupHandle.applyLedgerEntries`, `bootstrapLedger`, an accepted
+ * commit — re-verifies what it admits. Nothing left to check, nothing to
+ * memoize; this replaced a loader that re-verified every stored `signed_token`
+ * per authority check, needed only because the SQL row could not vouch for
+ * itself.
+ *
+ * The position indexes the WHOLE ledger, not the selected subset, so a role
+ * entry's slot is comparable with a circle entry's — which is what makes "was
+ * this issuer an admin when that entry was enacted" answerable at all.
+ *
+ * The cast is unavoidable: the log is typed over an unknown claim value, and the
+ * entry `type` is what says the value is a role, so selecting by that type is
+ * what makes the narrowing true.
+ */
+export declare function selectRoleEntries(ledger: ReadonlyArray<LedgerLogEntry>): Array<PositionedFoldInput<RoleValue>>;

package/lib/groups/admin-roster.js

@@ -0,0 +1,69 @@
+import { foldRoster, ROLE_ENTRY_TYPE } from '@kumiai/mls';
+/**
+ * Ledger entry `type` for a role grant or demotion. This is `@kumiai/mls`'s own
+ * interpreted type: the same signed entry the library folds into the roster its
+ * commit policy enforces, so kubun's projection and the MLS authority that
+ * accepts or refuses a commit can never disagree about who is an admin.
+ */ export const ADMIN_ROLE_ENTRY_TYPE = ROLE_ENTRY_TYPE;
+function adminsFromRoles(roles) {
+    const admins = new Set();
+    for (const [did, permission] of roles){
+        if (permission === 'admin') {
+            admins.add(did);
+        }
+    }
+    return admins;
+}
+/**
+ * Fold the role ledger into the admin set.
+ *
+ * With `throughPosition`, only entries enacted at or before that ledger slot are
+ * folded — the roster as it stood at that point in the group's history. That is
+ * the was-admin-then answer the current-only `role` column cannot express, and
+ * unlike the HLC it used to be keyed on, a position is assigned by the commit
+ * chain rather than asserted by the signer, so it cannot be backdated.
+ *
+ * The entries are folded in the order given, which is the order the handle's log
+ * holds them. Authority is rooted at the genesis anchor (the creator is the
+ * epoch-0 admin) and grows only through admins-so-far — `foldRoster` also drops
+ * an entry signed for another group and one that would leave the roster with
+ * zero admins.
+ */ export function foldAdminRoster(entries, anchor, groupID, throughPosition) {
+    const scoped = throughPosition == null ? entries : entries.filter(({ position })=>position <= throughPosition);
+    const roster = foldRoster(scoped, anchor, groupID);
+    return {
+        admins: adminsFromRoles(roster.roles)
+    };
+}
+/**
+ * Select the role entries out of a group's control ledger, as fold inputs
+ * carrying the ledger slot each one occupies.
+ *
+ * Every entry is already verified: the log is the handle's own, and each of its
+ * doors — `GroupHandle.applyLedgerEntries`, `bootstrapLedger`, an accepted
+ * commit — re-verifies what it admits. Nothing left to check, nothing to
+ * memoize; this replaced a loader that re-verified every stored `signed_token`
+ * per authority check, needed only because the SQL row could not vouch for
+ * itself.
+ *
+ * The position indexes the WHOLE ledger, not the selected subset, so a role
+ * entry's slot is comparable with a circle entry's — which is what makes "was
+ * this issuer an admin when that entry was enacted" answerable at all.
+ *
+ * The cast is unavoidable: the log is typed over an unknown claim value, and the
+ * entry `type` is what says the value is a role, so selecting by that type is
+ * what makes the narrowing true.
+ */ export function selectRoleEntries(ledger) {
+    const entries = [];
+    for (const [position, held] of ledger.entries()){
+        if (held.verified.entry.type !== ADMIN_ROLE_ENTRY_TYPE) {
+            continue;
+        }
+        entries.push({
+            verified: held.verified,
+            entryID: held.entryID,
+            position
+        });
+    }
+    return entries;
+}

package/lib/groups/anchor-store.d.ts

@@ -0,0 +1,15 @@
+import type { StoreProvider } from '@kubun/db';
+import type { AnchorStore } from '@kumiai/rpc';
+/**
+ * The `@kumiai/rpc` `AnchorStore` port for one group, backed by the device's
+ * single-slot anchor store. The port carries no group scope — the group a peer
+ * belongs to is fixed for its lifetime — so the adapter closes over `groupID`
+ * and threads it into every store call.
+ *
+ * `null` from `load` MEANS FIRST BOOT AND ONLY FIRST BOOT — the peer answers it by
+ * seeding the anchor from its live handle, and MLS ratchets forward so no earlier
+ * epoch's secret can be re-exported. A read error must therefore PROPAGATE, never
+ * be coerced to `null`: a `null` for a group that HAS an anchor silently derives
+ * different topic IDs and partitions this device with nothing reported.
+ */
+export declare function createAnchorStore(stores: StoreProvider, groupID: string): AnchorStore;

package/lib/groups/anchor-store.js

@@ -0,0 +1,37 @@
+import { getP2PStore } from '@kubun/store-p2p';
+/**
+ * The `@kumiai/rpc` `AnchorStore` port for one group, backed by the device's
+ * single-slot anchor store. The port carries no group scope — the group a peer
+ * belongs to is fixed for its lifetime — so the adapter closes over `groupID`
+ * and threads it into every store call.
+ *
+ * `null` from `load` MEANS FIRST BOOT AND ONLY FIRST BOOT — the peer answers it by
+ * seeding the anchor from its live handle, and MLS ratchets forward so no earlier
+ * epoch's secret can be re-exported. A read error must therefore PROPAGATE, never
+ * be coerced to `null`: a `null` for a group that HAS an anchor silently derives
+ * different topic IDs and partitions this device with nothing reported.
+ */ export function createAnchorStore(stores, groupID) {
+    return {
+        async load () {
+            const store = await getP2PStore(stores);
+            const row = await store.getGroupAnchor(groupID);
+            if (row == null) {
+                return null;
+            }
+            // Copied into a fresh `Uint8Array` the port owns, so nothing downstream
+            // holds a view onto the adapter's decoded row.
+            return {
+                secret: new Uint8Array(row.secret),
+                epoch: row.epoch
+            };
+        },
+        async save (anchor) {
+            const store = await getP2PStore(stores);
+            await store.putGroupAnchor({
+                groupID,
+                secret: anchor.secret,
+                epoch: anchor.epoch
+            });
+        }
+    };
+}

package/lib/groups/app-cursor-store.d.ts

@@ -0,0 +1,17 @@
+import type { StoreProvider } from '@kubun/db';
+import type { AppCursorStore } from '@kumiai/rpc';
+/**
+ * The `@kumiai/rpc` `AppCursorStore` port for one group, backed by the device's
+ * per-topic cursor store. The port keys positions by topic ID alone — a topic
+ * ID is already globally unique — so the adapter closes over `groupID` purely
+ * to give each row an owner: a deleted group's cursors go with it, rather than
+ * staying behind as unreachable rows nothing accounts for.
+ *
+ * `null` here means this device has never processed a frame on the topic, and
+ * the drain answers it by reading from the hub's oldest retained frame. Unlike
+ * the anchor, a wrong `null` costs a re-read, not a partition.
+ *
+ * Positions are opaque log positions: stored and returned verbatim, never
+ * compared or parsed here.
+ */
+export declare function createAppCursorStore(stores: StoreProvider, groupID: string): AppCursorStore;

package/lib/groups/app-cursor-store.js

@@ -0,0 +1,34 @@
+import { getP2PStore } from '@kubun/store-p2p';
+/**
+ * The `@kumiai/rpc` `AppCursorStore` port for one group, backed by the device's
+ * per-topic cursor store. The port keys positions by topic ID alone — a topic
+ * ID is already globally unique — so the adapter closes over `groupID` purely
+ * to give each row an owner: a deleted group's cursors go with it, rather than
+ * staying behind as unreachable rows nothing accounts for.
+ *
+ * `null` here means this device has never processed a frame on the topic, and
+ * the drain answers it by reading from the hub's oldest retained frame. Unlike
+ * the anchor, a wrong `null` costs a re-read, not a partition.
+ *
+ * Positions are opaque log positions: stored and returned verbatim, never
+ * compared or parsed here.
+ */ export function createAppCursorStore(stores, groupID) {
+    return {
+        async load (topicID) {
+            const store = await getP2PStore(stores);
+            const row = await store.getAppCursor({
+                groupID,
+                topicID
+            });
+            return row?.position ?? null;
+        },
+        async save (topicID, position) {
+            const store = await getP2PStore(stores);
+            await store.putAppCursor({
+                groupID,
+                topicID,
+                position
+            });
+        }
+    };
+}

package/lib/groups/broadcast-codec.js

@@ -1 +1,6 @@
-export function serializeBroadcast(e){return new TextEncoder().encode(JSON.stringify(e))}export function deserializeBroadcast(e){return JSON.parse(new TextDecoder().decode(e))}
+export function serializeBroadcast(message) {
+    return new TextEncoder().encode(JSON.stringify(message));
+}
+export function deserializeBroadcast(bytes) {
+    return JSON.parse(new TextDecoder().decode(bytes));
+}