@prson/login-sdk 0.0.0-stage → 0.2.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,645 @@
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) and request replies
164
+ * (`response`) are ignored, `request()` resolves with
165
+ * `{ ok: false, error: "unsupported" }` and no field values are sent
166
+ * (`focus`). Sign-in, renewals and claim updates (all verified
167
+ * presentations) and sign-out still work. See SECURITY.md §4.
168
+ */
169
+ private _legacyChannel;
170
+ /** `iat` of the newest verified presentation (sign-in or renewal).
171
+ * A renewal / claim-update must be strictly newer. */
172
+ private _lastPresentationIat;
173
+ /** SHA-256 of every presentation this session accepted, so a replay
174
+ * of an earlier one (even with a still-fresh `iat`) is refused. */
175
+ private _seenPresentations;
176
+ /** Pairs outbound `request` envelopes with inbound `response`s. */
177
+ private _requestController;
178
+ /**
179
+ * Per-`requestId` mouse-update subscribers. Populated by
180
+ * [`bindMouse`] when it opens a `kind: "mouse"` request and torn
181
+ * down when the controller disposes or the wallet's final
182
+ * `response` arrives. Keys are RFC-4122 v4 UUIDs (the request id);
183
+ * values get a stream of decoded `mouse` bodies.
184
+ */
185
+ private _mouseSubscribers;
186
+ /**
187
+ * Ambient mouse-update handler. Used when the wallet starts a
188
+ * mouse stream WITHOUT a prior `kind: "mouse"` request — i.e.
189
+ * the pre-grant flow enabled by [SignInOptions.mouseControl].
190
+ * [`bindMouse`] registers itself here; any inbound
191
+ * `mouse-update` frame whose `requestId` doesn't match a
192
+ * specific subscriber falls through to this handler so the
193
+ * cursor moves regardless of who initiated the stream.
194
+ *
195
+ * Null when no [`bindMouse`] is mounted; only one ambient
196
+ * handler is active at a time (last call wins, mirroring the
197
+ * remote-nav listener semantics).
198
+ */
199
+ private _ambientMouseHandler;
200
+ /**
201
+ * File-transfer envelope handler. [`enableRemoteNavigation`]
202
+ * installs one of these to receive `file-begin` / `file-chunk` /
203
+ * `file-end` envelopes and reassemble the bytes into a `File`
204
+ * the focused `<input type="file">` accepts. The session layer
205
+ * just dispatches — assembly logic lives in `bind.ts` so the
206
+ * DOM dependency stays out of the protocol layer.
207
+ */
208
+ private _fileEnvelopeHandler;
209
+ /**
210
+ * Remote-navigation listener — installed by
211
+ * [`enableRemoteNavigation`]. Receives every inbound `nav`,
212
+ * `value`, and `logout` envelope. Only one listener at a time
213
+ * (later registrations replace the prior). Null when remote-nav
214
+ * is not active for this session.
215
+ */
216
+ private _remoteNavListener;
217
+ /**
218
+ * User's preferred UI language as a BCP-47 tag. Captured from the
219
+ * initial `presentation` envelope's `preferredLanguage` field;
220
+ * updated whenever a fresh envelope arrives with a new value.
221
+ * Null until the first envelope lands. The host page reads this
222
+ * to localise its own UI without an extra round-trip.
223
+ */
224
+ private _preferredLanguage;
225
+ /**
226
+ * Public-profile display name (cosmetic — host should treat as
227
+ * untrusted). Seeded from the wallet's initial `presentation`
228
+ * envelope and updated via `display-update` envelopes; mirrored
229
+ * by the `display_name_changed` event.
230
+ */
231
+ private _displayName;
232
+ /**
233
+ * Public-profile avatar pointer (cosmetic). Same trust model as
234
+ * `_displayName`. Updated via `display-update` envelopes; mirrored
235
+ * by `avatar_changed`.
236
+ */
237
+ private _avatar;
238
+ /** Per-type listener map. */
239
+ private _listeners;
240
+ /** "Fire on every event" subscribers — for logging / telemetry. */
241
+ private _anyListeners;
242
+ private _seenIds;
243
+ private _seenIdsOrder;
244
+ private _pendingAcks;
245
+ private _pingSendTimes;
246
+ private _pingTimer;
247
+ private _offlineTimer;
248
+ private _connectionStatus;
249
+ private _lastRttMs;
250
+ private _connectionListeners;
251
+ /**
252
+ * `pagehide` handler reference. Held so we can deregister at
253
+ * teardown without anchoring `this` to the global listener
254
+ * forever — important because the SDK can outlive multiple
255
+ * sign-in / sign-out cycles in a single tab.
256
+ */
257
+ private _onPageHide;
258
+ constructor(opts: {
259
+ cnf: {
260
+ jwk: CnfJwk;
261
+ };
262
+ credential: {
263
+ expiresAt: number;
264
+ };
265
+ transport: Transport;
266
+ ephKeys: EphemeralKeys;
267
+ verifierContext: VerifierContext;
268
+ /**
269
+ * The verified-claim map from the initial sign-in. Cached so
270
+ * `claim-update` events can compute a real diff (and so
271
+ * `claim_added` / `claim_updated` carry old + new values). Optional
272
+ * for back-compat; if absent the first `claim-update` treats
273
+ * every claim as `claim_added`, which is the safe direction.
274
+ */
275
+ initialClaims?: Record<string, unknown>;
276
+ /**
277
+ * The `SignInResult` to deliver as the payload of the
278
+ * `signed_in` event fired via microtask. Optional — pass to
279
+ * enable `signed_in` dispatch; omit to leave the event silent.
280
+ */
281
+ initialSignedInResult?: SignInResult;
282
+ /**
283
+ * The wallet's session X25519 public key from the initial
284
+ * `presentation` envelope. Required to open the browser→wallet
285
+ * request channel (`session.request(...)`). Optional only for
286
+ * back-compat with older wallets that don't yet publish it.
287
+ */
288
+ walletSessionPk?: string;
289
+ /**
290
+ * True when the sign-in presentation didn't bind [walletSessionPk]
291
+ * (wallet older than envelope v2): inbound senders can't be checked,
292
+ * so page-acting envelopes are ignored. Default false.
293
+ */
294
+ legacyChannel?: boolean;
295
+ /**
296
+ * The verified sign-in presentation and its holder-signed `iat`:
297
+ * the baseline for renewal anti-replay (a renewal must carry a
298
+ * strictly newer `iat` and must not repeat an accepted presentation).
299
+ */
300
+ initialPresentation?: {
301
+ presentation: string;
302
+ iat: number;
303
+ };
304
+ /**
305
+ * Initial `preferredLanguage` value from the wallet's first
306
+ * envelope. The session's own `_handleMessage` only sees
307
+ * envelopes that arrive AFTER signIn() has consumed the
308
+ * presentation, so the language tag on the first envelope is
309
+ * otherwise lost — leaving `session.preferredLanguage` null
310
+ * until a later renewal envelope. Seeded here so the value
311
+ * is available immediately when the host inspects it after
312
+ * `signIn()` resolves.
313
+ */
314
+ initialPreferredLanguage?: string;
315
+ /**
316
+ * Initial `displayName` from the wallet's first envelope.
317
+ * Cosmetic public-profile data; see [displayName] getter for
318
+ * the trust model. Seeded here so the host sees the name
319
+ * immediately after `signIn()` resolves rather than waiting for
320
+ * the first `display-update`.
321
+ */
322
+ initialDisplayName?: string | null;
323
+ /** Initial `avatar` from the wallet's first envelope (same
324
+ * rationale as [initialDisplayName]). */
325
+ initialAvatar?: {
326
+ url: string;
327
+ hash: string;
328
+ } | null;
329
+ });
330
+ get expiresAt(): number;
331
+ get cnf(): {
332
+ jwk: CnfJwk;
333
+ };
334
+ /** Snapshot of the most recent verified claims (since last renew / update). */
335
+ get claims(): Readonly<Record<string, unknown>>;
336
+ /**
337
+ * Who is signed in: the person's Prson ID for this site (`cnf.jwk.x`,
338
+ * the same value as `SignInResult.prsonId`). Show it — or a name your
339
+ * backend maps it to — on the page, so the person can see it's them
340
+ * and not someone who scanned the code first.
341
+ */
342
+ get prsonId(): string;
343
+ /** The wallet's pinned X25519 session key (base64url), or null. */
344
+ get walletSessionPk(): string | null;
345
+ /** User's preferred UI language (BCP-47 tag) or null if the
346
+ * wallet hasn't published one yet. */
347
+ get preferredLanguage(): string | null;
348
+ /** Public-profile display name from the wallet's identity record,
349
+ * or null if the wallet hasn't published one yet (anonymous
350
+ * identity, etc.). Cosmetic — do not gate privileged actions on
351
+ * this value. */
352
+ get displayName(): string | null;
353
+ /** Public-profile avatar pointer, or null. Same cosmetic-only
354
+ * trust model as [displayName]. */
355
+ get avatar(): {
356
+ url: string;
357
+ hash: string;
358
+ } | null;
359
+ /** Coarse health of the wallet ↔ browser data channel as observed
360
+ * via the periodic ping/pong loop. `unknown` until the first pong
361
+ * lands; `offline` after 5 s of no pong; `unstable` when the most
362
+ * recent RTT crossed 1 s; otherwise `stable`. */
363
+ get connectionStatus(): ConnectionStatus;
364
+ /** Most recently observed RTT in milliseconds, or null until the
365
+ * first pong lands. */
366
+ get lastRttMs(): number | null;
367
+ /** Subscribe to connection-status changes. Fires on every transition
368
+ * with the new status + the RTT that triggered it (null on the
369
+ * `offline` transition). Returns an unsubscribe handle. */
370
+ onConnectionStatus(cb: (status: ConnectionStatus, rttMs: number | null) => void): Unsubscribe;
371
+ /**
372
+ * Subscribe to a single event type. The callback is invoked with
373
+ * the typed event variant (TS narrows on the `type` discriminant).
374
+ * Returns an unsubscribe handle.
375
+ *
376
+ * const off = session.on("claim_updated", (e) => {
377
+ * if (e.name === "verification_level") refreshBadge(e.newValue);
378
+ * });
379
+ * // later:
380
+ * off();
381
+ */
382
+ on<T extends LoginEventType>(type: T, cb: (event: Extract<LoginEvent, {
383
+ type: T;
384
+ }>) => void): Unsubscribe;
385
+ /** Subscribe to every event. Returns an unsubscribe handle. */
386
+ onAny(cb: (event: LoginEvent) => void): Unsubscribe;
387
+ /** @deprecated Use `on("renewed", e => cb(e.result))` instead. */
388
+ onRenewed(cb: (fresh: SignInResult) => void): Unsubscribe;
389
+ /** @deprecated Use `on("signed_out", e => cb(e.reason))` instead. */
390
+ onExpiry(cb: (reason: ExpiryReason) => void): Unsubscribe;
391
+ close(): void;
392
+ /**
393
+ * Send a [request] to the wallet and resolve with the wallet's
394
+ * reply. The wallet shows a bottom drawer for the user to
395
+ * approve / decline / pick a matching fragment or document; the
396
+ * promise resolves when the user acts (or the [timeoutMs]
397
+ * elapses, or the session closes).
398
+ *
399
+ * Common error codes:
400
+ * * `no-active-session` — request issued before the wallet has
401
+ * published its session pk (race against the initial
402
+ * `presentation` envelope) or after the session closed.
403
+ * * `declined` — user tapped Decline in the wallet drawer.
404
+ * * `not-present` — no matching fragment / document on the
405
+ * device AND the user declined to acquire one.
406
+ * * `queue-full` — wallet is sitting at the 5-in-flight cap and
407
+ * isn't accepting more requests. Try later.
408
+ * * `rate-limited` — wallet's 1-request-per-second throttle
409
+ * rejected this one.
410
+ * * `timeout` — the [timeoutMs] elapsed before the wallet
411
+ * replied. Defaults to 60 s.
412
+ * * `session-closed` — the session shut down with this request
413
+ * in flight.
414
+ * * `unsupported` — the wallet predates envelope v2 (it bound no
415
+ * session key into the sign-in), so its replies couldn't be told
416
+ * apart from anyone else's. Nothing is sent to it.
417
+ *
418
+ * Wire grammar: outbound envelope shape is
419
+ * `{ v, msg: "request", issuedAt, domain, requestId, kind, ...kindFields }`,
420
+ * NaCl-boxed to the wallet's session pk. Reply is a matching
421
+ * `{ msg: "response", requestId, result | error }`.
422
+ */
423
+ request(req: LoginRequest, opts?: RequestOptions): Promise<LoginResponse>;
424
+ /**
425
+ * Streaming variant of [request] for `kind: "mouse"`. Identical
426
+ * to `request()` except [onFrame] is invoked for every
427
+ * `mouse-update` envelope the wallet emits against the request's
428
+ * UUID until the terminating `response` arrives. The returned
429
+ * promise resolves with the final response (i.e. when the user
430
+ * closes the wallet drawer). Used by [`bindMouse`].
431
+ *
432
+ * Separated from `request()` because the subscriber MUST be
433
+ * attached against the requestId BEFORE the envelope is sent —
434
+ * otherwise the first `mouse-update` frame can race ahead of the
435
+ * subscription. `request()` doesn't expose its requestId, so we
436
+ * provide this dedicated entry point rather than leak the id.
437
+ */
438
+ requestMouse(req: Extract<LoginRequest, {
439
+ kind: "mouse";
440
+ }>, onFrame: (mouse: NonNullable<DecryptedEnvelope["mouse"]>) => void, opts?: RequestOptions): Promise<LoginResponse>;
441
+ /**
442
+ * Push the currently-focused input's metadata + value to the
443
+ * wallet so the user can edit it on the phone. Pass `null` to
444
+ * clear the wallet's focus mirror (blur, page change, etc.).
445
+ *
446
+ * Used by [`enableRemoteNavigation`]; not part of the documented
447
+ * public API but exposed so the helper lives in a separate module
448
+ * without reaching into private fields. NaCl-boxed to the wallet's
449
+ * session pk on the way out.
450
+ *
451
+ * @internal
452
+ */
453
+ _sendFocus(focus: {
454
+ name: string;
455
+ label?: string;
456
+ inputType?: string;
457
+ value?: string;
458
+ placeholder?: string;
459
+ minLength?: number;
460
+ maxLength?: number;
461
+ min?: number;
462
+ max?: number;
463
+ pattern?: string;
464
+ required?: boolean;
465
+ options?: {
466
+ value: string;
467
+ label?: string;
468
+ }[];
469
+ /** Navigation-row visibility hints. Computed by
470
+ * `enableRemoteNavigation`'s `computeNavMeta` from the
471
+ * current tabbable pool and the focused element's
472
+ * surrounding form. The wallet renders only the buttons
473
+ * that match. See `bind.ts:computeNavMeta` + the wallet's
474
+ * `_navigationRow`. */
475
+ hasPrev?: boolean;
476
+ hasNext?: boolean;
477
+ isLastInForm?: boolean;
478
+ isButton?: boolean;
479
+ /** File-input attributes. Present only when the focused
480
+ * element is `<input type="file">`; drives the wallet's
481
+ * picker UI (camera vs gallery vs files filtered by
482
+ * MIME). `accept` is the raw `accept` attribute string
483
+ * (e.g. `"image/*,application/pdf"`); the wallet
484
+ * normalises it. `multiple` enables multi-select on the
485
+ * picker. `capture` (`"user"` / `"environment"`) hints
486
+ * which camera the host expects when the user opens the
487
+ * camera mode. */
488
+ accept?: string;
489
+ multiple?: boolean;
490
+ capture?: string;
491
+ } | null): Promise<void>;
492
+ /**
493
+ * Install a `pagehide` listener that fires a synchronous
494
+ * `browser-revoke` envelope at the wallet right before the tab
495
+ * closes / refreshes / navigates away. Without this the wallet
496
+ * has to wait for the slower transport-collapse pathway
497
+ * (`peer-gone` over the signaling WS + ICE failure on the data
498
+ * channel) to learn the browser is gone — long enough for the
499
+ * connection-status dot to oscillate and any in-flight ack
500
+ * promises to time out.
501
+ *
502
+ * `pagehide` is preferred over `beforeunload` because:
503
+ * * it fires for bfcache evictions (back/forward navigation
504
+ * on iOS Safari), tab closes, AND refreshes
505
+ * * `beforeunload` is increasingly restricted by browsers
506
+ * for non-blocking-prompt use
507
+ *
508
+ * The envelope itself rides through the same NaCl box as every
509
+ * other browser→wallet message. We can't await the ack — the
510
+ * page is being torn down — so this is a true fire-and-forget;
511
+ * the wallet's [LoginSession.inbound] handler treats receipt
512
+ * as the trigger to close.
513
+ */
514
+ private _installUnloadGuard;
515
+ /**
516
+ * Browser→wallet pause-state notification. The wallet's mouse
517
+ * controller dims its surface + shows "Remote control paused"
518
+ * while the page is in the background. Fire-and-forget over
519
+ * NaCl-box to the wallet's session pk; loss is acceptable
520
+ * (we re-fire on every focus / blur).
521
+ *
522
+ * @internal
523
+ */
524
+ _sendControlStatus(paused: boolean): Promise<void>;
525
+ /**
526
+ * Install the ambient `mouse-update` handler. Mirrors
527
+ * [`_setRemoteNavListener`] — only one ambient subscriber at a
528
+ * time (last call wins). Used by [`bindMouse`] when the
529
+ * session was pre-granted mouse control at sign-in
530
+ * ([SignInOptions.mouseControl]).
531
+ *
532
+ * @internal
533
+ */
534
+ _setAmbientMouseHandler(cb: ((mouse: NonNullable<DecryptedEnvelope["mouse"]>) => void) | null): Unsubscribe;
535
+ /**
536
+ * Install the file-envelope handler. Mirrors
537
+ * [`_setAmbientMouseHandler`] — only one handler at a time;
538
+ * [`enableRemoteNavigation`] owns it during its lifetime and
539
+ * tears it down on disposal so the next mount can install a
540
+ * fresh one. The handler receives `file-begin` / `file-chunk` /
541
+ * `file-end` envelopes in arrival order; assembly + DOM
542
+ * dispatch lives in [`bind.ts`].
543
+ *
544
+ * @internal
545
+ */
546
+ _setFileEnvelopeHandler(cb: ((envelope: DecryptedEnvelope) => void) | null): Unsubscribe;
547
+ /**
548
+ * Install the remote-navigation listener. Replaces any prior
549
+ * listener — only one is active at a time. Returns an unsubscribe
550
+ * handle. Used by [`enableRemoteNavigation`].
551
+ *
552
+ * @internal
553
+ */
554
+ _setRemoteNavListener(cb: ((envelope: {
555
+ msg: "nav";
556
+ action: "prev" | "next" | "submit";
557
+ } | {
558
+ msg: "value";
559
+ value: string;
560
+ } | {
561
+ msg: "logout";
562
+ }) => void) | null): Unsubscribe;
563
+ private _sendRequest;
564
+ /**
565
+ * Fire a single event to per-type listeners + onAny subscribers.
566
+ * Listener errors are swallowed so one buggy host listener can't
567
+ * break the rest of the dispatch (or close the session).
568
+ */
569
+ private _dispatch;
570
+ private _armExpiryTimer;
571
+ private _handleMessage;
572
+ private _markSeen;
573
+ /** Auto-ack any inbound envelope that carries an `id`, except
574
+ * protocol primitives. `ping` is implicitly acked by `pong`;
575
+ * `pong` and `ack` would loop. */
576
+ private _sendAckFor;
577
+ private _handleAck;
578
+ private _sendPing;
579
+ private _sendPong;
580
+ private _handlePong;
581
+ private _armOfflineTimer;
582
+ private _setConnectionStatus;
583
+ /** Send a JSON envelope with ack tracking + retry. Stamps a fresh
584
+ * `id` onto [body] and retransmits every [ACK_RETRY_DELAY_MS]
585
+ * until the matching ack lands or [ACK_MAX_ATTEMPTS] is reached.
586
+ * Resolves with `true` on ack, `false` on exhaustion. */
587
+ private _sendWithAck;
588
+ /**
589
+ * Pure dispatch entry-point — takes an already-decrypted envelope
590
+ * and routes it through the same per-message handlers
591
+ * `_handleMessage` does after decryption. Public-but-prefixed so
592
+ * unit tests can exercise the dispatch contract without
593
+ * constructing real NaCl-boxed ciphertext.
594
+ *
595
+ * NOT part of the documented public API; treat as @internal.
596
+ */
597
+ _dispatchDecryptedForTest(envelope: DecryptedEnvelope): Promise<void>;
598
+ private _handleRenewal;
599
+ /**
600
+ * Verify a renewal / claim-update presentation and enforce in-session
601
+ * anti-replay: same holder key, a holder-signed `iat` strictly newer
602
+ * than the last accepted presentation, and never a presentation this
603
+ * session already accepted. Returns null (drop it) otherwise.
604
+ */
605
+ private _verifyFresh;
606
+ /**
607
+ * Verify the embedded presentation, then diff its claims against
608
+ * the cached snapshot and emit name-only per-claim events. The
609
+ * actual claim values land in `this._claimsSnapshot` (accessible
610
+ * via `session.claims`) but **never** in the event payloads —
611
+ * see the privacy note on the [LoginEvent] type.
612
+ *
613
+ * Re-verifies against the same audience + accepted-VCT set as the
614
+ * initial sign-in. A `claim-update` whose presentation fails
615
+ * verification is dropped silently — fail-closed. Same for a
616
+ * cnf-mismatch (the wallet swapped per-domain key under us).
617
+ *
618
+ * The wire-level `envelope.delta` is intentionally ignored — we
619
+ * recompute the diff from the verified SD-JWT so a malicious
620
+ * wallet can't lie about which claim changed. The wallet should
621
+ * not include values in `envelope.delta` at all (the wire
622
+ * grammar in `crypto.ts` documents this as name-only); we'd
623
+ * ignore them even if it did.
624
+ */
625
+ private _handleClaimUpdate;
626
+ /**
627
+ * Display-only update. Fires `display_name_changed` and/or
628
+ * `avatar_changed` based on which fields the envelope carries.
629
+ * NOT cryptographically verified — partner sites should treat
630
+ * the payload as advisory (refresh the cosmetic UI) and not
631
+ * grant any privileged access on the basis of these values.
632
+ */
633
+ private _handleDisplayUpdate;
634
+ /**
635
+ * Credential-revoked. Fires `credential_revoked` with the
636
+ * wallet-supplied reason, then tears the session down with
637
+ * `signed_out / reason="credential_revoked"`. Both events land
638
+ * before the transport closes.
639
+ */
640
+ private _handleCredentialRevoked;
641
+ private _teardown;
642
+ }
643
+ type VerifierContext = Omit<VerifyOptions, "expectedNonce"> & {
644
+ expectedNonceFactory: () => string;
645
+ };