@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 CHANGED
@@ -1,14 +1,26 @@
1
1
  import * as _sinclair_typebox from '@sinclair/typebox';
2
2
  import { Static } from '@sinclair/typebox';
3
3
 
4
- /** Binary viewer frame: [type u8][width u16 BE][height u16 BE][JPEG bytes]. Width/height are page CSS pixels. */
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
- declare function encodeFrame(f: Frame): Uint8Array;
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
- /** Send this takeover to the user's paired phones (Unstuck Cloud); undefined means yes, false skips it. */
80
- alerts?: boolean;
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 encodeFrame(f) {
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
- return { width: view.getUint16(1), height: view.getUint16(3), jpeg: b.slice(HEADER) };
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({ t: Lit("ready"), reason: Type.String(), site: Type.String(), expiresAt: Num, resumeKey: Type.String(), vn: Type.Optional(Type.String()) }),
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
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velmlabs/unstuck-protocol",
3
- "version": "0.1.7",
3
+ "version": "0.2.1",
4
4
  "description": "Wire protocol shared by the Unstuck engine, viewer and relays (frames, RPC, end-to-end encryption).",
5
5
  "keywords": [
6
6
  "ai",