@kubun/plugin-p2p 0.12.1 → 0.13.1

package/lib/groups/credential-grant.js

@@ -0,0 +1,165 @@
+import { normalizeDID } from '@kokuin/token';
+import { toB64U } from '@sozai/codec';
+import { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappingDigest, signCredentialKeyGrant } from './credential-grant-token.js';
+/**
+ * The recipient of a grant holds no leaf in the group, so there is no
+ * authenticated document to wrap to.
+ *
+ * Named rather than left to fail at wrap time: an unresolved recipient reaches
+ * `deriveSharedSecret` as whatever string the caller passed, and comes back as a
+ * DID-shaped complaint about a form — which reads as a bad argument when what
+ * happened is that the group has no such member.
+ */ export class CredentialRecipientNotInGroup extends Error {
+    #groupID;
+    #recipientDID;
+    constructor(groupID, recipientDID){
+        super(`Group ${groupID} has no member ${recipientDID} to grant a credential key to`);
+        this.name = 'CredentialRecipientNotInGroup';
+        this.#groupID = groupID;
+        this.#recipientDID = recipientDID;
+    }
+    get groupID() {
+        return this.#groupID;
+    }
+    get recipientDID() {
+        return this.#recipientDID;
+    }
+}
+/**
+ * The rows a grant wrote are gone by the time the frame is assembled.
+ *
+ * Reachable: a rotation landing between the grant's version read and this read
+ * back leaves the new wrapping below the current version, so it is not among the
+ * ones read here. Refusing is what stops a frame going out that names a version
+ * with no way in.
+ */ export class CredentialGrantNotReadable extends Error {
+    #keyID;
+    constructor(keyID, detail){
+        super(`Credential key ${keyID} cannot be read back for a grant frame: ${detail}`);
+        this.name = 'CredentialGrantNotReadable';
+        this.#keyID = keyID;
+    }
+    get keyID() {
+        return this.#keyID;
+    }
+}
+/**
+ * Grant a credential key to a co-member, resolving what to wrap to from the MLS
+ * roster, and broadcast the frame that carries it there.
+ *
+ * The leaf credential is the authenticated original — signed, and immutable for
+ * as long as the leaf exists — so it is the only copy of a member's resolvable
+ * DID that cannot have been rewritten. The membership row cannot answer: its
+ * `member_did` is normalized, and for `did:peer:4` that is the short form, which
+ * carries no document and so no agreement key.
+ *
+ * The write happens OUTSIDE the handle lock. Resolving is a pure read of the
+ * ratchet tree, while the grant is a store call, and holding a group's mutex
+ * across one is the deadlock this repo has already paid for once.
+ */ export async function grantCredentialKeyToMember(params) {
+    const { registry, credentials, identity, store, groupID, keyID, recipientDID, stores } = params;
+    const wrappableDID = await registry.readHandle(groupID, (handle)=>handle.findMemberLongForm(recipientDID), {
+        stores
+    });
+    if (wrappableDID == null) {
+        throw new CredentialRecipientNotInGroup(groupID, recipientDID);
+    }
+    // `methods` stays undefined here — a resolved roster long form needs none — and
+    // the per-request authority overrides the manager's constructed default.
+    const result = await credentials.grant(keyID, wrappableDID, {
+        authority: params.authority
+    });
+    // Read back NOW and dispatch on commit, not the reverse. The read has to run
+    // on the caller's connection while the transaction is still open, and it has
+    // to see the state the grant left rather than whatever a later write leaves —
+    // an entry written after this point belongs to its own `credential:entry-put`.
+    const frame = await readGrantFrame(store, identity, keyID, wrappableDID);
+    stores.onCommit(()=>params.scheduleBroadcast(groupID, frame));
+    return result;
+}
+/**
+ * Rebuild the frame from what the grant persisted, rather than from what the
+ * manager held mid-call.
+ *
+ * The stored rows are the only copy that survives the call, and they are what a
+ * receiver has to end up with — so assembling from anything else would let the
+ * frame and the granter's own store disagree without either being wrong.
+ */ async function readGrantFrame(store, identity, keyID, recipientWrappableDID) {
+    const bundle = await readCredentialKeyBundle(store, keyID, recipientWrappableDID);
+    return {
+        type: 'credential:key-grant',
+        ...bundle,
+        // Digests over the carried bytes, not a re-read: the token has to describe
+        // the frame that ships, so anything computed from a second read could
+        // authenticate something other than what travels.
+        auth: await signCredentialKeyGrant(identity, {
+            keyID: bundle.keyID,
+            keyVersion: bundle.keyVersion,
+            suite: bundle.suite,
+            recipientDID: bundle.wrapping.recipientDID,
+            wrappingDigest: credentialWrappingDigest(bundle.wrapping),
+            entriesDigest: credentialEntriesDigest(bundle.entries),
+            keyBranchesDigest: credentialKeyBranchesDigest(bundle.keyBranches)
+        })
+    };
+}
+/**
+ * Read one key's row bytes back for a recipient, as a grant carries them minus
+ * the `auth` envelope. Shared by the grant path and the credential reconcile
+ * lane, which both have to hand a receiver exactly the granter's stored rows.
+ *
+ * Throws {@link CredentialGrantNotReadable} on a granter-side gap — a missing
+ * key row, or a wrapping a rotation removed between the version read and this
+ * read back — so a caller never ships a bundle that names bytes with no way in.
+ */ export async function readCredentialKeyBundle(store, keyID, recipientWrappableDID) {
+    /**
+   * A row with no op is a row nothing vouches for, and shipping it would ask the
+   * receiver to invent an author. Granter-side failure, like a missing wrapping.
+   */ const readOp = async (kind, subjectID)=>{
+        const op = await store.getOp(kind, subjectID);
+        if (op == null || op.deleted !== 0) {
+            throw new CredentialGrantNotReadable(keyID, `no live op for ${kind} ${subjectID}`);
+        }
+        return op.op_jwt;
+    };
+    const key = await store.getKey(keyID);
+    if (key == null) {
+        throw new CredentialGrantNotReadable(keyID, 'no key row');
+    }
+    const recipient = normalizeDID(recipientWrappableDID);
+    const wrappings = await store.listWrappings(keyID, key.version);
+    const wrapping = wrappings.find((candidate)=>candidate.recipient_did != null && normalizeDID(candidate.recipient_did) === recipient);
+    const wrappingRecipient = wrapping?.recipient_did;
+    if (wrapping == null || wrappingRecipient == null) {
+        throw new CredentialGrantNotReadable(keyID, `no wrapping for ${recipient} at v${key.version}`);
+    }
+    const entries = await store.listEntries(keyID);
+    const carriedWrapping = {
+        wrappingID: wrapping.wrapping_id,
+        factors: wrapping.factors,
+        iv: toB64U(wrapping.iv),
+        wrappedKey: toB64U(wrapping.wrapped_key),
+        recipientDID: wrappingRecipient,
+        op: await readOp('wrapping', wrapping.wrapping_id)
+    };
+    // Only the granted version. An entry under a retired one is unreadable with
+    // this wrapping, and shipping it would be ciphertext the recipient is
+    // structurally unable to open.
+    const carriedEntries = await Promise.all(entries.filter((entry)=>entry.key_version === key.version).map(async (entry)=>({
+            entryID: entry.entry_id,
+            iv: toB64U(entry.iv),
+            ciphertext: toB64U(entry.ciphertext),
+            hlc: entry.hlc,
+            op: await readOp('entry', entry.entry_id)
+        })));
+    return {
+        keyID,
+        keyVersion: key.version,
+        suite: key.suite,
+        ownerDID: key.owner_did,
+        keyOp: await readOp('key', keyID),
+        keyBranches: (await store.listKeyBranches(keyID, key.version)).map((branch)=>branch.op_jwt),
+        wrapping: carriedWrapping,
+        entries: carriedEntries
+    };
+}

