@velmlabs/unstuck-protocol 0.1.4 → 0.1.5

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
@@ -74,6 +74,8 @@ interface TakeoverParams {
74
74
  site?: string;
75
75
  /** Ask the human for a 6-digit code delivered with the link (relay spec §5.8). */
76
76
  requireCode?: boolean;
77
+ /** Sites besides the page's own the human may navigate to, e.g. ["accounts.google.com"] (page lock). */
78
+ allowedSites?: string[];
77
79
  }
78
80
  interface CdpSendParams {
79
81
  pageId: string;
@@ -123,6 +125,8 @@ declare const ViewerToEngineSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.
123
125
  token: _sinclair_typebox.TString;
124
126
  resumeKey: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
125
127
  code: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
128
+ /** The viewer's random value for this connection; engines that announce v: 2 echo it in ready (anti-replay). */
129
+ vn: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
126
130
  }>, _sinclair_typebox.TObject<{
127
131
  t: _sinclair_typebox.TLiteral<"mouse">;
128
132
  action: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"down">, _sinclair_typebox.TLiteral<"up">, _sinclair_typebox.TLiteral<"move">]>;
@@ -179,6 +183,7 @@ declare const EngineToViewerSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.
179
183
  site: _sinclair_typebox.TString;
180
184
  expiresAt: _sinclair_typebox.TNumber;
181
185
  resumeKey: _sinclair_typebox.TString;
