@kubun/plugin-p2p 0.14.0 → 0.15.1

package/lib/groups/credential-manifest-token.js

@@ -0,0 +1,49 @@
+import { isVerifiedToken, normalizeDID, stringifyToken, verifyToken } from '@kokuin/token';
+/**
+ * Check that a value is a finite, safe, positive integer (>= 1).
+ * Rejects NaN, Infinity, floats, negatives, and zero.
+ */ const isPosInt = (n)=>typeof n === 'number' && Number.isSafeInteger(n) && n >= 1;
+export async function signCredentialManifest(identity, claim) {
+    const fullClaim = {
+        kind: 'credential/key-manifest',
+        grantorDID: identity.id,
+        ...claim
+    };
+    const signed = await identity.signToken(fullClaim, {
+        embedLongForm: true
+    });
+    return stringifyToken(signed);
+}
+function isValidKeysArray(value) {
+    return Array.isArray(value) && value.every((entry)=>entry != null && typeof entry === 'object' && typeof entry.keyID === 'string' && isPosInt(entry.version));
+}
+/**
+ * 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 async function verifyCredentialManifest(envelope) {
+    let verified;
+    try {
+        verified = await verifyToken(envelope);
+    } catch  {
+        return null;
+    }
+    if (!isVerifiedToken(verified)) {
+        return null;
+    }
+    const { iss, kind, ownerDID, recipientDID, epoch, sequence, keys, issuedAt } = verified.payload;
+    if (kind !== 'credential/key-manifest' || typeof ownerDID !== 'string' || typeof recipientDID !== 'string' || !isPosInt(epoch) || !isPosInt(sequence) || typeof issuedAt !== 'string' || !isValidKeysArray(keys)) {
+        return null;
+    }
+    return {
+        kind: 'credential/key-manifest',
+        ownerDID,
+        recipientDID,
+        grantorDID: normalizeDID(iss),
+        epoch,
+        sequence,
+        keys,
+        issuedAt
+    };
+}

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

@@ -0,0 +1,69 @@
+import type { CredentialManager } from '@kubun/credential';
+import type { CredentialStoreAPI } from '@kubun/store-credential';
+import { type DelegatedWrappingCheckDeps } from './grantor-authority.js';
+/**
+ * The readiness verdict for one owner's provisioning: `complete` iff every
+ * durable expectation is satisfied; `missing` names keys still needing
+ * decrypt-materialization; `reason` explains a `false` verdict (absent on
+ * `complete`).
+ */
+export type CredentialProvisioningReadiness = {
+    complete: boolean;
+    missing: Array<string>;
+    reason?: 'not-initiated' | 'pending' | 'incomplete';
+};
+/**
+ * Whether one expected key is materialized on this device AT the manifest's
+ * named version: key op present, a wrapping addressed to this device exists,
+ * and — when the key has entries — at least one DECRYPT-VERIFIES (a wrapping
+ * over a garbage key still stores and reports `available`, so signature alone
+ * isn't proof). Zero entries: an openable wrapping is the whole proof.
+ *
+ * `expectedVersion` is the manifest's required version, not whatever is
+ * materialized locally — a stale pre-rotation version must not satisfy it.
+ */
+export declare function isKeyMaterialized(params: {
+    store: CredentialStoreAPI;
+    credentials: CredentialManager;
+    keyID: string;
+    self: string;
+    owner: string;
+    expectedVersion: number;
+}): Promise<boolean>;
+/**
+ * The readiness authority: `complete:true` iff `selfDID` durably holds,
+ * decrypt-verified, every credential the CURRENT provisioning attempt(s) for
+ * `ownerDID` targeted. Revalidates each held manifest's delegation proof
+ * present-time before trusting it — never a false or vacuous complete.
+ *
+ * Rule order (first match wins):
+ * 1. Any outstanding attempt ⇒ `pending`.
+ * 2. Zero expectation rows ⇒ `not-initiated`.
+ * 3. Otherwise, each expectation `(grantor, floor)` needs a held manifest
+ *    with `epoch >= floor`, a present-time delegation proof, and every
+ *    target key decrypt-materialized at its named version.
+ *
+ * Self-issued exception: grantor === owner skips the admin-chain check
+ * (mirrors `grantDeviceCredentials`'s self-issued path, which mints no
+ * envelope either) — `checkAdministerChain`'s check has no meaning when
+ * issuer == subject.
+ */
+export declare function computeCredentialProvisioningStatus(params: {
+    store: CredentialStoreAPI;
+    credentials: CredentialManager;
+    selfDID: string;
+    ownerDID: string;
+    deps: DelegatedWrappingCheckDeps;
+}): Promise<CredentialProvisioningReadiness>;
+/**
+ * The candidate `ownerDIDs` whose provisioning is not yet satisfied. A thin
+ * filter over {@link computeCredentialProvisioningStatus}, used by the
+ * credential-only PULL reconcile trigger.
+ */
+export declare function unmetCredentialOwners(params: {
+    store: CredentialStoreAPI;
+    credentials: CredentialManager;
+    selfDID: string;
+    ownerDIDs: Array<string>;
+    deps: DelegatedWrappingCheckDeps;
+}): Promise<Array<string>>;

