@forgesworn/fold-kit 0.10.0 → 0.13.0

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export type { DeviceCredential, AccessTier, AgentRule, RoomPolicy, KindredProof
 export type { RelayTransport } from './transport.js';
 export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, RestampedCredentialExpiryError, } from './credential.js';
 export type { CreateCredentialOptions, VerifyResult } from './credential.js';
-export { SEAL_TAG, isSealPubkey, generateSealKey, credentialSeal, sealTarget, sealTo, openSealed, newerCredential, } from './seal.js';
+export { SEAL_TAG, SENDER_TAG, sealSender, isSealPubkey, generateSealKey, credentialSeal, sealTarget, sealTo, openSealed, newerCredential, } from './seal.js';
 export type { SealKey } from './seal.js';
 export { deriveScoped, SCOPED_LABEL_PATTERN } from './scoped.js';
 export type { ScopedKeys } from './scoped.js';
@@ -18,8 +18,10 @@ export { MAX_RELAY_HINTS, MAX_ICE_HINTS, MAX_NETWORK_HINT_LENGTH, isSafeRelayUrl
 export { sanitiseDisplayName, MAX_DISPLAY_NAME_LENGTH } from './display-name.js';
 export { issueKindredProof, evaluateAccess, ACCESS_LABELS, } from './access.js';
 export type { IssueKindredProofOptions } from './access.js';
-export { INVITATION_DELEGATION_TTL_SECONDS, MAX_INVITATION_DELEGATION_DEPTH, createRoomInvitation, roomInvitation, deriveInvitationId, encodeInvitationRequest, decodeInvitationRequest, verifyInvitationDelegation, encodeInvitationGrant, decodeRoomAdmissionGrant, decodeInvitationGrant, ROOM_ENDED_MESSAGE, encodeInvitationRetirement, decodeInvitationRetirement, decodeInvitationRetirementNotice, retirementError, hostRoomInvitation, requestRoomAdmissionCapability, requestRoomAdmission, INVITATION_LABELS, } from './invitation.js';
-export type { RoomInvitation, RoomInvitationHost, InvitationDelegation, RoomInvitationDelegate, RoomAdmission, EncodeInvitationRequestOptions, InvitationRequest, DecodeInvitationRequestOptions, EncodeInvitationGrantOptions, DecodeInvitationGrantOptions, HostRoomInvitationOptions, EncodeInvitationRetirementOptions, RequestRoomAdmissionOptions, } from './invitation.js';
+export { INVITATION_DELEGATION_TTL_SECONDS, MAX_INVITATION_DELEGATION_DEPTH, createRoomInvitation, roomInvitation, deriveInvitationId, encodeInvitationAccountProof, encodeInvitationRequest, decodeInvitationRequest, verifyInvitationDelegation, encodeInvitationGrant, decodeRoomAdmissionGrant, decodeInvitationGrant, ROOM_ENDED_MESSAGE, encodeInvitationRetirement, decodeInvitationRetirement, decodeInvitationRetirementNotice, retirementError, hostRoomInvitation, requestRoomAdmissionCapability, requestRoomAdmission, INVITATION_LABELS, } from './invitation.js';
+export type { RoomInvitation, RoomInvitationHost, InvitationDelegation, RoomInvitationDelegate, RoomAdmission, EncodeInvitationAccountProofOptions, EncodeInvitationRequestOptions, InvitationRequest, DecodeInvitationRequestOptions, EncodeInvitationGrantOptions, DecodeInvitationGrantOptions, HostRoomInvitationOptions, EncodeInvitationRetirementOptions, RequestRoomAdmissionOptions, } from './invitation.js';
+export { encodeInvitationDecline, decodeInvitationDecline, InvitationDeclinedError } from './invitation-decline.js';
+export type { EncodeInvitationDeclineOptions, InvitationDecline } from './invitation-decline.js';
 export { encodePersistentInvitation, decodePersistentInvitation, requestPersistentRoomAdmission, PERSISTENT_INVITATION_LABELS, } from './persistent-invitation.js';
 export type { PersistentRoomAdmission } from './persistent-invitation.js';
 export { withExpiration, isRoomEnds, requireRoomEnds, MAX_ROOM_ENDS_SECONDS } from './expiration.js';
@@ -28,6 +30,8 @@ export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from '.
 export type { RoomLink } from './link.js';
 export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, decodeRekeyEvent, HISTORY_WINDOW_SECONDS, MAX_HISTORY_EPOCHS, epochsInWindow, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, sealCredential, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
 export type { RoomEpoch, EpochKeys, EncodeRekeyOptions, RekeyRecipient, RekeyNotice, PeekRekeyOptions, DecodeRekeyOptions, LeftEpoch, EpochRequestAdmissionOptions, EncodeEpochRequestOptions, DecodeEpochRequestOptions, EpochRequest, EpochRefusal, EncodeEpochGrantOptions, DecodeEpochGrantOptions, EpochGrant, HostRoomEpochOptions, RequestRoomEpochOptions, SignAdminsOptions, SignChannelsOptions, VerifyChannelsOptions, VerifyAdminsOptions, } from './epoch.js';
+export { DEFAULT_REPLY_DELAY_MS, REFUSE_AGAIN_AFTER_SECONDS, MAX_REFUSALS_PER_MINUTE, REFUSAL_LIMITER_CAPACITY, RefusalLimiter, replyDelay, } from './quiet-reply.js';
+export type { ReplyDelayRange, ReplySchedule, RefusalLimiterOptions } from './quiet-reply.js';
 export { EPOCH_COMMIT_PREFIX, epochCommitment, EPOCH_COMMIT_LABELS } from './epoch-commit.js';
 export { MEMBER_EPOCH_KINDS, MEMBER_EPOCH_REQUEST_KEY_INFO, MAX_MEMBER_EPOCH_CHAIN, deriveMemberEpochRequestKey, readRekeyEvidence, encodeMemberEpochRequest, decodeMemberEpochRequest, encodeMemberEpochGrant, decodeMemberEpochGrant, hostMemberEpochDesk, memberEpochSource, requestMemberEpoch, MEMBER_EPOCH_LABELS, } from './member-epoch.js';
 export type { RekeyEvidence, EncodeMemberEpochRequestOptions, DecodeMemberEpochRequestOptions, MemberEpochRequest, EncodeMemberEpochGrantOptions, DecodeMemberEpochGrantOptions, MemberEpochGrant, HostMemberEpochDeskOptions, MemberEpochRequestOptions, MemberEpochSource, } from './member-epoch.js';

package/dist/index.js

@@ -5,19 +5,21 @@ export { verifyEventUncached, boundedEventVerifier } from './verify.js';
 export { localIdentity } from './identity.js';
 export { KINDS } from './kinds.js';
 export { createDeviceCredential, verifyDeviceCredential, PERSON_CREDENTIAL_MAX_SECONDS, RestampedCredentialExpiryError, } from './credential.js';
-export { SEAL_TAG, isSealPubkey, generateSealKey, credentialSeal, sealTarget, sealTo, openSealed, newerCredential, } from './seal.js';
+export { SEAL_TAG, SENDER_TAG, sealSender, isSealPubkey, generateSealKey, credentialSeal, sealTarget, sealTo, openSealed, newerCredential, } from './seal.js';
 export { deriveScoped, SCOPED_LABEL_PATTERN } from './scoped.js';
 export { createSubKeyCertificate, verifySubKeyCertificate, SUB_KEY_CERTIFICATE_SCOPE, } from './sub-cert.js';
 export { generateRoomSecret, deriveRoom, encodeJoinUrl, decodeJoinUrl, parseRoomPolicy, ROOM_LABELS, } from './room.js';
 export { MAX_RELAY_HINTS, MAX_ICE_HINTS, MAX_NETWORK_HINT_LENGTH, isSafeRelayUrl, safeRelayUrls, isSafeIceUrl, safeIceUrls, assertNetworkHintBounds, } from './network-hints.js';
 export { sanitiseDisplayName, MAX_DISPLAY_NAME_LENGTH } from './display-name.js';
 export { issueKindredProof, evaluateAccess, ACCESS_LABELS, } from './access.js';
-export { INVITATION_DELEGATION_TTL_SECONDS, MAX_INVITATION_DELEGATION_DEPTH, createRoomInvitation, roomInvitation, deriveInvitationId, encodeInvitationRequest, decodeInvitationRequest, verifyInvitationDelegation, encodeInvitationGrant, decodeRoomAdmissionGrant, decodeInvitationGrant, ROOM_ENDED_MESSAGE, encodeInvitationRetirement, decodeInvitationRetirement, decodeInvitationRetirementNotice, retirementError, hostRoomInvitation, requestRoomAdmissionCapability, requestRoomAdmission, INVITATION_LABELS, } from './invitation.js';
+export { INVITATION_DELEGATION_TTL_SECONDS, MAX_INVITATION_DELEGATION_DEPTH, createRoomInvitation, roomInvitation, deriveInvitationId, encodeInvitationAccountProof, encodeInvitationRequest, decodeInvitationRequest, verifyInvitationDelegation, encodeInvitationGrant, decodeRoomAdmissionGrant, decodeInvitationGrant, ROOM_ENDED_MESSAGE, encodeInvitationRetirement, decodeInvitationRetirement, decodeInvitationRetirementNotice, retirementError, hostRoomInvitation, requestRoomAdmissionCapability, requestRoomAdmission, INVITATION_LABELS, } from './invitation.js';
+export { encodeInvitationDecline, decodeInvitationDecline, InvitationDeclinedError } from './invitation-decline.js';
 export { encodePersistentInvitation, decodePersistentInvitation, requestPersistentRoomAdmission, PERSISTENT_INVITATION_LABELS, } from './persistent-invitation.js';
 export { withExpiration, isRoomEnds, requireRoomEnds, MAX_ROOM_ENDS_SECONDS } from './expiration.js';
 export { isInvitationRelays, requireInvitationRelays, MAX_INVITATION_RELAYS } from './invitation-relays.js';
 export { MAX_ROOM_LINK_FRAGMENT_LENGTH, parseRoomLink, encodeRoomLink, } from './link.js';
 export { EPOCH_ID_INFO, EPOCH_KEY_INFO, MAX_EPOCH, EPOCH_REQUEST_KEY_INFO, generateEpochSecret, deriveEpoch, encodeRekeyEvent, peekRekeyEvent, readMemberList, REPORT_UNKNOWN_EVERY_SECONDS, decodeRekeyEvent, HISTORY_WINDOW_SECONDS, MAX_HISTORY_EPOCHS, epochsInWindow, deriveEpochRequestKey, epochRequestAdmission, encodeEpochRequest, decodeEpochRequest, encodeEpochGrant, decodeEpochGrant, hostRoomEpoch, sealCredential, EpochRefusedError, requestRoomEpoch, canonicalAdmins, CHANNEL_NAME, RESERVED_CHANNELS, canonicalChannels, signChannels, verifyChannels, signAdmins, verifyAdmins, EPOCH_LABELS, } from './epoch.js';
+export { DEFAULT_REPLY_DELAY_MS, REFUSE_AGAIN_AFTER_SECONDS, MAX_REFUSALS_PER_MINUTE, REFUSAL_LIMITER_CAPACITY, RefusalLimiter, replyDelay, } from './quiet-reply.js';
 export { EPOCH_COMMIT_PREFIX, epochCommitment, EPOCH_COMMIT_LABELS } from './epoch-commit.js';
 export { MEMBER_EPOCH_KINDS, MEMBER_EPOCH_REQUEST_KEY_INFO, MAX_MEMBER_EPOCH_CHAIN, deriveMemberEpochRequestKey, readRekeyEvidence, encodeMemberEpochRequest, decodeMemberEpochRequest, encodeMemberEpochGrant, decodeMemberEpochGrant, hostMemberEpochDesk, memberEpochSource, requestMemberEpoch, MEMBER_EPOCH_LABELS, } from './member-epoch.js';
 export { deriveChannel, CHANNEL_ID_INFO, CHANNEL_KEY_INFO, MAX_CHANNEL_NAME_LENGTH, CHANNEL_LABELS } from './channel.js';

package/dist/invitation-decline.d.ts

@@ -0,0 +1,26 @@
+import { type Event } from 'nostr-tools/pure';
+import type { DecodeInvitationGrantOptions, InvitationDelegation, RoomInvitation } from './invitation.js';
+export interface EncodeInvitationDeclineOptions {
+    invitation: RoomInvitation;
+    inviterSk: Uint8Array;
+    requester: string;
+    request: string;
+    now: number;
+    /** Root-to-responder chain; empty only for the pinned root inviter. */
+    delegation?: InvitationDelegation[];
+}
+export interface InvitationDecline {
+    request: string;
+    responder: string;
+}
+export declare class InvitationDeclinedError extends Error {
+    constructor();
+}
+/** 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 declare function encodeInvitationDecline(opts: EncodeInvitationDeclineOptions): Event;
+/** 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 declare function decodeInvitationDecline(event: Event, opts: DecodeInvitationGrantOptions): InvitationDecline | null;

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"];