@forgesworn/fold-kit 0.10.0 → 0.13.0

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",

package/dist/mls-admission.d.ts

@@ -0,0 +1,79 @@
+import type { UnsignedEvent } from './identity.js';
+export declare const MLS_ADMISSION_LABELS: readonly string[];
+export declare const MLS_ADMISSION_PLAINTEXT_BYTES = 16384;
+export declare const MLS_ADMISSION_CIPHERTEXT_CHARACTERS = 21936;
+/** Evidence only. No admission/capability constructor is exported. */
+export interface VerifiedMlsAdmissionRequest {
+    readonly __verifiedMlsAdmissionRequest: unique symbol;
+}
+export interface VerifiedAdmissionAnswer {
+    readonly __verifiedAdmissionAnswer: unique symbol;
+}
+/** Link fragment only; caller owns CSPRNG generation and secret lifetime. */
+export declare function encodeMlsInvitationV4(root: string, bearer: Uint8Array): string;
+export declare function readMlsInvitationV4(fragment: string): {
+    root: string;
+    bearer: Uint8Array;
+    invitationId: string;
+};
+/** Templates only. Account/device signers remain caller-owned and settle under
+ * the application's actual custody. Returned templates never confer authority.
+ * core is the exact canonical request array or, with request, Allow array. */
+export declare function mlsAdmissionProofTemplatesV4(opts: {
+    fragment: string;
+    core: string;
+    now: number;
+    request?: VerifiedMlsAdmissionRequest;
+}): {
+    pubkey: string;
+    event: UnsignedEvent;
+}[];
+/** proofs is canonical JSON of the three seven-field signed proof arrays. */
+export declare function encodeMlsAdmissionRequestV4(opts: {
+    fragment: string;
+    core: string;
+    proofs: string;
+    requestSecretKey: Uint8Array;
+    now: number;
+}): string;
+/** Either endpoint may decode its exact request; only this decoder issues the
+ * nominal result, after fresh outer/inner checks. Caller secrets are not kept. */
+export declare function decodeMlsAdmissionRequestV4(opts: {
+    fragment: string;
+    event: string;
+    localSecretKey: Uint8Array;
+    side: 'root' | 'joiner';
+    now: number;
+}): VerifiedMlsAdmissionRequest;
+/** Returned strings are copies of evidence, not a rehydration format. */
+export declare function readMlsAdmissionRequestV4(handle: VerifiedMlsAdmissionRequest): Readonly<{
+    core: string;
+    digest: string;
+    eventId: string;
+}>;
+/** Root correlation and signed keeper consent only. This encoder cannot attest
+ * current keeper role; actual vault/box custody and fresh checks stay external. */
+export declare function encodeMlsAdmissionAnswerV4(opts: {
+    fragment: string;
+    request: VerifiedMlsAdmissionRequest;
+    core: string;
+    proofs: string;
+    rootSecretKey: Uint8Array;
+    now: number;
+}): string;
+export declare function decodeMlsAdmissionAnswerV4(opts: {
+    fragment: string;
+    request: VerifiedMlsAdmissionRequest;
+    event: string;
+    requestSecretKey: Uint8Array;
+    now: number;
+}): VerifiedAdmissionAnswer;
+/** Cryptographic evidence only: no usable capability, child or admission. The
+ * application must obtain current role witness and consume the operation once. */
+export declare function readMlsAdmissionAnswerV4(handle: VerifiedAdmissionAnswer): Readonly<{
+    decision: 'allow' | 'deny';
+    core: string;
+    digest: string;
+    eventId: string;
+    requestEventId: string;
+}>;