186
+ vn: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
182
187
  }>, _sinclair_typebox.TObject<{
183
188
  t: _sinclair_typebox.TLiteral<"state">;
184
189
  status: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<string>[]>;
@@ -214,6 +219,7 @@ type EngineToViewer = {
214
219
  site: string;
215
220
  expiresAt: number;
216
221
  resumeKey: string;
222
+ vn?: string;
217
223
  } | {
218
224
  t: 'state';
219
225
  status: SessionStatus;
@@ -247,6 +253,11 @@ declare const RELAY_LIMITS: {
247
253
  readonly agentPayloadMax: 2097152;
248
254
  readonly viewerPayloadMax: 65536;
249
255
  readonly viewersPerSession: 4;
256
+ /** Viewers that haven't been confirmed (see relay-core attachViewer) one client IP may hold in one session. */
257
+ readonly unconfirmedViewersPerIp: 2;
258
+ /** Viewer → agent bytes one viewer connection may send per window. */
259
+ readonly viewerBytesPerWindow: 2097152;
260
+ readonly viewerByteWindowMs: 10000;
250
261
  readonly idleMs: 120000;
251
262
  readonly heartbeatMs: 30000;
252
263
  readonly graceMs: 60000;
@@ -255,12 +266,16 @@ declare const RELAY_LIMITS: {
255
266
  readonly backpressureBytes: 4194304;
256
267
  readonly viewerUpgradesPerMinPerIp: 30;
257
268
  readonly agentUpgradesPerMinPerKey: 20;
269
+ /** Agent upgrades per client IP per minute, counted on refused authorizations only (key brute force). */
270
+ readonly agentAuthFailuresPerMinPerIp: 10;
258
271
  };
259
272
  declare const RELAY_CLOSE: {
260
273
  readonly agentReconnecting: 1012;
261
274
  readonly replaced: 4409;
262
275
  readonly badMessage: 1003;
263
276
  readonly tooBig: 1009;
277
+ readonly policy: 1008;
278
+ readonly tryAgainLater: 1013;
264
279
  /** A refused agent: 4000 + the HTTP status (4401, 4402, 4403, 4429). Clients can't read upgrade statuses. */
265
280
  readonly refused: (status: number) => number;
266
281
  };
@@ -313,6 +328,11 @@ declare function b64urlEncode(b: Uint8Array): string;
313
328
  declare function b64urlDecode(s: string): Uint8Array | null;
314
329
  /** Plaintext JSON messages start with '{'; screen frames start with their type byte (0x01). */
315
330
  declare const isJsonPlaintext: (p: Uint8Array) => boolean;
331
+ /**
332
+ * Pads a JSON plaintext with trailing spaces (still valid JSON for any peer) to 256 bytes, then to the next power of
333
+ * two up to what still fits 64 KB once sealed, so a relay can't tell keys, digits or the length of typed text from message sizes.
334
+ */
335
+ declare function padPlaintext(p: Uint8Array): Uint8Array;
316
336
  /**
317
337
  * Replay protection (relay spec §5.4): every message on a viewer connection is bound to that connection's random
318
338
  * nonce (sent by the engine in a sealed challenge) and carries a sequence number the receiver requires to increase.
@@ -326,5 +346,5 @@ declare function openMsg(key: CryptoKey, sessionId: string, dir: Direction, conn
326
346
  plain: Uint8Array;
327
347
  } | null>;
328
348
 
329
- 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, importE2eKey, isJsonPlaintext, newConnNonce, newE2eKey, open, openMsg, parseAgentToRelay, parseRelayToAgent, parseViewerMessage, seal, sealMsg };
349
+ 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, importE2eKey, isJsonPlaintext, newConnNonce, newE2eKey, open, openMsg, padPlaintext, parseAgentToRelay, parseRelayToAgent, parseViewerMessage, seal, sealMsg };
330
350
  export type { AgentToRelay, 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
@@ -126,7 +126,14 @@ var Num = Type.Number();
126
126
  var Lit = (v) => Type.Literal(v);
127
127
  var ViewerToEngineSchema = Type.Union([
128
128
  Type.Object(
129
- { t: Lit("hello"), token: Type.String(), resumeKey: Type.Optional(Type.String()), code: Type.Optional(Type.String({ pattern: "^[0-9]{6}$" })) },
129
+ {
130
+ t: Lit("hello"),
131
+ token: Type.String(),
132
+ resumeKey: Type.Optional(Type.String()),
133
+ code: Type.Optional(Type.String({ pattern: "^[0-9]{6}$" })),
134
+ /** The viewer's random value for this connection; engines that announce v: 2 echo it in ready (anti-replay). */
135
+ vn: Type.Optional(Type.String({ pattern: "^[A-Za-z0-9_-]{16,64}$" }))
136
+ },
130
137
  { additionalProperties: false }
131
138
  ),
132
139
  Type.Object(
@@ -155,7 +162,7 @@ var ViewerToEngineSchema = Type.Union([
155
162
  ),
156
163
  Type.Object({ t: Lit("text"), text: Type.String() }, { additionalProperties: false }),
157
164
  Type.Object({ t: Lit("done") }, { additionalProperties: false }),
158
- Type.Object({ t: Lit("cant_solve"), reason: Type.Optional(Type.String()) }, { additionalProperties: false }),
165
+ Type.Object({ t: Lit("cant_solve"), reason: Type.Optional(Type.String({ maxLength: 200 })) }, { additionalProperties: false }),
159
166
  Type.Object({ t: Lit("ping") }, { additionalProperties: false })
160
167
  ]);
161
168
  var ViewerErrorCodes = ["token_invalid", "token_used", "expired", "session_closed", "bad_message", "code_required", "code_invalid"];
@@ -163,7 +170,7 @@ var FieldKinds = ["text", "numeric", "otp", "email", "password"];
163
170
  var FieldKindSchema = Type.Union(FieldKinds.map((k) => Lit(k)));
164
171
  var FieldSchema = Type.Object({ x: Num, y: Num, w: Num, h: Num, kind: FieldKindSchema }, { additionalProperties: false });
165
172
  var EngineToViewerSchema = Type.Union([
166
- Type.Object({ t: Lit("ready"), reason: Type.String(), site: Type.String(), expiresAt: Num, resumeKey: Type.String() }),
173
+ Type.Object({ t: Lit("ready"), reason: Type.String(), site: Type.String(), expiresAt: Num, resumeKey: Type.String(), vn: Type.Optional(Type.String()) }),
167
174
  Type.Object({ t: Lit("state"), status: SessionStatusSchema }),
168
175
  Type.Object({ t: Lit("error"), code: Type.Union(ViewerErrorCodes.map((c) => Lit(c))), message: Type.String() }),
169
176
  Type.Object({ t: Lit("pong") }),
@@ -191,6 +198,11 @@ var RELAY_LIMITS = {
191
198
  agentPayloadMax: 2097152,
192
199
  viewerPayloadMax: 65536,
193
200
  viewersPerSession: 4,
201
+ /** Viewers that haven't been confirmed (see relay-core attachViewer) one client IP may hold in one session. */
202
+ unconfirmedViewersPerIp: 2,
203
+ /** Viewer → agent bytes one viewer connection may send per window. */
204
+ viewerBytesPerWindow: 2097152,
205
+ viewerByteWindowMs: 1e4,
194
206
  idleMs: 12e4,
195
207
  heartbeatMs: 3e4,
196
208
  graceMs: 6e4,
@@ -198,18 +210,27 @@ var RELAY_LIMITS = {
198
210
  billableBytes: 4096,
199
211
  backpressureBytes: 4194304,
200
212
  viewerUpgradesPerMinPerIp: 30,
201
- agentUpgradesPerMinPerKey: 20
213
+ agentUpgradesPerMinPerKey: 20,
214
+ /** Agent upgrades per client IP per minute, counted on refused authorizations only (key brute force). */
215
+ agentAuthFailuresPerMinPerIp: 10
202
216
  };
203
217
  var RELAY_CLOSE = {
204
218
  agentReconnecting: 1012,
205
219
  replaced: 4409,
206
220
  badMessage: 1003,
207
221
  tooBig: 1009,
222
+ policy: 1008,
223
+ tryAgainLater: 1013,
208
224
  /** A refused agent: 4000 + the HTTP status (4401, 4402, 4403, 4429). Clients can't read upgrade statuses. */
209
225
  refused: (status) => 4e3 + status
210
226
  };
211
227
  var C = Type2.Integer({ minimum: 1, maximum: 4294967295 });
212
228
  var strict = { additionalProperties: false };
229
+ var CloseCode = Type2.Union([
230
+ Type2.Integer({ minimum: 1e3, maximum: 1003 }),
231
+ Type2.Integer({ minimum: 1007, maximum: 1014 }),
232
+ Type2.Integer({ minimum: 3e3, maximum: 4999 })
233
+ ]);
213
234
  var RelayToAgentSchema = Type2.Union([
214
235
  Type2.Object({ t: Type2.Literal("open"), c: C }, strict),
215
236
  Type2.Object({ t: Type2.Literal("close"), c: C }, strict),
@@ -218,7 +239,7 @@ var RelayToAgentSchema = Type2.Union([
218
239
  ]);
219
240
  var AgentToRelaySchema = Type2.Union([
220
241
  Type2.Object({ t: Type2.Literal("hello"), expiresAt: Type2.Number(), secret: Type2.String({ minLength: 1, maxLength: 128 }) }, strict),
221
- Type2.Object({ t: Type2.Literal("close"), c: C, code: Type2.Integer() }, strict),
242
+ Type2.Object({ t: Type2.Literal("close"), c: C, code: CloseCode }, strict),
222
243
  Type2.Object({ t: Type2.Literal("pong") }, strict),
223
244
  Type2.Object({ t: Type2.Literal("end") }, strict),
224
245
  Type2.Object({ t: Type2.Literal("event"), name: Type2.String({ maxLength: 64 }) }, strict)
@@ -293,6 +314,18 @@ function b64urlDecode(s) {
293
314
  }
294
315
  }
295
316
  var isJsonPlaintext = (p) => p[0] === 123;
317
+ var PAD_MIN = 256;
318
+ var PAD_MAX = 65536 - 32;
319
+ function padPlaintext(p) {
320
+ if (p.length >= PAD_MAX) return p;
321
+ let size = PAD_MIN;
322
+ while (size < p.length) size *= 2;
323
+ size = Math.min(size, PAD_MAX);
324
+ if (size === p.length) return p;
325
+ const out = new Uint8Array(size).fill(32);
326
+ out.set(p);
327
+ return out;
328
+ }
296
329
  var newConnNonce = () => b64urlEncode(crypto.getRandomValues(new Uint8Array(16)));
297
330
  var msgAad = (sessionId, dir, conn, seq) => enc.encode(`unstuck/1|${sessionId}|${dir}|${conn}|${seq}`);
298
331
  async function sealMsg(key, sessionId, dir, conn, seq, plain) {
@@ -348,6 +381,7 @@ export {
348
381
  newE2eKey,
349
382
  open,
350
383
  openMsg,
384
+ padPlaintext,
351
385
  parseAgentToRelay,
352
386
  parseRelayToAgent,
353
387
  parseViewerMessage,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velmlabs/unstuck-protocol",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
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",