@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.
- package/LICENSE +202 -0
- package/README.md +348 -2
- package/dist/api.d.ts +59 -0
- package/dist/api.js +40 -0
- package/dist/bind.d.ts +224 -0
- package/dist/bind.js +1384 -0
- package/dist/crypto.d.ts +352 -0
- package/dist/crypto.js +159 -0
- package/dist/index.d.ts +345 -0
- package/dist/index.js +6102 -0
- package/dist/index.js.map +7 -0
- package/dist/notify.d.ts +8 -0
- package/dist/notify.js +17 -0
- package/dist/point_phone_overlay.d.ts +41 -0
- package/dist/point_phone_overlay.js +157 -0
- package/dist/qr.d.ts +105 -0
- package/dist/qr.js +149 -0
- package/dist/requests.d.ts +279 -0
- package/dist/requests.js +128 -0
- package/dist/select_overlay.d.ts +70 -0
- package/dist/select_overlay.js +426 -0
- package/dist/session.d.ts +639 -0
- package/dist/session.js +1436 -0
- package/dist/signaling.d.ts +59 -0
- package/dist/signaling.js +91 -0
- package/dist/status.d.ts +48 -0
- package/dist/status.js +105 -0
- package/dist/transport.d.ts +45 -0
- package/dist/transport.js +183 -0
- package/dist/verification.d.ts +56 -0
- package/dist/verification.js +169 -0
- package/dist/verify.d.ts +69 -0
- package/dist/verify.js +331 -0
- package/package.json +59 -4
|
@@ -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
|
+
};
|