@forgesworn/fold-kit 0.10.0 → 0.12.0

package/dist/invitation-decline.js

@@ -0,0 +1,74 @@
+import { nip44 } from 'nostr-tools';
+import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
+import { hexEquals, normaliseHex } from './hex.js';
+import { KINDS } from './kinds.js';
+import { deriveInvitationId, verifyInvitationDelegation } from './invitation.js';
+import { verifyEventUncached } from './verify.js';
+export class InvitationDeclinedError extends Error {
+    constructor() {
+        super('Someone in the room declined your request to join.');
+        this.name = 'InvitationDeclinedError';
+    }
+}
+/** A private refusal, carrying no room secret or new responder delegation.
+ * Version 3 distinguishes it from version-2 grants on the same reply kind.
+ * Older readers ignore it and continue their existing bounded wait. */
+export function encodeInvitationDecline(opts) {
+    if (opts.inviterSk.length !== 32)
+        throw new Error('inviter secret key must be 32 bytes');
+    if (!Number.isSafeInteger(opts.now) || opts.now < 0)
+        throw new Error('invalid invitation decline time');
+    if (!/^[0-9a-f]{64}$/i.test(opts.requester) || !/^[0-9a-f]{64}$/i.test(opts.request)) {
+        throw new Error('request and requester must be 32-byte hex');
+    }
+    const responder = getPublicKey(opts.inviterSk);
+    const delegation = opts.delegation ?? [];
+    const authority = verifyInvitationDelegation(opts.invitation, delegation, opts.now);
+    if (authority === null || !hexEquals(authority, responder)) {
+        throw new Error('responder is not delegated for invitation');
+    }
+    const requester = normaliseHex(opts.requester);
+    return finalizeEvent({
+        kind: KINDS.INVITATION_GRANT,
+        created_at: opts.now,
+        tags: [['d', deriveInvitationId(opts.invitation)], ['p', requester]],
+        content: nip44.v2.encrypt(JSON.stringify({
+            v: 3, decision: 'declined', request: normaliseHex(opts.request), delegation,
+        }), nip44.v2.utils.getConversationKey(opts.inviterSk, requester)),
+    }, opts.inviterSk);
+}
+/** Only a fresh, request-bound refusal from the pinned root or a currently
+ * delegated responder can stop this guest's wait. A bearer holder has no
+ * authority to refuse someone else. No room capability is returned. */
+export function decodeInvitationDecline(event, opts) {
+    try {
+        const age = opts.maxAgeSeconds ?? 90;
+        if (!Number.isSafeInteger(opts.now) || opts.now < 0 || !Number.isSafeInteger(age) || age < 0)
+            return null;
+        if (event.kind !== KINDS.INVITATION_GRANT || !verifyEventUncached(event))
+            return null;
+        if (!Number.isSafeInteger(event.created_at) || event.created_at < 0 || Math.abs(opts.now - event.created_at) > age)
+            return null;
+        const rendezvous = event.tags.filter(t => t[0] === 'd');
+        const addressed = event.tags.filter(t => t[0] === 'p');
+        if (rendezvous.length !== 1 || rendezvous[0]?.[1] !== deriveInvitationId(opts.invitation))
+            return null;
+        const requester = getPublicKey(opts.requesterSk);
+        if (addressed.length !== 1 || !hexEquals(addressed[0]?.[1] ?? '', requester))
+            return null;
+        const body = JSON.parse(nip44.v2.decrypt(event.content, nip44.v2.utils.getConversationKey(opts.requesterSk, event.pubkey)));
+        if (!body || body.v !== 3 || body.decision !== 'declined')
+            return null;
+        if (typeof body.request !== 'string' || !/^[0-9a-f]{64}$/i.test(body.request) || !hexEquals(body.request, opts.request))
+            return null;
+        if ('secret' in body || !Array.isArray(body.delegation))
+            return null;
+        const authority = verifyInvitationDelegation(opts.invitation, body.delegation, opts.now);
+        if (authority === null || !hexEquals(authority, event.pubkey))
+            return null;
+        return { request: normaliseHex(body.request), responder: normaliseHex(event.pubkey) };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/invitation.d.ts

@@ -1,5 +1,7 @@
 import { type Event } from 'nostr-tools/pure';
 import type { RelayTransport } from './transport.js';
+import type { ParticipantIdentity } from './identity.js';
+import { type ReplyDelayRange, type ReplySchedule } from './quiet-reply.js';
 /** A delegated responder cannot silently make its authority permanent. */
 export declare const INVITATION_DELEGATION_TTL_SECONDS: number;
 /** Bounds both verification work and the size of a grant from a hostile peer. */
@@ -73,13 +75,31 @@ export interface EncodeInvitationRequestOptions {
     now: number;
     name?: string;
     participant?: string;
+    /** Account-signed proof bound to this invitation, request device and time.
+     *  The proof stays inside the bearer-encrypted request, never a public relay
+     *  event. Without it, `participant` remains an unverified claim. */
+    accountProof?: Event;
 }
+export interface EncodeInvitationAccountProofOptions {
+    invitation: RoomInvitation;
+    device: string;
+    identity: ParticipantIdentity;
+    now: number;
+}
+/** Prove control of an account for one ephemeral admission device. This is
+ * deliberately separate from a room device credential: a guest does not yet
+ * know the room or its traffic key, and this proof grants neither. */
+export declare function encodeInvitationAccountProof(opts: EncodeInvitationAccountProofOptions): Promise<Event>;
 /** Who is asking, as decoded from a request. */
 export interface InvitationRequest {
     device: string;
     request: string;
     name?: string;
     participant?: string;
+    /** Present only after fresh signature verification of an account proof
+     *  bound to this exact invitation, request-signing device and timestamp.
+     *  Never authorise automatic admission from `participant` alone. */
+    verifiedParticipant?: string;
 }
 /** Prove possession of the bearer without putting it, or a traffic key, on a relay. */
 export declare function encodeInvitationRequest(opts: EncodeInvitationRequestOptions): Event;
@@ -144,7 +164,8 @@ export interface HostRoomInvitationOptions {
     onAdmitted?: (device: string) => void;
     /** The same publication acknowledgement, correlated to the request. */
     onGrantPublished?: (request: InvitationRequest) => void;
-    /** Publication rejected or threw. No admission callback is made. */
+    /** A publication attempt failed, or approval came after request expiry.
+     * A valid retry may recover; no admission callback follows a failed send. */
     onGrantFailed?: (request: InvitationRequest, error: unknown) => void;
     /** Called when the creator's durable retirement tombstone is heard. */
     onRetired?: () => void;
@@ -152,7 +173,7 @@ export interface HostRoomInvitationOptions {
      *  moves. Omit to say nothing, which a joiner treats as unknown. */
     epoch?: () => number;
     /**
-     * Asked before every grant, when present. Return true to let the
+     * Asked once per fresh signed request, when present. Return true to let the
      * request in, false to leave it unanswered: there is no refusal on the
      * wire, so a declined person sees the room not answer, which is the same
      * as nobody being home. A request is asked about once, whatever its
@@ -161,6 +182,30 @@ export interface HostRoomInvitationOptions {
      * room's link has always meant.
      */
     admit?: (request: InvitationRequest) => boolean | Promise<boolean>;
+    /**
+     * Wait a random time in this range, in milliseconds, before publishing
+     * each grant, after `admit` when there is one. Absent, a grant goes out
+     * as soon as it is decided, as it always has (or after
+     * `DEFAULT_REPLY_DELAY_MS` when `coordinate` is set). For a device that
+     * answers automatically: an instant answer under the same key tells
+     * whoever holds the link when that device is online.
+     */
+    grantDelayMs?: ReplyDelayRange;
+    /**
+     * Several of the room's devices answer the same link: wait first, and
+     * stand down if another responder's grant to the same requester appears
+     * during the wait, so normally one device answers. Waits
+     * `grantDelayMs`, default `[500, 2000]`. A grant is seen by its public
+     * tags only, so anyone holding the link could post a false one; this
+     * responder stands down at most once per request, and answers the
+     * requester's next retry. Absent or false, nothing changes and no extra
+     * subscription is opened.
+     */
+    coordinate?: boolean;
+    /** For tests: a source of numbers in [0, 1). Default `Math.random`. */
+    random?: () => number;
+    /** For tests: how the wait is timed. Default `setTimeout`. */
+    schedule?: ReplySchedule;
 }
 export interface EncodeInvitationRetirementOptions {
     invitation: RoomInvitation;
@@ -219,10 +264,15 @@ export interface RequestRoomAdmissionOptions {
     /** Carried in the request for a host who asks before letting people in. */
     name?: string;
     participant?: string;
+    /** Optional proof of the claimed account, made by this matching identity.
+     *  A signer error is a failed request, never a switch to another account. */
+    identity?: ParticipantIdentity;
+    signal?: AbortSignal;
 }
-/** Resolve the room and a bounded responder delegation, with no account or
- * prompt. Retaining the delegation is what removes the creator as an
- * availability dependency for the next arrival. */
+/** Resolve the room and a bounded responder delegation. Anonymous requests
+ * need no account. Supplying an identity signs a proof for this request; its
+ * signer may ask the person to approve. Retaining the delegation removes the
+ * creator as an availability dependency for the next arrival. */
 export declare function requestRoomAdmissionCapability(opts: RequestRoomAdmissionOptions): Promise<RoomAdmission>;
 /** Compatibility wrapper for non-interactive consumers. It joins correctly,
  * but discards the ability to keep the link available for somebody else. */
@@ -231,4 +281,4 @@ export declare function requestRoomAdmission(opts: RequestRoomAdmissionOptions):
  *  `src/labels.test.ts`, which checks each module against its own exported
  *  list rather than scanning file text for matching comments. Pure data -
  *  adding this export changes no runtime behaviour. */
-export declare const INVITATION_LABELS: readonly ["kithmoot/v2/invitation-delegation:", "kithmoot/v2/invitation-id", "kithmoot/v2/invitation-request-key"];
+export declare const INVITATION_LABELS: readonly ["kithmoot/v2/invitation-account-proof", "kithmoot/v2/invitation-delegation:", "kithmoot/v2/invitation-id", "kithmoot/v2/invitation-request-key"];

package/dist/invitation.js

@@ -10,8 +10,11 @@ import { KINDS } from './kinds.js';
 import { verifyEventUncached } from './verify.js';
 import { withExpiration } from './expiration.js';
 import { deriveRoom } from './room.js';
+import { decodeInvitationDecline, InvitationDeclinedError } from './invitation-decline.js';
+import { DEFAULT_REPLY_DELAY_MS, defaultReplySchedule, replyDelay } from './quiet-reply.js';
 const INVITATION_ID_INFO = 'kithmoot/v2/invitation-id';
 const INVITATION_REQUEST_KEY_INFO = 'kithmoot/v2/invitation-request-key';
+const INVITATION_ACCOUNT_PROOF = 'kithmoot/v2/invitation-account-proof';
 const INVITATION_MAX_AGE_SECONDS = 90;
 const DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_RETRY_MS = 2_000;
@@ -56,6 +59,40 @@ function requestKey(invitation) {
 /** How much of a name an admission request carries. The same bound as a
  *  display name on the roster. */
 const MAX_REQUEST_NAME_LENGTH = 64;
+/** Prove control of an account for one ephemeral admission device. This is
+ * deliberately separate from a room device credential: a guest does not yet
+ * know the room or its traffic key, and this proof grants neither. */
+export async function encodeInvitationAccountProof(opts) {
+    if (!Number.isSafeInteger(opts.now) || opts.now < 0)
+        throw new Error('invalid invitation account proof time');
+    const device = requirePubkey(opts.device), participant = requirePubkey(opts.identity.pubkey);
+    const proof = await opts.identity.signEvent({
+        kind: KINDS.INVITATION_REQUEST,
+        created_at: opts.now,
+        tags: [['t', INVITATION_ACCOUNT_PROOF], ['d', deriveInvitationId(opts.invitation)], ['p', requirePubkey(opts.invitation.inviter)]],
+        content: JSON.stringify({ v: 1, device }),
+    });
+    if (!accountProofMatches(proof, { invitation: opts.invitation, device, participant, now: opts.now }))
+        throw new Error('invalid invitation account proof from signer');
+    return proof;
+}
+function accountProofMatches(raw, opts) {
+    try {
+        if (!raw || typeof raw !== 'object' || !opts.participant)
+            return false;
+        const proof = raw;
+        if (proof.kind !== KINDS.INVITATION_REQUEST || proof.created_at !== opts.now || !hexEquals(proof.pubkey, opts.participant))
+            return false;
+        if (JSON.stringify(proof.tags) !== JSON.stringify([['t', INVITATION_ACCOUNT_PROOF], ['d', deriveInvitationId(opts.invitation)], ['p', requirePubkey(opts.invitation.inviter)]]))
+            return false;
+        if (proof.content !== JSON.stringify({ v: 1, device: requirePubkey(opts.device) }))
+            return false;
+        return verifyEventUncached(proof);
+    }
+    catch {
+        return false;
+    }
+}
 /** Prove possession of the bearer without putting it, or a traffic key, on a relay. */
 export function encodeInvitationRequest(opts) {
     require32(opts.requesterSk, 'requester secret key');
@@ -66,6 +103,11 @@ export function encodeInvitationRequest(opts) {
         body.name = name;
     if (opts.participant !== undefined)
         body.participant = requirePubkey(opts.participant);
+    if (opts.accountProof !== undefined) {
+        if (!accountProofMatches(opts.accountProof, { invitation: opts.invitation, device, participant: body.participant, now: opts.now }))
+            throw new Error('invalid invitation account proof');
+        body.accountProof = opts.accountProof;
+    }
     return finalizeEvent({
         kind: KINDS.INVITATION_REQUEST,
         created_at: opts.now,
@@ -105,6 +147,8 @@ export function decodeInvitationRequest(event, opts) {
         }
         if (typeof body.participant === 'string' && /^[0-9a-f]{64}$/i.test(body.participant))
             decoded.participant = body.participant.toLowerCase();
+        if (accountProofMatches(body.accountProof, { invitation: opts.invitation, device: decoded.device, participant: decoded.participant, now: event.created_at }))
+            decoded.verifiedParticipant = decoded.participant;
         return decoded;
     }
     catch {
@@ -339,16 +383,38 @@ export function hostRoomInvitation(opts) {
     }
     const responder = getPublicKey(opts.inviterSk);
     const invitationId = deriveInvitationId(opts.invitation);
-    const answered = new Set();
+    // Keep each live decision, including refusals and pending approval, until
+    // its authenticated request expires. Evicting a live entry could re-prompt
+    // or mint fresh authority for the same signed request.
+    const requests = new Map();
+    const delayRange = opts.grantDelayMs ?? (opts.coordinate ? DEFAULT_REPLY_DELAY_MS : undefined);
+    const random = opts.random ?? Math.random;
+    const schedule = opts.schedule ?? defaultReplySchedule;
+    /** Grants waiting out their delay, each as how to cancel it. */
+    const waits = new Set();
+    /** Requesting devices another responder's grant was seen for since their
+     *  request reached this one. Only with `coordinate`. */
+    const grantSeen = new Set();
+    const bound = (set) => {
+        if (set.size > 256)
+            set.delete(set.values().next().value);
+    };
     let closed = false;
     let unsubRequests = () => { };
     let unsubRetirement = () => { };
+    let unsubGrants = () => { };
     const close = () => {
         if (closed)
             return;
         closed = true;
+        for (const cancel of waits)
+            cancel();
+        waits.clear();
+        requests.clear();
+        grantSeen.clear();
         unsubRequests();
         unsubRetirement();
+        unsubGrants();
     };
     // Subscribe to the durable tombstone before accepting requests. Real
     // relays replay stored regular events, so a responder returning from an
@@ -363,26 +429,74 @@ export function hostRoomInvitation(opts) {
         unsubRetirement();
         return { close };
     }
+    if (opts.coordinate) {
+        unsubGrants = opts.transport.subscribe([{ kinds: [KINDS.INVITATION_GRANT], '#d': [invitationId] }], (event) => {
+            if (closed || hexEquals(event.pubkey, responder))
+                return;
+            const to = event.tags.find((t) => t[0] === 'p')?.[1];
+            if (to === undefined || !/^[0-9a-f]{64}$/i.test(to))
+                return;
+            grantSeen.add(normaliseHex(to));
+            bound(grantSeen);
+        });
+    }
     unsubRequests = opts.transport.subscribe([{ kinds: [KINDS.INVITATION_REQUEST], '#d': [invitationId], '#p': [opts.invitation.inviter] }], (event) => {
         if (closed)
             return;
         const request = decodeInvitationRequest(event, { invitation: opts.invitation, now: now() });
         // Some relays incorrectly retain and replay ephemeral requests. A newly
         // admitted delegate must not answer the request that admitted itself.
-        if (!request || hexEquals(request.device, responder) || answered.has(request.request))
+        if (!request || hexEquals(request.device, responder))
+            return;
+        const existing = requests.get(request.request);
+        if (existing) {
+            existing.retry();
             return;
-        answered.add(request.request);
-        // A long-running public room must not grow this replay guard without
-        // bound. Duplicate requests are harmless after eviction: they only
-        // cause the same encrypted grant to be sent again.
-        if (answered.size > 256)
-            answered.delete(answered.values().next().value);
+        }
+        const at = now();
+        for (const [id, state] of requests) {
+            if (state.idle() && at - state.createdAt > INVITATION_MAX_AGE_SECONDS)
+                requests.delete(id);
+        }
+        // Saturation refuses new work rather than forgetting a live decision.
+        if (requests.size >= 256)
+            return;
+        let approved = !opts.admit;
+        let deciding = !approved;
+        let busy = false;
+        let stoodDown = false;
+        let acknowledged = false;
+        let grant;
+        const state = { createdAt: event.created_at, idle: () => !deciding && !busy, retry: () => { if (approved && !busy)
+                grantLater(); } };
+        requests.set(request.request, state);
+        grantSeen.delete(normaliseHex(request.device));
+        const current = () => !closed && requests.get(request.request) === state;
+        const fresh = () => {
+            if (!current())
+                return false;
+            if (!decodeInvitationRequest(event, { invitation: opts.invitation, now: now() })) {
+                try {
+                    opts.onGrantFailed?.(request, new Error('the invitation request expired before admission'));
+                }
+                catch { /* Observer only. */ }
+                return false;
+            }
+            // Reusing a signed grant must not extend the responder's authority.
+            const authority = verifyInvitationDelegation(opts.invitation, delegation, now());
+            if (authority === null || !hexEquals(authority, responder)) {
+                close();
+                return false;
+            }
+            return true;
+        };
         const grantNow = () => {
-            if (closed)
+            if (!fresh()) {
+                busy = false;
                 return;
-            let grant;
+            }
             try {
-                grant = encodeInvitationGrant({
+                grant ??= encodeInvitationGrant({
                     invitation: opts.invitation,
                     inviterSk: opts.inviterSk,
                     requester: request.device,
@@ -399,16 +513,17 @@ export function hostRoomInvitation(opts) {
                 close();
                 return;
             }
-            // The decision to approve and the publication of its grant are
-            // separate states. A rejected send must never look like admission.
+            // The first ephemeral grant may precede the guest's subscription.
+            // A retry sends this exact envelope, never new delegation or approval.
             Promise.resolve()
-                .then(() => { if (!closed)
-                return opts.transport.publish(grant); })
-                .then(() => {
-                if (closed)
+                .then(async () => {
+                if (!fresh())
                     return;
-                // One observer throwing must not change the publish outcome or
-                // prevent an independent observer from hearing it.
+                await opts.transport.publish(grant);
+                if (!current() || acknowledged)
+                    return;
+                acknowledged = true;
+                // Observer acknowledgement is once per request, not per retry.
                 try {
                     opts.onGrantPublished?.(request);
                 }
@@ -417,64 +532,78 @@ export function hostRoomInvitation(opts) {
                     opts.onAdmitted?.(request.device);
                 }
                 catch { /* Observer only. */ }
-            }, error => {
-                if (!closed)
-                    opts.onGrantFailed?.(request, error);
             })
-                .catch(() => { });
+                .catch(error => {
+                if (current()) {
+                    try {
+                        opts.onGrantFailed?.(request, error);
+                    }
+                    catch { /* Observer only. */ }
+                }
+            })
+                .finally(() => { busy = false; });
         };
-        if (!opts.admit) {
+        const grantAfterWait = () => {
+            if (!fresh()) {
+                busy = false;
+                return;
+            }
+            if (opts.coordinate && grantSeen.has(normaliseHex(request.device)) && !stoodDown) {
+                // Stand down at most once. The retry retains the original approval.
+                stoodDown = true;
+                busy = false;
+                return;
+            }
             grantNow();
+        };
+        const grantLater = () => {
+            if (!current() || busy)
+                return;
+            busy = true;
+            const delay = delayRange ? replyDelay(delayRange, random) : 0;
+            if (delay === 0) {
+                grantAfterWait();
+                return;
+            }
+            if (waits.size >= 256) {
+                busy = false;
+                return;
+            }
+            let cancel = () => { };
+            let done = false;
+            cancel = schedule(() => { done = true; waits.delete(cancel); grantAfterWait(); }, delay);
+            if (!done)
+                waits.add(cancel);
+        };
+        if (approved) {
+            grantLater();
             return;
         }
-        // A host that asks first answers later, if at all. Never awaited in
-        // the relay callback, and a hook that throws declines.
+        // Pending and declined decisions stay cached. Duplicates cannot ask
+        // again, race approval, or publish before the original decision.
         Promise.resolve()
-            .then(() => opts.admit(request))
-            .then((yes) => { if (yes)
-            grantNow(); })
-            .catch(() => { });
+            .then(() => current() ? opts.admit(request) : false)
+            .then((yes) => { deciding = false; if (yes && current()) {
+            approved = true;
+            grantLater();
+        } })
+            .catch(() => { deciding = false; });
     });
     return { close };
 }
-/** Resolve the room and a bounded responder delegation, with no account or
- * prompt. Retaining the delegation is what removes the creator as an
- * availability dependency for the next arrival. */
+/** Resolve the room and a bounded responder delegation. Anonymous requests
+ * need no account. Supplying an identity signs a proof for this request; its
+ * signer may ask the person to approve. Retaining the delegation removes the
+ * creator as an availability dependency for the next arrival. */
 export function requestRoomAdmissionCapability(opts) {
     const now = opts.now ?? (() => Math.floor(Date.now() / 1000));
-    const requesterSk = opts.requesterSk ?? generateSecretKey();
-    const requester = getPublicKey(requesterSk);
-    const request = encodeInvitationRequest({
-        invitation: opts.invitation, requesterSk, now: now(),
-        ...(opts.name !== undefined ? { name: opts.name } : {}),
-        ...(opts.participant !== undefined ? { participant: opts.participant } : {}),
-    });
     return new Promise((resolve, reject) => {
         let settled = false;
+        let ownedKey;
+        let request;
         let retry;
         let expiry;
-        const invitationId = deriveInvitationId(opts.invitation);
         let unsub = () => { };
-        unsub = opts.transport.subscribe([
-            { kinds: [KINDS.INVITATION_GRANT], '#d': [invitationId], '#p': [requester] },
-            { kinds: [KINDS.INVITATION_RETIREMENT], '#d': [invitationId], authors: [opts.invitation.inviter] },
-        ], (event) => {
-            const retired = decodeInvitationRetirementNotice(event, opts.invitation);
-            if (retired) {
-                finish(() => reject(retirementError(retired)));
-                return;
-            }
-            const admission = decodeRoomAdmissionGrant(event, {
-                invitation: opts.invitation,
-                requesterSk,
-                request: request.id,
-                now: now(),
-            });
-            if (admission)
-                finish(() => resolve(admission));
-        });
-        if (settled)
-            unsub();
         function finish(settle) {
             if (settled)
                 return;
@@ -483,16 +612,108 @@ export function requestRoomAdmissionCapability(opts) {
                 clearInterval(retry);
             if (expiry !== undefined)
                 clearTimeout(expiry);
-            unsub();
+            opts.signal?.removeEventListener('abort', abort);
+            try {
+                unsub();
+            }
+            catch { /* A broken observer cannot keep the request live. */ }
+            ownedKey?.fill(0);
             settle();
         }
+        function abort() {
+            const error = new Error('invitation request cancelled');
+            error.name = 'AbortError';
+            finish(() => reject(error));
+        }
         function ask() {
-            if (!settled)
-                opts.transport.publish(request).catch(() => { });
+            if (!settled && request) {
+                // Keep the same signed request on retries; a late publish result
+                // never revives a cancelled or expired exchange.
+                try {
+                    void opts.transport.publish(request).catch(() => { });
+                }
+                catch { /* Retried within the same deadline. */ }
+            }
+        }
+        try {
+            if (opts.signal?.aborted) {
+                abort();
+                return;
+            }
+            const requestedTimeout = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS, retryMs = opts.retryMs ?? DEFAULT_RETRY_MS;
+            if (!Number.isFinite(requestedTimeout) || requestedTimeout <= 0 || !Number.isFinite(retryMs) || retryMs <= 0)
+                throw new Error('invalid invitation request timing');
+            const participant = opts.participant === undefined
+                ? (opts.identity ? requirePubkey(opts.identity.pubkey) : undefined)
+                : requirePubkey(opts.participant);
+            if (opts.identity && (!participant || !hexEquals(requirePubkey(opts.identity.pubkey), participant)))
+                throw new Error('invitation account does not match the requested participant');
+            // Clone caller-owned keys before asynchronous signing, and erase only
+            // our copy on every outcome. The caller retains ownership of its key.
+            if (opts.requesterSk)
+                require32(opts.requesterSk, 'requester secret key');
+            ownedKey = opts.requesterSk?.slice() ?? generateSecretKey();
+            const requester = getPublicKey(ownedKey), invitationId = deriveInvitationId(opts.invitation), requestedAt = now();
+            if (!Number.isSafeInteger(requestedAt) || requestedAt < 0)
+                throw new Error('invalid invitation request time');
+            // Signing and relay waiting share one deadline, no longer than the
+            // request's authenticated freshness window. Approval does not renew it.
+            expiry = setTimeout(() => finish(() => reject(new Error(opts.identity && !request
+                ? 'the account did not finish signing the invitation request'
+                : 'the room is not answering this invitation'))), Math.min(requestedTimeout, INVITATION_MAX_AGE_SECONDS * 1000));
+            opts.signal?.addEventListener('abort', abort, { once: true });
+            if (opts.signal?.aborted) {
+                abort();
+                return;
+            }
+            unsub = opts.transport.subscribe([
+                { kinds: [KINDS.INVITATION_GRANT], '#d': [invitationId], '#p': [requester] },
+                { kinds: [KINDS.INVITATION_RETIREMENT], '#d': [invitationId], authors: [opts.invitation.inviter] },
+            ], event => {
+                if (settled)
+                    return;
+                const retired = decodeInvitationRetirementNotice(event, opts.invitation);
+                if (retired) {
+                    finish(() => reject(retirementError(retired)));
+                    return;
+                }
+                if (!request)
+                    return;
+                const declined = decodeInvitationDecline(event, { invitation: opts.invitation, requesterSk: ownedKey, request: request.id, now: now() });
+                if (declined) {
+                    finish(() => reject(new InvitationDeclinedError()));
+                    return;
+                }
+                const admission = decodeRoomAdmissionGrant(event, { invitation: opts.invitation, requesterSk: ownedKey, request: request.id, now: now() });
+                if (admission) {
+                    // The delegation owns its responder key after admission. Erasing
+                    // our exchange key must not erase that independently retained key.
+                    const retained = { ...admission, delegate: { ...admission.delegate, delegateSk: admission.delegate.delegateSk.slice() } };
+                    finish(() => resolve(retained));
+                }
+            });
+            if (settled) {
+                unsub();
+                return;
+            }
+            const prepare = async () => {
+                const accountProof = opts.identity ? await encodeInvitationAccountProof({ invitation: opts.invitation, device: requester, identity: opts.identity, now: requestedAt }) : undefined;
+                if (settled)
+                    return;
+                const at = now();
+                if (!Number.isSafeInteger(at) || Math.abs(at - requestedAt) > INVITATION_MAX_AGE_SECONDS)
+                    throw new Error('the invitation request expired while signing');
+                request = encodeInvitationRequest({ invitation: opts.invitation, requesterSk: ownedKey, now: requestedAt,
+                    ...(opts.name !== undefined ? { name: opts.name } : {}), ...(participant !== undefined ? { participant } : {}),
+                    ...(accountProof ? { accountProof } : {}) });
+                retry = setInterval(ask, retryMs);
+                ask();
+            };
+            void prepare().catch(error => finish(() => reject(error)));
+        }
+        catch (error) {
+            finish(() => reject(error));
         }
-        expiry = setTimeout(() => finish(() => reject(new Error('the room is not answering this invitation'))), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
-        retry = setInterval(ask, opts.retryMs ?? DEFAULT_RETRY_MS);
-        ask();
     });
 }
 /** Compatibility wrapper for non-interactive consumers. It joins correctly,
@@ -505,6 +726,7 @@ export async function requestRoomAdmission(opts) {
  *  list rather than scanning file text for matching comments. Pure data -
  *  adding this export changes no runtime behaviour. */
 export const INVITATION_LABELS = [
+    "kithmoot/v2/invitation-account-proof",
     "kithmoot/v2/invitation-delegation:",
     "kithmoot/v2/invitation-id",
     "kithmoot/v2/invitation-request-key",