package/lib/groups/credential-readiness.js

@@ -0,0 +1,172 @@
+import { normalizeDID } from '@kokuin/token';
+import { checkAdministerChain } from './grantor-authority.js';
+/**
+ * Whether one expected key is materialized on this device AT the manifest's
+ * named version: key op present, a wrapping addressed to this device exists,
+ * and — when the key has entries — at least one DECRYPT-VERIFIES (a wrapping
+ * over a garbage key still stores and reports `available`, so signature alone
+ * isn't proof). Zero entries: an openable wrapping is the whole proof.
+ *
+ * `expectedVersion` is the manifest's required version, not whatever is
+ * materialized locally — a stale pre-rotation version must not satisfy it.
+ */ export async function isKeyMaterialized(params) {
+    const { store, credentials, keyID, self, owner, expectedVersion } = params;
+    const key = await store.getKey(keyID);
+    if (key == null) {
+        return false;
+    }
+    // Owner mismatch: not materialized (stays in `missing`), never a throw --
+    // this is a readiness probe, not an authorization check.
+    if (normalizeDID(key.owner_did) !== owner) {
+        return false;
+    }
+    const version = expectedVersion;
+    const wrappings = await store.listWrappings(keyID, version);
+    const addressedToSelf = wrappings.some((wrapping)=>wrapping.recipient_did != null && normalizeDID(wrapping.recipient_did) === self);
+    if (!addressedToSelf) {
+        return false;
+    }
+    const entries = (await store.listEntries(keyID)).filter((entry)=>entry.key_version === version);
+    if (entries.length === 0) {
+        // No ciphertext to authenticate, so an openable wrapping is the proof.
+        // Probed at the manifest's expected version, not the key's current one.
+        const status = await credentials.status(keyID, version);
+        return status.state === 'available' || status.state === 'unlocked';
+    }
+    // The load-bearing gate: a real content key authenticates its entries, a
+    // garbage one MAC-fails. One entry that decrypt-verifies is enough.
+    for (const entry of entries){
+        try {
+            await credentials.readEntry(entry.entry_id);
+            return true;
+        } catch  {
+        // This entry did not decrypt-verify — try the next; if none do, the key
+        // is pending.
+        }
+    }
+    return false;
+}
+/**
+ * The readiness authority: `complete:true` iff `selfDID` durably holds,
+ * decrypt-verified, every credential the CURRENT provisioning attempt(s) for
+ * `ownerDID` targeted. Revalidates each held manifest's delegation proof
+ * present-time before trusting it — never a false or vacuous complete.
+ *
+ * Rule order (first match wins):
+ * 1. Any outstanding attempt ⇒ `pending`.
+ * 2. Zero expectation rows ⇒ `not-initiated`.
+ * 3. Otherwise, each expectation `(grantor, floor)` needs a held manifest
+ *    with `epoch >= floor`, a present-time delegation proof, and every
+ *    target key decrypt-materialized at its named version.
+ *
+ * Self-issued exception: grantor === owner skips the admin-chain check
+ * (mirrors `grantDeviceCredentials`'s self-issued path, which mints no
+ * envelope either) — `checkAdministerChain`'s check has no meaning when
+ * issuer == subject.
+ */ export async function computeCredentialProvisioningStatus(params) {
+    const { store, credentials, deps } = params;
+    const self = normalizeDID(params.selfDID);
+    const owner = normalizeDID(params.ownerDID);
+    const expectations = await store.listProvisioningExpectations({
+        ownerDID: owner
+    });
+    // Rule 1: an attempt in flight forces false even against a materialized OLD
+    // manifest -- its floor is not yet bound.
+    if (expectations.some((expectation)=>expectation.outstanding > 0)) {
+        return {
+            complete: false,
+            missing: [],
+            reason: 'pending'
+        };
+    }
+    // Rule 2: nothing has ever been asked for — never a vacuous complete.
+    if (expectations.length === 0) {
+        return {
+            complete: false,
+            missing: [],
+            reason: 'not-initiated'
+        };
+    }
+    const manifests = await store.listManifests({
+        ownerDID: owner,
+        recipientDID: self
+    });
+    const byGrantor = new Map(manifests.map((manifest)=>[
+            normalizeDID(manifest.record.grantorDID),
+            manifest
+        ]));
+    const missing = [];
+    let allSatisfied = true;
+    for (const expectation of expectations){
+        const grantor = normalizeDID(expectation.grantorDID);
+        const manifest = byGrantor.get(grantor);
+        // No held manifest at/above the floor: this expectation names no known
+        // target keys to report as `missing` — it is simply unsatisfied.
+        if (manifest == null || manifest.record.epoch < expectation.epochFloor) {
+            allSatisfied = false;
+            continue;
+        }
+        const authorized = grantor === owner ? true : await checkAdministerChain({
+            grantorDID: grantor,
+            ownerDID: owner,
+            delegationTokens: manifest.delegationTokens,
+            deps
+        });
+        if (!authorized) {
+            // Expired/revoked/unwired proof: fail-closed means unmet, not thrown.
+            allSatisfied = false;
+            continue;
+        }
+        for (const key of manifest.record.keys){
+            let materialized = false;
+            try {
+                materialized = await isKeyMaterialized({
+                    store,
+                    credentials,
+                    keyID: key.keyID,
+                    self,
+                    owner,
+                    expectedVersion: key.version
+                });
+            } catch  {
+                // Any error (locked factor, unopenable wrapping, store fault) means
+                // pending, not a thrown query.
+                materialized = false;
+            }
+            if (!materialized) {
+                missing.push(key.keyID);
+                allSatisfied = false;
+            }
+        }
+    }
+    if (allSatisfied && missing.length === 0) {
+        return {
+            complete: true,
+            missing: []
+        };
+    }
+    return {
+        complete: false,
+        missing,
+        reason: 'incomplete'
+    };
+}
+/**
+ * The candidate `ownerDIDs` whose provisioning is not yet satisfied. A thin
+ * filter over {@link computeCredentialProvisioningStatus}, used by the
+ * credential-only PULL reconcile trigger.
+ */ export async function unmetCredentialOwners(params) {
+    const { store, credentials, selfDID, deps } = params;
+    // Independent per-owner status probes — compute concurrently, preserve order.
+    const statuses = await Promise.all(params.ownerDIDs.map(async (ownerDID)=>({
+            ownerDID,
+            complete: (await computeCredentialProvisioningStatus({
+                store,
+                credentials,
+                selfDID,
+                ownerDID,
+                deps
+            })).complete
+        })));
+    return statuses.filter((status)=>!status.complete).map((status)=>normalizeDID(status.ownerDID));
+}

