@velmlabs/unstuck-protocol 0.1.7 → 0.2.1
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/dist/index.d.ts +36 -6
- package/dist/index.js +47 -6
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,14 +1,26 @@
|
|
|
1
1
|
import * as _sinclair_typebox from '@sinclair/typebox';
|
|
2
2
|
import { Static } from '@sinclair/typebox';
|
|
3
3
|
|
|
4
|
-
/**
|
|
4
|
+
/**
|
|
5
|
+
* Binary viewer frames. Width/height are page CSS pixels.
|
|
6
|
+
* - type 1: [0x01][width u16 BE][height u16 BE][JPEG bytes]
|
|
7
|
+
* - type 2: [0x02][seq u32 BE][width u16 BE][height u16 BE][JPEG bytes] — only sent to a viewer that opted in to frame
|
|
8
|
+
* credit (`{ t: 'credit', v: 1 }`), which acks each drawn frame by its sequence number.
|
|
9
|
+
*/
|
|
5
10
|
declare const FRAME_TYPE_JPEG = 1;
|
|
11
|
+
declare const FRAME_TYPE_JPEG_SEQ = 2;
|
|
12
|
+
declare const FRAME_SEQ_MAX = 4294967295;
|
|
6
13
|
interface Frame {
|
|
7
14
|
width: number;
|
|
8
15
|
height: number;
|
|
9
16
|
jpeg: Uint8Array;
|
|
17
|
+
/** Set on type-2 frames: the number the viewer acks once it has drawn the frame. */
|
|
18
|
+
seq?: number;
|
|
10
19
|
}
|
|
11
|
-
|
|
20
|
+
/** Encodes a type-1 frame, or a type-2 frame when `seq` is given. */
|
|
21
|
+
declare function encodeFrame(f: Pick<Frame, 'width' | 'height' | 'jpeg'>, seq?: number): Uint8Array;
|
|
22
|
+
/** The same frame as type 2 with this sequence number, from an encoded type-1 frame (the engine caches those). */
|
|
23
|
+
declare function withFrameSeq(type1: Uint8Array, seq: number): Uint8Array;
|
|
12
24
|
declare function decodeFrame(b: Uint8Array): Frame | null;
|
|
13
25
|
|
|
14
26
|
declare class RpcCallError extends Error {
|
|
@@ -76,8 +88,12 @@ interface TakeoverParams {
|
|
|
76
88
|
requireCode?: boolean;
|
|
77
89
|
/** Sites besides the page's own the human may navigate to, e.g. ["accounts.google.com"] (page lock). */
|
|
78
90
|
allowedSites?: string[];
|
|
79
|
-
/**
|
|
80
|
-
|
|
91
|
+
/**
|
|
92
|
+
* Send this takeover to the user's paired phones (Unstuck Cloud); undefined means yes, false skips it. 'required' fails
|
|
93
|
+
* the takeover with `alert_failed` when Unstuck Cloud can't accept the link for at least one paired phone; without
|
|
94
|
+
* Unstuck Cloud the engine answers the request with error code `config_error`.
|
|
95
|
+
*/
|
|
96
|
+
alerts?: boolean | 'required';
|
|
81
97
|
}
|
|
82
98
|
interface CdpSendParams {
|
|
83
99
|
pageId: string;
|
|
@@ -117,6 +133,10 @@ interface TakeoverResult {
|
|
|
117
133
|
sessionId: string;
|
|
118
134
|
url: string;
|
|
119
135
|
durationS: number;
|
|
136
|
+
/**
|
|
137
|
+
* Why it ended, when there is more to say: e.g. `page_closed`, `viewer_left`, `engine_closed`, `alert_failed` (with
|
|
138
|
+
* `alerts: 'required'`, the link reached no paired phone), or the human's own words after Can't solve.
|
|
139
|
+
*/
|
|
120
140
|
detail?: string;
|
|
121
141
|
}
|
|
122
142
|
|
|
@@ -160,6 +180,12 @@ declare const ViewerToEngineSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.
|
|
|
160
180
|
reason: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
|
|
161
181
|
}>, _sinclair_typebox.TObject<{
|
|
162
182
|
t: _sinclair_typebox.TLiteral<"ping">;
|
|
183
|
+
}>, _sinclair_typebox.TObject<{
|
|
184
|
+
t: _sinclair_typebox.TLiteral<"credit">;
|
|
185
|
+
v: _sinclair_typebox.TLiteral<1>;
|
|
186
|
+
}>, _sinclair_typebox.TObject<{
|
|
187
|
+
t: _sinclair_typebox.TLiteral<"ack">;
|
|
188
|
+
seq: _sinclair_typebox.TInteger;
|
|
163
189
|
}>]>;
|
|
164
190
|
type ViewerToEngine = Static<typeof ViewerToEngineSchema>;
|
|
165
191
|
type ViewerInput = Extract<ViewerToEngine, {
|
|
@@ -186,6 +212,7 @@ declare const EngineToViewerSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.
|
|
|
186
212
|
expiresAt: _sinclair_typebox.TNumber;
|
|
187
213
|
resumeKey: _sinclair_typebox.TString;
|
|
188
214
|
vn: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
|
|
215
|
+
credit: _sinclair_typebox.TOptional<_sinclair_typebox.TLiteral<1>>;
|
|
189
216
|
}>, _sinclair_typebox.TObject<{
|
|
190
217
|
t: _sinclair_typebox.TLiteral<"state">;
|
|
191
218
|
status: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<string>[]>;
|
|
@@ -215,13 +242,16 @@ declare const EngineToViewerSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.
|
|
|
215
242
|
kind: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"text" | "numeric" | "otp" | "email" | "password">[]>;
|
|
216
243
|
}>>;
|
|
217
244
|
}>]>;
|
|
218
|
-
type EngineToViewer =
|
|
245
|
+
type EngineToViewer =
|
|
246
|
+
/** `credit: 1`: this engine paces frames by the viewer's acks once the viewer opts in with `{ t: 'credit', v: 1 }`. */
|
|
247
|
+
{
|
|
219
248
|
t: 'ready';
|
|
220
249
|
reason: string;
|
|
221
250
|
site: string;
|
|
222
251
|
expiresAt: number;
|
|
223
252
|
resumeKey: string;
|
|
224
253
|
vn?: string;
|
|
254
|
+
credit?: 1;
|
|
225
255
|
} | {
|
|
226
256
|
t: 'state';
|
|
227
257
|
status: SessionStatus;
|
|
@@ -369,5 +399,5 @@ declare function parseAlertFragment(hash: string): {
|
|
|
369
399
|
blob: string;
|
|
370
400
|
} | null;
|
|
371
401
|
|
|
372
|
-
export { EngineToViewerSchema, FRAME_TYPE_JPEG, FieldKinds, FieldSchema, KEY_SUBPROTOCOL_PREFIX, Methods, PROTOCOL_VERSION, RELAY_CLOSE, RELAY_LIMITS, RELAY_SUBPROTOCOL, RESUME_WINDOW_MS, RpcCallError, SESSION_ID_RE, SessionStatusSchema, ViewerErrorCodes, ViewerToEngineSchema, b64urlDecode, b64urlEncode, createRpcPeer, decodeEnvelope, decodeFrame, encodeEnvelope, encodeFrame, exportDevicePublicKey, importE2eKey, isJsonPlaintext, newConnNonce, newDeviceKeyPair, newE2eKey, open, openAlert, openMsg, padPlaintext, parseAgentToRelay, parseAlertFragment, parseRelayToAgent, parseViewerMessage, seal, sealAlert, sealMsg };
|
|
402
|
+
export { EngineToViewerSchema, FRAME_SEQ_MAX, FRAME_TYPE_JPEG, FRAME_TYPE_JPEG_SEQ, FieldKinds, FieldSchema, KEY_SUBPROTOCOL_PREFIX, Methods, PROTOCOL_VERSION, RELAY_CLOSE, RELAY_LIMITS, RELAY_SUBPROTOCOL, RESUME_WINDOW_MS, RpcCallError, SESSION_ID_RE, SessionStatusSchema, ViewerErrorCodes, ViewerToEngineSchema, b64urlDecode, b64urlEncode, createRpcPeer, decodeEnvelope, decodeFrame, encodeEnvelope, encodeFrame, exportDevicePublicKey, importE2eKey, isJsonPlaintext, newConnNonce, newDeviceKeyPair, newE2eKey, open, openAlert, openMsg, padPlaintext, parseAgentToRelay, parseAlertFragment, parseRelayToAgent, parseViewerMessage, seal, sealAlert, sealMsg, withFrameSeq };
|
|
373
403
|
export type { AgentToRelay, AlertPayload, CdpClosedParams, CdpEventParams, CdpSendParams, CdpSubscribeParams, Direction, EngineToViewer, Field, FieldKind, Frame, HelloParams, HelloResult, PagePopupParams, RelayToAgent, RpcError, RpcNotification, RpcPeer, RpcRequest, RpcResponse, SessionStatus, TakeoverLinkParams, TakeoverParams, TakeoverResult, TakeoverStatus, ViewerErrorCode, ViewerInput, ViewerToEngine };
|
package/dist/index.js
CHANGED
|
@@ -1,10 +1,16 @@
|
|
|
1
1
|
// src/frame.ts
|
|
2
2
|
var FRAME_TYPE_JPEG = 1;
|
|
3
|
+
var FRAME_TYPE_JPEG_SEQ = 2;
|
|
4
|
+
var FRAME_SEQ_MAX = 4294967295;
|
|
3
5
|
var HEADER = 5;
|
|
6
|
+
var SEQ_BYTES = 4;
|
|
4
7
|
function checkU16(name, v) {
|
|
5
8
|
if (!Number.isInteger(v) || v < 0 || v > 65535) throw new RangeError(`${name} must be an integer 0..65535, got ${v}`);
|
|
6
9
|
}
|
|
7
|
-
function
|
|
10
|
+
function checkSeq(seq) {
|
|
11
|
+
if (!Number.isInteger(seq) || seq < 1 || seq > FRAME_SEQ_MAX) throw new RangeError(`seq must be an integer 1..${FRAME_SEQ_MAX}, got ${seq}`);
|
|
12
|
+
}
|
|
13
|
+
function encodeFrame(f, seq) {
|
|
8
14
|
checkU16("width", f.width);
|
|
9
15
|
checkU16("height", f.height);
|
|
10
16
|
const out = new Uint8Array(HEADER + f.jpeg.length);
|
|
@@ -13,12 +19,29 @@ function encodeFrame(f) {
|
|
|
13
19
|
view.setUint16(1, f.width);
|
|
14
20
|
view.setUint16(3, f.height);
|
|
15
21
|
out.set(f.jpeg, HEADER);
|
|
22
|
+
return seq === void 0 ? out : withFrameSeq(out, seq);
|
|
23
|
+
}
|
|
24
|
+
function withFrameSeq(type1, seq) {
|
|
25
|
+
if (type1.length < HEADER || type1[0] !== FRAME_TYPE_JPEG) throw new RangeError("not a type-1 frame");
|
|
26
|
+
checkSeq(seq);
|
|
27
|
+
const out = new Uint8Array(type1.length + SEQ_BYTES);
|
|
28
|
+
const view = new DataView(out.buffer);
|
|
29
|
+
view.setUint8(0, FRAME_TYPE_JPEG_SEQ);
|
|
30
|
+
view.setUint32(1, seq);
|
|
31
|
+
out.set(type1.subarray(1), 1 + SEQ_BYTES);
|
|
16
32
|
return out;
|
|
17
33
|
}
|
|
18
34
|
function decodeFrame(b) {
|
|
19
|
-
if (b.length < HEADER || b[0] !== FRAME_TYPE_JPEG) return null;
|
|
20
35
|
const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
|
|
21
|
-
|
|
36
|
+
if (b[0] === FRAME_TYPE_JPEG && b.length >= HEADER) {
|
|
37
|
+
return { width: view.getUint16(1), height: view.getUint16(3), jpeg: b.slice(HEADER) };
|
|
38
|
+
}
|
|
39
|
+
if (b[0] === FRAME_TYPE_JPEG_SEQ && b.length >= HEADER + SEQ_BYTES) {
|
|
40
|
+
const seq = view.getUint32(1);
|
|
41
|
+
if (seq === 0) return null;
|
|
42
|
+
return { width: view.getUint16(5), height: view.getUint16(7), jpeg: b.slice(HEADER + SEQ_BYTES), seq };
|
|
43
|
+
}
|
|
44
|
+
return null;
|
|
22
45
|
}
|
|
23
46
|
|
|
24
47
|
// src/rpc.ts
|
|
@@ -163,14 +186,29 @@ var ViewerToEngineSchema = Type.Union([
|
|
|
163
186
|
Type.Object({ t: Lit("text"), text: Type.String() }, { additionalProperties: false }),
|
|
164
187
|
Type.Object({ t: Lit("done") }, { additionalProperties: false }),
|
|
165
188
|
Type.Object({ t: Lit("cant_solve"), reason: Type.Optional(Type.String({ maxLength: 200 })) }, { additionalProperties: false }),
|
|
166
|
-
Type.Object({ t: Lit("ping") }, { additionalProperties: false })
|
|
189
|
+
Type.Object({ t: Lit("ping") }, { additionalProperties: false }),
|
|
190
|
+
/**
|
|
191
|
+
* Frame credit opt-in, sent only to an engine whose ready says `credit: 1` (older engines refuse unknown messages):
|
|
192
|
+
* from now on the engine sends type-2 frames and keeps at most a few (CREDIT_MAX_IN_FLIGHT in core) unacknowledged.
|
|
193
|
+
*/
|
|
194
|
+
Type.Object({ t: Lit("credit"), v: Type.Literal(1) }, { additionalProperties: false }),
|
|
195
|
+
/** This frame (and every earlier one) has been drawn. */
|
|
196
|
+
Type.Object({ t: Lit("ack"), seq: Type.Integer({ minimum: 1, maximum: 4294967295 }) }, { additionalProperties: false })
|
|
167
197
|
]);
|
|
168
198
|
var ViewerErrorCodes = ["token_invalid", "token_used", "expired", "session_closed", "bad_message", "code_required", "code_invalid"];
|
|
169
199
|
var FieldKinds = ["text", "numeric", "otp", "email", "password"];
|
|
170
200
|
var FieldKindSchema = Type.Union(FieldKinds.map((k) => Lit(k)));
|
|
171
201
|
var FieldSchema = Type.Object({ x: Num, y: Num, w: Num, h: Num, kind: FieldKindSchema }, { additionalProperties: false });
|
|
172
202
|
var EngineToViewerSchema = Type.Union([
|
|
173
|
-
Type.Object({
|
|
203
|
+
Type.Object({
|
|
204
|
+
t: Lit("ready"),
|
|
205
|
+
reason: Type.String(),
|
|
206
|
+
site: Type.String(),
|
|
207
|
+
expiresAt: Num,
|
|
208
|
+
resumeKey: Type.String(),
|
|
209
|
+
vn: Type.Optional(Type.String()),
|
|
210
|
+
credit: Type.Optional(Type.Literal(1))
|
|
211
|
+
}),
|
|
174
212
|
Type.Object({ t: Lit("state"), status: SessionStatusSchema }),
|
|
175
213
|
Type.Object({ t: Lit("error"), code: Type.Union(ViewerErrorCodes.map((c) => Lit(c))), message: Type.String() }),
|
|
176
214
|
Type.Object({ t: Lit("pong") }),
|
|
@@ -417,7 +455,9 @@ function parseAlertFragment(hash) {
|
|
|
417
455
|
}
|
|
418
456
|
export {
|
|
419
457
|
EngineToViewerSchema,
|
|
458
|
+
FRAME_SEQ_MAX,
|
|
420
459
|
FRAME_TYPE_JPEG,
|
|
460
|
+
FRAME_TYPE_JPEG_SEQ,
|
|
421
461
|
FieldKinds,
|
|
422
462
|
FieldSchema,
|
|
423
463
|
KEY_SUBPROTOCOL_PREFIX,
|
|
@@ -455,5 +495,6 @@ export {
|
|
|
455
495
|
parseViewerMessage,
|
|
456
496
|
seal,
|
|
457
497
|
sealAlert,
|
|
458
|
-
sealMsg
|
|
498
|
+
sealMsg,
|
|
499
|
+
withFrameSeq
|
|
459
500
|
};
|