@prson/login-sdk 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,639 @@
1
+ /**
2
+ * PrsonLoginSession — the live handle the SDK returns from
3
+ * `signIn()`. Owns the established WebRTC transport + ephemeral
4
+ * keys; dispatches a typed event stream as the wallet pushes
5
+ * post-sign-in updates; tears everything down when the credential
6
+ * expires or the host calls `close()`.
7
+ *
8
+ * Event taxonomy (see [ROADMAP §1](../../ROADMAP.md)):
9
+ *
10
+ * Identity lifecycle:
11
+ * signed_in — fires once, right after `signIn()`
12
+ * resolves (via a microtask so listeners
13
+ * attached synchronously after the await
14
+ * still receive it).
15
+ * signed_out — terminal; fires once with an
16
+ * ExpiryReason.
17
+ * renewed — wallet pushed a fresh VC + KB-JWT.
18
+ *
19
+ * Claim updates (require a re-verified SD-JWT-VC in the same
20
+ * envelope):
21
+ * claim_added — a claim name appeared that wasn't in
22
+ * the prior snapshot.
23
+ * claim_removed — a prior claim name is no longer
24
+ * present.
25
+ * claim_updated — same name, different value.
26
+ *
27
+ * Display hints (no crypto re-verify; the host should treat the
28
+ * payload as advisory and ignore it for any privileged decision):
29
+ * display_name_changed
30
+ * avatar_changed
31
+ *
32
+ * Compliance:
33
+ * credential_revoked — followed by signed_out with reason
34
+ * "credential_revoked".
35
+ *
36
+ * Wire grammar lives in `crypto.ts:DecryptedEnvelope`.
37
+ */
38
+ import type { CnfJwk, SignInResult } from "./index.js";
39
+ import type { DecryptedEnvelope, EphemeralKeys } from "./crypto.js";
40
+ import type { Transport } from "./transport.js";
41
+ import { type VerifyOptions } from "./verify.js";
42
+ import { type LoginRequest, type LoginResponse, type RequestOptions } from "./requests.js";
43
+ export type { LoginRequest, LoginResponse, RequestOptions, InputType } from "./requests.js";
44
+ export type ExpiryReason = "ttl_reached" | "wallet_signed_out" | "user_revoked" | "network_loss" | "credential_revoked";
45
+ export type CredentialRevokedReason = "alias_transferred" | "user_revoked" | "key_compromised";
46
+ /**
47
+ * Coarse health of the wallet ↔ browser data channel as observed via
48
+ * the periodic ping/pong loop. Drives the connection-status dot the
49
+ * wallet renders on its remote-nav banner; partner sites can mirror
50
+ * the same signal by reading [PrsonLoginSession.connectionStatus] /
51
+ * subscribing via [PrsonLoginSession.onConnectionStatus].
52
+ *
53
+ * * `unknown` — before the first pong has landed.
54
+ * * `stable` — last RTT under [CONNECTION_UNSTABLE_THRESHOLD_MS].
55
+ * * `unstable` — last RTT crossed the threshold.
56
+ * * `offline` — no pong for [CONNECTION_OFFLINE_AFTER_MS]; the
57
+ * channel is either dead or paused.
58
+ */
59
+ export type ConnectionStatus = "unknown" | "stable" | "unstable" | "offline";
60
+ /** Convenience alias kept for callers that consumed the old shape. */
61
+ export type Renewal = Pick<SignInResult, "sdJwtVc" | "claims" | "credential">;
62
+ /**
63
+ * Discriminated union of every lifecycle event the SDK emits during
64
+ * a live session. Each variant carries exactly the fields a
65
+ * subscriber needs — no shared base envelope, so `e.type` is the
66
+ * only discriminator and the TS compiler narrows the rest.
67
+ *
68
+ * The `signed_in` event also rides this union for uniform
69
+ * subscription, even though `signIn()` already returns the result
70
+ * synchronously. Useful for `onAny` listeners that want a single
71
+ * log line per lifecycle transition.
72
+ *
73
+ * **Privacy policy: claim events never carry raw values.**
74
+ * `claim_added` / `claim_updated` / `claim_removed` deliver only
75
+ * the changed claim **name**. The actual value lives in
76
+ * `session.claims` (the verified snapshot the SDK keeps in sync
77
+ * with the latest SD-JWT-VC) and is read on-demand by the host.
78
+ *
79
+ * Why: `onAny` is the natural attachment point for telemetry
80
+ * (analytics, error reporters, ML feature pipes, …). Any of those
81
+ * trivially capture entire event objects. Putting `value` into the
82
+ * event payload would silently leak raw identity data — name,
83
+ * birthdate, verification level — through every such pipe without
84
+ * the host owner noticing. Name-only events let telemetry log
85
+ * **that** a claim changed without ever seeing **what** it changed
86
+ * to. The host reads `session.claims[name]` when (and only when)
87
+ * it needs the value, and is free to scrub that read site
88
+ * independently of the event surface.
89
+ *
90
+ * The exceptions are the explicitly-public display fields
91
+ * (`display_name_changed`, `avatar_changed`) — those carry their
92
+ * values directly because they're meant to drive UI without an
93
+ * extra read step.
94
+ */
95
+ export type LoginEvent = {
96
+ type: "signed_in";
97
+ result: SignInResult;
98
+ } | {
99
+ type: "signed_out";
100
+ reason: ExpiryReason;
101
+ } | {
102
+ type: "renewed";
103
+ result: SignInResult;
104
+ }
105
+ /**
106
+ * Claim added / updated. `newHash` is a hex-encoded SHA-256 of the
107
+ * canonical-JSON encoding of the NEW value — the host can compare
108
+ * against a precomputed `sha256(canonical(expected))` to confirm
109
+ * what the new value is without ever seeing the value travel
110
+ * through the event payload. The full value lives in
111
+ * `session.claims[name]` for callers that need it.
112
+ */
113
+ | {
114
+ type: "claim_added";
115
+ name: string;
116
+ newHash: string;
117
+ } | {
118
+ type: "claim_updated";
119
+ name: string;
120
+ newHash: string;
121
+ } | {
122
+ type: "claim_removed";
123
+ name: string;
124
+ } | {
125
+ type: "display_name_changed";
126
+ displayName: string | null;
127
+ } | {
128
+ type: "avatar_changed";
129
+ avatar: {
130
+ url: string;
131
+ hash: string;
132
+ } | null;
133
+ } | {
134
+ type: "credential_revoked";
135
+ reason: CredentialRevokedReason;
136
+ };
137
+ export type LoginEventType = LoginEvent["type"];
138
+ /** Function returned by `on()` / `onAny()` to remove the listener. */
139
+ export type Unsubscribe = () => void;
140
+ export declare class PrsonLoginSession {
141
+ private _expiresAt;
142
+ private _cnf;
143
+ private _claimsSnapshot;
144
+ private _transport;
145
+ private _ephKeys;
146
+ private _verifierContext;
147
+ private _expiryTimer;
148
+ private _closed;
149
+ /**
150
+ * Wallet's session X25519 public key, PINNED from the verified
151
+ * sign-in presentation (its KB-JWT `prson_wsk` claim, signed by the
152
+ * cnf key). Every inbound envelope must be boxed by this key or it is
153
+ * dropped, and every outbound one is boxed to it. It changes only when
154
+ * a verified `renewal` presentation carries a new `prson_wsk`. Null
155
+ * when the wallet published none — calls to `request()` then resolve
156
+ * with `{ ok: false, error: "no-active-session" }`.
157
+ */
158
+ private _walletSessionPk;
159
+ /**
160
+ * True when the sign-in presentation didn't bind a session key (a
161
+ * wallet older than envelope v2). The sender of inbound envelopes
162
+ * can't be checked then, so envelopes that act on the page (`nav`,
163
+ * `value`, `mouse-update`, file transfer) are ignored; everything
164
+ * else still works. See SECURITY.md §4.
165
+ */
166
+ private _legacyChannel;
167
+ /** `iat` of the newest verified presentation (sign-in or renewal).
168
+ * A renewal / claim-update must be strictly newer. */
169
+ private _lastPresentationIat;
170
+ /** SHA-256 of every presentation this session accepted, so a replay
171
+ * of an earlier one (even with a still-fresh `iat`) is refused. */
172
+ private _seenPresentations;
173
+ /** Pairs outbound `request` envelopes with inbound `response`s. */
174
+ private _requestController;
175
+ /**
176
+ * Per-`requestId` mouse-update subscribers. Populated by
177
+ * [`bindMouse`] when it opens a `kind: "mouse"` request and torn
178
+ * down when the controller disposes or the wallet's final
179
+ * `response` arrives. Keys are RFC-4122 v4 UUIDs (the request id);
180
+ * values get a stream of decoded `mouse` bodies.
181
+ */
182
+ private _mouseSubscribers;
183
+ /**
184
+ * Ambient mouse-update handler. Used when the wallet starts a
185
+ * mouse stream WITHOUT a prior `kind: "mouse"` request — i.e.
186
+ * the pre-grant flow enabled by [SignInOptions.mouseControl].
187
+ * [`bindMouse`] registers itself here; any inbound
188
+ * `mouse-update` frame whose `requestId` doesn't match a
189
+ * specific subscriber falls through to this handler so the
190
+ * cursor moves regardless of who initiated the stream.
191
+ *
192
+ * Null when no [`bindMouse`] is mounted; only one ambient
193
+ * handler is active at a time (last call wins, mirroring the
194
+ * remote-nav listener semantics).
195
+ */
196
+ private _ambientMouseHandler;
197
+ /**
198
+ * File-transfer envelope handler. [`enableRemoteNavigation`]
199
+ * installs one of these to receive `file-begin` / `file-chunk` /
200
+ * `file-end` envelopes and reassemble the bytes into a `File`
201
+ * the focused `<input type="file">` accepts. The session layer
202
+ * just dispatches — assembly logic lives in `bind.ts` so the
203
+ * DOM dependency stays out of the protocol layer.
204
+ */
205
+ private _fileEnvelopeHandler;
206
+ /**
207
+ * Remote-navigation listener — installed by
208
+ * [`enableRemoteNavigation`]. Receives every inbound `nav`,
209
+ * `value`, and `logout` envelope. Only one listener at a time
210
+ * (later registrations replace the prior). Null when remote-nav
211
+ * is not active for this session.
212
+ */
213
+ private _remoteNavListener;
214
+ /**
215
+ * User's preferred UI language as a BCP-47 tag. Captured from the
216
+ * initial `presentation` envelope's `preferredLanguage` field;
217
+ * updated whenever a fresh envelope arrives with a new value.
218
+ * Null until the first envelope lands. The host page reads this
219
+ * to localise its own UI without an extra round-trip.
220
+ */
221
+ private _preferredLanguage;
222
+ /**
223
+ * Public-profile display name (cosmetic — host should treat as
224
+ * untrusted). Seeded from the wallet's initial `presentation`
225
+ * envelope and updated via `display-update` envelopes; mirrored
226
+ * by the `display_name_changed` event.
227
+ */
228
+ private _displayName;
229
+ /**
230
+ * Public-profile avatar pointer (cosmetic). Same trust model as
231
+ * `_displayName`. Updated via `display-update` envelopes; mirrored
232
+ * by `avatar_changed`.
233
+ */
234
+ private _avatar;
235
+ /** Per-type listener map. */
236
+ private _listeners;
237
+ /** "Fire on every event" subscribers — for logging / telemetry. */
238
+ private _anyListeners;
239
+ private _seenIds;
240
+ private _seenIdsOrder;
241
+ private _pendingAcks;
242
+ private _pingSendTimes;
243
+ private _pingTimer;
244
+ private _offlineTimer;
245
+ private _connectionStatus;
246
+ private _lastRttMs;
247
+ private _connectionListeners;
248
+ /**
249
+ * `pagehide` handler reference. Held so we can deregister at
250
+ * teardown without anchoring `this` to the global listener
251
+ * forever — important because the SDK can outlive multiple
252
+ * sign-in / sign-out cycles in a single tab.
253
+ */
254
+ private _onPageHide;
255
+ constructor(opts: {
256
+ cnf: {
257
+ jwk: CnfJwk;
258
+ };
259
+ credential: {
260
+ expiresAt: number;
261
+ };
262
+ transport: Transport;
263
+ ephKeys: EphemeralKeys;
264
+ verifierContext: VerifierContext;
265
+ /**
266
+ * The verified-claim map from the initial sign-in. Cached so
267
+ * `claim-update` events can compute a real diff (and so
268
+ * `claim_added` / `claim_updated` carry old + new values). Optional
269
+ * for back-compat; if absent the first `claim-update` treats
270
+ * every claim as `claim_added`, which is the safe direction.
271
+ */
272
+ initialClaims?: Record<string, unknown>;
273
+ /**
274
+ * The `SignInResult` to deliver as the payload of the
275
+ * `signed_in` event fired via microtask. Optional — pass to
276
+ * enable `signed_in` dispatch; omit to leave the event silent.
277
+ */
278
+ initialSignedInResult?: SignInResult;
279
+ /**
280
+ * The wallet's session X25519 public key from the initial
281
+ * `presentation` envelope. Required to open the browser→wallet
282
+ * request channel (`session.request(...)`). Optional only for
283
+ * back-compat with older wallets that don't yet publish it.
284
+ */
285
+ walletSessionPk?: string;
286
+ /**
287
+ * True when the sign-in presentation didn't bind [walletSessionPk]
288
+ * (wallet older than envelope v2): inbound senders can't be checked,
289
+ * so page-acting envelopes are ignored. Default false.
290
+ */
291
+ legacyChannel?: boolean;
292
+ /**
293
+ * The verified sign-in presentation and its holder-signed `iat`:
294
+ * the baseline for renewal anti-replay (a renewal must carry a
295
+ * strictly newer `iat` and must not repeat an accepted presentation).
296
+ */
297
+ initialPresentation?: {
298
+ presentation: string;
299
+ iat: number;
300
+ };
301
+ /**
302
+ * Initial `preferredLanguage` value from the wallet's first
303
+ * envelope. The session's own `_handleMessage` only sees
304
+ * envelopes that arrive AFTER signIn() has consumed the
305
+ * presentation, so the language tag on the first envelope is
306
+ * otherwise lost — leaving `session.preferredLanguage` null
307
+ * until a later renewal envelope. Seeded here so the value
308
+ * is available immediately when the host inspects it after
309
+ * `signIn()` resolves.
310
+ */
311
+ initialPreferredLanguage?: string;
312
+ /**
313
+ * Initial `displayName` from the wallet's first envelope.
314
+ * Cosmetic public-profile data; see [displayName] getter for
315
+ * the trust model. Seeded here so the host sees the name
316
+ * immediately after `signIn()` resolves rather than waiting for
317
+ * the first `display-update`.
318
+ */
319
+ initialDisplayName?: string | null;
320
+ /** Initial `avatar` from the wallet's first envelope (same
321
+ * rationale as [initialDisplayName]). */
322
+ initialAvatar?: {
323
+ url: string;
324
+ hash: string;
325
+ } | null;
326
+ });
327
+ get expiresAt(): number;
328
+ get cnf(): {
329
+ jwk: CnfJwk;
330
+ };
331
+ /** Snapshot of the most recent verified claims (since last renew / update). */
332
+ get claims(): Readonly<Record<string, unknown>>;
333
+ /**
334
+ * Who is signed in: the person's Prson ID for this site (`cnf.jwk.x`,
335
+ * the same value as `SignInResult.prsonId`). Show it — or a name your
336
+ * backend maps it to — on the page, so the person can see it's them
337
+ * and not someone who scanned the code first.
338
+ */
339
+ get prsonId(): string;
340
+ /** The wallet's pinned X25519 session key (base64url), or null. */
341
+ get walletSessionPk(): string | null;
342
+ /** User's preferred UI language (BCP-47 tag) or null if the
343
+ * wallet hasn't published one yet. */
344
+ get preferredLanguage(): string | null;
345
+ /** Public-profile display name from the wallet's identity record,
346
+ * or null if the wallet hasn't published one yet (anonymous
347
+ * identity, etc.). Cosmetic — do not gate privileged actions on
348
+ * this value. */
349
+ get displayName(): string | null;
350
+ /** Public-profile avatar pointer, or null. Same cosmetic-only
351
+ * trust model as [displayName]. */
352
+ get avatar(): {
353
+ url: string;
354
+ hash: string;
355
+ } | null;
356
+ /** Coarse health of the wallet ↔ browser data channel as observed
357
+ * via the periodic ping/pong loop. `unknown` until the first pong
358
+ * lands; `offline` after 5 s of no pong; `unstable` when the most
359
+ * recent RTT crossed 1 s; otherwise `stable`. */
360
+ get connectionStatus(): ConnectionStatus;
361
+ /** Most recently observed RTT in milliseconds, or null until the
362
+ * first pong lands. */
363
+ get lastRttMs(): number | null;
364
+ /** Subscribe to connection-status changes. Fires on every transition
365
+ * with the new status + the RTT that triggered it (null on the
366
+ * `offline` transition). Returns an unsubscribe handle. */
367
+ onConnectionStatus(cb: (status: ConnectionStatus, rttMs: number | null) => void): Unsubscribe;
368
+ /**
369
+ * Subscribe to a single event type. The callback is invoked with
370
+ * the typed event variant (TS narrows on the `type` discriminant).
371
+ * Returns an unsubscribe handle.
372
+ *
373
+ * const off = session.on("claim_updated", (e) => {
374
+ * if (e.name === "verification_level") refreshBadge(e.newValue);
375
+ * });
376
+ * // later:
377
+ * off();
378
+ */
379
+ on<T extends LoginEventType>(type: T, cb: (event: Extract<LoginEvent, {
380
+ type: T;
381
+ }>) => void): Unsubscribe;
382
+ /** Subscribe to every event. Returns an unsubscribe handle. */
383
+ onAny(cb: (event: LoginEvent) => void): Unsubscribe;
384
+ /** @deprecated Use `on("renewed", e => cb(e.result))` instead. */
385
+ onRenewed(cb: (fresh: SignInResult) => void): Unsubscribe;
386
+ /** @deprecated Use `on("signed_out", e => cb(e.reason))` instead. */
387
+ onExpiry(cb: (reason: ExpiryReason) => void): Unsubscribe;
388
+ close(): void;
389
+ /**
390
+ * Send a [request] to the wallet and resolve with the wallet's
391
+ * reply. The wallet shows a bottom drawer for the user to
392
+ * approve / decline / pick a matching fragment or document; the
393
+ * promise resolves when the user acts (or the [timeoutMs]
394
+ * elapses, or the session closes).
395
+ *
396
+ * Common error codes:
397
+ * * `no-active-session` — request issued before the wallet has
398
+ * published its session pk (race against the initial
399
+ * `presentation` envelope) or after the session closed.
400
+ * * `declined` — user tapped Decline in the wallet drawer.
401
+ * * `not-present` — no matching fragment / document on the
402
+ * device AND the user declined to acquire one.
403
+ * * `queue-full` — wallet is sitting at the 5-in-flight cap and
404
+ * isn't accepting more requests. Try later.
405
+ * * `rate-limited` — wallet's 1-request-per-second throttle
406
+ * rejected this one.
407
+ * * `timeout` — the [timeoutMs] elapsed before the wallet
408
+ * replied. Defaults to 60 s.
409
+ * * `session-closed` — the session shut down with this request
410
+ * in flight.
411
+ *
412
+ * Wire grammar: outbound envelope shape is
413
+ * `{ v, msg: "request", issuedAt, domain, requestId, kind, ...kindFields }`,
414
+ * NaCl-boxed to the wallet's session pk. Reply is a matching
415
+ * `{ msg: "response", requestId, result | error }`.
416
+ */
417
+ request(req: LoginRequest, opts?: RequestOptions): Promise<LoginResponse>;
418
+ /**
419
+ * Streaming variant of [request] for `kind: "mouse"`. Identical
420
+ * to `request()` except [onFrame] is invoked for every
421
+ * `mouse-update` envelope the wallet emits against the request's
422
+ * UUID until the terminating `response` arrives. The returned
423
+ * promise resolves with the final response (i.e. when the user
424
+ * closes the wallet drawer). Used by [`bindMouse`].
425
+ *
426
+ * Separated from `request()` because the subscriber MUST be
427
+ * attached against the requestId BEFORE the envelope is sent —
428
+ * otherwise the first `mouse-update` frame can race ahead of the
429
+ * subscription. `request()` doesn't expose its requestId, so we
430
+ * provide this dedicated entry point rather than leak the id.
431
+ */
432
+ requestMouse(req: Extract<LoginRequest, {
433
+ kind: "mouse";
434
+ }>, onFrame: (mouse: NonNullable<DecryptedEnvelope["mouse"]>) => void, opts?: RequestOptions): Promise<LoginResponse>;
435
+ /**
436
+ * Push the currently-focused input's metadata + value to the
437
+ * wallet so the user can edit it on the phone. Pass `null` to
438
+ * clear the wallet's focus mirror (blur, page change, etc.).
439
+ *
440
+ * Used by [`enableRemoteNavigation`]; not part of the documented
441
+ * public API but exposed so the helper lives in a separate module
442
+ * without reaching into private fields. NaCl-boxed to the wallet's
443
+ * session pk on the way out.
444
+ *
445
+ * @internal
446
+ */
447
+ _sendFocus(focus: {
448
+ name: string;
449
+ label?: string;
450
+ inputType?: string;
451
+ value?: string;
452
+ placeholder?: string;
453
+ minLength?: number;
454
+ maxLength?: number;
455
+ min?: number;
456
+ max?: number;
457
+ pattern?: string;
458
+ required?: boolean;
459
+ options?: {
460
+ value: string;
461
+ label?: string;
462
+ }[];
463
+ /** Navigation-row visibility hints. Computed by
464
+ * `enableRemoteNavigation`'s `computeNavMeta` from the
465
+ * current tabbable pool and the focused element's
466
+ * surrounding form. The wallet renders only the buttons
467
+ * that match. See `bind.ts:computeNavMeta` + the wallet's
468
+ * `_navigationRow`. */
469
+ hasPrev?: boolean;
470
+ hasNext?: boolean;
471
+ isLastInForm?: boolean;
472
+ isButton?: boolean;
473
+ /** File-input attributes. Present only when the focused
474
+ * element is `<input type="file">`; drives the wallet's
475
+ * picker UI (camera vs gallery vs files filtered by
476
+ * MIME). `accept` is the raw `accept` attribute string
477
+ * (e.g. `"image/*,application/pdf"`); the wallet
478
+ * normalises it. `multiple` enables multi-select on the
479
+ * picker. `capture` (`"user"` / `"environment"`) hints
480
+ * which camera the host expects when the user opens the
481
+ * camera mode. */
482
+ accept?: string;
483
+ multiple?: boolean;
484
+ capture?: string;
485
+ } | null): Promise<void>;
486
+ /**
487
+ * Install a `pagehide` listener that fires a synchronous
488
+ * `browser-revoke` envelope at the wallet right before the tab
489
+ * closes / refreshes / navigates away. Without this the wallet
490
+ * has to wait for the slower transport-collapse pathway
491
+ * (`peer-gone` over the signaling WS + ICE failure on the data
492
+ * channel) to learn the browser is gone — long enough for the
493
+ * connection-status dot to oscillate and any in-flight ack
494
+ * promises to time out.
495
+ *
496
+ * `pagehide` is preferred over `beforeunload` because:
497
+ * * it fires for bfcache evictions (back/forward navigation
498
+ * on iOS Safari), tab closes, AND refreshes
499
+ * * `beforeunload` is increasingly restricted by browsers
500
+ * for non-blocking-prompt use
501
+ *
502
+ * The envelope itself rides through the same NaCl box as every
503
+ * other browser→wallet message. We can't await the ack — the
504
+ * page is being torn down — so this is a true fire-and-forget;
505
+ * the wallet's [LoginSession.inbound] handler treats receipt
506
+ * as the trigger to close.
507
+ */
508
+ private _installUnloadGuard;
509
+ /**
510
+ * Browser→wallet pause-state notification. The wallet's mouse
511
+ * controller dims its surface + shows "Remote control paused"
512
+ * while the page is in the background. Fire-and-forget over
513
+ * NaCl-box to the wallet's session pk; loss is acceptable
514
+ * (we re-fire on every focus / blur).
515
+ *
516
+ * @internal
517
+ */
518
+ _sendControlStatus(paused: boolean): Promise<void>;
519
+ /**
520
+ * Install the ambient `mouse-update` handler. Mirrors
521
+ * [`_setRemoteNavListener`] — only one ambient subscriber at a
522
+ * time (last call wins). Used by [`bindMouse`] when the
523
+ * session was pre-granted mouse control at sign-in
524
+ * ([SignInOptions.mouseControl]).
525
+ *
526
+ * @internal
527
+ */
528
+ _setAmbientMouseHandler(cb: ((mouse: NonNullable<DecryptedEnvelope["mouse"]>) => void) | null): Unsubscribe;
529
+ /**
530
+ * Install the file-envelope handler. Mirrors
531
+ * [`_setAmbientMouseHandler`] — only one handler at a time;
532
+ * [`enableRemoteNavigation`] owns it during its lifetime and
533
+ * tears it down on disposal so the next mount can install a
534
+ * fresh one. The handler receives `file-begin` / `file-chunk` /
535
+ * `file-end` envelopes in arrival order; assembly + DOM
536
+ * dispatch lives in [`bind.ts`].
537
+ *
538
+ * @internal
539
+ */
540
+ _setFileEnvelopeHandler(cb: ((envelope: DecryptedEnvelope) => void) | null): Unsubscribe;
541
+ /**
542
+ * Install the remote-navigation listener. Replaces any prior
543
+ * listener — only one is active at a time. Returns an unsubscribe
544
+ * handle. Used by [`enableRemoteNavigation`].
545
+ *
546
+ * @internal
547
+ */
548
+ _setRemoteNavListener(cb: ((envelope: {
549
+ msg: "nav";
550
+ action: "prev" | "next" | "submit";
551
+ } | {
552
+ msg: "value";
553
+ value: string;
554
+ } | {
555
+ msg: "logout";
556
+ }) => void) | null): Unsubscribe;
557
+ private _sendRequest;
558
+ /**
559
+ * Fire a single event to per-type listeners + onAny subscribers.
560
+ * Listener errors are swallowed so one buggy host listener can't
561
+ * break the rest of the dispatch (or close the session).
562
+ */
563
+ private _dispatch;
564
+ private _armExpiryTimer;
565
+ private _handleMessage;
566
+ private _markSeen;
567
+ /** Auto-ack any inbound envelope that carries an `id`, except
568
+ * protocol primitives. `ping` is implicitly acked by `pong`;
569
+ * `pong` and `ack` would loop. */
570
+ private _sendAckFor;
571
+ private _handleAck;
572
+ private _sendPing;
573
+ private _sendPong;
574
+ private _handlePong;
575
+ private _armOfflineTimer;
576
+ private _setConnectionStatus;
577
+ /** Send a JSON envelope with ack tracking + retry. Stamps a fresh
578
+ * `id` onto [body] and retransmits every [ACK_RETRY_DELAY_MS]
579
+ * until the matching ack lands or [ACK_MAX_ATTEMPTS] is reached.
580
+ * Resolves with `true` on ack, `false` on exhaustion. */
581
+ private _sendWithAck;
582
+ /**
583
+ * Pure dispatch entry-point — takes an already-decrypted envelope
584
+ * and routes it through the same per-message handlers
585
+ * `_handleMessage` does after decryption. Public-but-prefixed so
586
+ * unit tests can exercise the dispatch contract without
587
+ * constructing real NaCl-boxed ciphertext.
588
+ *
589
+ * NOT part of the documented public API; treat as @internal.
590
+ */
591
+ _dispatchDecryptedForTest(envelope: DecryptedEnvelope): Promise<void>;
592
+ private _handleRenewal;
593
+ /**
594
+ * Verify a renewal / claim-update presentation and enforce in-session
595
+ * anti-replay: same holder key, a holder-signed `iat` strictly newer
596
+ * than the last accepted presentation, and never a presentation this
597
+ * session already accepted. Returns null (drop it) otherwise.
598
+ */
599
+ private _verifyFresh;
600
+ /**
601
+ * Verify the embedded presentation, then diff its claims against
602
+ * the cached snapshot and emit name-only per-claim events. The
603
+ * actual claim values land in `this._claimsSnapshot` (accessible
604
+ * via `session.claims`) but **never** in the event payloads —
605
+ * see the privacy note on the [LoginEvent] type.
606
+ *
607
+ * Re-verifies against the same audience + accepted-VCT set as the
608
+ * initial sign-in. A `claim-update` whose presentation fails
609
+ * verification is dropped silently — fail-closed. Same for a
610
+ * cnf-mismatch (the wallet swapped per-domain key under us).
611
+ *
612
+ * The wire-level `envelope.delta` is intentionally ignored — we
613
+ * recompute the diff from the verified SD-JWT so a malicious
614
+ * wallet can't lie about which claim changed. The wallet should
615
+ * not include values in `envelope.delta` at all (the wire
616
+ * grammar in `crypto.ts` documents this as name-only); we'd
617
+ * ignore them even if it did.
618
+ */
619
+ private _handleClaimUpdate;
620
+ /**
621
+ * Display-only update. Fires `display_name_changed` and/or
622
+ * `avatar_changed` based on which fields the envelope carries.
623
+ * NOT cryptographically verified — partner sites should treat
624
+ * the payload as advisory (refresh the cosmetic UI) and not
625
+ * grant any privileged access on the basis of these values.
626
+ */
627
+ private _handleDisplayUpdate;
628
+ /**
629
+ * Credential-revoked. Fires `credential_revoked` with the
630
+ * wallet-supplied reason, then tears the session down with
631
+ * `signed_out / reason="credential_revoked"`. Both events land
632
+ * before the transport closes.
633
+ */
634
+ private _handleCredentialRevoked;
635
+ private _teardown;
636
+ }
637
+ type VerifierContext = Omit<VerifyOptions, "expectedNonce"> & {
638
+ expectedNonceFactory: () => string;
639
+ };