package/lib/groups/credential-wrapping-deps.d.ts

@@ -0,0 +1,23 @@
+import type { DIDMethodResolver } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import type { DelegatedWrappingCheckDeps } from './grantor-authority.js';
+/**
+ * How the plugin obtains the engine's `did:kokuin:` controller resolver for a
+ * store provider — the SAME seam the engine builds for document controller
+ * resolution. Typed here rather than imported from `@kubun/engine` so
+ * plugin-p2p keeps no dependency on the engine.
+ */
+export type ControllerResolverFor = (stores: StoreProvider, opts?: {
+    localOnly?: boolean;
+}) => DIDMethodResolver;
+/**
+ * Source the delegated-wrapping admission deps: a controller resolver (for a
+ * `did:kokuin:` grantor's administer chain) and a revocation checker over
+ * this device's delegation store, both built from the same store provider.
+ *
+ * Fail-closed: no `controllerResolverFor` seam returns an empty deps object,
+ * and {@link authorizeDelegatedWrapping} refuses. Neither dep is emitted
+ * without the other -- a revocation checker is only meaningful paired with
+ * the resolver.
+ */
+export declare function createCredentialWrappingDeps(stores: StoreProvider, controllerResolverFor?: ControllerResolverFor): Promise<DelegatedWrappingCheckDeps>;

