@kubun/plugin-p2p 0.11.0 → 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

@@ -1,130 +1,55 @@
-import type { Logger } from '@kubun/logger';
-import type { P2PStoreAPI } from '@kubun/store-p2p';
-import type { GroupAnchor } from './group-anchor.js';
-import { type VerifiedLedgerEntry } from './ledger-entry.js';
-import { type FoldInput, type LedgerReducer } from './ledger-fold.js';
-/** Ledger entry `type` for an admin-role grant or revocation. */
-export declare const ADMIN_ROLE_ENTRY_TYPE = "group.role.admin";
+import { type GroupAnchor, type LedgerLogEntry, type RoleValue } from '@kumiai/mls';
+import type { PositionedFoldInput } from './ledger.js';
 /**
- * Projection key for the admin-roster watermark. One projection per entry type
- * in this design, so the key is the entry type itself.
+ * 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_ROSTER_PROJECTION = "group.role.admin";
+export declare const ADMIN_ROLE_ENTRY_TYPE = "kumiai.role";
 /**
- * The claim carried by an admin-role entry. `subject` (on the entry) is the
- * member DID the claim is about; this value says whether that member becomes an
- * admin or loses the 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 = 'admin' | 'revoked';
+export type AdminRoleValue = RoleValue;
 /** Folded admin set: the normalized DIDs currently holding the admin role. */
 export type AdminRosterState = {
     admins: Set<string>;
 };
 /**
- * Self-referential admin roster. Authority is rooted at the genesis anchor (the
- * creator is the epoch-0 admin) and grows only through admins-so-far: every
- * grant or revocation must be issued by a DID already in the set accumulated
- * from strictly-earlier entries. That state-so-far check is what makes rotation
- * sound — an admin can revoke the very creator that granted them without
- * retroactively voiding their own earlier grants.
- */
-export declare const adminRosterReducer: LedgerReducer<AdminRoleValue, AdminRosterState>;
-/**
- * Fold the admin-role ledger into the current admin set. With `atHLC`, only
- * entries at or before that HLC are folded, yielding the exact was-admin-at-HLC
- * answer the current-only role column cannot express. The string `<=` compare on
- * the serialized HLC is the total order (zero-padded, lexicographic), matching
- * the membership-removal LWW elsewhere in the store.
- */
-export declare function foldAdminRoster(entries: Array<FoldInput<AdminRoleValue>>, anchor: GroupAnchor, atHLC?: string): AdminRosterState;
-export type ProjectAdminRosterParams = {
-    store: P2PStoreAPI;
-    groupID: string;
-    anchor: GroupAnchor;
-    /** The group's admin-role ledger entries, in any order. */
-    entries: Array<FoldInput<AdminRoleValue>>;
-    /** Current active members whose role overlay should be reconciled. */
-    memberDIDs: Array<string>;
-};
-/**
- * Project the folded admin set onto the store's `role` column. Membership stays
- * MLS-native — this only overlays a role on members that already exist: each
- * current member is set to `admin` when the fold places them in the set and
- * `member` otherwise. `setGroupMemberRole` is update-only, so a DID in the
- * admin set with no membership row is silently skipped.
- */
-export declare function projectAdminRoster(params: ProjectAdminRosterParams): Promise<void>;
-/**
- * Load the group's admin-role ledger entries and re-verify each `signed_token`
- * into a fold input. The stored token is re-verified rather than trusting the
- * decoded `value` column: the ledger is the source of truth and must stay
- * self-verifying, so a stored token that no longer verifies is dropped and the
- * rest survive. Returned in store order; the fold sorts by total order. Results
- * are memoized per group on the stored id set (see {@link verifiedAdminEntryCache}).
- */
-export declare function loadVerifiedAdminEntries(store: P2PStoreAPI, groupID: string, logger?: Logger): Promise<Array<FoldInput<AdminRoleValue>>>;
-/**
- * Re-project the admin overlay from the stored ledger. The active member set
- * bounds the overlay — `projectAdminRoster` only touches rows that already
- * exist, so an admin DID with no membership is silently skipped.
- */
-export type ProjectAdminRosterFromStoreParams = {
-    store: P2PStoreAPI;
-    groupID: string;
-    anchor: GroupAnchor;
-    logger?: Logger;
-};
-export declare function projectAdminRosterFromStore(params: ProjectAdminRosterFromStoreParams): Promise<void>;
-/**
- * Was `did` a group admin at `atHLC`? Authority is folded from the
- * anchor-seeded ledger evaluated at the operation's HLC (rotation-aware:
- * was-admin-at-HLC, not is-admin-now), conjoined with membership at that HLC.
- * Folding from the genesis anchor — not the local `role` column — is what makes
- * a receiver agree with the author's peer: the creator is the epoch-0 admin on
- * every peer regardless of how its membership row's role was written.
+ * Fold the role ledger into the admin set.
  *
- * Admin implies membership: an MLS-removed member loses admin regardless of the
- * ledger, so membership-at-HLC is checked first and short-circuits.
- */
-export type IsLedgerAdminAtHLCParams = {
-    store: P2PStoreAPI;
-    groupID: string;
-    anchor: GroupAnchor;
-    did: string;
-    atHLC: string;
-    logger?: Logger;
-};
-export declare function isLedgerAdminAtHLC(params: IsLedgerAdminAtHLCParams): Promise<boolean>;
-/**
- * Authoritatively rebuild the admin overlay from the whole ledger and reset the
- * watermark to the newest folded entry. Used on a first projection, an
- * out-of-order arrival, or drift repair — anywhere the cached projection can no
- * longer be trusted as a fold-through-watermark. Seeds the admin set from the
- * genesis anchor (the creator is the epoch-0 admin), so it never relies on a
- * pre-existing `role` value in the store.
+ * 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 type ReprojectAdminRosterParams = {
-    store: P2PStoreAPI;
-    groupID: string;
-    anchor: GroupAnchor;
-    logger?: Logger;
-};
-export declare function reprojectAdminRoster(params: ReprojectAdminRosterParams): Promise<void>;
+export declare function foldAdminRoster(entries: Array<PositionedFoldInput<RoleValue>>, anchor: GroupAnchor, groupID: string, throughPosition?: number): AdminRosterState;
 /**
- * Apply a single just-appended in-order entry onto the current projection
- * without re-folding the whole ledger. The caller guarantees the entry is
- * strictly newer than the watermark, so the projection already equals the
- * fold-so-far: the current admins are exactly the members projected with role
- * `admin`. Authority is read from that projection — only a current admin may
- * grant or revoke — so an entry from a non-admin issuer is dropped (never
- * thrown). `setGroupMemberRole` is update-only, so a grant for a DID with no
- * membership row is silently skipped; admin implies membership and membership
- * stays MLS-native.
+ * 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 type ApplyAdminEntryIncrementalParams = {
-    store: P2PStoreAPI;
-    groupID: string;
-    verified: VerifiedLedgerEntry<AdminRoleValue>;
-    logger?: Logger;
-};
-export declare function applyAdminEntryIncremental(params: ApplyAdminEntryIncrementalParams): Promise<void>;
+export declare function selectRoleEntries(ledger: ReadonlyArray<LedgerLogEntry>): Array<PositionedFoldInput<RoleValue>>;

package/lib/groups/admin-roster.js

@@ -1,184 +1,69 @@
-import { normalizeDID } from '@kokuin/token';
-import { verifyLedgerEntry } from './ledger-entry.js';
-import { foldLedger } from './ledger-fold.js';
-/** Ledger entry `type` for an admin-role grant or revocation. */ export const ADMIN_ROLE_ENTRY_TYPE = 'group.role.admin';
+import { foldRoster, ROLE_ENTRY_TYPE } from '@kumiai/mls';
 /**
- * Projection key for the admin-roster watermark. One projection per entry type
- * in this design, so the key is the entry type itself.
- */ export const ADMIN_ROSTER_PROJECTION = ADMIN_ROLE_ENTRY_TYPE;
-/**
- * Self-referential admin roster. Authority is rooted at the genesis anchor (the
- * creator is the epoch-0 admin) and grows only through admins-so-far: every
- * grant or revocation must be issued by a DID already in the set accumulated
- * from strictly-earlier entries. That state-so-far check is what makes rotation
- * sound — an admin can revoke the very creator that granted them without
- * retroactively voiding their own earlier grants.
- */ export const adminRosterReducer = {
-    type: ADMIN_ROLE_ENTRY_TYPE,
-    seed: (anchor)=>({
-            admins: new Set([
-                normalizeDID(anchor.creatorDID)
-            ])
-        }),
-    verifyAuthority: (verified, state)=>state.admins.has(verified.issuer),
-    apply: (verified, state)=>{
-        const admins = new Set(state.admins);
-        const subject = normalizeDID(verified.entry.subject);
-        if (verified.entry.value === 'admin') {
-            admins.add(subject);
-        } else if (verified.entry.value === 'revoked') {
-            admins.delete(subject);
-        } else {
-            // Unknown claim value: leave the set untouched rather than guess intent.
-            return state;
+ * 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 admin-role ledger into the current admin set. With `atHLC`, only
- * entries at or before that HLC are folded, yielding the exact was-admin-at-HLC
- * answer the current-only role column cannot express. The string `<=` compare on
- * the serialized HLC is the total order (zero-padded, lexicographic), matching
- * the membership-removal LWW elsewhere in the store.
- */ export function foldAdminRoster(entries, anchor, atHLC) {
-    const scoped = atHLC == null ? entries : entries.filter(({ verified })=>verified.entry.hlc <= atHLC);
-    return foldLedger(scoped, anchor, adminRosterReducer);
-}
-/**
- * Project the folded admin set onto the store's `role` column. Membership stays
- * MLS-native — this only overlays a role on members that already exist: each
- * current member is set to `admin` when the fold places them in the set and
- * `member` otherwise. `setGroupMemberRole` is update-only, so a DID in the
- * admin set with no membership row is silently skipped.
- */ export async function projectAdminRoster(params) {
-    const { store, groupID, anchor, entries, memberDIDs } = params;
-    const { admins } = foldAdminRoster(entries, anchor);
-    for (const memberDID of memberDIDs){
-        const role = admins.has(normalizeDID(memberDID)) ? 'admin' : 'member';
-        await store.setGroupMemberRole(groupID, memberDID, role);
     }
+    return admins;
 }
 /**
- * Memoized verified admin entries, one slot per group keyed by the exact set of
- * stored entry ids. Verifying every stored token is the dominant cost of an
- * authority check, and the gate folds on every control op, so re-verifying an
- * unchanged ledger each time is pure waste. Reading the id set stays cheap (an
- * indexed scan); signatures are re-verified only when the set changes. The key
- * is derived purely from content-addressed entry ids — never the `role` column —
- * so the cache can never reintroduce the column-trust bypass: a forged or
- * altered entry produces a different id set, a different key, and a full
- * re-verification. One slot per group bounds memory and self-invalidates, since
- * the ledger is append-only and every append changes the id set.
+ * Fold the role ledger into the admin set.
  *
- * Cross-instance safety: this Map is process-global, shared across store
- * instances and keyed only by group id. Two instances using the same group id
- * with different ledgers stay correct because differing ledgers yield differing
- * keys (entry ids are content digests); the only shared key is the empty-ledger
- * `''`, whose cached value is `[]` — exactly what either empty ledger produces.
- * Group growth is bounded: only device-side peers fold rosters (the blind relay
- * hub never calls this path), so the distinct-group set per process is small and
- * needs no eviction.
- */ const verifiedAdminEntryCache = new Map();
-function adminEntryCacheKey(entryIDs) {
-    return entryIDs.join('\n');
+ * 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)
+    };
 }
 /**
- * Load the group's admin-role ledger entries and re-verify each `signed_token`
- * into a fold input. The stored token is re-verified rather than trusting the
- * decoded `value` column: the ledger is the source of truth and must stay
- * self-verifying, so a stored token that no longer verifies is dropped and the
- * rest survive. Returned in store order; the fold sorts by total order. Results
- * are memoized per group on the stored id set (see {@link verifiedAdminEntryCache}).
- */ export async function loadVerifiedAdminEntries(store, groupID, logger) {
-    const rows = await store.getLedgerEntriesByType(groupID, ADMIN_ROLE_ENTRY_TYPE);
-    const key = adminEntryCacheKey(rows.map((row)=>row.entry_id));
-    const cached = verifiedAdminEntryCache.get(groupID);
-    if (cached != null && cached.key === key) {
-        return cached.entries;
-    }
+ * 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 row of rows){
-        const verified = await verifyLedgerEntry(row.signed_token);
-        if (verified == null) {
-            logger?.warn('admin roster: dropped stored entry whose token no longer verifies', {
-                groupID,
-                entryID: row.entry_id
-            });
+    for (const [position, held] of ledger.entries()){
+        if (held.verified.entry.type !== ADMIN_ROLE_ENTRY_TYPE) {
             continue;
         }
         entries.push({
-            verified,
-            entryID: row.entry_id
+            verified: held.verified,
+            entryID: held.entryID,
+            position
         });
     }
-    verifiedAdminEntryCache.set(groupID, {
-        key,
-        entries
-    });
     return entries;
 }
-export async function projectAdminRosterFromStore(params) {
-    const { store, groupID, anchor, logger } = params;
-    const entries = await loadVerifiedAdminEntries(store, groupID, logger);
-    const memberDIDs = (await store.listGroupMembers(groupID)).map((member)=>member.member_did);
-    await projectAdminRoster({
-        store,
-        groupID,
-        anchor,
-        entries,
-        memberDIDs
-    });
-}
-export async function isLedgerAdminAtHLC(params) {
-    const { store, groupID, anchor, did, atHLC, logger } = params;
-    if (!await store.isGroupMemberAtHLC(groupID, did, atHLC)) return false;
-    const entries = await loadVerifiedAdminEntries(store, groupID, logger);
-    const { admins } = foldAdminRoster(entries, anchor, atHLC);
-    return admins.has(normalizeDID(did));
-}
-export async function reprojectAdminRoster(params) {
-    const { store, groupID, anchor, logger } = params;
-    const entries = await loadVerifiedAdminEntries(store, groupID, logger);
-    const memberDIDs = (await store.listGroupMembers(groupID)).map((member)=>member.member_did);
-    await projectAdminRoster({
-        store,
-        groupID,
-        anchor,
-        entries,
-        memberDIDs
-    });
-    // Watermark through the newest folded entry: the projection now equals the
-    // fold of every verified entry, so a later in-order arrival (strictly newer
-    // HLC) can be applied incrementally instead of forcing a full reproject.
-    let maxHLC = null;
-    for (const { verified } of entries){
-        if (maxHLC == null || verified.entry.hlc > maxHLC) {
-            maxHLC = verified.entry.hlc;
-        }
-    }
-    if (maxHLC != null) {
-        await store.setProjectionWatermark(groupID, ADMIN_ROSTER_PROJECTION, maxHLC);
-    }
-}
-export async function applyAdminEntryIncremental(params) {
-    const { store, groupID, verified, logger } = params;
-    const members = await store.listGroupMembers(groupID);
-    const currentAdmins = new Set(members.filter((m)=>m.role === 'admin').map((m)=>normalizeDID(m.member_did)));
-    if (!currentAdmins.has(verified.issuer)) {
-        logger?.warn('admin roster: dropped incremental entry from a non-admin issuer', {
-            groupID,
-            issuer: verified.issuer
-        });
-        return;
-    }
-    const subject = normalizeDID(verified.entry.subject);
-    if (verified.entry.value === 'admin') {
-        await store.setGroupMemberRole(groupID, subject, 'admin');
-    } else if (verified.entry.value === 'revoked') {
-        await store.setGroupMemberRole(groupID, subject, 'member');
-    }
-// Unknown value: no-op, mirroring the reducer's leave-untouched policy.
-}

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
+            });
+        }
+    };
+}