@phuzle/relay 0.1.0

package/index.d.ts

@@ -0,0 +1,148 @@
+/** Thrown when the plaintext message exceeds 2 KiB. */
+export declare class PayloadTooLargeError extends Error {
+	constructor(size: number);
+}
+export type Priority = "min" | "low" | "default" | "high" | "urgent";
+export type ActionRequest = {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+};
+/**
+ * A button on the notification. Either it **sends an HTTP request** from the phone (`request`), or it **opens a link** in the
+ * browser (`link`, https only: a dashboard, a runbook, a PR, …). Exactly one of the two.
+ */
+export type Action = {
+    id?: string;
+    label: string;
+    style?: "default" | "destructive";
+    confirm?: boolean;
+    retry?: boolean;
+} & ({
+    request: ActionRequest;
+    link?: never;
+} | {
+    link: string;
+    request?: never;
+});
+export type Message = {
+    topic: string;
+    title: string;
+    body?: string;
+    priority?: Priority;
+    tags?: string[];
+    /** One of the built-in icons (`GLYPHS`): `"rocket"`, `"flame"`, `"bug"`… The phone draws it; nothing is downloaded. */
+    icon?: string;
+    /** Opens when the notification is tapped (https only). */
+    url?: string;
+    /**
+     * An https image to show with the message. The link is inside the encrypted message; the phone downloads it only if the user
+     * turned on "Load images" for the topic, and then the image's server sees that phone's IP address and the time. Max 1000 characters.
+     */
+    image?: string;
+    /** Notifications with the same group stack together on the phone. */
+    group?: string;
+    /** Up to 3 buttons: each either calls your HTTPS endpoint straight from the phone (`request`; the request and any secrets in headers are inside the ciphertext) or opens an https `link` in the browser. */
+    actions?: Action[];
+    /** How long to keep trying while the phone is offline. Default 24 h, max 4 weeks. */
+    ttlSeconds?: number;
+    /** A newer message with the same key replaces an undelivered older one. */
+    collapseKey?: string;
+    idempotencyKey?: string;
+    /** Hold delivery until this time (up to 30 days ahead). Relay keeps only the sealed message until then. */
+    deliverAt?: Date | string;
+    /** Shorthand for `deliverAt: now + delaySeconds`. */
+    delaySeconds?: number;
+    /** Re-send the same message every `everySeconds` (≥ 60), up to `times` more times, until a phone acknowledges it (opens it or presses a button). */
+    repeat?: {
+        everySeconds: number;
+        times: number;
+    };
+    /**
+     * If nobody acknowledges this message within `afterSeconds`, deliver a message to `topic` (another on-call group). Encrypted for
+     * that topic's phones now, so Relay still can't read it; cancelled when this one is acknowledged. Anything not set here
+     * (title, body, priority…) is taken from the original message, with priority raised to `urgent` by default.
+     */
+    escalate?: {
+        topic: string;
+        afterSeconds: number;
+        title?: string;
+        body?: string;
+        priority?: Priority;
+        repeat?: {
+            everySeconds: number;
+            times: number;
+        };
+    };
+    /** Advanced: only deliver if the message with this id is still unacknowledged at delivery time (what `escalate` uses). */
+    unlessAcked?: string;
+};
+export type SendResult = {
+    messageId: string;
+    accepted: number;
+    rejected: {
+        deviceId: string;
+        reason: string;
+    }[];
+    missing: string[];
+    duplicate?: boolean;
+    /** Set when delivery is held until a later time. */
+    scheduledFor?: string;
+    /** `escalate` was set: the second message's result. */
+    escalation?: SendResult;
+};
+/** A failed call to Relay. Branch on `code` (stable), never on `message`. */
+export declare class RelayError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(message: string, status: number, code: string, retryAfterSeconds?: number | undefined);
+}
+export type RelayOptions = {
+    apiKey: string;
+    /** Relay's origin (default `https://relay.phuzle.com`; the SDK adds `/v1/…`). Point it at a local, staging or self-hosted Relay; a path prefix is kept. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    maxRetries?: number;
+};
+export declare class Relay {
+    private readonly opts;
+    private readonly base;
+    private readonly doFetch;
+    private readonly retries;
+    private readonly cache;
+    /** Trust-on-first-use: a device id must keep the same identity key, or something is swapping keys (crypto-spec §3, T4). */
+    private readonly pinned;
+    constructor(opts: RelayOptions);
+    /** Reads `RELAY_API_KEY` and, optionally, `RELAY_API_URL`; `overrides` win over the environment. */
+    static fromEnv(env?: Record<string, string | undefined>, overrides?: Partial<RelayOptions>): Relay;
+    send(m: Message): Promise<SendResult>;
+    private sendCore;
+    private sendOnce;
+    /** Recipients for a topic, verified and cached by ETag (a cheap conditional GET on every send keeps the key set fresh). */
+    private recipients;
+    private request;
+    private raw;
+    private parse;
+}
+type Plain = {
+    ts: number;
+    title: string;
+    body?: string;
+    priority: Priority;
+    tags?: string[];
+    icon?: string;
+    url?: string;
+    image?: string;
+    group?: string;
+    actions?: ((Required<Omit<Action, "link">> & {
+        link?: never;
+    }) | {
+        id: string;
+        label: string;
+        link: string;
+    })[];
+};
+/** Validates and shapes the plaintext (crypto-spec §6). Throws RelayError(code) on anything the phone would reject. */
+export declare function buildPlaintext(m: Message): Omit<Plain, "id">;