package/lib/groups/credential-wrapping-deps.js

@@ -0,0 +1,25 @@
+import { createDelegationRevocationChecker, getDelegationStore } from '@kubun/store-delegation';
+/**
+ * Source the delegated-wrapping admission deps: a controller resolver (for a
+ * `did:kokuin:` grantor's administer chain) and a revocation checker over
+ * this device's delegation store, both built from the same store provider.
+ *
+ * Fail-closed: no `controllerResolverFor` seam returns an empty deps object,
+ * and {@link authorizeDelegatedWrapping} refuses. Neither dep is emitted
+ * without the other -- a revocation checker is only meaningful paired with
+ * the resolver.
+ */ export async function createCredentialWrappingDeps(stores, controllerResolverFor) {
+    if (controllerResolverFor == null) {
+        return {};
+    }
+    const controllerResolver = controllerResolverFor(stores);
+    const delegationStore = await getDelegationStore(stores);
+    return {
+        controllerResolver,
+        // Resolver rides `methods` so a `did:kokuin:` controller-DID issuer can
+        // be resolved and honoured (mirrors the engine's own checker).
+        revocationChecker: createDelegationRevocationChecker(delegationStore, [
+            controllerResolver
+        ])
+    };
+}

package/lib/groups/did-cache-seed.d.ts

@@ -0,0 +1,26 @@
+import { type DIDCache } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import type { GroupHandleRegistry } from './group-handle-registry.js';
+export type SeedDIDCacheParams = {
+    cache: DIDCache;
+    registry: GroupHandleRegistry;
+    groupID: string;
+    stores?: StoreProvider;
+    logger?: Logger;
+};
+/**
+ * Seed the shared DID cache with every `did:peer:4` co-member's document, read
+ * off the MLS roster's authenticated leaf long forms.
+ *
+ * A co-member's short-form `iss` on a peer-lane token carries no document, so a
+ * freshly-spawned tunnel/sync Server cannot resolve it without this. The roster
+ * leaf is the one authenticated source of the long form — the membership row
+ * holds only the normalized short form, which carries none.
+ *
+ * Monotonic and idempotent: a peer:4 doc is content-addressed, so re-seeding an
+ * existing entry is a no-op and a departed member's lingering doc is harmless
+ * (per-scope authorization gates access downstream, not cache presence). So the
+ * membership-change seam only ever adds, never evicts.
+ */
+export declare function seedDIDCacheFromRoster(params: SeedDIDCacheParams): Promise<void>;

package/lib/groups/did-cache-seed.js

@@ -0,0 +1,38 @@
+import { decodePeer4, isPeer4 } from '@kokuin/token';
+/**
+ * Seed the shared DID cache with every `did:peer:4` co-member's document, read
+ * off the MLS roster's authenticated leaf long forms.
+ *
+ * A co-member's short-form `iss` on a peer-lane token carries no document, so a
+ * freshly-spawned tunnel/sync Server cannot resolve it without this. The roster
+ * leaf is the one authenticated source of the long form — the membership row
+ * holds only the normalized short form, which carries none.
+ *
+ * Monotonic and idempotent: a peer:4 doc is content-addressed, so re-seeding an
+ * existing entry is a no-op and a departed member's lingering doc is harmless
+ * (per-scope authorization gates access downstream, not cache presence). So the
+ * membership-change seam only ever adds, never evicts.
+ */ export async function seedDIDCacheFromRoster(params) {
+    const { cache, registry, groupID, stores, logger } = params;
+    const members = await registry.readHandle(groupID, (handle)=>handle.listMembers(), stores == null ? undefined : {
+        stores
+    });
+    for (const member of members){
+        // did:key members resolve natively; only a genuine peer:4 long form (≠ the
+        // short-form `id`) carries a document worth caching.
+        if (!isPeer4(member.longForm) || member.longForm === member.id) {
+            continue;
+        }
+        try {
+            const { shortForm, doc } = decodePeer4(member.longForm);
+            await cache.set(shortForm, doc);
+        } catch (error) {
+            // A single unparseable leaf must not abort seeding the rest of the roster.
+            logger?.warn('did-cache roster seed skipped a member', {
+                groupID,
+                id: member.id,
+                error
+            });
+        }
+    }
+}

