@kubun/plugin-p2p 0.13.1 → 0.15.0

package/lib/groups/broadcast.js

@@ -6,7 +6,7 @@ import { createReceiveAccessGate } from '../sync/receive-access-gate.js';
 import { applyAccessDefaultSetFrame } from './access-default-apply.js';
 import { verifyAccessDefault } from './access-default-token.js';
 import { verifyCatalog } from './catalog-token.js';
-import { applyCredentialKeyGrantFrame } from './credential-apply.js';
+import { applyCredentialKeyGrantFrame, applyCredentialManifestFrame } from './credential-apply.js';
 import { storeReceivedGrant } from './store-received-grant.js';
 import { storeReceivedRevocation } from './store-received-revocation.js';
 /**
@@ -229,6 +229,12 @@ import { storeReceivedRevocation } from './store-received-revocation.js';
                         applied: false
                     };
                 }
+                // Both halves or neither -- a partial source is unwired, so the
+                // delegated wrapping fails closed.
+                const credentialDeps = params.credentialControllerResolver != null && params.credentialRevocationChecker != null ? {
+                    controllerResolver: params.credentialControllerResolver,
+                    revocationChecker: params.credentialRevocationChecker
+                } : undefined;
                 const applied = await applyCredentialKeyGrantFrame({
                     store: params.credentialStore,
                     frame: message,
@@ -240,7 +246,43 @@ import { storeReceivedRevocation } from './store-received-revocation.js';
                     ...params.logger != null ? {
                         logger: params.logger
                     } : {},
-                    groupID
+                    groupID,
+                    ...credentialDeps != null ? {
+                        deps: credentialDeps
+                    } : {}
+                });
+                return {
+                    applied
+                };
+            }
+        case 'credential:key-manifest':
+            {
+                if (params.credentialStore == null) {
+                    params.logger?.warn('credential:key-manifest dropped: no credential store on this device', {
+                        groupID
+                    });
+                    return {
+                        applied: false
+                    };
+                }
+                // Both halves or neither, as the grant case above -- a partial source
+                // is unwired, so the manifest fails closed.
+                const credentialDeps = params.credentialControllerResolver != null && params.credentialRevocationChecker != null ? {
+                    controllerResolver: params.credentialControllerResolver,
+                    revocationChecker: params.credentialRevocationChecker
+                } : undefined;
+                const applied = await applyCredentialManifestFrame({
+                    store: params.credentialStore,
+                    frame: message,
+                    selfDID: params.selfDID,
+                    maxDriftMS: params.maxDriftMS ?? DEFAULT_MAX_DRIFT_MS,
+                    ...params.logger != null ? {
+                        logger: params.logger
+                    } : {},
+                    groupID,
+                    ...credentialDeps != null ? {
+                        deps: credentialDeps
+                    } : {}
                 });
                 return {
                     applied

package/lib/groups/credential-apply.d.ts

@@ -2,6 +2,7 @@ import { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
 import type { CredentialStoreAPI } from '@kubun/store-credential';
 import type { CredentialKeyBundle, GroupBroadcastMessage } from './broadcast-message.js';
+import { type DelegatedWrappingCheckDeps } from './grantor-authority.js';
 export type ApplyCredentialKeyGrantFrameParams = {
     store: CredentialStoreAPI;
     frame: Extract<GroupBroadcastMessage, {
@@ -24,6 +25,11 @@ export type ApplyCredentialKeyGrantFrameParams = {
     maxDriftMS: number;
     logger?: Logger;
     groupID?: string;
+    /**
+     * Present-time admission gate for a delegate-signed wrapping, forwarded to
+     * {@link applyCredentialKeyRows}. Unwired means the wrapping refuses (fail-closed).
+     */
+    deps?: DelegatedWrappingCheckDeps;
 };
 /**
  * Apply a signed `credential:key-grant`: the key's public record, the one
@@ -42,6 +48,42 @@ export type ApplyCredentialKeyGrantFrameParams = {
  * Returns whether anything was written.
  */
 export declare function applyCredentialKeyGrantFrame(params: ApplyCredentialKeyGrantFrameParams): Promise<boolean>;
