@phuzle/relay 0.1.0 → 0.1.2

package/index.cjs

@@ -23,10 +23,17 @@ __export(src_exports, {
   PayloadTooLargeError: () => PayloadTooLargeError,
   Relay: () => Relay,
   RelayError: () => RelayError,
+  StreamError: () => StreamError,
+  Subscription: () => Subscription,
   buildPlaintext: () => buildPlaintext
 });
 module.exports = __toCommonJS(src_exports);
 
+// ../core/src/crypto/consumer.ts
+var import_ed255192 = require("@noble/curves/ed25519");
+var import_hkdf = require("@noble/hashes/hkdf");
+var import_sha22 = require("@noble/hashes/sha2");
+
 // ../core/src/encoding.ts
 function b64urlEncode(bytes) {
   let s = "";
@@ -42,6 +49,11 @@ function b64urlDecode(text) {
 }
 var enc = new TextEncoder();
 var utf8 = (s) => enc.encode(s);
+var fromUtf8 = (b) => new TextDecoder().decode(b);
+
+// ../core/src/crypto/keys.ts
+var import_ed25519 = require("@noble/curves/ed25519");
+var import_sha2 = require("@noble/hashes/sha2");
 
 // ../core/src/crypto/suite.ts
 var import_chacha20poly1305 = require("@hpke/chacha20poly1305");
@@ -53,19 +65,71 @@ var suite = new import_core.CipherSuite({
   aead: new import_chacha20poly1305.Chacha20Poly1305()
 });
 
+// ../core/src/crypto/keys.ts
+function bindingMessage(encPub, idPub) {
+  return utf8(`relay-bind-v1
+${b64urlEncode(encPub)}
+${b64urlEncode(idPub)}`);
+}
+function signBinding(idPriv, encPub, idPub) {
+  return import_ed25519.ed25519.sign(bindingMessage(encPub, idPub), idPriv);
+}
+function verifyBinding(sig, encPub, idPub) {
+  try {
+    return import_ed25519.ed25519.verify(sig, bindingMessage(encPub, idPub), idPub);
+  } catch {
+    return false;
+  }
+}
+
+// ../core/src/crypto/consumer.ts
+var CONSUMER_SECRET_BYTES = 32;
+function generateConsumerSecret() {
+  return b64urlEncode(
+    crypto.getRandomValues(new Uint8Array(CONSUMER_SECRET_BYTES))
+  );
+}
+var derive = (secret, label) => (0, import_hkdf.hkdf)(import_sha22.sha256, secret, void 0, utf8(`relay-consumer-v1/${label}`), 32);
+async function consumerKeysFromSecret(secret) {
+  const raw = b64urlDecode(secret.trim());
+  if (raw.length !== CONSUMER_SECRET_BYTES)
+    throw new Error("A consumer key is 43 characters (32 bytes, base64url)");
+  const idPriv = derive(raw, "identity");
+  const idPub = import_ed255192.ed25519.getPublicKey(idPriv);
+  const kp = await suite.kem.deriveKeyPair(derive(raw, "encryption"));
+  const encPriv = new Uint8Array(
+    await suite.kem.serializePrivateKey(kp.privateKey)
+  );
+  const encPub = new Uint8Array(
+    await suite.kem.serializePublicKey(kp.publicKey)
+  );
+  return { idPriv, idPub, encPriv, encPub };
+}
+async function consumerRegistration(secret) {
+  const k = await consumerKeysFromSecret(secret);
+  return {
+    idPub: b64urlEncode(k.idPub),
+    encPub: b64urlEncode(k.encPub),
+    bindSig: b64urlEncode(signBinding(k.idPriv, k.encPub, k.idPub))
+  };
+}
+
 // ../core/src/crypto/envelope.ts
 var MAX_PLAINTEXT_BYTES = 2048;
+var MAX_STREAM_EVENT_BYTES = 256 * 1024;
 var PayloadTooLargeError = class extends Error {
-  constructor(size) {
-    super(`Payload is ${size} bytes; limit is ${MAX_PLAINTEXT_BYTES}`);
+  constructor(size, limit = MAX_PLAINTEXT_BYTES) {
+    super(`Payload is ${size} bytes; limit is ${limit}`);
     this.name = "PayloadTooLargeError";
   }
 };
 var infoFor = (c) => utf8(`relay/v1\0${c.deviceId}\0${c.messageId}\0${c.topicId}`);
-async function seal(encPub, ctx, plaintext, ekm) {
+function seal(encPub, ctx, plaintext, ekm) {
+  return sealUpTo(MAX_PLAINTEXT_BYTES, encPub, ctx, plaintext, ekm);
+}
+async function sealUpTo(limit, encPub, ctx, plaintext, ekm) {
   const pt = utf8(plaintext);
-  if (pt.length > MAX_PLAINTEXT_BYTES)
-    throw new PayloadTooLargeError(pt.length);
+  if (pt.length > limit) throw new PayloadTooLargeError(pt.length, limit);
   const recipientPublicKey = await suite.kem.deserializePublicKey(encPub);
   const sender = await suite.createSenderContext({
     recipientPublicKey,
@@ -79,26 +143,20 @@ async function seal(encPub, ctx, plaintext, ekm) {
     ct: b64urlEncode(ct)
   };
 }
-
-// ../core/src/crypto/keys.ts
-var import_ed25519 = require("@noble/curves/ed25519");
-var import_sha2 = require("@noble/hashes/sha2");
-function bindingMessage(encPub, idPub) {
-  return utf8(`relay-bind-v1
-${b64urlEncode(encPub)}
-${b64urlEncode(idPub)}`);
-}
-function verifyBinding(sig, encPub, idPub) {
-  try {
-    return import_ed25519.ed25519.verify(sig, bindingMessage(encPub, idPub), idPub);
-  } catch {
-    return false;
-  }
+async function open(encPriv, ctx, envelope) {
+  const recipientKey = await suite.kem.deserializePrivateKey(encPriv);
+  const recipient = await suite.createRecipientContext({
+    recipientKey,
+    enc: b64urlDecode(envelope.enc),
+    info: infoFor(ctx)
+  });
+  const pt = await recipient.open(b64urlDecode(envelope.ct));
+  return fromUtf8(new Uint8Array(pt));
 }
 
 // ../core/src/crypto/signing.ts
-var import_ed255192 = require("@noble/curves/ed25519");
-var import_sha22 = require("@noble/hashes/sha2");
+var import_ed255193 = require("@noble/curves/ed25519");
+var import_sha23 = require("@noble/hashes/sha2");
 
 // ../core/src/lib/glyphs.ts
 var GLYPHS = [
@@ -160,6 +218,415 @@ function ulid(now = Date.now()) {
   return time + rand;
 }
 
+// src/stream.ts
+var import_node_zlib = require("zlib");
+var StreamError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "StreamError";
+  }
+  status;
+  code;
+};
+var sleep = (ms, signal) => new Promise((resolve) => {
+  const t = setTimeout(resolve, ms);
+  signal?.addEventListener(
+    "abort",
+    () => {
+      clearTimeout(t);
+      resolve();
+    },
+    { once: true }
+  );
+});
+function binParser() {
+  let buf = new Uint8Array(0);
+  const dec = new TextDecoder();
+  const b64 = (b) => Buffer.from(b).toString("base64url");
+  const NAMES = { 1: "ready", 3: "gap", 4: "bye" };
+  return (chunk) => {
+    if (buf.length === 0) buf = chunk;
+    else {
+      const next = new Uint8Array(buf.length + chunk.length);
+      next.set(buf);
+      next.set(chunk, buf.length);
+      buf = next;
+    }
+    const out = [];
+    for (; ; ) {
+      if (buf.length < 5) break;
+      const dv = new DataView(
+        buf.buffer,
+        buf.byteOffset,
+        buf.byteLength
+      );
+      const len = dv.getUint32(1);
+      if (buf.length < 5 + len) break;
+      const kind = buf[0];
+      const body = buf.subarray(5, 5 + len);
+      buf = buf.subarray(5 + len);
+      if (kind === 5) out.push({ event: ":", data: "" });
+      else if (kind === 2) {
+        const bd = new DataView(
+          body.buffer,
+          body.byteOffset,
+          body.byteLength
+        );
+        const metaLen = bd.getUint32(0);
+        const meta = JSON.parse(dec.decode(body.subarray(4, 4 + metaLen)));
+        const encLen = body[4 + metaLen];
+        const encBytes = body.subarray(5 + metaLen, 5 + metaLen + encLen);
+        const ct = body.subarray(5 + metaLen + encLen);
+        out.push({
+          event: "event",
+          data: JSON.stringify({ ...meta, enc: b64(encBytes), ct: b64(ct) })
+        });
+      } else if (NAMES[kind])
+        out.push({ event: NAMES[kind], data: dec.decode(body) });
+    }
+    return out;
+  };
+}
+function sseParser() {
+  let buf = "";
+  return (chunk) => {
+    buf += chunk.replace(/\r\n/g, "\n");
+    const out = [];
+    let i;
+    while ((i = buf.indexOf("\n\n")) >= 0) {
+      const block = buf.slice(0, i);
+      buf = buf.slice(i + 2);
+      let event = "message";
+      let id;
+      const data = [];
+      let comment = false;
+      for (const line of block.split("\n")) {
+        if (line.startsWith(":")) comment = true;
+        else if (line.startsWith("event:")) event = line.slice(6).trim();
+        else if (line.startsWith("id:")) id = line.slice(3).trim();
+        else if (line.startsWith("data:"))
+          data.push(line.slice(5).replace(/^ /, ""));
+      }
+      if (comment && data.length === 0 && event === "message")
+        out.push({ event: ":", data: "" });
+      else out.push({ event, id, data: data.join("\n") });
+    }
+    return out;
+  };
+}
+var Subscription = class {
+  constructor(t, topic, name, secret, tuning = {}, o = { name }) {
+    this.t = t;
+    this.topic = topic;
+    this.name = name;
+    this.secret = secret;
+    this.tuning = tuning;
+    this.o = o;
+  }
+  t;
+  topic;
+  name;
+  secret;
+  tuning;
+  o;
+  queue = [];
+  waiter = null;
+  failure = null;
+  ctl = new AbortController();
+  stopped = false;
+  _state = "connecting";
+  listeners = { open: [], reconnecting: [], error: [], gap: [] };
+  firstConnect = true;
+  current = null;
+  settledEvents = /* @__PURE__ */ new WeakSet();
+  acks = [];
+  nacks = [];
+  flushing = null;
+  flushTimer = null;
+  flushWaiters = [];
+  started = null;
+  get state() {
+    return this._state;
+  }
+  on(ev, fn) {
+    this.listeners[ev].push(fn);
+    return this;
+  }
+  emit(ev, v) {
+    for (const fn of this.listeners[ev]) {
+      try {
+        fn(v);
+      } catch {
+      }
+    }
+  }
+  /** Resolves once the consumer is registered and the stream is open (or rejects if it can't be). */
+  ready() {
+    this.start();
+    return new Promise((resolve, reject) => {
+      if (this._state === "open") return resolve();
+      this.on("open", () => resolve());
+      this.on("error", (e) => reject(e));
+    });
+  }
+  close() {
+    this.stopped = true;
+    this._state = "closed";
+    this.ctl.abort();
+    this.waiter?.();
+    if (this.current && !this.settledEvents.has(this.current))
+      this.nacks.push(this.current.seq);
+    this.current = null;
+    for (const e of this.queue) this.nacks.push(e.seq);
+    this.queue = [];
+    void this.flush();
+  }
+  /** Acknowledgements and hand-backs are sent in one request after a short pause (or at 50), not one request per event. */
+  settle(seq, kind) {
+    (kind === "ack" ? this.acks : this.nacks).push(seq);
+    return new Promise((resolve, reject) => {
+      this.flushWaiters.push({ resolve, reject });
+      if (this.acks.length + this.nacks.length >= 50) void this.flush();
+      else this.flushTimer ??= setTimeout(() => void this.flush(), 25);
+    });
+  }
+  async flush() {
+    if (this.flushTimer) clearTimeout(this.flushTimer);
+    this.flushTimer = null;
+    if (this.flushing) await this.flushing.catch(() => {
+    });
+    if (this.acks.length === 0 && this.nacks.length === 0) return;
+    const body = {
+      consumer: this.name,
+      ...this.acks.length ? { seqs: this.acks } : {},
+      ...this.nacks.length ? { nack: this.nacks } : {}
+    };
+    const waiters = this.flushWaiters;
+    this.acks = [];
+    this.nacks = [];
+    this.flushWaiters = [];
+    this.flushing = this.t.ack(this.topic, body).then(() => waiters.forEach((w) => w.resolve())).catch((e) => {
+      const err = e instanceof Error ? e : new Error(String(e));
+      waiters.forEach((w) => w.reject(err));
+      this.emit("error", err);
+    });
+    await this.flushing;
+  }
+  [Symbol.asyncIterator]() {
+    this.start();
+    return {
+      next: async () => {
+        if (this.current && !this.settledEvents.has(this.current) && (this.o.ack ?? "auto") === "auto")
+          void this.current.ack().catch(() => {
+          });
+        for (; ; ) {
+          const e = this.queue.shift();
+          if (e) {
+            this.current = e;
+            return { value: e, done: false };
+          }
+          if (this.failure) throw this.failure;
+          if (this.stopped) return { value: void 0, done: true };
+          await new Promise((r) => {
+            this.waiter = r;
+          });
+          this.waiter = null;
+        }
+      },
+      return: async () => {
+        this.close();
+        return { value: void 0, done: true };
+      }
+    };
+  }
+  start() {
+    if (!this.started)
+      this.started = this.run().catch(
+        (e) => this.fail(e instanceof Error ? e : new Error(String(e)))
+      );
+  }
+  fail(e) {
+    if (this.stopped) return;
+    this.failure = e;
+    this._state = "closed";
+    this.emit("error", e);
+    this.waiter?.();
+  }
+  push(e) {
+    this.queue.push(e);
+    this.waiter?.();
+  }
+  async run() {
+    const keys = await consumerKeysFromSecret(this.secret);
+    const registration = {
+      ...await consumerRegistration(this.secret),
+      options: this.o.filter ?? {}
+    };
+    let attempt = 0;
+    let ids = null;
+    while (!this.stopped) {
+      try {
+        ids = await this.t.register(this.topic, this.name, registration);
+        const res = await this.t.open(
+          this.topic,
+          this.name,
+          this.query(),
+          this.ctl.signal
+        );
+        if (!res.body)
+          throw new StreamError(
+            "The stream had no body",
+            res.status,
+            "no_body"
+          );
+        attempt = 0;
+        this._state = "open";
+        const bin = (res.headers.get("content-type") ?? "").includes(
+          "vnd.relay.stream"
+        );
+        const why = await this.read(res.body, keys.encPriv, ids, bin);
+        if (this.stopped) return;
+        this._state = "reconnecting";
+        this.emit("reconnecting", { attempt: 1, reason: why });
+        if (why === "revoked")
+          throw new StreamError(
+            "This consumer was removed",
+            0,
+            "consumer_revoked"
+          );
+        continue;
+      } catch (e) {
+        if (this.stopped) return;
+        const status = e.status ?? 0;
+        if (e instanceof StreamError && (e.code === "consumer_revoked" || e.status >= 400 && e.status < 500 && e.status !== 429))
+          throw e;
+        if (status >= 400 && status < 500 && status !== 429 && status !== 0)
+          throw e;
+        attempt++;
+        this._state = "reconnecting";
+        this.emit("reconnecting", {
+          attempt,
+          reason: e instanceof Error ? e.message : "error"
+        });
+        const cap = this.tuning.maxBackoffMs ?? 3e4;
+        const base = Math.min(cap, 500 * 2 ** Math.min(attempt, 7));
+        await sleep(base * (0.7 + Math.random() * 0.6), this.ctl.signal);
+      }
+    }
+  }
+  /** The first connection starts where the caller asked; every later one resumes from what is still unacknowledged. */
+  query() {
+    const q = {};
+    if (this.firstConnect && this.o.from !== void 0) q.from = this.o.from;
+    this.firstConnect = false;
+    q.format = this.o.format ?? "bin";
+    if (this.o.prefetch) q.prefetch = this.o.prefetch;
+    if (this.o.lease) q.lease = this.o.lease;
+    return q;
+  }
+  /** Reads one connection until it ends. Returns why: `recycle`, `revoked`, `dropped`, or `silent` (heartbeat watchdog). */
+  async read(body, encPriv, ids, bin = false) {
+    const reader = body.getReader();
+    const dec = new TextDecoder();
+    const parse = sseParser();
+    const parseBin = binParser();
+    const timeout = this.tuning.heartbeatTimeoutMs ?? 45e3;
+    let why = "dropped";
+    try {
+      for (; ; ) {
+        const chunk = await Promise.race([
+          reader.read(),
+          sleep(timeout, this.ctl.signal).then(() => "silent")
+        ]);
+        if (this.stopped) return "closed";
+        if (chunk === "silent") {
+          why = "silent";
+          break;
+        }
+        if (chunk.done) break;
+        for (const m of bin ? parseBin(chunk.value) : parse(dec.decode(chunk.value, { stream: true }))) {
+          if (m.event === "ready") this.emit("open");
+          else if (m.event === "event")
+            await this.deliver(m.data, encPriv, ids);
+          else if (m.event === "gap") this.emit("gap", JSON.parse(m.data));
+          else if (m.event === "bye") {
+            why = JSON.parse(m.data || "{}").reason ?? "recycle";
+            return why;
+          }
+        }
+      }
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {
+      }
+    }
+    return why;
+  }
+  async deliver(data, encPriv, ids) {
+    const w = JSON.parse(data);
+    let p;
+    try {
+      p = JSON.parse(
+        await open(
+          encPriv,
+          { messageId: w.id, topicId: ids.topicId, deviceId: ids.id },
+          w
+        )
+      );
+      const z = p;
+      if (z.z === "gzip" && z.d)
+        p = JSON.parse(
+          (0, import_node_zlib.gunzipSync)(Buffer.from(z.d, "base64")).toString("utf8")
+        );
+    } catch {
+      this.emit(
+        "error",
+        new StreamError(
+          "An event could not be opened with this consumer key",
+          0,
+          "undecryptable"
+        )
+      );
+      void this.settle(w.seq, "ack").catch(() => {
+      });
+      return;
+    }
+    const ev = {
+      id: p.id,
+      seq: w.seq,
+      attempt: w.attempt,
+      source: p.source,
+      type: p.type,
+      deliveryId: p.deliveryId,
+      receivedAt: p.receivedAt,
+      headers: p.headers,
+      contentType: p.contentType,
+      body: p.body,
+      bodyBytes: p.bodyBytes,
+      truncated: p.truncated === true,
+      projected: p.projected === true,
+      json: () => {
+        if (p.body == null) throw new Error("This event has no body");
+        return JSON.parse(p.body);
+      },
+      ack: () => {
+        if (this.settledEvents.has(ev)) return Promise.resolve();
+        this.settledEvents.add(ev);
+        return this.settle(w.seq, "ack");
+      },
+      nack: () => {
+        if (this.settledEvents.has(ev)) return Promise.resolve();
+        this.settledEvents.add(ev);
+        return this.settle(w.seq, "nack");
+      }
+    };
+    this.push(ev);
+  }
+};
+
 // src/index.ts
 var deliverAtIso = (m) => {
   if (m.deliverAt !== void 0 && m.delaySeconds !== void 0)
@@ -197,7 +664,7 @@ var RelayError = class extends Error {
   retryAfterSeconds;
 };
 var DEFAULT_URL = "https://relay.phuzle.com";
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
 var Relay = class _Relay {
   constructor(opts) {
     this.opts = opts;
@@ -236,6 +703,90 @@ var Relay = class _Relay {
       }
     });
   }
+  /** A new consumer key for `subscribe()`: 43 characters, shown once. Store it as `RELAY_CONSUMER_KEY`; Relay never sees it and cannot recover it. */
+  static generateConsumerKey() {
+    return generateConsumerSecret();
+  }
+  /** One topic by its full name (`<org>-<slug>`): send to it, list its phones, or subscribe to its events from a server. */
+  topic(name) {
+    return {
+      name,
+      send: (m) => this.send({ ...m, topic: name }),
+      devices: () => this.devices(name),
+      subscribe: (o) => this.subscribe(name, o)
+    };
+  }
+  /**
+   * Receive a topic's events on a server (Relay Streams): webhooks Relay received for this topic, delivered over one long-lived
+   * connection, sealed to your consumer key so only this process can open them. Needs an API key with “Can receive events” for the
+   * topic. Reconnects by itself, and **at-least-once**: events wait for you (for your plan's retention) until acknowledged, so a
+   * restart loses nothing; repeats are possible, so use `ev.id` to ignore ones you have handled.
+   *
+   *     const sub = relay.topic("acme-github-api").subscribe({ name: "deploy-bot" });   // key from RELAY_CONSUMER_KEY
+   *     for await (const ev of sub) { if (ev.type === "push") deploy(ev.json()); }
+   */
+  subscribe(topic, o) {
+    const key = (o.key ?? process.env.RELAY_CONSUMER_KEY ?? "").trim();
+    if (!key)
+      throw new RelayError(
+        "A consumer key is required: pass `key` or set RELAY_CONSUMER_KEY (create one with Relay.generateConsumerKey())",
+        0,
+        "consumer_key_required"
+      );
+    const t = {
+      register: async (tp, name, body) => await this.request(
+        "PUT",
+        `/v1/stream/${encodeURIComponent(tp)}/consumers/${encodeURIComponent(name)}`,
+        body
+      ),
+      ack: async (tp, body) => {
+        await this.parse(
+          await this.raw(
+            "POST",
+            `/v1/stream/${encodeURIComponent(tp)}/ack`,
+            body
+          )
+        );
+      },
+      open: async (tp, name, query, signal) => {
+        const qs = new URLSearchParams({ consumer: name });
+        for (const [k, v] of Object.entries(query)) qs.set(k, String(v));
+        const res = await this.raw(
+          "GET",
+          `/v1/stream/${encodeURIComponent(tp)}/events?${qs}`,
+          void 0,
+          { accept: "text/event-stream" },
+          signal
+        );
+        if (!res.ok) await this.parse(res);
+        return res;
+      }
+    };
+    return new Subscription(t, topic, o.name, key, {}, o);
+  }
+  /** The topics this key may send to (its `trigger:*` / `trigger:<slug>` permissions), and whether it may create more. */
+  async topics() {
+    const r = await this.request("GET", "/v1/trigger/topics");
+    return { topics: r.data, canCreate: r.canCreate };
+  }
+  /**
+   * Create a topic. Needs the **Can create topics** permission on the key (`scope_denied` otherwise) and counts against the plan's
+   * topic limit (`topic_limit`). Only keys that can send to all topics can have this permission, so the new topic is usable straight away. Not retried automatically:
+   * a second attempt would only answer `slug_taken`.
+   */
+  async createTopic(t) {
+    return await this.parse(
+      await this.raw("POST", "/v1/trigger/topics", t)
+    );
+  }
+  /** The phones receiving `topic` (the full `<org>-<slug>` name). The key must be allowed to send to it. */
+  async devices(topic) {
+    const r = await this.request(
+      "GET",
+      `/v1/trigger/topics/${encodeURIComponent(topic)}/devices`
+    );
+    return r.data;
+  }
   async send(m) {
     checkRepeat(m.repeat);
     checkRepeat(m.escalate?.repeat);
@@ -377,13 +928,14 @@ var Relay = class _Relay {
       } catch (e) {
         const transient = e instanceof RelayError ? e.status >= 500 || e.status === 0 && e.code === "network" : false;
         if (!transient || attempt >= this.retries) throw e;
-        await sleep(250 * 2 ** attempt++);
+        await sleep2(250 * 2 ** attempt++);
       }
     }
   }
-  async raw(method, path, body, headers = {}) {
+  async raw(method, path, body, headers = {}, signal) {
     try {
       return await this.doFetch(this.base + path, {
+        ...signal ? { signal } : {},
         method,
         headers: {
           authorization: `Bearer ${this.opts.apiKey}`,
@@ -492,5 +1044,7 @@ function buildPlaintext(m) {
   PayloadTooLargeError,
   Relay,
   RelayError,
+  StreamError,
+  Subscription,
   buildPlaintext
 });