package/lib/groups/grantor-authority.d.ts

@@ -0,0 +1,65 @@
+import { type VerifyTokenHook } from '@kokuin/capability';
+import { type DIDMethodResolver, type SigningIdentity } from '@kokuin/token';
+/**
+ * What a grantor signs when handing a credential-wrapping op to a recipient:
+ * binds the op to a monotonic refresh sequence. Domain separation from other
+ * signed payloads comes from the `kind` marker plus the structural check in
+ * `verifyGrantorAuthority` -- `signToken` itself has no domain override.
+ */
+export type GrantorAuthorityClaim = {
+    kind: 'credential/grantor-authority';
+    wrappingOpHash: string;
+    refreshSeq: number;
+    grantorDID: string;
+    ownerDID: string;
+    recipientDID: string;
+    delegationTokens: Array<string>;
+};
+/** The envelope carried on the wire and persisted is the signed token string itself. */
+export type GrantorAuthorityEnvelope = string;
+export declare function signGrantorAuthority(identity: SigningIdentity, claim: Omit<GrantorAuthorityClaim, 'kind' | 'grantorDID'>): Promise<GrantorAuthorityEnvelope>;
+/**
+ * Verify a grantor-authority envelope and extract its claim. Returns `null`
+ * (never throws) when the token is unparseable, unsigned (`alg: 'none'`), or
+ * structurally not a grantor-authority claim -- `grantorDID` is trusted only
+ * from the verified `iss`, never from a same-named field in the payload.
+ */
+export declare function verifyGrantorAuthority(envelope: GrantorAuthorityEnvelope): Promise<GrantorAuthorityClaim | null>;
+export type DelegatedWrappingCheckDeps = {
+    /** Injected so a `did:kokuin:` grantor's capability chain resolves without a dependency cycle. */
+    controllerResolver?: DIDMethodResolver;
+    /** The delegation-revocation hook, consulted for every capability in the chain. */
+    revocationChecker?: VerifyTokenHook;
+    /** Evaluate capability expiry at this time (epoch seconds) rather than now(). */
+    atTime?: number;
+};
+/**
+ * Present-time `credential/administer` chain check shared by
+ * {@link authorizeDelegatedWrapping} and the credential-manifest admission
+ * gate. Mirrors `@kubun/engine`'s `createControllerAuthority` check; never
+ * throws.
+ *
+ * Fail-CLOSED: no `controllerResolver`/`revocationChecker` wired returns
+ * `false`. Tries both the owner's user resource and `*`, since a grant may
+ * scope its administer right to either.
+ */
+export declare function checkAdministerChain(params: {
+    grantorDID: string;
+    ownerDID: string;
+    delegationTokens: Array<string>;
+    deps: DelegatedWrappingCheckDeps;
+}): Promise<boolean>;
+/**
+ * Present-time admission gate for a delegated credential-wrapping op: `true`
+ * iff (a) the envelope structurally binds this exact op + issuer + owner
+ * (defeats envelope transplant and issuer-swap), and (b) the VERIFIED issuer
+ * `G` presently holds a `credential/administer` capability over the owner
+ * via the shared {@link checkAdministerChain}. Never throws.
+ */
+export declare function authorizeDelegatedWrapping(params: {
+    envelope: GrantorAuthorityEnvelope;
+    wrappingOpIssuer: string;
+    wrappingOpHash: string;
+    ownerDID: string;
+    deps: DelegatedWrappingCheckDeps;
+}): Promise<boolean>;

package/lib/groups/grantor-authority.js