+export type ApplyCredentialManifestFrameParams = {
+    store: CredentialStoreAPI;
+    frame: Extract<GroupBroadcastMessage, {
+        type: 'credential:key-manifest';
+    }>;
+    /**
+     * This device, for the recipient check: a manifest fans out group-wide but
+     * names ONE recipient in its signed claim.
+     */
+    selfDID: string;
+    /**
+     * Future-drift bound applied to the manifest's `issuedAt`. `issuedAt` is a
+     * drift bound ONLY -- ordering/authorization is `sequence`.
+     */
+    maxDriftMS: number;
+    logger?: Logger;
+    groupID?: string;
+    /**
+     * The administer-chain check's deps. Unwired means the gate refuses
+     * (fail-closed) -- a manifest is stored only when its chain check passes.
+     */
+    deps?: DelegatedWrappingCheckDeps;
+};
+/**
+ * Apply a `credential:key-manifest`: verify the token, require the grantor's
+ * present-time `credential/administer` chain over the owner, require
+ * `recipientDID` to name this device, bound `issuedAt` against future drift,
+ * then store under the lexicographic `(epoch, sequence)` rule.
+ *
+ * ADVISORY only -- a recipient proves readiness by decrypt-verifying its own
+ * keys, never by trusting this record. Fail-CLOSED: any check failure drops
+ * without storing.
+ *
+ * Returns whether a row was stored.
+ */
+export declare function applyCredentialManifestFrame(params: ApplyCredentialManifestFrameParams): Promise<boolean>;
 /** A revoked subject's tombstone as the reconcile lane ships it. */
 export type CredentialReconcileTombstone = {
     keyID: string;
@@ -59,20 +101,40 @@ export type ApplyCredentialReconcileParams = {
     bundles: Array<CredentialKeyBundle>;
     /** Tombstones for advertised held IDs the server reports revoked. */
     tombstones: Array<CredentialReconcileTombstone>;
+    /**
+     * Manifests riding with this catch-up response, applied via
+     * {@link applyCredentialManifestFrame} BEFORE the bundles below -- the
+     * fail-safe order: a crash mid-apply leaves the expectation recorded with
+     * keys still to follow, never keys landed with nothing that predicted them.
+     */
+    manifests?: Array<{
+        manifest: string;
+        delegationTokens: Array<string>;
+    }>;
     hlc?: HLC;
     /** Future-drift bound on the granter's stamps. Defaults to {@link DEFAULT_MAX_DRIFT_MS}. */
     maxDriftMS?: number;
     logger?: Logger;
+    /** Forwarded to {@link applyCredentialKeyRows} and {@link applyCredentialManifestFrame}. */
+    deps?: DelegatedWrappingCheckDeps;
 };
 export type ApplyCredentialReconcileResult = {
+    /** Manifests that wrote a row. */
+    manifestsApplied: number;
     /** Bundles that wrote rows. */
     applied: number;
     /** Tombstones that deleted a row. */
     tombstoned: number;
 };
 /**
- * Apply a credential reconcile response: materialise the catch-up bundles a
- * recipient missed, then GC the rows a tombstone revokes.
+ * Apply a credential reconcile response: store the manifests it carries,
+ * materialise the catch-up bundles a recipient missed, then GC the rows a
+ * tombstone revokes — manifests first, so readiness never transiently
+ * under-declares.
+ *
+ * Runs as ONE atomic unit via `store.transaction`, which is nesting-safe
+ * (mirrors `writeAtomically`), so this never throws a Kysely nested-tx error
+ * even when `store` already runs inside an ambient transaction.
  *
  * The server's scoping is NOT trusted. Every row re-verifies its op signature
  * and every wrapping re-checks it is addressed to this device before a write,

package/lib/groups/credential-apply.js

@@ -4,6 +4,8 @@ import { HLC } from '@kubun/hlc';
 import { DEFAULT_MAX_DRIFT_MS } from '@kubun/mutation';
 import { fromB64U } from '@sozai/codec';
 import { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappingDigest, verifyCredentialKeyGrant } from './credential-grant-token.js';
+import { verifyCredentialManifest } from './credential-manifest-token.js';
+import { authorizeDelegatedWrapping, checkAdministerChain, verifyGrantorAuthority } from './grantor-authority.js';
 /**
  * Apply a signed `credential:key-grant`: the key's public record, the one
  * wrapping addressed to this device, and every entry ciphertext at that version.
@@ -51,7 +53,10 @@ import { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappin
         groupID,
         bundle: frame,
         requireIssuer: verified.issuer,
-        label: 'credential:key-grant'
+        label: 'credential:key-grant',
+        ...params.deps != null ? {
+            deps: params.deps
+        } : {}
     });
 }
 /**
@@ -201,6 +206,72 @@ import { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappin
             branchID: op.claim.branchID ?? ''
         };
     };
+    /**
+   * As {@link acceptOp}, but for the WRAPPING subject also accepts an op
+   * signed by a delegate `G` the owner has authorized (entry/key-branch ops
+   * stay on `acceptOp`'s owner-only rule). An op byte-identical to what this
+   * device already holds is accepted as trusted local state with no
+   * authorization check; otherwise `bundle.grantorAuthority` must be present
+   * and `authorizeDelegatedWrapping` must return `true`.
+   */ const acceptWrappingOp = async (token, subject)=>{
+        const verified = await verifyCredentialOp(token);
+        if (verified == null || !credentialOpMatchesPut(verified.claim, subject)) {
+            return null;
+        }
+        const opInput = {
+            keyID: verified.claim.keyID,
+            authorDID: verified.issuer,
+            hlc: verified.claim.hlc,
+            opJWT: token,
+            opHash: digestParts([
+                token
+            ]),
+            branchID: verified.claim.branchID ?? ''
+        };
+        if (verified.issuer === issuer) {
+            return {
+                op: opInput
+            };
+        }
+        // Hash computed the same way the store persists `op_hash` (mirrors
+        // `acceptOp`) -- a mismatch would fail-open the held short-circuit below
+        // in either direction.
+        const incomingHash = opInput.opHash;
+        const stored = await store.getOp('wrapping', bundle.wrapping.wrappingID);
+        if (stored?.op_hash === incomingHash) {
+            // Already-admitted op: trusted local state, no re-authorization or
+            // envelope persist needed.
+            return {
+                op: opInput
+            };
+        }
+        if (bundle.grantorAuthority == null) {
+            return null;
+        }
+        const authorized = await authorizeDelegatedWrapping({
+            envelope: bundle.grantorAuthority,
+            wrappingOpIssuer: verified.issuer,
+            wrappingOpHash: incomingHash,
+            ownerDID: issuer,
+            deps: params.deps ?? {}
+        });
+        if (!authorized) {
+            return null;
+        }
+        // Re-verified only to recover `refreshSeq` for the provenance write below
+        // -- `authorized === true` already proved the binding.
+        const claim = await verifyGrantorAuthority(bundle.grantorAuthority);
+        if (claim == null) {
+            return null;
+        }
+        return {
+            op: opInput,
+            authority: {
+                envelope: bundle.grantorAuthority,
+                refreshSeq: claim.refreshSeq
+            }
+        };
+    };
     const keyOpHash = digestParts([
         bundle.keyOp
     ]);
@@ -242,7 +313,7 @@ import { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappin
             branchID: `${verified.claim.hlc}:${opHash}`
         });
     }
