@interop/wallet-core 0.45.0 → 0.46.0

package/dist/webvh/companion.d.ts

@@ -0,0 +1,681 @@
+import type { DIDDoc, DIDLog, ServiceEndpoint, Signer } from '@interop/did-method-webvh';
+import type { IZcap } from '@interop/data-integrity-core';
+import type { ZcapClient } from '@interop/ezcap';
+import type { WasClient } from '@interop/was-client';
+import type { ResourceLogPinStore } from '../resourceLog/pin.js';
+import type { ClientWebvhUpdateKeys, WebvhIdStore } from './didWebvh.js';
+import type { WebvhLogResourceStore } from './wasIdStore.js';
+/**
+ * The Space Description `type` array of the auxiliary companion Space, set at
+ * creation (the server treats a Space's `type` as immutable afterwards).
+ * Wire-level and permanent: the server's inspector clause recognizes the
+ * `DelegatedClientsSpace` member, and user-data surfaces exclude auxiliary
+ * Spaces by it.
+ */
+export declare const COMPANION_SPACE_TYPE: string[];
+/**
+ * The literal prefix of every generation collection's name. Wire-level and
+ * permanent: orphan discovery is a plain prefix match over the auxiliary
+ * Space's collection listing, and the segment embeds in every companion DID
+ * string ever published.
+ */
+export declare const GENERATION_SEGMENT_PREFIX = "gen-";
+/**
+ * Mints a fresh generation segment -- the generation collection's name, e.g.
+ * `gen-Ux3v0kQf9aPmB2hZ`. Random rather than a counter on purpose: never-reuse
+ * is structural (nothing durable survives GC to carry a counter), at the same
+ * probabilistic order as every other random-id convention in the system.
+ *
+ * @returns {string}
+ */
+export declare function mintGenerationSegment(): string;
+/**
+ * Refuses anything that is not a well-formed generation segment. Run by every
+ * companion builder that takes a segment, so a malformed one is refused
+ * before it can reach a DID string, an HKDF label, or a collection id.
+ *
+ * @param segment {string}
+ */
+export declare function assertGenerationSegment(segment: string): void;
+/**
+ * The pin-slot key for one companion generation's log -- host-free like every
+ * pin-slot key, keyed by the auxiliary Space id and the generation segment.
+ * A transient session keeps this slot in an in-memory pin store (a durable
+ * pin is the wrong lifetime for a disposable log, and a transient session
+ * must not durably create the pin store on a read); a durable client's store
+ * clears companion slots when the generation is collected.
+ *
+ * @param options {object}
+ * @param options.spaceId {string}   the auxiliary companion Space's id
+ * @param options.segment {string}   the generation collection's name
+ * @returns {string}
+ */
+export declare function companionLogPinId({ spaceId, segment }: {
+    spaceId: string;
+    segment: string;
+}): string;
+/**
+ * The WAS-backed store a companion generation's ceremonies read and publish
+ * through with controller-tier signing (an enrolled client). A transient
+ * session writes through the delegated store instead
+ * (`delegatedWebvhLogStore`, invoking the credential's sibling delegation);
+ * both carry the same CAS/ETag conditional-publish discipline.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}
+ * @param options.spaceId {string}   the auxiliary companion Space's id
+ * @param options.segment {string}   the generation collection's name
+ * @returns {WebvhLogResourceStore}
+ */
+export declare function companionLogStore({ was, spaceId, segment }: {
+    was: WasClient;
+    spaceId: string;
+    segment: string;
+}): WebvhLogResourceStore;
+/**
+ * Creates the one-entry companion generation log. The genesis parameters are
+ * the companion posture (see the module doc): prerotation on via the rung-0
+ * hash commitments, no witnesses, portability off (the library's default,
+ * stated explicitly in the emitted entry), and a bare document -- id and the
+ * DID core context, nothing else.
+ *
+ * The caller supplies the update authority: the minting credential's
+ * companion rung-0 key as the sole `updateKeys` member, `nextKeyHashes` as
+ * every standing credential's rung-0 hash (restated explicitly on every later
+ * entry, never inherited), and rung 0's signer. The minting key's own
+ * carry-over hash MUST be among the commitments -- every companion entry
+ * re-states `updateKeys` containing the revealed rung-0 keys, and the
+ * resolver checks the re-statement against the previous entry's commitments
+ * -- so a `nextKeyHashes` that omits it is refused here rather than
+ * publishing a generation no one can ever extend.
+ *
+ * @param options {object}
+ * @param options.wasServerUrl {string}
+ * @param options.spaceId {string}   the auxiliary companion Space's id
+ * @param options.segment {string}   the generation collection's name
+ * @param options.updateKeyPublicKeyMultibase {string}   the minting
+ *   credential's companion rung-0 key
+ * @param options.nextKeyHashes {string[]}   every standing credential's
+ *   rung-0 hash, the minting credential's included
+ * @param options.signer {Signer}   the minting credential's rung-0 signer
+ * @returns {Promise<{ log: DIDLog; did: string; doc: DIDDoc }>}
+ */
+export declare function createCompanionLog({ wasServerUrl, spaceId, segment, updateKeyPublicKeyMultibase, nextKeyHashes, signer }: {
+    wasServerUrl: string;
+    spaceId: string;
+    segment: string;
+    updateKeyPublicKeyMultibase: string;
+    nextKeyHashes: string[];
+    signer: Signer;
+}): Promise<{
+    log: DIDLog;
+    did: string;
+    doc: DIDDoc;
+}>;
+/**
+ * Ensures the auxiliary companion Space exists: created with the typed
+ * Description ({@link COMPANION_SPACE_TYPE}) under the given controller when
+ * absent, verified when present. The `type` array must ride the create -- the
+ * server accepts it at creation only and treats it as immutable afterwards --
+ * which is also why an existing Space at this id that is NOT typed as the
+ * delegated-clients Space is refused loudly: it can never become one.
+ *
+ * The Space id is minted by the caller at credential bind time with the
+ * account Space's `mintSpaceId` convention (32 random bytes, base64url
+ * no-pad): the sibling delegation's `invocationTarget` embeds the id and is
+ * sealed into the unlock record before the account DID exists, so no
+ * derivation over the account identity is possible -- and hash-derived
+ * addressing would import the unlock Spaces' existence-oracle posture,
+ * unwanted here.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}
+ * @param options.spaceId {string}   the auxiliary companion Space's id
+ * @param options.controller {string}   the Space controller (the account
+ *   did:webvh where it exists; a bootstrap did:key on a client-less signup,
+ *   promoted the same way the account Space's controller is)
+ * @returns {Promise<void>}
+ */
+export declare function ensureCompanionSpace({ was, spaceId, controller }: {
+    was: WasClient;
+    spaceId: string;
+    controller: string;
+}): Promise<void>;
+/**
+ * Mints a fresh companion generation with controller-tier signing: ensures
+ * the typed auxiliary Space, mints a fresh random segment, creates the
+ * generation collection, and publishes the genesis `did.jsonl` as a
+ * create-if-absent -- the same conditional-publish discipline as every log
+ * write, though a fresh random segment makes a create collision negligible.
+ *
+ * The account document's `#DelegatedClients` service entry is deliberately
+ * NOT written here: the companion log publishes first, and the caller
+ * re-points the account document at the returned DID afterwards. A run torn
+ * between the two leaves an unpointed generation -- authorization-inert (no
+ * delegation names it), collected by the standing `gen-` prefix orphan
+ * discovery at the next durable login.
+ *
+ * A re-run after a tear mints a FRESH generation rather than resuming: the
+ * genesis entry is timestamped, so a re-created log has a different SCID and
+ * a resume could never land its create-if-absent PUT; the torn generation is
+ * an inert orphan like any other.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}   the storage client, signing as an enrolled
+ *   client (or the bootstrap controller on a client-less signup)
+ * @param options.wasServerUrl {string}
+ * @param options.spaceId {string}   the auxiliary companion Space's id
+ * @param options.controller {string}   the auxiliary Space's controller, used
+ *   only when the Space does not exist yet
+ * @param options.updateKeyPublicKeyMultibase {string}   the minting
+ *   credential's companion rung-0 key
+ * @param options.nextKeyHashes {string[]}   every standing credential's
+ *   rung-0 hash, the minting credential's included
+ * @param options.signer {Signer}   the minting credential's rung-0 signer
+ * @returns {Promise<{ did: string; segment: string; log: DIDLog;
+ *   doc: DIDDoc }>}
+ */
+export declare function mintCompanionGeneration({ was, wasServerUrl, spaceId, controller, updateKeyPublicKeyMultibase, nextKeyHashes, signer }: {
+    was: WasClient;
+    wasServerUrl: string;
+    spaceId: string;
+    controller: string;
+    updateKeyPublicKeyMultibase: string;
+    nextKeyHashes: string[];
+    signer: Signer;
+}): Promise<{
+    did: string;
+    segment: string;
+    log: DIDLog;
+    doc: DIDDoc;
+}>;
+/**
+ * The type IRI of the account document's delegated-clients service entry --
+ * the pointer at the current companion generation's DID. Wire-level and
+ * permanent: readers (this module's {@link delegatedClientsPointer}, the
+ * server's companion-chain inspector clause) dispatch on this IRI, never on
+ * the entry's fragment id, which is non-semantic by convention.
+ */
+export declare const DELEGATED_CLIENTS_SERVICE_TYPE = "https://w3id.org/byoe#DelegatedClients";
+/**
+ * Builds a fresh delegated-clients service entry for the account document.
+ * The `serviceEndpoint` is the companion DID STRING, deliberately not a URL:
+ * the DID is self-certifying and host-independent, and the account pointer
+ * already carries the host.
+ *
+ * @param options {object}
+ * @param options.accountDid {string}   the account did:webvh
+ * @param options.companionDid {string}   the current generation's companion
+ *   DID
+ * @returns {ServiceEndpoint}
+ */
+export declare function delegatedClientsServiceEntry({ accountDid, companionDid }: {
+    accountDid: string;
+    companionDid: string;
+}): ServiceEndpoint;
+/**
+ * The companion DID the account document currently points at: the
+ * `serviceEndpoint` of the service entry whose `type` names (or includes)
+ * {@link DELEGATED_CLIENTS_SERVICE_TYPE}. Only a bare DID-string endpoint
+ * counts -- the same predicate the server's inspector clause evaluates, so
+ * wallet and server can never disagree on which generation is pointed.
+ *
+ * @param options {object}
+ * @param options.doc {DIDDoc}   the resolved (and verified) account document
+ * @returns {string | undefined}
+ */
+export declare function delegatedClientsPointer({ doc }: {
+    doc: DIDDoc;
+}): string | undefined;
+/**
+ * The unlock-record sibling delegation's `allowedAction` set: GET beside PUT,
+ * so an enrolling transient client can read the companion head it appends to.
+ * Wire-level and permanent (wallet-core decision 0005): the server's
+ * inspector clause admits a delegated-clients delegation with `allowedAction`
+ * a subset of exactly this pair.
+ */
+export declare const DELEGATED_CLIENTS_DELEGATION_ACTIONS: string[];
+/**
+ * The sibling delegation's lifetime: the house standing-zcap value (one
+ * year; see `standingZcap.ts`). It rots on exactly the account bridge's axis
+ * -- same signer, same current-key-set rule, same renewal window -- so the
+ * re-mint pass that refreshes the bridge refreshes it too.
+ */
+export declare const DELEGATED_CLIENTS_DELEGATION_TTL_MS: number;
+/**
+ * Mints one delegated-clients (companion-Space) delegation: the pre-minted
+ * zcap sealed into a standing credential's unlock record beside the account
+ * bridge, which is what lets a transient login reach the companion log with
+ * nothing but the credential. The shape is a permanent wire artifact
+ * (wallet-core decision 0005):
+ *
+ * - `invocationTarget` is the AUXILIARY companion Space's items subtree --
+ *   the Space URL with a trailing slash, built with was-client's paths
+ *   helpers so the bytes match the server's target check on a sub-path
+ *   deployment. Generation coverage comes from segment-bounded attenuation
+ *   over the flat `gen-` collection names, so no GC cycle rewrites the
+ *   record or the registry.
+ * - `controller` is the credential-derived signing DID (the same grantee
+ *   the account bridge names).
+ * - `allowedActions` is {@link DELEGATED_CLIENTS_DELEGATION_ACTIONS}.
+ * - The chain is rooted directly in the auxiliary Space's root zcap.
+ * - `expires` is {@link DELEGATED_CLIENTS_DELEGATION_TTL_MS} out.
+ *
+ * @param options {object}
+ * @param options.zcapClient {ZcapClient}   the delegating signer (an
+ *   enrolled client's promoted signer, or the account ladder VM)
+ * @param options.wasServerUrl {string}   the auxiliary Space's storage
+ *   server (the account pointer's host)
+ * @param options.companionSpaceId {string}   the auxiliary companion
+ *   Space's id
+ * @param options.controller {string}   the credential-derived signing DID
+ * @param [options.now] {number}   epoch milliseconds, for tests
+ * @returns {Promise<IZcap>}
+ */
+export declare function mintDelegatedClientsDelegation({ zcapClient, wasServerUrl, companionSpaceId, controller, now }: {
+    zcapClient: ZcapClient;
+    wasServerUrl: string;
+    companionSpaceId: string;
+    controller: string;
+    now?: number;
+}): Promise<IZcap>;
+/**
+ * The auxiliary companion Space id a delegated-clients delegation targets,
+ * read out of its `invocationTarget` (the items-subtree URL,
+ * `.../space/<companionSpaceId>/`). The id has no other home -- a transient
+ * login learns the Space from the delegation it unwraps, and a refresh pass
+ * that holds the old delegation rebuilds the target from it -- so this parse
+ * is the one reader. Returns `undefined` on anything that is not an
+ * items-subtree Space URL.
+ *
+ * @param options {object}
+ * @param options.delegation {IZcap}   a delegated-clients delegation
+ * @returns {string | undefined}
+ */
+export declare function delegatedClientsDelegationSpaceId({ delegation }: {
+    delegation: IZcap;
+}): string | undefined;
+/**
+ * The type IRI of the companion document's generation-delegation service
+ * entry -- the generation's standing Space-scoped zcap, embedded where an
+ * enrolling transient client can reach it before it holds any other
+ * authority. Wire-level and permanent: readers (this module's
+ * {@link embeddedGenerationDelegation}, the app-side loader) dispatch on this
+ * IRI, never on the entry's fragment id, which is non-semantic by the byoe
+ * service-entry convention.
+ */
+export declare const GENERATION_DELEGATION_SERVICE_TYPE = "https://w3id.org/byoe#GenerationDelegation";
+/**
+ * The generation delegation's `allowedAction` set: the full closed WAS
+ * action vocabulary. Wire-level and permanent (the app-connect-spec
+ * generation-delegation record): attenuation is structural, not enumerated
+ * -- child-within-parent is enforced on both actions and targets, so any
+ * verb missing here would cap every transient-visit App Connect grant below
+ * its durable-client shape. What stays outside the delegation is carried by
+ * the TARGET instead: the items subtree excludes the bare Space URL, and
+ * with it the Space Description PUT (a controller rewrite) and the Space
+ * DELETE.
+ */
+export declare const GENERATION_DELEGATION_ACTIONS: string[];
+/**
+ * The generation delegation's lifetime: the house standing-zcap value (one
+ * year; see `standingZcap.ts`). GC's explicit revoke is the intended
+ * end-of-life; expiry is the backstop, deliberately not matched to the
+ * quarterly GC cadence -- a 90-day-class TTL would begin renewal churn
+ * exactly when GC is merely due.
+ */
+export declare const GENERATION_DELEGATION_TTL_MS: number;
+/**
+ * Mints one generation delegation: the standing Space-scoped zcap a
+ * generation's transient clients invoke under. The shape is a permanent wire
+ * artifact (the app-connect-spec generation-delegation record):
+ *
+ * - `invocationTarget` is the ACCOUNT Space's items subtree -- the Space URL
+ *   with a trailing slash, built with was-client's paths helpers so the
+ *   bytes match the server's target check on a sub-path deployment. The
+ *   bare Space URL sits outside the capability bytes (see
+ *   {@link GENERATION_DELEGATION_ACTIONS} for what that excludes).
+ * - `controller` is the bare companion DID string. Transient keys invoke as
+ *   `<companionDid>#<vm>`, and the server's inspector clause compares this
+ *   string against the account document's delegated-clients pointer.
+ * - The chain is rooted directly in the account Space's root zcap, so an
+ *   App Connect grant delegated under it forms the depth-3 chain
+ *   `[root id string, this delegation embedded]`.
+ * - `expires` is {@link GENERATION_DELEGATION_TTL_MS} out.
+ *
+ * The delegation signer is the caller's choice of licensed authority: the
+ * account ladder VM (`ladderVmZcapClient`) or an enrolled durable client's
+ * promoted signer (`webvhZcapClient`).
+ *
+ * @param options {object}
+ * @param options.zcapClient {ZcapClient}   the delegating signer (ladder VM
+ *   or a durable client's promoted signer)
+ * @param options.wasServerUrl {string}   the ACCOUNT Space's storage server
+ * @param options.spaceId {string}   the ACCOUNT Space's id
+ * @param options.companionDid {string}   the generation's companion DID
+ * @param [options.now] {number}   epoch milliseconds, for tests
+ * @returns {Promise<IZcap>}
+ */
+export declare function mintGenerationDelegation({ zcapClient, wasServerUrl, spaceId, companionDid, now }: {
+    zcapClient: ZcapClient;
+    wasServerUrl: string;
+    spaceId: string;
+    companionDid: string;
+    now?: number;
+}): Promise<IZcap>;
+/**
+ * A child grant's `expires` under the generation delegation: the requested
+ * TTL, clamped to the delegation's own expiry -- the library's per-hop
+ * monotonicity rule IS the TTL clamp, so a grant minted past the parent's
+ * `expires` would verify nowhere. By construction the bounded grants (30-day
+ * read, 7-day write) always receive their full TTL; only 365-day-class
+ * grants ever meet the clamp, at 30 or more days remaining (the
+ * renew-precedes-mint stage keeps the delegation outside its renewal window
+ * whenever a grant is minted).
+ *
+ * @param options {object}
+ * @param options.ttlMs {number}   the grant's requested TTL
+ * @param options.delegation {IZcap}   the generation delegation
+ * @param [options.now] {number}   epoch milliseconds, for tests
+ * @returns {Date}
+ */
+export declare function clampGrantExpires({ ttlMs, delegation, now }: {
+    ttlMs: number;
+    delegation: IZcap;
+    now?: number;
+}): Date;
+/**
+ * Builds a fresh generation-delegation service entry for a companion
+ * document. The `serviceEndpoint` is the full delegated-zcap JSON as a
+ * single map, byte-identical to what `zcapClient.delegate` produced -- the
+ * companion entry proof (JCS canonicalization) then covers it byte for byte,
+ * so host tampering with the stored delegation is client-visible.
+ *
+ * @param options {object}
+ * @param options.companionDid {string}   the generation's companion DID
+ * @param options.delegation {IZcap}   the minted generation delegation
+ * @returns {ServiceEndpoint}
+ */
+export declare function generationDelegationServiceEntry({ companionDid, delegation }: {
+    companionDid: string;
+    delegation: IZcap;
+}): ServiceEndpoint;
+/**
+ * The generation delegation a companion document carries: the
+ * `serviceEndpoint` map of the service entry whose `type` names (or
+ * includes) {@link GENERATION_DELEGATION_SERVICE_TYPE}. Only a map-form
+ * endpoint counts (the delegation is embedded as the zcap JSON itself,
+ * never as a URL or an encoded string).
+ *
+ * @param options {object}
+ * @param options.doc {DIDDoc}   the resolved (and verified) companion
+ *   document
+ * @returns {IZcap | undefined}
+ */
+export declare function embeddedGenerationDelegation({ doc }: {
+    doc: DIDDoc;
+}): IZcap | undefined;
+/**
+ * Parses the auxiliary Space id and generation segment out of a companion DID
+ * string. Both are permanent substrings of every companion DID by
+ * construction (`did:webvh:<scid>:<host>:...:space:<spaceId>:<segment>`), and
+ * the segment is the generation-identifying half of the companion rung HKDF
+ * labels, so this parse is what lets an enrollee derive its writing key from
+ * the pointer alone -- no log read, no registry.
+ *
+ * @param options {object}
+ * @param options.did {string}   a companion did:webvh string
+ * @returns {{ spaceId: string, segment: string }}
+ */
+export declare function companionDidParts({ did }: {
+    did: string;
+}): {
+    spaceId: string;
+    segment: string;
+};
+/**
+ * Thrown when the published companion log commits neither the writing
+ * credential's rung-0 key nor its hash -- the mid-generation lockout: a
+ * credential bound after the generation's genesis cannot write the companion
+ * until an existing writer commits its rung-0 hash or the next GC swap's
+ * genesis does. Typed so callers can map it to the fresh-generation path
+ * where one is licensed (the transient-recovery continuation) or to honest
+ * copy where none is.
+ */
+export declare class CompanionRungUncommittedError extends Error {
+    constructor(message: string);
+}
+/**
+ * The narrow store seam a companion entry is read and published through: the
+ * log read and the conditional `did.jsonl` PUT, nothing else (a companion has
+ * no `did.json` projection and no key map). Satisfied by
+ * {@link companionLogStore} (controller-tier signing) and by the delegated
+ * store a transient session writes through (`delegatedWebvhLogStore`,
+ * invoking the credential's sibling delegation).
+ */
+export type CompanionWriteStore = Pick<WebvhIdStore, 'getIdResourceRaw' | 'putIdResource'>;
+/**
+ * TRANSIENT ENROLLMENT: publishes one per-visit verification method into a
+ * companion generation's log -- one atomic entry, signed by the writing
+ * credential's static rung 0 (derived from the ladder seed and the segment;
+ * see `companionRung`). The entry:
+ *
+ * - reveals the writer's rung-0 key into `updateKeys` at its first companion
+ *   write (later writes re-state it unchanged);
+ * - re-states `nextKeyHashes` verbatim -- every standing credential's rung-0
+ *   hash, the writer's own carry-over hash included -- explicitly on the
+ *   entry, never inherited from the prior entry's parameters;
+ * - adds the transient VM under `capabilityInvocation` ONLY, with all five
+ *   relationship arrays stated explicitly (no `authentication`, no
+ *   `assertionMethod`, no `keyAgreement` twin -- the DIDAuth path signs as
+ *   the bare did:key, and the controller-marker convention does not arise in
+ *   the companion at all).
+ *
+ * The transient key set carries no update key, and nothing here touches the
+ * ACCOUNT log's `updateKeys` or `nextKeyHashes`. There is no two-entry
+ * reveal/add split and no attribution scan: a CAS loser re-signs with the
+ * SAME key via the ordinary conflict retry, and resumability reduces to the
+ * published document's own state -- a VM already present is a no-op.
+ *
+ * A writer whose rung-0 key is neither revealed nor committed is refused
+ * ({@link CompanionRungUncommittedError}): companion entries verify against
+ * the log's own hash-commitment chain, so no admission rule can make an
+ * uncommitted key verify mid-log.
+ *
+ * @param options {object}
+ * @param options.store {CompanionWriteStore}   the generation's log store
+ *   (delegated through the credential's sibling delegation, or
+ *   controller-tier)
+ * @param options.ladderSeed {Uint8Array}   the credential's ladder seed, from
+ *   its unlock record
+ * @param options.segment {string}   the generation collection's name
+ * @param options.transientKeyMultibase {string}   the visit's in-memory
+ *   Ed25519 signing key, public multibase
+ * @param [options.services] {ServiceEndpoint[]}   the companion document's
+ *   full service-entry list, replacing the published one wholesale; omitted,
+ *   the prior entries are preserved verbatim (or extended by
+ *   `mintGenerationDelegation` below). Supplying both is refused in favor of
+ *   the explicit list
+ * @param [options.mintGenerationDelegation] {Function}
+ *   `({ companionDid }) => Promise<IZcap>` -- mints the generation
+ *   delegation this entry installs when it publishes the generation's FIRST
+ *   transient verification method (and the document carries no delegation
+ *   entry yet). Never invoked otherwise: the delegation is installed with
+ *   the first transient VM or by the GC ceremony's own install stage, never
+ *   by genesis (a genesis-embedded signed zcap can never verify -- its
+ *   `controller` embeds the SCID the genesis hash derives from)
+ * @param [options.expectedDid] {string}   the companion DID the log must
+ *   resolve to, from the account document's pointer
+ * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins (a
+ *   transient session passes an in-memory store)
+ * @param [options.logId] {string}   the generation's pin-slot key, from
+ *   {@link companionLogPinId}; required whenever a `pinStore` is supplied
+ * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog }>}
+ */
+export declare function enrollCompanionTransientClient(options: {
+    store: CompanionWriteStore;
+    ladderSeed: Uint8Array;
+    segment: string;
+    transientKeyMultibase: string;
+    services?: ServiceEndpoint[];
+    mintGenerationDelegation?: (options: {
+        companionDid: string;
+    }) => Promise<IZcap>;
+    expectedDid?: string;
+    pinStore?: ResourceLogPinStore;
+    logId?: string;
+}): Promise<{
+    did: string;
+    doc: DIDDoc;
+    log: DIDLog;
+}>;
+/**
+ * Points the account document's delegated-clients service entry at a
+ * companion DID -- the first install after a generation's genesis, and the GC
+ * swap's re-point alike. One ordinary document-update entry, signed by an
+ * enrolled durable client's active update key; the companion log always
+ * publishes FIRST (see {@link mintCompanionGeneration}), so a tear leaves an
+ * unpointed, authorization-inert generation, never a dangling pointer.
+ *
+ * An existing delegated-clients entry is re-pointed in place, its fragment id
+ * preserved verbatim (the id is non-semantic and stable); absent one, a fresh
+ * entry is appended ({@link delegatedClientsServiceEntry}). Every other
+ * service entry, the verification methods, and the relationship arrays are
+ * preserved untouched. Idempotent: a document already pointing at the DID is
+ * a no-op on the log (it still heals a lagging `did.json`).
+ *
+ * @param options {object}
+ * @param options.idStore {WebvhIdStore}   the ACCOUNT log's store
+ * @param options.updateKeys {ClientWebvhUpdateKeys}   this durable client's
+ *   update-key seeds
+ * @param options.companionDid {string}   the generation to point at
+ * @param [options.expectedDid] {string}   the account DID the log must
+ *   resolve to, from the account pointer
+ * @param [options.pinStore] {ResourceLogPinStore}   this client's chain-head
+ *   pins for the account log
+ * @param [options.logId] {string}   the account log's pin-slot key, from
+ *   `accountLogPinId({ spaceId })`; required whenever a `pinStore` is
+ *   supplied
+ * @returns {Promise<{ did: string, doc: DIDDoc }>}
+ */
+export declare function setDelegatedClientsPointer(options: {
+    idStore: WebvhIdStore;
+    updateKeys: ClientWebvhUpdateKeys;
+    companionDid: string;
+    expectedDid?: string;
+    pinStore?: ResourceLogPinStore;
+    logId?: string;
+}): Promise<{
+    did: string;
+    doc: DIDDoc;
+}>;
+/**
+ * The whole transient-enrollment ceremony as the enrollee runs it: resolve
+ * the account document's delegated-clients pointer, enroll the visit's key
+ * into the pointed generation, then RE-READ the pointer -- the GC-race
+ * closure. An enrollment landing between a GC pass's guard check and its
+ * re-point would otherwise yield a session whose generation the pointer then
+ * abandons and whose delegation is already revoked; the enrollee closes the
+ * race with one extra read, re-enrolling into the fresh generation on a
+ * mismatch. Convergent under retry (each round enrolls into whatever the
+ * pointer names NOW), and idempotent per generation like the entry itself.
+ *
+ * @param options {object}
+ * @param options.readAccountDocument {Function}   reads the VERIFIED account
+ *   document (the caller's `verifyAccountLog` read, pins and `expectedDid`
+ *   applied there); called once per round
+ * @param options.storeForSegment {Function}   builds the generation's log
+ *   store for a segment (the delegated store over the credential's sibling
+ *   delegation, or a controller-tier store)
+ * @param options.ladderSeed {Uint8Array}   the credential's ladder seed
+ * @param options.transientKeyMultibase {string}   the visit's in-memory
+ *   signing key, public multibase
+ * @param [options.mintGenerationDelegation] {Function}
+ *   `({ companionDid }) => Promise<IZcap>` -- forwarded to the enrollment
+ *   entry, which installs the minted delegation when it publishes the
+ *   generation's first transient VM (see
+ *   {@link enrollCompanionTransientClient}). The closure receives whichever
+ *   companion DID the round enrolls into, so a GC-race re-enroll mints for
+ *   the fresh generation
+ * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins for the
+ *   generation logs (a transient session passes an in-memory store); slot
+ *   keys are derived per generation with {@link companionLogPinId}
+ * @param [options.maxRounds] {number}   how many pointer moves to chase
+ *   before giving up (a GC pass is quarterly, so more than one mid-ceremony
+ *   move means something else is wrong)
+ * @returns {Promise<{ companionDid: string, doc: DIDDoc, log: DIDLog }>}
+ */
+export declare function enrollTransientClient({ readAccountDocument, storeForSegment, ladderSeed, transientKeyMultibase, mintGenerationDelegation: mintDelegation, pinStore, maxRounds }: {
+    readAccountDocument: () => Promise<DIDDoc>;
+    storeForSegment: (segment: string) => CompanionWriteStore;
+    ladderSeed: Uint8Array;
+    transientKeyMultibase: string;
+    mintGenerationDelegation?: (options: {
+        companionDid: string;
+    }) => Promise<IZcap>;
+    pinStore?: ResourceLogPinStore;
+    maxRounds?: number;
+}): Promise<{
+    companionDid: string;
+    doc: DIDDoc;
+    log: DIDLog;
+}>;
+/**
+ * RENEW PRECEDES MINT: the blocking pre-mint stage a transient App Connect
+ * approval runs before delegating any grant. Reads the companion document
+ * and hands back its embedded generation delegation -- renewing it first
+ * when it is expired or inside the 30-day renewal window ({@link
+ * zcapExpiring}): a fresh delegation is minted through the caller's closure
+ * (ladder-signed -- the renewal must not depend on the very delegation it
+ * replaces; published through the store, which in a transient session is
+ * the credential's sibling delegation, so even a hard-expired delegation is
+ * recoverable), and one companion entry replaces the service entry's
+ * endpoint in place, signed by the writing credential's static rung 0.
+ *
+ * A companion document carrying no delegation entry at all installs one the
+ * same way (the GC ceremony's own install stage and the first-VM install
+ * make this rare; a heal, not a policy).
+ *
+ * Failure is the caller's failure: a renewal that cannot complete throws,
+ * and the App Connect approval fails with the standard retryable-ceremony
+ * posture -- deliberately no clamp-on-failure fallback, which would deliver
+ * exactly the silently short grant this stage exists to prevent. By
+ * construction a grant minted behind a completed renewal never meets the
+ * monotonicity clamp below its full TTL except for 365-day-class grants at
+ * 30 or more days remaining ({@link clampGrantExpires}).
+ *
+ * @param options {object}
+ * @param options.store {CompanionWriteStore}   the generation's log store
+ *   (delegated through the credential's sibling delegation, or
+ *   controller-tier)
+ * @param options.ladderSeed {Uint8Array}   the credential's ladder seed, from
+ *   its unlock record
+ * @param options.segment {string}   the generation collection's name
+ * @param options.mintGenerationDelegation {Function}
+ *   `({ companionDid }) => Promise<IZcap>` -- mints the replacement
+ *   delegation (ladder-signed in a transient session)
+ * @param [options.expectedDid] {string}   the companion DID the log must
+ *   resolve to, from the account document's pointer
+ * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins (a
+ *   transient session passes an in-memory store)
+ * @param [options.logId] {string}   the generation's pin-slot key, from
+ *   {@link companionLogPinId}; required whenever a `pinStore` is supplied
+ * @param [options.now] {number}   epoch milliseconds, for tests
+ * @returns {Promise<{ delegation: IZcap, renewed: boolean }>}
+ */
+export declare function ensureGenerationDelegationCurrent(options: {
+    store: CompanionWriteStore;
+    ladderSeed: Uint8Array;
+    segment: string;
+    mintGenerationDelegation: (options: {
+        companionDid: string;
+    }) => Promise<IZcap>;
+    expectedDid?: string;
+    pinStore?: ResourceLogPinStore;
+    logId?: string;
+    now?: number;
+}): Promise<{
+    delegation: IZcap;
+    renewed: boolean;
+}>;
+//# sourceMappingURL=companion.d.ts.map