@@ -0,0 +1,107 @@
+import { checkCapability } from '@kokuin/capability';
+import { isVerifiedToken, normalizeDID, stringifyToken, verifyToken } from '@kokuin/token';
+import { CREDENTIAL_ADMINISTER_ACTION, credentialUserResource } from '@kubun/credential';
+export async function signGrantorAuthority(identity, claim) {
+    const fullClaim = {
+        kind: 'credential/grantor-authority',
+        grantorDID: identity.id,
+        ...claim
+    };
+    const signed = await identity.signToken(fullClaim, {
+        embedLongForm: true
+    });
+    return stringifyToken(signed);
+}
+/**
+ * Verify a grantor-authority envelope and extract its claim. Returns `null`
+ * (never throws) when the token is unparseable, unsigned (`alg: 'none'`), or
+ * structurally not a grantor-authority claim -- `grantorDID` is trusted only
+ * from the verified `iss`, never from a same-named field in the payload.
+ */ export async function verifyGrantorAuthority(envelope) {
+    let verified;
+    try {
+        verified = await verifyToken(envelope);
+    } catch  {
+        return null;
+    }
+    if (!isVerifiedToken(verified)) {
+        return null;
+    }
+    const { iss, kind, wrappingOpHash, refreshSeq, ownerDID, recipientDID, delegationTokens } = verified.payload;
+    if (kind !== 'credential/grantor-authority' || typeof wrappingOpHash !== 'string' || typeof refreshSeq !== 'number' || typeof ownerDID !== 'string' || typeof recipientDID !== 'string' || !Array.isArray(delegationTokens) || !delegationTokens.every((token)=>typeof token === 'string')) {
+        return null;
+    }
+    return {
+        kind: 'credential/grantor-authority',
+        wrappingOpHash,
+        refreshSeq,
+        grantorDID: normalizeDID(iss),
+        ownerDID,
+        recipientDID,
+        delegationTokens
+    };
+}
+/**
+ * Present-time `credential/administer` chain check shared by
+ * {@link authorizeDelegatedWrapping} and the credential-manifest admission
+ * gate. Mirrors `@kubun/engine`'s `createControllerAuthority` check; never
+ * throws.
+ *
+ * Fail-CLOSED: no `controllerResolver`/`revocationChecker` wired returns
+ * `false`. Tries both the owner's user resource and `*`, since a grant may
+ * scope its administer right to either.
+ */ export async function checkAdministerChain(params) {
+    const { grantorDID, ownerDID, delegationTokens, deps } = params;
+    if (deps.controllerResolver == null || deps.revocationChecker == null) {
+        return false;
+    }
+    const methods = [
+        deps.controllerResolver
+    ];
+    for (const res of [
+        credentialUserResource(ownerDID),
+        '*'
+    ]){
+        try {
+            await checkCapability({
+                act: CREDENTIAL_ADMINISTER_ACTION,
+                res
+            }, {
+                iss: grantorDID,
+                sub: ownerDID,
+                cap: delegationTokens
+            }, {
+                ...deps.atTime != null ? {
+                    atTime: deps.atTime
+                } : {},
+                verifyToken: deps.revocationChecker,
+                methods
+            });
+            return true;
+        } catch  {
+        // This resource does not match the chain -- try the next one.
+        }
+    }
+    return false;
+}
+/**
+ * Present-time admission gate for a delegated credential-wrapping op: `true`
+ * iff (a) the envelope structurally binds this exact op + issuer + owner
+ * (defeats envelope transplant and issuer-swap), and (b) the VERIFIED issuer
+ * `G` presently holds a `credential/administer` capability over the owner
+ * via the shared {@link checkAdministerChain}. Never throws.
+ */ export async function authorizeDelegatedWrapping(params) {
+    const claim = await verifyGrantorAuthority(params.envelope);
+    if (claim == null) {
+        return false;
+    }
+    if (claim.grantorDID !== normalizeDID(params.wrappingOpIssuer) || claim.wrappingOpHash !== params.wrappingOpHash || normalizeDID(claim.ownerDID) !== normalizeDID(params.ownerDID)) {
+        return false;
+    }
+    return await checkAdministerChain({
+        grantorDID: claim.grantorDID,
+        ownerDID: params.ownerDID,
+        delegationTokens: claim.delegationTokens,
+        deps: params.deps
+    });
+}

package/lib/groups/group-handlers.js

@@ -123,6 +123,13 @@ import { processBroadcast } from './broadcast.js';
                         entries: data.entries,
                         auth: data.auth
                     }, groupID)),