-    const wrappingOp = await acceptOp(bundle.wrapping.op, {
+    const acceptedWrapping = await acceptWrappingOp(bundle.wrapping.op, {
         kind: 'wrapping',
         params: wrappingParams
     });
@@ -250,13 +321,14 @@ import { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappin
             kind: 'entry',
             params: put.params
         })));
-    if (wrappingOp == null || entryOps.some((op)=>op == null)) {
+    if (acceptedWrapping == null || entryOps.some((op)=>op == null)) {
         logger?.warn(`${label} dropped: an op does not speak for the row it travels with`, {
             groupID,
             keyID: bundle.keyID
         });
         return false;
     }
+    const wrappingOp = acceptedWrapping.op;
     const provenBranchIDs = new Set(keyBranches.map((branch)=>branch.branchID));
     for (const rowOp of [
         wrappingOp,
@@ -302,7 +374,10 @@ import { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappin
             branchID: branch.branchID
         });
     }
-    await store.putWrapping(wrappingParams, wrappingOp);
+    // Envelope, when present, writes in the SAME transaction as the wrapping
+    // row -- a crash between the two must never leave a wrapping with no
+    // provenance record.
+    await store.putWrapping(wrappingParams, wrappingOp, acceptedWrapping.authority);
     for (const [index, put] of entryPuts.entries()){
         await store.putEntry(put.params, entryOps[index]);
         // Merged so a later local write sorts after what was received. Safe to
@@ -316,41 +391,151 @@ import { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappin
     return true;
 }
 /**
- * Apply a credential reconcile response: materialise the catch-up bundles a
- * recipient missed, then GC the rows a tombstone revokes.
+ * Apply a `credential:key-manifest`: verify the token, require the grantor's
+ * present-time `credential/administer` chain over the owner, require
+ * `recipientDID` to name this device, bound `issuedAt` against future drift,
+ * then store under the lexicographic `(epoch, sequence)` rule.
+ *
+ * ADVISORY only -- a recipient proves readiness by decrypt-verifying its own
+ * keys, never by trusting this record. Fail-CLOSED: any check failure drops
+ * without storing.
+ *
+ * Returns whether a row was stored.
+ */ export async function applyCredentialManifestFrame(params) {
+    const { store, frame, groupID, logger } = params;
+    const claim = await verifyCredentialManifest(frame.manifest);
+    if (claim == null) {
+        logger?.warn('credential:key-manifest dropped: token verification failed', {
+            groupID
+        });
+        return false;
+    }
+    // Ordinary outcome for every co-member but one, so debug not warning
+    // (mirrors `applyCredentialKeyRows`'s wrapping-recipient check).
+    if (normalizeDID(claim.recipientDID) !== normalizeDID(params.selfDID)) {
+        logger?.debug('credential:key-manifest ignored: manifest is addressed elsewhere', {
+            groupID,
+            ownerDID: claim.ownerDID
+        });
+        return false;
+    }
+    // Present-time admission: grantor must hold a live `credential/administer`
+    // chain over the owner, proven by `delegationTokens`. Fail-closed on
+    // unwired deps -- the SAME gate a delegated wrapping passes.
+    //
+    // Self-issued exception (grantor === owner), mirroring
+    // `computeCredentialProvisioningStatus`: `checkAdministerChain`'s synthetic
+    // top-level check doesn't apply to a self-grant. Safe because `grantorDID`
+    // comes only from the VERIFIED `iss`, never a payload field, so forging
+    // `grantorDID === ownerDID` requires already controlling the owner's
+    // signing key.
+    const authorized = normalizeDID(claim.grantorDID) === normalizeDID(claim.ownerDID) ? true : await checkAdministerChain({
+        grantorDID: claim.grantorDID,
+        ownerDID: claim.ownerDID,
+        delegationTokens: frame.delegationTokens,
+        deps: params.deps ?? {}
+    });
+    if (!authorized) {
+        logger?.warn('credential:key-manifest dropped: grantor holds no administer chain over the owner', {
+            groupID,
+            ownerDID: claim.ownerDID
+        });
+        return false;
+    }
+    // Future-drift bound only, unlike the grant lane's entry stamps: a manifest
+    // leaves no op row for the sync lane to order, so this never floors the
+    // device clock.
+    const stamp = HLC.tryParse(claim.issuedAt);
+    if (stamp == null || stamp.wallTime - Date.now() > params.maxDriftMS) {
+        logger?.warn('credential:key-manifest dropped: issuedAt stamp is unusable', {
+            groupID,
+            issuedAt: claim.issuedAt
+        });
+        return false;
+    }
+    // Replay check mirrors the store's own upsert rule (so `applied` reports
+    // accurately): lexicographic (epoch, sequence) -- a higher epoch always
+    // wins; within the same epoch, lower-or-equal sequence is replay.
+    const existing = await store.listManifests({
+        ownerDID: claim.ownerDID,
+        recipientDID: claim.recipientDID
+    });
+    const prior = existing.find((manifest)=>manifest.record.grantorDID === claim.grantorDID);
+    if (prior != null && (prior.record.epoch > claim.epoch || prior.record.epoch === claim.epoch && claim.sequence <= prior.record.sequence)) {
+        logger?.warn('credential:key-manifest dropped: replayed or stale epoch/sequence', {
+            groupID,
+            epoch: claim.epoch,
+            sequence: claim.sequence
+        });
+        return false;
+    }
+    await store.putManifest(claim, frame.manifest, frame.delegationTokens);
+    return true;
+}
+/**
+ * Apply a credential reconcile response: store the manifests it carries,
+ * materialise the catch-up bundles a recipient missed, then GC the rows a
+ * tombstone revokes — manifests first, so readiness never transiently
+ * under-declares.
+ *
+ * Runs as ONE atomic unit via `store.transaction`, which is nesting-safe
+ * (mirrors `writeAtomically`), so this never throws a Kysely nested-tx error
+ * even when `store` already runs inside an ambient transaction.
  *
  * The server's scoping is NOT trusted. Every row re-verifies its op signature
  * and every wrapping re-checks it is addressed to this device before a write,
  * exactly as an unsolicited grant would — a reconcile is a batch of the same
  * self-authenticating rows, pulled instead of pushed.
  */ export async function applyCredentialReconcile(params) {
-    const { store, selfDID, logger } = params;
+    const { selfDID, logger } = params;
     const maxDriftMS = params.maxDriftMS ?? DEFAULT_MAX_DRIFT_MS;
-    let applied = 0;
-    for (const bundle of params.bundles){
-        const wrote = await applyCredentialKeyRows({
-            store,
-            selfDID,
-            hlc: params.hlc,
-            maxDriftMS,
-            logger,
-            bundle,
-            label: 'credential:reconcile'
-        });
-        if (wrote) {
-            applied += 1;
+    return await params.store.transaction(async (store)=>{
+        let manifestsApplied = 0;
+        for (const { manifest, delegationTokens } of params.manifests ?? []){
+            const wrote = await applyCredentialManifestFrame({
+                store,
+                selfDID,
+                frame: {
+                    type: 'credential:key-manifest',
+                    manifest,
+                    delegationTokens
+                },
+                maxDriftMS,
+                logger,
+                deps: params.deps
+            });
+            if (wrote) {
+                manifestsApplied += 1;
+            }
         }
-    }
-    let tombstoned = 0;
-    for (const tombstone of params.tombstones){
-        if (await applyReconcileTombstone(store, tombstone, logger)) {
-            tombstoned += 1;
+        let applied = 0;
+        for (const bundle of params.bundles){
+            const wrote = await applyCredentialKeyRows({
+                store,
+                selfDID,
+                hlc: params.hlc,
+                maxDriftMS,
+                logger,
+                bundle,
+                label: 'credential:reconcile',
+                deps: params.deps
+            });
+            if (wrote) {
+                applied += 1;
+            }
         }
-    }
-    return {
-        applied,
-        tombstoned
-    };
+        let tombstoned = 0;
+        for (const tombstone of params.tombstones){
+            if (await applyReconcileTombstone(store, tombstone, logger)) {
+                tombstoned += 1;
+            }
+        }
+        return {
+            manifestsApplied,
+            applied,
+            tombstoned
+        };
+    });
 }
 /**
  * Delete one revoked subject, keying on the tombstone op it carries.

package/lib/groups/credential-grant.d.ts

@@ -62,7 +62,28 @@ export type GrantCredentialKeyParams = {
      * will resolve a request authority is a follow-up.
      */
     authority?: CredentialAuthority;
+    /**
+     * The credential key's owner and signing device `G`. Present and DISTINCT
+     * iff delegate-signed (absent, or equal, for an owner-signed grant, which
+     * needs no envelope). `identity` must resolve to `grantorDID` when
+     * delegate-signed -- `signGrantorAuthority` signs with `identity`, not
+     * this field.
+     */
+    ownerDID?: string;
+    grantorDID?: string;
+    /**
+     * `G`'s current administer capability chain, carried in the envelope for
+     * present-time admission checks. Ignored outside the delegate-signed path.
+     */
+    delegationTokens?: Array<string>;
 };
+/**
+ * What a grant call settled as, beyond `created`. `grantCredentialKeyToMember`
+ * only ever produces `'granted'` or `'refreshed'` -- `'not-held'`/`'error'`
+ * are reserved for callers, kept here so nothing downstream needs a type
+ * this module doesn't produce.
+ */
+export type CredentialGrantOutcomeKind = 'granted' | 'refreshed' | 'not-held' | 'error';
 export type GrantCredentialKeyResult = {
     version: number;
     /**
@@ -70,6 +91,7 @@ export type GrantCredentialKeyResult = {
      * way: a repeat grant is how an undelivered one is retried.
      */
     created: boolean;
+    outcome: CredentialGrantOutcomeKind;
 };
 /**
  * Grant a credential key to a co-member, resolving what to wrap to from the MLS

package/lib/groups/credential-grant.js

@@ -1,6 +1,7 @@
 import { normalizeDID } from '@kokuin/token';
 import { toB64U } from '@sozai/codec';
 import { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappingDigest, signCredentialKeyGrant } from './credential-grant-token.js';
+import { signGrantorAuthority } from './grantor-authority.js';
 /**
  * The recipient of a grant holds no leaf in the group, so there is no
  * authenticated document to wrap to.
@@ -69,13 +70,82 @@ import { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappin
     const result = await credentials.grant(keyID, wrappableDID, {
         authority: params.authority
     });
+    const outcome = await mintGrantorAuthorityIfDelegated({
+        store,
+        identity,
+        keyID,
+        wrappableDID,
+        result,
+        grant: params
+    });
     // 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`.
+    // Also reads back the envelope `mintGrantorAuthorityIfDelegated` just
+    // persisted (or none), via `readCredentialKeyBundle`'s `getWrappingAuthority`
+    // call — no second write path.
     const frame = await readGrantFrame(store, identity, keyID, wrappableDID);
     stores.onCommit(()=>params.scheduleBroadcast(groupID, frame));
-    return result;
+    return {
+        version: result.version,
+        created: result.created,
+        outcome
+    };
+}
+/**
+ * Mint or refresh the beside-the-op grantor-authority envelope for a
+ * delegate-signed grant, and report the outcome.
+ *
+ * Gated on `ownerDID`/`grantorDID` present AND distinct -- an owner-signed
+ * grant needs no envelope (owner authority doesn't expire like a delegate's
+ * chain).
+ *
+ * Runs on BOTH first grant and re-grant: nothing else in this codebase mints
+ * a grantor-authority envelope, so a delegate-signed first grant must mint
+ * its envelope here too, or ship with none.
+ */ async function mintGrantorAuthorityIfDelegated(params) {
+    const { store, identity, keyID, wrappableDID, result, grant } = params;
+    const { ownerDID, grantorDID } = grant;
+    if (ownerDID == null || grantorDID == null || normalizeDID(grantorDID) === normalizeDID(ownerDID)) {
+        return 'granted';
+    }
+    const wrappings = await store.listWrappings(keyID, result.version);
+    const wrapping = findWrappingForRecipient(wrappings, wrappableDID);
+    if (wrapping == null) {
+        throw new CredentialGrantNotReadable(keyID, `no wrapping for ${normalizeDID(wrappableDID)} at v${result.version}`);
+    }
+    // The SAME `op_hash` the store holds -- never recomputed, since this
+    // function has no token to recompute it from.
+    const op = await store.getOp('wrapping', wrapping.wrapping_id);
+    if (op == null || op.deleted !== 0) {
+        throw new CredentialGrantNotReadable(keyID, `no live op for wrapping ${wrapping.wrapping_id}`);
+    }
+    // The wrapping's own (un-normalized) recipient -- what a receiver compares
+    // `bundle.wrapping.recipientDID` against.
+    const recipientDID = wrapping.recipient_did ?? wrappableDID;
+    const refreshSeq = await store.nextGrantorSequence({
+        ownerDID,
+        recipientDID,
+        grantorDID
+    });
+    const envelope = await signGrantorAuthority(identity, {
+        wrappingOpHash: op.op_hash,
+        refreshSeq,
+        ownerDID,
+        recipientDID,
+        delegationTokens: grant.delegationTokens ?? []
+    });
+    await store.putWrappingAuthority({
+        wrappingID: wrapping.wrapping_id,
+        envelope,
+        refreshSeq
+    });
+    return result.created ? 'granted' : 'refreshed';
+}
+/** The wrapping addressed to `recipientWrappableDID`, or `undefined` when none. */ function findWrappingForRecipient(wrappings, recipientWrappableDID) {
+    const recipient = normalizeDID(recipientWrappableDID);
+    return wrappings.find((candidate)=>candidate.recipient_did != null && normalizeDID(candidate.recipient_did) === recipient);
 }
 /**
  * Rebuild the frame from what the grant persisted, rather than from what the
@@ -134,6 +204,7 @@ import { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappin
         throw new CredentialGrantNotReadable(keyID, `no wrapping for ${recipient} at v${key.version}`);
     }
     const entries = await store.listEntries(keyID);
+    const authority = await store.getWrappingAuthority(wrapping.wrapping_id);
     const carriedWrapping = {
         wrappingID: wrapping.wrapping_id,
         factors: wrapping.factors,
@@ -160,6 +231,9 @@ import { credentialEntriesDigest, credentialKeyBranchesDigest, credentialWrappin
         keyOp: await readOp('key', keyID),
         keyBranches: (await store.listKeyBranches(keyID, key.version)).map((branch)=>branch.op_jwt),
         wrapping: carriedWrapping,
-        entries: carriedEntries
+        entries: carriedEntries,
+        ...authority != null ? {
+            grantorAuthority: authority.envelope
+        } : {}
     };
 }

package/lib/groups/credential-manifest-token.d.ts

@@ -0,0 +1,31 @@
+import { type SigningIdentity } from '@kokuin/token';
+/**
+ * What a grantor signs to record the set of keys it granted a recipient: a
+ * claim the recipient checks its store against to prove completeness. Domain
+ * separation from other signed payloads comes from the `kind` marker plus the
+ * structural check in `verifyCredentialManifest` -- `signToken` has no
+ * domain override of its own.
+ */
+export type CredentialManifestClaim = {
+    kind: 'credential/key-manifest';
+    ownerDID: string;
+    recipientDID: string;
+    grantorDID: string;
+    epoch: number;
+    sequence: number;
+    keys: Array<{
+        keyID: string;
+        version: number;
+    }>;
+    issuedAt: string;
+};
+/** The envelope carried on the wire and persisted is the signed token string itself. */
+export type CredentialManifestEnvelope = string;
+export declare function signCredentialManifest(identity: SigningIdentity, claim: Omit<CredentialManifestClaim, 'kind' | 'grantorDID'>): Promise<CredentialManifestEnvelope>;
+/**
+ * Verify a credential-manifest envelope and extract its claim. Returns `null`
+ * (never throws) when the token is unparseable, unsigned (`alg: 'none'`), or
+ * structurally not a credential-manifest claim -- `grantorDID` is trusted
+ * only from the verified `iss`, never from a same-named field in the payload.
+ */
+export declare function verifyCredentialManifest(envelope: CredentialManifestEnvelope): Promise<CredentialManifestClaim | null>;