package/lib/groups/group-handlers.js

@@ -7,8 +7,8 @@ import { processBroadcast } from './broadcast.js';
  * broadcast responder writes a reply for whatever a handler returns, and the
  * requester's gather drops replies that carried an error and keeps the rest. So a
  * decline bounds the RESULT, not the traffic — every member still publishes one
- * reply frame — and the spec's "only matching devices reply" is true of what a
- * gather reports, not of what crosses the hub.
+ * reply frame — and "only matching devices reply" is true of what a gather
+ * reports, not of what crosses the hub.
  */ class PeerQueryDeclined extends Error {
     constructor(reason){
         super(`peer/query declined: ${reason}`);
@@ -100,6 +100,29 @@ import { processBroadcast } from './broadcast.js';
                         hlc: data.hlc,
                         auth: data.auth
                     }, groupID)),
+            // Carried back verbatim, for the same reason the access-default frames
+            // are: the token covers digests over these exact bytes, so a handler that
+            // filled a field in from context would hand `processBroadcast` a frame its
+            // own signature no longer describes.
+            'control/credentialKeyGrant': ({ data })=>safeApply(()=>processBroadcast(params, {
+                        type: 'credential:key-grant',
+                        keyID: data.keyID,
+                        keyVersion: data.keyVersion,
+                        suite: data.suite,
+                        ownerDID: data.ownerDID,
+                        keyOp: data.keyOp,
+                        keyBranches: data.keyBranches,
+                        wrapping: {
+                            wrappingID: data.wrapping.wrappingID,
+                            factors: data.wrapping.factors,
+                            iv: data.wrapping.iv,
+                            wrappedKey: data.wrapping.wrappedKey,
+                            recipientDID: data.wrapping.recipientDID,
+                            op: data.wrapping.op
+                        },
+                        entries: data.entries,
+                        auth: data.auth
+                    }, groupID)),
             'control/groupLeaveRequest': ({ data })=>safeApply(()=>processBroadcast(params, {
                         type: 'group:leaveRequest',
                         groupID,

package/lib/groups/group-mls.d.ts

@@ -36,6 +36,11 @@ export type CreateGroupMLSParams = {
      * timestamps (the second would silently lose under last-writer-wins).
      */
     hlc: HLC;
+    /**
+     * How far into the future a folded control entry's `ord` may sit before its
+     * clock merge is refused — see `LedgerIngestParams.maxDriftMS`.
+     */
+    maxDriftMS?: number;
     groupID: string;
     /**
      * Emitter for the domain events a landed commit's control entries drive

package/lib/groups/group-mls.js

@@ -5,8 +5,8 @@ import { getP2PStore } from '@kubun/store-p2p';
 import { CommitRejectedError, createRecoveryRequest, joinGroupExternal, MissingLedgerEntriesError, openSealedGroupInfo, openSealedLedger, readGroupAnchor, readMessageEpoch, sealGroupInfo, sealLedger } from '@kumiai/mls';
 import { fromB64 } from '@sozai/codec';
 import { toISO } from '../context/types.js';
-import { bootstrapGroupLedger } from './broadcast.js';
 import { readRecoverySecret } from './group-anchor.js';
+import { bootstrapGroupLedger } from './ledger-adopt.js';
 import { emitLedgerAffectedEvents } from './ledger-affected-events.js';
 import { entriesRetainedByCommit, foldCommittedLedgerEntries } from './ledger-commit-fold.js';
 import { DecryptError } from './mls-receive-errors.js';
@@ -383,6 +383,9 @@ import { mirrorRosterRoles, roleFromRoster } from './roster-projection.js';
                     p2pStore,
                     groupID,
                     hlc,
+                    ...params.maxDriftMS != null ? {
+                        maxDriftMS: params.maxDriftMS
+                    } : {},
                     logger
                 });
                 return {

package/lib/groups/group-peer-manager.d.ts

@@ -12,7 +12,7 @@ import { type DeviceHub, type ReconnectingDeviceHub } from '../hub/hub-like.js';
 import type { SyncProtocol } from '../protocol.js';
 import type { ForwardingConfig } from '../sync/forwarder.js';
 import type { LedgerCatchupOptions, LedgerCatchupSummary, RejoinResult, StoreUnreadableMode } from '../types.js';
-import type { GroupBroadcastMessage } from './broadcast.js';
+import type { GroupBroadcastMessage } from './broadcast-message.js';
 import { type SettleLostControlRequestDeps } from './commit-adoption.js';
 import type { P2PEventEmitter } from './events.js';
 import type { GroupHandleRegistry } from './group-handle-registry.js';
@@ -60,6 +60,12 @@ export type GroupPeerManagerParams = {
     graph: GraphInternals;
     /** Device-wide monotonic clock shared with the engine and MLS receive path. */
     hlc: HLC;
+    /**
+     * The engine's future-drift bound, forwarded to the apply path. Optional: a
+     * suite that builds a manager by hand falls back to the same default the
+     * engine does, so absence is never an absent bound.
+     */
+    maxDriftMS?: number;
     /** Authenticated DID of this device (normalized). */
     localDID: string;
     /**

package/lib/groups/group-peer-manager.js

@@ -1,3 +1,4 @@
+import { CREDENTIAL_STORE, getCredentialStore } from '@kubun/store-credential';
 import { getDelegationStore } from '@kubun/store-delegation';
 import { getP2PStore } from '@kubun/store-p2p';
 import { readGroupAnchor } from '@kumiai/mls';
@@ -6,9 +7,10 @@ import { createHubLike } from '../hub/hub-like.js';
 import { createLoopbackLogHub } from '../hub/loopback-log-hub.js';
 import { createHubServerDIDResolver } from '../hub/server-did.js';
 import { createTunnelListeners } from '../sync/tunnel-listeners.js';
+import { applyAccessDefaultSetToken } from './access-default-apply.js';
 import { createAnchorStore } from './anchor-store.js';
 import { createAppCursorStore } from './app-cursor-store.js';
-import { applyAccessDefaultSetToken, bootstrapGroupLedger, processBroadcast } from './broadcast.js';
+import { processBroadcast } from './broadcast.js';
 import { reprojectGroupSettings } from './circle-projection.js';
 import { adoptCommitJournalBlob, readJournalRequestID, settleLostControlRequest } from './commit-adoption.js';
 import { createCommitJournal } from './commit-journal.js';
@@ -18,7 +20,9 @@ import { buildGroupHandlers } from './group-handlers.js';
 import { createGroupMLS } from './group-mls.js';
 import { groupProtocols } from './group-protocols.js';
 import { ledgerEntryDigest } from './ledger.js';
+import { bootstrapGroupLedger } from './ledger-adopt.js';
 import { createPeerPresence } from './peer-presence.js';
+import { CREDENTIAL_SYNC_PROTOCOL, CREDENTIAL_SYNC_VERSION } from './peer-selection.js';
 const peerKey = (groupID, hubURL)=>`${groupID}|${hubURL}`;
 /**
  * Send-side union → procedure mapping — the inverse of `buildGroupHandlers`.
@@ -91,6 +95,23 @@ const peerKey = (groupID, hubURL)=>`${groupID}|${hubURL}`;
                 type: message.type
             });
             return;
+        case 'credential:key-grant':
+            // Every field rides, including the `ownerDID` the receiver ignores: the
+            // token digests the wrapping and the entries as they are carried, so a
+            // payload that dropped or rewrote one produces a frame the receiver
+            // verifies and correctly rejects.
+            await peer.protocol('control').dispatch('control/credentialKeyGrant', {
+                keyID: message.keyID,
+                keyVersion: message.keyVersion,
+                suite: message.suite,
+                ownerDID: message.ownerDID,
+                keyOp: message.keyOp,
+                keyBranches: message.keyBranches,
+                wrapping: message.wrapping,
+                entries: message.entries,
+                auth: message.auth
+            });
+            return;
         default:
             {
                 // Exhaustiveness gate. A broadcast type with no case here used to fall off
@@ -440,9 +461,17 @@ export function createGroupPeerManager(params) {
             getP2PStore(params.stores),
             getDelegationStore(params.stores)
         ]);
+        // Registered by `@kubun/plugin-credential`, not here, so its absence is
+        // "that plugin is not installed" rather than a fault. Asked through
+        // `hasStore` because `getStore` on an unregistered name throws, and a device
+        // with no credential plugin must still bind its peers.
+        const credentialStore = params.stores.hasStore(CREDENTIAL_STORE) ? await getCredentialStore(params.stores) : undefined;
         return {
             p2pStore,
             delegationStore,
+            ...credentialStore != null ? {
+                credentialStore
+            } : {},
             graphStore: params.graphStore,
             graph: params.graph,
             selfDID: params.localDID,
@@ -455,6 +484,7 @@ export function createGroupPeerManager(params) {
             scheduleBroadcast: params.scheduleBroadcast,
             emitter: params.emitter,
             hlc: params.hlc,
+            maxDriftMS: params.maxDriftMS,
             // Reads the genesis anchor baked into the MLS GroupContext so role
             // projection on a received ledger entry runs against the authenticated
             // epoch-0 creator. Null for a group with no anchor (e.g. external).
@@ -547,6 +577,9 @@ export function createGroupPeerManager(params) {
                 stores: params.stores,
                 identity: params.identity,
                 hlc: params.hlc,
+                ...params.maxDriftMS != null ? {
+                    maxDriftMS: params.maxDriftMS
+                } : {},
                 groupID,
                 // A received commit's control entries fold into this device's
                 // projections, so the changes they carry reach subscribers as the same
@@ -791,6 +824,16 @@ export function createGroupPeerManager(params) {
             }
         },
         getGroupEpoch: (groupID)=>params.registry.groupEpoch(groupID) ?? undefined,
+        // Read per announce: a credential store registered after the profile was set
+        // still makes this device advertise the lane, and a device without one never
+        // does — the opt-out is the absence of the store.
+        deviceCapabilities: ()=>params.stores.hasStore(CREDENTIAL_STORE) ? [
+                {
+                    protocol: CREDENTIAL_SYNC_PROTOCOL,
+                    version: CREDENTIAL_SYNC_VERSION,
+                    transports: null
+                }
+            ] : [],
         publish: broadcastToPeers,
         // Gathered over every hub-peer of the group, concurrently: `timeoutMs` bounds
         // each window, so in sequence a dark hub burns its whole window before the

package/lib/groups/group-protocols.d.ts

@@ -197,6 +197,119 @@ export declare const controlProtocol: {
             readonly additionalProperties: false;
         };
     };
+    readonly 'control/credentialKeyGrant': {
+        readonly type: "event";
+        readonly retain: "log";
+        readonly description: "Hand one co-member what it needs to open a credential key: the key's public record, the single wrapping addressed to that member, and every entry ciphertext at that version. Group-wide because confidentiality is content-level; only the addressed DID applies it. `auth` signs identifiers and content digests, and the receiver recomputes both from this frame.";
+        readonly data: {
+            readonly type: "object";
+            readonly properties: {
+                readonly keyID: {
+                    readonly type: "string";
+                };
+                readonly keyVersion: {
+                    readonly type: "number";
+                };
+                readonly suite: {
+                    readonly type: "number";
+                };
+                readonly ownerDID: {
+                    readonly type: "string";
+                    readonly description: "Claimed owner. A mirror — the receiver stores the `auth` issuer instead.";
+                };
+                readonly keyOp: {
+                    readonly type: "string";
+                    readonly description: "The granter's signed op for the key row, stored verbatim. The key row rides inline on this frame, so its op has nowhere else to hang.";
+                };
+                readonly keyBranches: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "The proven key-op JWTs that introduced this key version's branches.";
+                };
+                readonly wrapping: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly wrappingID: {
+                            readonly type: "string";
+                        };
+                        readonly factors: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly kind: {
+                                        readonly type: "string";
+                                    };
+                                    readonly params: {
+                                        readonly type: "object";
+                                        readonly description: "Per-kind PUBLIC material — a salt or an ephemeral public key.";
+                                        readonly additionalProperties: true;
+                                    };
+                                };
+                                readonly required: readonly ["kind", "params"];
+                                readonly additionalProperties: false;
+                            };
+                            readonly description: "ORDERED, and bound into the wrapping AAD: a permuted copy will not open.";
+                        };
+                        readonly iv: {
+                            readonly type: "string";
+                            readonly description: "base64url";
+                        };
+                        readonly wrappedKey: {
+                            readonly type: "string";
+                            readonly description: "base64url";
+                        };
+                        readonly recipientDID: {
+                            readonly type: "string";
+                            readonly description: "Un-normalized: a key-resolution input, not an identity to compare.";
+                        };
+                        readonly op: {
+                            readonly type: "string";
+                            readonly description: "The granter's signed op for this row, stored verbatim — the receiver never mints its own.";
+                        };
+                    };
+                    readonly required: readonly ["wrappingID", "factors", "iv", "wrappedKey", "recipientDID", "op"];
+                    readonly additionalProperties: false;
+                };
+                readonly entries: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly entryID: {
+                                readonly type: "string";
+                            };
+                            readonly iv: {
+                                readonly type: "string";
+                                readonly description: "base64url";
+                            };
+                            readonly ciphertext: {
+                                readonly type: "string";
+                                readonly description: "base64url";
+                            };
+                            readonly hlc: {
+                                readonly type: "string";
+                            };
+                            readonly op: {
+                                readonly type: "string";
+                                readonly description: "The granter's signed op for this row, stored verbatim.";
+                            };
+                        };
+                        readonly required: readonly ["entryID", "iv", "ciphertext", "hlc", "op"];
+                        readonly additionalProperties: false;
+                    };
+                };
+                readonly auth: {
+                    readonly type: "string";
+                    readonly description: "Signed credential key-grant token.";
+                };
+            };
+            readonly required: readonly ["keyID", "keyVersion", "suite", "ownerDID", "keyOp", "keyBranches", "wrapping", "entries", "auth"];
+            readonly additionalProperties: false;
+        };
+    };
     readonly 'control/groupLeaveRequest': {
         readonly type: "event";
         readonly retain: "ephemeral";
@@ -380,6 +493,7 @@ export type DelegationShareData = FromSchema<(typeof controlProtocol)['control/d
 export type DelegationRevokeData = FromSchema<(typeof controlProtocol)['control/delegationRevoke']['data']>;
 export type AccessDefaultSetData = FromSchema<(typeof controlProtocol)['control/accessDefaultSet']['data']>;
 export type AccessDefaultRemoveData = FromSchema<(typeof controlProtocol)['control/accessDefaultRemove']['data']>;
+export type CredentialKeyGrantData = FromSchema<(typeof controlProtocol)['control/credentialKeyGrant']['data']>;
 export type GroupLeaveRequestData = FromSchema<(typeof controlProtocol)['control/groupLeaveRequest']['data']>;
 export type MutationApplyData = FromSchema<(typeof syncProtocol)['sync/mutationApply']['data']>;
 export type PeerAnnounceData = FromSchema<(typeof peerProtocol)['peer/announce']['data']>;
@@ -579,6 +693,119 @@ export declare const groupProtocols: {
                 readonly additionalProperties: false;
             };
         };
+        readonly 'control/credentialKeyGrant': {
+            readonly type: "event";
+            readonly retain: "log";
+            readonly description: "Hand one co-member what it needs to open a credential key: the key's public record, the single wrapping addressed to that member, and every entry ciphertext at that version. Group-wide because confidentiality is content-level; only the addressed DID applies it. `auth` signs identifiers and content digests, and the receiver recomputes both from this frame.";
+            readonly data: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly keyID: {
+                        readonly type: "string";
+                    };
+                    readonly keyVersion: {
+                        readonly type: "number";
+                    };
+                    readonly suite: {
+                        readonly type: "number";
+                    };
+                    readonly ownerDID: {
+                        readonly type: "string";
+                        readonly description: "Claimed owner. A mirror — the receiver stores the `auth` issuer instead.";
+                    };
+                    readonly keyOp: {
+                        readonly type: "string";
+                        readonly description: "The granter's signed op for the key row, stored verbatim. The key row rides inline on this frame, so its op has nowhere else to hang.";
+                    };
+                    readonly keyBranches: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "The proven key-op JWTs that introduced this key version's branches.";
+                    };
+                    readonly wrapping: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly wrappingID: {
+                                readonly type: "string";
+                            };
+                            readonly factors: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "object";
+                                    readonly properties: {
+                                        readonly kind: {
+                                            readonly type: "string";
+                                        };
+                                        readonly params: {
+                                            readonly type: "object";
+                                            readonly description: "Per-kind PUBLIC material — a salt or an ephemeral public key.";
+                                            readonly additionalProperties: true;
+                                        };
+                                    };
+                                    readonly required: readonly ["kind", "params"];
+                                    readonly additionalProperties: false;
+                                };
+                                readonly description: "ORDERED, and bound into the wrapping AAD: a permuted copy will not open.";
+                            };
+                            readonly iv: {
+                                readonly type: "string";
+                                readonly description: "base64url";
+                            };
+                            readonly wrappedKey: {
+                                readonly type: "string";
+                                readonly description: "base64url";
+                            };
+                            readonly recipientDID: {
+                                readonly type: "string";
+                                readonly description: "Un-normalized: a key-resolution input, not an identity to compare.";
+                            };
+                            readonly op: {
+                                readonly type: "string";
+                                readonly description: "The granter's signed op for this row, stored verbatim — the receiver never mints its own.";
+                            };
+                        };
+                        readonly required: readonly ["wrappingID", "factors", "iv", "wrappedKey", "recipientDID", "op"];
+                        readonly additionalProperties: false;
+                    };
+                    readonly entries: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly entryID: {
+                                    readonly type: "string";
+                                };
+                                readonly iv: {
+                                    readonly type: "string";
+                                    readonly description: "base64url";
+                                };
+                                readonly ciphertext: {
+                                    readonly type: "string";
+                                    readonly description: "base64url";
+                                };
+                                readonly hlc: {
+                                    readonly type: "string";
+                                };
+                                readonly op: {
+                                    readonly type: "string";
+                                    readonly description: "The granter's signed op for this row, stored verbatim.";
+                                };
+                            };
+                            readonly required: readonly ["entryID", "iv", "ciphertext", "hlc", "op"];
+                            readonly additionalProperties: false;
+                        };
+                    };
+                    readonly auth: {
+                        readonly type: "string";
+                        readonly description: "Signed credential key-grant token.";
+                    };
+                };
+                readonly required: readonly ["keyID", "keyVersion", "suite", "ownerDID", "keyOp", "keyBranches", "wrapping", "entries", "auth"];
+                readonly additionalProperties: false;
+            };
+        };
         readonly 'control/groupLeaveRequest': {
             readonly type: "event";
             readonly retain: "ephemeral";