+            // Carried back verbatim: the manifest token digests its own fields, so
+            // reshaping it would break its signature.
+            'control/credentialKeyManifest': ({ data })=>safeApply(()=>processBroadcast(params, {
+                        type: 'credential:key-manifest',
+                        manifest: data.manifest,
+                        delegationTokens: data.delegationTokens
+                    }, groupID)),
             'control/groupLeaveRequest': ({ data })=>safeApply(()=>processBroadcast(params, {
                         type: 'group:leaveRequest',
                         groupID,

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

@@ -1,9 +1,10 @@
 import type { ProcedureHandlers } from '@enkaku/server';
-import type { OwnIdentity } from '@kokuin/token';
+import type { DIDCache, OwnIdentity } from '@kokuin/token';
 import type { StoreProvider } from '@kubun/db';
 import type { DefaultAccessLevel, GraphInternals } from '@kubun/engine';
 import type { HLC } from '@kubun/hlc';
 import type { Logger } from '@kubun/logger';
+import type { ServiceConfig } from '@kubun/plugin-service-api';
 import type { GraphStoreAPI } from '@kubun/store-graph';
 import { type GroupPeer, type LaneResult, type PendingCommit } from '@kumiai/rpc';
 import type { Runtime } from '@sozai/runtime';
@@ -11,9 +12,12 @@ import type { CreateHubClient } from '../hub/http-client.js';
 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 { ServeService } from '../sync/hub-tunnel-service-listener.js';
+import { HubTunnelServiceProvider } from '../sync/hub-tunnel-service-provider.js';
 import type { LedgerCatchupOptions, LedgerCatchupSummary, RejoinResult, StoreUnreadableMode } from '../types.js';
 import type { GroupBroadcastMessage } from './broadcast-message.js';
 import { type SettleLostControlRequestDeps } from './commit-adoption.js';
+import { type ControllerResolverFor } from './credential-wrapping-deps.js';
 import type { P2PEventEmitter } from './events.js';
 import type { GroupHandleRegistry } from './group-handle-registry.js';
 import { type GroupProtocols } from './group-protocols.js';
@@ -66,6 +70,12 @@ export type GroupPeerManagerParams = {
      * engine does, so absence is never an absent bound.
      */
     maxDriftMS?: number;
+    /**
+     * The engine's `did:kokuin:` controller-resolver seam, forwarded to the apply
+     * path for delegate-signed wrapping authorization. Absent means fail-closed
+     * (owner-signed wrappings only).
+     */
+    controllerResolverFor?: ControllerResolverFor;
     /** Authenticated DID of this device (normalized). */
     localDID: string;
     /**
@@ -114,6 +124,20 @@ export type GroupPeerManagerParams = {
      * handlers has no sync surface to expose.
      */
     syncHandlers?: ProcedureHandlers<SyncProtocol>;
+    /**
+     * Injected `plugin-service-server` `serve()` for answering an inbound
+     * service-lane tunnel session (see {@link ServeService}). Paired with
+     * `services`: both present is what serves the lane.
+     */
+    serviceServe?: ServeService;
+    /** Which services to serve on an inbound service-lane session. */
+    services?: Record<string, ServiceConfig>;
+    /**
+     * Shared, plugin-lifetime DID cache forwarded to the sync- and service-tunnel
+     * listeners, which seed it from each group's roster and hand it to every
+     * spawned session's Server (see {@link TunnelListenersParams.cache}).
+     */
+    cache?: DIDCache;
     /** @see TunnelListenersParams.idleTimeoutMs */
     tunnelIdleTimeoutMs?: number;
 };
@@ -215,6 +239,13 @@ export type GroupPeerManager = {
      * nothing here holds.
      */
     tunnelHub: (groupID: string) => DeviceHub | undefined;
+    /**
+     * Build the dial-side provider for one directed SERVICE-lane session to a
+     * co-member, relayed by the group's hub. `undefined` when the group has no
+     * hub bound — the mirror of {@link tunnelHub}'s gate, on the service lane
+     * rather than the sync one.
+     */
+    serviceTransportTo: (groupID: string, peerDID: string) => Promise<HubTunnelServiceProvider | undefined>;
     /**
      * Try every hub this device holds now, rather than when each one's backoff
      * says so, and answer with whether any of them is connected afterwards.