package/index.js

@@ -0,0 +1,466 @@
+// ../core/src/encoding.ts
+function b64urlEncode(bytes) {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function b64urlDecode(text) {
+  const pad = "=".repeat((4 - text.length % 4) % 4);
+  const bin = atob(text.replace(/-/g, "+").replace(/_/g, "/") + pad);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+var enc = new TextEncoder();
+var utf8 = (s) => enc.encode(s);
+
+// ../core/src/crypto/suite.ts
+import { Chacha20Poly1305 } from "@hpke/chacha20poly1305";
+import { CipherSuite, HkdfSha256 } from "@hpke/core";
+import { DhkemX25519HkdfSha256 } from "@hpke/dhkem-x25519";
+var suite = new CipherSuite({
+  kem: new DhkemX25519HkdfSha256(),
+  kdf: new HkdfSha256(),
+  aead: new Chacha20Poly1305()
+});
+
+// ../core/src/crypto/envelope.ts
+var MAX_PLAINTEXT_BYTES = 2048;
+var PayloadTooLargeError = class extends Error {
+  constructor(size) {
+    super(`Payload is ${size} bytes; limit is ${MAX_PLAINTEXT_BYTES}`);
+    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) {
+  const pt = utf8(plaintext);
+  if (pt.length > MAX_PLAINTEXT_BYTES)
+    throw new PayloadTooLargeError(pt.length);
+  const recipientPublicKey = await suite.kem.deserializePublicKey(encPub);
+  const sender = await suite.createSenderContext({
+    recipientPublicKey,
+    info: infoFor(ctx),
+    ...ekm ? { ekm } : {}
+  });
+  const ct = new Uint8Array(await sender.seal(pt));
+  return {
+    deviceId: ctx.deviceId,
+    enc: b64urlEncode(new Uint8Array(sender.enc)),
+    ct: b64urlEncode(ct)
+  };
+}
+
+// ../core/src/crypto/keys.ts
+import { ed25519 } from "@noble/curves/ed25519";
+import { sha256 } from "@noble/hashes/sha2";
+function bindingMessage(encPub, idPub) {
+  return utf8(`relay-bind-v1
+${b64urlEncode(encPub)}
+${b64urlEncode(idPub)}`);
+}
+function verifyBinding(sig, encPub, idPub) {
+  try {
+    return ed25519.verify(sig, bindingMessage(encPub, idPub), idPub);
+  } catch {
+    return false;
+  }
+}
+
+// ../core/src/crypto/signing.ts
+import { ed25519 as ed255192 } from "@noble/curves/ed25519";
+import { sha256 as sha2562 } from "@noble/hashes/sha2";
+
+// ../core/src/lib/glyphs.ts
+var GLYPHS = [
+  "activity",
+  "alert",
+  "battery",
+  "bell",
+  "bug",
+  "calendar",
+  "cart",
+  "check",
+  "clock",
+  "cloud",
+  "cpu",
+  "credit-card",
+  "database",
+  "dollar",
+  "error",
+  "flame",
+  "git-branch",
+  "git-pr",
+  "globe",
+  "heart",
+  "info",
+  "key",
+  "lock",
+  "mail",
+  "moon",
+  "package",
+  "phone",
+  "power",
+  "rocket",
+  "server",
+  "shield",
+  "star",
+  "success",
+  "terminal",
+  "thermometer",
+  "trending-down",
+  "trending-up",
+  "users",
+  "wifi",
+  "zap"
+];
+var isGlyph = (v) => typeof v === "string" && GLYPHS.includes(v);
+
+// ../core/src/lib/ids.ts
+var CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function ulid(now = Date.now()) {
+  let t = now;
+  let time = "";
+  for (let i = 0; i < 10; i++) {
+    time = CROCKFORD[t % 32] + time;
+    t = Math.floor(t / 32);
+  }
+  const r = crypto.getRandomValues(new Uint8Array(16));
+  let rand = "";
+  for (let i = 0; i < 16; i++) rand += CROCKFORD[r[i] % 32];
+  return time + rand;
+}
+
+// src/index.ts
+var deliverAtIso = (m) => {
+  if (m.deliverAt !== void 0 && m.delaySeconds !== void 0)
+    throw new RelayError(
+      "Use deliverAt or delaySeconds, not both",
+      0,
+      "invalid_message"
+    );
+  const d = m.deliverAt !== void 0 ? new Date(m.deliverAt) : m.delaySeconds !== void 0 ? new Date(Date.now() + m.delaySeconds * 1e3) : void 0;
+  if (d && Number.isNaN(d.getTime()))
+    throw new RelayError("deliverAt is not a valid date", 0, "invalid_message");
+  return d?.toISOString();
+};
+var checkRepeat = (r) => {
+  if (!r) return;
+  if (!Number.isInteger(r.everySeconds) || r.everySeconds < 60 || r.everySeconds > 86400)
+    throw new RelayError(
+      "repeat.everySeconds must be 60 to 86400",
+      0,
+      "invalid_message"
+    );
+  if (!Number.isInteger(r.times) || r.times < 1 || r.times > 20)
+    throw new RelayError("repeat.times must be 1 to 20", 0, "invalid_message");
+};
+var RelayError = class extends Error {
+  constructor(message, status, code, retryAfterSeconds) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.name = "RelayError";
+  }
+  status;
+  code;
+  retryAfterSeconds;
+};
+var DEFAULT_URL = "https://relay.phuzle.com";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var Relay = class _Relay {
+  constructor(opts) {
+    this.opts = opts;
+    if (!opts.apiKey?.startsWith("rly_"))
+      throw new RelayError(
+        "apiKey must be a Relay API key (rly_\u2026)",
+        0,
+        "bad_api_key"
+      );
+    const base = (opts.baseUrl || DEFAULT_URL).trim();
+    if (!/^https?:\/\/[^\s/]+/i.test(base))
+      throw new RelayError(
+        `baseUrl must be an http(s) URL, got "${base}"`,
+        0,
+        "bad_base_url"
+      );
+    this.base = base.replace(/\/+$/, "");
+    this.doFetch = opts.fetch ?? fetch;
+    this.retries = opts.maxRetries ?? 2;
+  }
+  opts;
+  base;
+  doFetch;
+  retries;
+  cache = /* @__PURE__ */ new Map();
+  /** Trust-on-first-use: a device id must keep the same identity key, or something is swapping keys (crypto-spec §3, T4). */
+  pinned = /* @__PURE__ */ new Map();
+  /** Reads `RELAY_API_KEY` and, optionally, `RELAY_API_URL`; `overrides` win over the environment. */
+  static fromEnv(env = process.env, overrides = {}) {
+    return new _Relay({
+      apiKey: env.RELAY_API_KEY ?? "",
+      baseUrl: overrides.baseUrl || env.RELAY_API_URL,
+      ...overrides.fetch && { fetch: overrides.fetch },
+      ...overrides.maxRetries !== void 0 && {
+        maxRetries: overrides.maxRetries
+      }
+    });
+  }
+  async send(m) {
+    checkRepeat(m.repeat);
+    checkRepeat(m.escalate?.repeat);
+    if (m.escalate && (!Number.isFinite(m.escalate.afterSeconds) || m.escalate.afterSeconds < 30))
+      throw new RelayError(
+        "escalate.afterSeconds must be at least 30",
+        0,
+        "invalid_message"
+      );
+    const result = await this.sendCore(m);
+    if (!m.escalate) return result;
+    const e = m.escalate;
+    const base = new Date(deliverAtIso(m) ?? Date.now());
+    result.escalation = await this.sendCore({
+      ...m,
+      topic: e.topic,
+      title: e.title ?? m.title,
+      body: e.body ?? m.body,
+      priority: e.priority ?? "urgent",
+      repeat: e.repeat,
+      escalate: void 0,
+      idempotencyKey: void 0,
+      delaySeconds: void 0,
+      deliverAt: new Date(base.getTime() + e.afterSeconds * 1e3),
+      unlessAcked: result.messageId
+    });
+    return result;
+  }
+  async sendCore(m) {
+    const plaintext = buildPlaintext(m);
+    let result = await this.sendOnce(
+      m,
+      plaintext,
+      await this.recipients(m.topic)
+    );
+    if (result.missing.length > 0) {
+      const fresh = await this.recipients(m.topic, true);
+      const only = {
+        ...fresh,
+        recipients: fresh.recipients.filter(
+          (r) => result.missing.includes(r.deviceId)
+        )
+      };
+      if (only.recipients.length > 0) {
+        const extra = await this.sendOnce(
+          { ...m, idempotencyKey: void 0 },
+          plaintext,
+          only
+        );
+        result = {
+          ...result,
+          accepted: result.accepted + extra.accepted,
+          // `extra.missing` lists devices we deliberately left out of the second request; keep only ones we still failed to reach.
+          missing: result.missing.filter(
+            (id) => !only.recipients.some((r) => r.deviceId === id) || extra.rejected.some((x) => x.deviceId === id)
+          ),
+          rejected: [...result.rejected, ...extra.rejected]
+        };
+      }
+    }
+    return result;
+  }
+  async sendOnce(m, plaintext, set) {
+    if (set.recipients.length === 0)
+      throw new RelayError(
+        `No devices are subscribed to ${m.topic} yet \u2014 pair a phone first.`,
+        0,
+        "no_recipients"
+      );
+    const messageId = ulid();
+    const body = JSON.stringify({ v: 1, id: messageId, ...plaintext });
+    const envelopes = await Promise.all(
+      set.recipients.map(
+        (r) => seal(
+          b64urlDecode(r.encPub),
+          { messageId, topicId: set.topicId, deviceId: r.deviceId },
+          body
+        )
+      )
+    );
+    const res = await this.request(
+      "POST",
+      "/v1/trigger",
+      {
+        topic: m.topic,
+        messageId,
+        priority: m.priority ?? "default",
+        ttlSeconds: m.ttlSeconds ?? 86400,
+        ...m.collapseKey ? { collapseKey: m.collapseKey } : {},
+        ...deliverAtIso(m) ? { deliverAt: deliverAtIso(m) } : {},
+        ...m.repeat ? { repeat: m.repeat } : {},
+        ...m.unlessAcked ? { unlessAcked: m.unlessAcked } : {},
+        envelopes
+      },
+      { "Idempotency-Key": m.idempotencyKey ?? messageId }
+    );
+    return res;
+  }
+  /** Recipients for a topic, verified and cached by ETag (a cheap conditional GET on every send keeps the key set fresh). */
+  async recipients(topic, bypass = false) {
+    const cached = this.cache.get(topic);
+    const res = await this.raw(
+      "GET",
+      `/v1/trigger/recipients?topic=${encodeURIComponent(topic)}`,
+      void 0,
+      !bypass && cached ? { "If-None-Match": cached.etag } : {}
+    );
+    if (res.status === 304 && cached) return cached.set;
+    const set = await this.parse(res);
+    for (const r of set.recipients) {
+      if (!verifyBinding(
+        b64urlDecode(r.bindSig),
+        b64urlDecode(r.encPub),
+        b64urlDecode(r.idPub)
+      ))
+        throw new RelayError(
+          `Device ${r.deviceId} returned an invalid key binding`,
+          0,
+          "bad_key_binding"
+        );
+      const pin = this.pinned.get(r.deviceId);
+      if (pin && pin !== r.idPub)
+        throw new RelayError(
+          `Device ${r.deviceId} changed its identity key`,
+          0,
+          "key_changed"
+        );
+      this.pinned.set(r.deviceId, r.idPub);
+    }
+    const etag = res.headers.get("etag");
+    if (etag) this.cache.set(topic, { etag, set });
+    return set;
+  }
+  async request(method, path, body, headers = {}) {
+    let attempt = 0;
+    for (; ; ) {
+      try {
+        return await this.parse(await this.raw(method, path, body, headers));
+      } 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++);
+      }
+    }
+  }
+  async raw(method, path, body, headers = {}) {
+    try {
+      return await this.doFetch(this.base + path, {
+        method,
+        headers: {
+          authorization: `Bearer ${this.opts.apiKey}`,
+          accept: "application/json",
+          ...body !== void 0 ? { "content-type": "application/json" } : {},
+          ...headers
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0
+      });
+    } catch {
+      throw new RelayError("Couldn't reach Relay", 0, "network");
+    }
+  }
+  async parse(res) {
+    const text = await res.text();
+    const json = text ? safeJson(text) : void 0;
+    if (res.ok) return json;
+    const retry = Number(res.headers.get("retry-after"));
+    throw new RelayError(
+      json?.error ?? `Relay returned ${res.status}`,
+      res.status,
+      json?.code ?? `http_${res.status}`,
+      Number.isFinite(retry) && retry > 0 ? retry : void 0
+    );
+  }
+};
+var safeJson = (t) => {
+  try {
+    return JSON.parse(t);
+  } catch {
+    return void 0;
+  }
+};
+function buildPlaintext(m) {
+  const bad = (msg, code) => new RelayError(msg, 0, code);
+  if (!m.title?.trim()) throw bad("A title is required", "invalid_message");
+  if (m.title.length > 120)
+    throw bad("Title is limited to 120 characters", "invalid_message");
+  if ((m.body?.length ?? 0) > 1e3)
+    throw bad("Body is limited to 1000 characters", "invalid_message");
+  if ((m.tags?.length ?? 0) > 5 || m.tags?.some((t) => t.length > 24))
+    throw bad("Up to 5 tags, 24 characters each", "invalid_message");
+  if (m.icon !== void 0 && !isGlyph(m.icon))
+    throw bad(
+      `Unknown icon "${m.icon}". Use one of: ${GLYPHS.join(", ")}`,
+      "invalid_message"
+    );
+  if (m.url && !/^https:\/\//i.test(m.url))
+    throw bad("url must be https", "invalid_message");
+  if (m.image && (!/^https:\/\//i.test(m.image) || m.image.length > 1e3))
+    throw bad(
+      "image must be an https link of at most 1000 characters",
+      "invalid_message"
+    );
+  if ((m.actions?.length ?? 0) > 3)
+    throw bad("At most 3 actions", "invalid_message");
+  for (const raw of m.actions ?? []) {
+    const a = raw;
+    if (!a.label?.trim() || a.label.length > 30)
+      throw bad(
+        "Action labels are required and limited to 30 characters",
+        "invalid_message"
+      );
+    if (a.link !== void 0 && a.request !== void 0)
+      throw bad(
+        `Action "${a.label}": use either request or link, not both`,
+        "invalid_message"
+      );
+    if (a.link !== void 0) {
+      if (!/^https:\/\//i.test(a.link))
+        throw bad(`Action "${a.label}": link must be https`, "invalid_message");
+      if (a.link.length > 1e3)
+        throw bad(
+          `Action "${a.label}": link is limited to 1000 characters`,
+          "invalid_message"
+        );
+    } else if (!a.request?.url || !/^https:\/\//i.test(a.request.url))
+      throw bad(`Action "${a.label}": url must be https`, "invalid_message");
+  }
+  const actions = m.actions?.map((a, i) => {
+    const id = a.id ?? `a${i + 1}`;
+    if (a.link !== void 0) return { id, label: a.label, link: a.link };
+    return {
+      style: "default",
+      confirm: a.style === "destructive",
+      retry: false,
+      ...a,
+      id
+    };
+  });
+  return {
+    ts: Math.floor(Date.now() / 1e3),
+    title: m.title,
+    ...m.body ? { body: m.body } : {},
+    priority: m.priority ?? "default",
+    ...m.tags?.length ? { tags: m.tags } : {},
+    ...m.icon ? { icon: m.icon } : {},
+    ...m.url ? { url: m.url } : {},
+    ...m.image ? { image: m.image } : {},
+    ...m.group ? { group: m.group } : {},
+    ...actions ? { actions } : {}
+  };
+}
+export {
+  PayloadTooLargeError,
+  Relay,
+  RelayError,
+  buildPlaintext
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@phuzle/relay",
+	"version": "0.1.0",
+	"description": "Send end-to-end encrypted push notifications through Relay: Node/Bun SDK and `relay` CLI. The message is encrypted on your machine; Relay only routes ciphertext.",
+	"keywords": [
+		"push",
+		"notifications",
+		"relay",
+		"fcm",
+		"e2ee",
+		"hpke",
+		"webhook"
+	],
+	"homepage": "https://docs.phuzle.com/relay",
+	"license": "MIT",
+	"author": "Phuzle Labs",
+	"type": "module",
+	"main": "./index.cjs",
+	"types": "./index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./index.d.ts",
+				"default": "./index.js"
+			},
+			"require": {
+				"types": "./index.d.cts",
+				"default": "./index.cjs"
+			}
+		},
+		"./package.json": "./package.json"
+	},
+	"bin": {
+		"relay": "cli.js"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"sideEffects": false,
+	"dependencies": {
+		"@hpke/core": "^1.7.0",
+		"@hpke/dhkem-x25519": "^1.7.0",
+		"@hpke/chacha20poly1305": "^1.7.0",
+		"@noble/curves": "^1.9.0",
+		"@noble/hashes": "^1.8.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}