ulda-auth 1.0.1 → 1.1.0

package/src/transfer.js

@@ -0,0 +1,80 @@
+import { check } from './errors.js';
+import { LIMITS, binary, exact, id, equal } from './values.js';
+
+export function needsTransfer(items) {
+  return items.length > LIMITS.batch || items.some(x => (x.payload?.byteLength ?? 0) > LIMITS.payloadBytes)
+    || items.reduce((n, x) => n + x.witness.byteLength + (x.payload?.byteLength ?? 0), 0) > LIMITS.messageBytes;
+}
+
+// Only ciphertext/proofs from SDK packet handles enter this generator.
+export function* fragments(items) {
+  let group = [], bytes = 0;
+  for (const item of items) {
+    const size = item.witness.byteLength + (item.payload?.byteLength ?? 0);
+    if (group.length && (group.length === LIMITS.batch || bytes + size > LIMITS.messageBytes || size > LIMITS.payloadBytes)) {
+      yield { kind: 'append', items: group }; group = []; bytes = 0;
+    }
+    if ((item.payload?.byteLength ?? 0) > LIMITS.payloadBytes) {
+      for (let offset = 0; offset < item.payload.length; offset += LIMITS.jsonBytes) {
+        yield { kind: 'part', ...(item.id === undefined ? {} : { resourceId: item.id }),
+          witness: item.witness, total: item.payload.length, offset,
+          payload: item.payload.subarray(offset, offset + LIMITS.jsonBytes) };
+      }
+    } else { group.push(item); bytes += size; }
+  }
+  if (group.length) yield { kind: 'append', items: group };
+}
+
+export class ChangeAssembly {
+  #items = [];
+  #partial;
+  #bytes;
+  constructor(count) {
+    check(Number.isSafeInteger(count) && count > 0 && count * 256 <= LIMITS.transferBytes, 'LIMIT');
+    this.count = count; this.#bytes = count * 256;
+  }
+  accept(frame) {
+    check(this.#items.length < this.count, 'INVALID_PACKET');
+    if (frame.kind === 'append') {
+      exact(frame, ['kind', 'items']);
+      check(!this.#partial && Array.isArray(frame.items) && frame.items.length > 0 && frame.items.length <= LIMITS.batch, 'INVALID_PACKET');
+      check(this.#items.length + frame.items.length <= this.count, 'INVALID_PACKET');
+      const prepared = frame.items.map(item => {
+        const payload = Object.hasOwn(item, 'payload');
+        exact(item, payload ? ['id', 'witness', 'payload'] : ['id']);
+        const witness = payload ? binary(item.witness, 167) : undefined;
+        const content = payload ? binary(item.payload) : undefined;
+        return { id: id(item.id), ...(payload ? { witness, payload: content } : {}) };
+      });
+      const bytes = prepared.reduce((n, x) => n + (x.witness?.length ?? 0) + (x.payload?.length ?? 0), 0);
+      check(bytes <= LIMITS.messageBytes && this.#bytes + bytes <= LIMITS.transferBytes, 'LIMIT');
+      this.#bytes += bytes;
+      for (const item of prepared) this.#items.push({ ...item, ...(item.payload ? { witness: item.witness.slice(), payload: item.payload.slice() } : {}) });
+    } else {
+      exact(frame, ['kind', 'resourceId', 'witness', 'total', 'offset', 'payload']);
+      check(frame.kind === 'part', 'INVALID_PACKET');
+      id(frame.resourceId);
+      const witness = binary(frame.witness, 167), payload = binary(frame.payload, LIMITS.jsonBytes);
+      check(Number.isSafeInteger(frame.total) && frame.total > 0 && frame.total <= LIMITS.resourceBytes, 'LIMIT');
+      check(Number.isSafeInteger(frame.offset) && frame.offset >= 0 && frame.offset + payload.length <= frame.total, 'INVALID_PACKET');
+      if (!this.#partial) {
+        check(frame.offset === 0 && this.#bytes + frame.total + witness.length <= LIMITS.transferBytes, 'LIMIT');
+        this.#bytes += frame.total + witness.length;
+        this.#partial = { id: frame.resourceId, witness: witness.slice(), payload: new Uint8Array(frame.total), offset: 0 };
+      }
+      const item = this.#partial;
+      check(item.id === frame.resourceId && item.offset === frame.offset && item.payload.length === frame.total && equal(item.witness, witness), 'INVALID_PACKET');
+      item.payload.set(payload, item.offset); item.offset += payload.length;
+      if (item.offset === item.payload.length) {
+        this.#items.push({ id: item.id, witness: item.witness, payload: item.payload }); this.#partial = undefined;
+      }
+    }
+  }
+  finish() {
+    check(!this.#partial && this.#items.length === this.count, 'INVALID_PACKET');
+    const updated = [], deleted = [];
+    for (const item of this.#items) item.payload === undefined ? deleted.push(item.id) : updated.push(item);
+    this.#items = [];
+    return { updated, deleted };
+  }
+}

package/src/transport.js

@@ -5,8 +5,10 @@ import {
   requestShape,
   acknowledgement,
   changed,
+  resource,
 } from "./protocol.js";
-import { LIMITS } from "./values.js";
+import { LIMITS, binary, equal, exact } from "./values.js";
+import { needsTransfer, fragments, ChangeAssembly } from './transfer.js';
 import { serverDiagnostic } from "./diagnostics.js";
 import { socketParser } from "./socket-parser.js";
 import { checkSignal } from "./reconnect.js";
@@ -40,6 +42,11 @@ export class SocketIoTransport {
   #generation = 0;
   #request = 0;
   #intentional = false;
+  #writeTail = Promise.resolve();
+  #readTail = Promise.resolve();
+  #transfers = 0;
+  #assembly;
+  #assemblyTimer;
   constructor(
     endpoint,
     { timeout = 10_000, allowInsecureLocalhost = false, diagnostics = false } = {},
@@ -68,6 +75,7 @@ export class SocketIoTransport {
       retries: 0,
       timeout,
       withCredentials: false,
+      auth: { uldaTransfer: 1 },
     });
     if (diagnostics) this.#socket.on("ulda:diagnostic", raw => {
       try {
@@ -78,13 +86,39 @@ export class SocketIoTransport {
       }
     });
     this.#socket.on("disconnect", () => {
+      clearTimeout(this.#assemblyTimer); this.#assembly = undefined;
       this.#trace(() => ({ phase: "connection", event: "disconnect" }));
       this.#generation++;
       this.#rejectPending();
       this.#notify("disconnect", { intentional: this.#intentional || this.#closed });
     });
+    this.#socket.on('ulda:changed.part', raw => {
+      try {
+        if (raw?.kind === 'begin') {
+          exact(raw, ['kind', 'count']);
+          check(!this.#assembly, 'INVALID_PACKET');
+          this.#assembly = new ChangeAssembly(raw.count);
+          this.#assemblyTimer = setTimeout(() => {
+            this.#assembly = undefined;
+            this.#notify('error', new UldaError('TIMEOUT'));
+          }, this.#timeout);
+        } else {
+          check(this.#assembly, 'INVALID_PACKET');
+          if (raw?.kind === 'end') {
+            exact(raw, ['kind']);
+            const value = changed(this.#assembly.finish(), true);
+            clearTimeout(this.#assemblyTimer); this.#assembly = undefined;
+            this.#notify('changed', value);
+          } else this.#assembly.accept(raw);
+        }
+      } catch {
+        clearTimeout(this.#assemblyTimer); this.#assembly = undefined;
+        this.#notify('error', new UldaError('INVALID_PACKET'));
+      }
+    });
     this.#socket.on("ulda:changed", (raw) => {
       try {
+        check(!this.#assembly, 'INVALID_PACKET');
         const value = changed(raw);
         this.#trace(() => ({
           phase: "push", event: "ulda:changed",
@@ -178,12 +212,81 @@ export class SocketIoTransport {
   async send(packet, { volatile = false, signal } = {}) {
     checkSignal(signal);
     const { action, body } = outgoing(packet);
-    requestShape(action, body);
+    requestShape(action, body, true);
+    if (['create', 'update', 'delete'].includes(action) && needsTransfer(body)) {
+      return this.#queued('write', () => this.#writeTransfer(action, body, signal));
+    }
+    try {
+      return await this.#sendWire(action, body, { volatile, signal });
+    } catch (error) {
+      if (action === 'read' && body.length === 1 && error.code === 'LIMIT') {
+        return this.#queued('read', () => this.#readTransfer(body[0], signal));
+      }
+      if (['create', 'update', 'delete'].includes(action) && error.code === 'LIMIT') {
+        return this.#queued('write', () => this.#writeTransfer(action, body, signal));
+      }
+      throw error;
+    }
+  }
+  #queued(kind, work) {
+    check(this.#transfers < LIMITS.queue, 'LIMIT');
+    this.#transfers++;
+    const generation = this.#generation;
+    const task = (kind === 'write' ? this.#writeTail : this.#readTail).then(() => {
+      check(generation === this.#generation, 'OFFLINE'); return work();
+    });
+    const tail = task.then(() => {}, () => {}).finally(() => this.#transfers--);
+    if (kind === 'write') this.#writeTail = tail; else this.#readTail = tail;
+    return task;
+  }
+  async #writeTransfer(action, body, signal) {
+    let token;
+    try {
+      token = await this.#sendWire('transfer', { kind: 'begin', action, count: body.length }, { signal }, raw => {
+        if (raw?.ok === false) acknowledgement('hello', {}, raw);
+        exact(raw, ['ok', 'token']); check(raw.ok === true && /^[a-f0-9]{32}$/.test(raw.token), 'INVALID_PACKET');
+        return raw.token;
+      });
+      for (const frame of fragments(body)) await this.#sendWire('transfer', { ...frame, token }, { signal });
+      return await this.#sendWire('transfer', { kind: 'commit', token }, { signal, commit: true, volatile: true }, raw => acknowledgement(action, body, raw, true));
+    } catch (error) {
+      // No replay. Closing discards any uncommitted staging. A lost commit ACK
+      // keeps UNKNOWN_OUTCOME even if the connection is subsequently closed.
+      if (token || error.code === 'TIMEOUT' || error.code === 'INVALID_PACKET') this.disconnect();
+      throw error;
+    }
+  }
+  async #readTransfer(id, signal) {
+    let result, offset = 0;
+    try { do {
+      const part = await this.#sendWire('transfer', { kind: 'read', resourceId: id, offset }, { signal }, raw => {
+        if (raw?.ok === false) acknowledgement('hello', {}, raw);
+        exact(raw, ['ok', 'data']); check(raw.ok === true, 'INVALID_PACKET');
+        const p = raw.data; exact(p, ['id', 'witness', 'payload', 'total', 'offset']);
+        check(p.id === id && p.offset === offset, 'INVALID_PACKET');
+        check(Number.isSafeInteger(p.total) && p.total > 0 && p.total <= LIMITS.resourceBytes, 'LIMIT');
+        const witness = binary(p.witness, 167), payload = binary(p.payload, LIMITS.jsonBytes);
+        check(offset + payload.length <= p.total, 'INVALID_PACKET');
+        return { ...p, witness, payload };
+      });
+      if (!result) result = { id, witness: part.witness.slice(), payload: new Uint8Array(part.total) };
+      check(result.payload.length === part.total && equal(result.witness, part.witness), 'INVALID_PACKET');
+      result.payload.set(part.payload, offset); offset += part.payload.length;
+    } while (offset < result.payload.length);
+    return [resource(result)];
+    } catch (error) {
+      // Release the server's pinned encrypted snapshot on a failed assembly.
+      this.disconnect();
+      throw error;
+    }
+  }
+  async #sendWire(action, body, { volatile = false, signal, commit = false } = {}, decode = raw => acknowledgement(action, body, raw)) {
+    checkSignal(signal);
     check(!this.#closed, "CLOSED");
     check(this.connected, "OFFLINE");
     check(this.#pending.size < LIMITS.queue, "LIMIT");
     const generation = this.#generation;
-    const write = ["create", "update", "delete"].includes(action);
+    const write = commit || ["create", "update", "delete"].includes(action);
     const tracing = !!this.#listeners.get("trace")?.size;
     const request = tracing ? ++this.#request : 0;
     const started = tracing ? performance.now() : 0;
@@ -214,14 +317,15 @@ export class SocketIoTransport {
       if (tracing) this.#trace(() => ({
         phase: "send", event, request, volatile: !!volatile,
         ...(action === "read" ? { ids: [...body] } : {}),
-        ...(write ? { items: resourceSummary(body) } : {}),
+        ...(write && Array.isArray(body) ? { items: resourceSummary(body) } : {}),
+        ...(action === 'transfer' ? { step: body.kind } : {}),
       }));
       sender.emit(event, body, (error, raw) => {
         if (done) return;
         if (error || generation !== this.#generation)
           return finish(new UldaError(write ? "UNKNOWN_OUTCOME" : "TIMEOUT"));
         try {
-          finish(undefined, acknowledgement(action, body, raw), true);
+          finish(undefined, decode(raw), true);
         } catch (e) {
           const clean = safeError(e);
           finish(
@@ -252,6 +356,7 @@ export class SocketIoTransport {
   close() {
     if (this.#closed) return;
     this.#closed = true;
+    clearTimeout(this.#assemblyTimer); this.#assembly = undefined;
     this.#generation++;
     this.#rejectPending();
     this.#socket.disconnect();

package/src/values.js

@@ -5,7 +5,9 @@ export const LIMITS = Object.freeze({
   messageBytes: 8_388_608,
   incoming: 8,
   batch: 64,
-  resources: 64,
+  // Resource/transfer byte budgets are independent of catalog entry count.
+  resourceBytes: 64 * 1_048_576,
+  transferBytes: 128 * 1_048_576,
   queue: 128,
   depth: 48,
   nodes: 40_000,
@@ -82,15 +84,17 @@ export function exact(value, keys) {
   );
 }
 // Clone JSON without invoking getters, toJSON or custom prototypes.
-export function json(value) {
+export function json(value, catalog = false) {
+  const bytesLimit = catalog ? LIMITS.resourceBytes - 4096 : LIMITS.jsonBytes;
+  const nodesLimit = catalog ? bytesLimit : LIMITS.nodes;
   const seen = new Set();
   let nodes = 0,
     characters = 0;
   function visit(v, depth) {
-    check(++nodes <= LIMITS.nodes && depth <= LIMITS.depth, "LIMIT");
+    check(++nodes <= nodesLimit && depth <= LIMITS.depth, "LIMIT");
     if (typeof v === "string") {
       characters += v.length;
-      check(characters <= LIMITS.jsonBytes, "LIMIT");
+      check(characters <= bytesLimit, "LIMIT");
       return v;
     }
     if (v === null || typeof v === "boolean") return v;
@@ -109,11 +113,11 @@ export function json(value) {
     seen.add(v);
     const result = array ? [] : Object.create(null);
     const keys = Reflect.ownKeys(v).filter((k) => !(array && k === "length"));
-    if (array) check(keys.length === v.length && v.length <= LIMITS.nodes);
+    if (array) check(keys.length === v.length && v.length <= nodesLimit);
     for (const key of keys) {
       check(typeof key === "string");
       characters += key.length;
-      check(characters <= LIMITS.jsonBytes, "LIMIT");
+      check(characters <= bytesLimit, "LIMIT");
       if (array) check(/^(0|[1-9][0-9]*)$/.test(key) && Number(key) < v.length);
       const desc = Object.getOwnPropertyDescriptor(v, key);
       check(desc.enumerable && Object.hasOwn(desc, "value"));
@@ -128,7 +132,7 @@ export function json(value) {
     return result;
   }
   const result = visit(value, 0);
-  check(utf8(JSON.stringify(result)).length <= LIMITS.jsonBytes, "LIMIT");
+  check(utf8(JSON.stringify(result)).length <= bytesLimit, "LIMIT");
   return result;
 }
 export function pathValue(value, path) {