@mh-gg/push 0.1.1-alpha.20260626T104441232Z

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matterhorn contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @mh-gg/push
+
+

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mh-gg/push",
+  "version": "0.1.1-alpha.20260626T104441232Z",
+  "type": "commonjs",
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs",
+    "./browser": "./src/browser.cjs"
+  },
+  "dependencies": {
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "web-push": "^3.6.7",
+    "@mh-gg/room-security": "^0.1.1-alpha.20260626T104441232Z"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "license": "MIT",
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.cjs",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=80 --test-coverage-include=src/**/*.cjs test/*.test.cjs"
+  }
+}

package/src/browser.cjs

@@ -0,0 +1,140 @@
+const { p256 } = require("@noble/curves/nist.js");
+const { sha256 } = require("@noble/hashes/sha2.js");
+const {
+  USER_VAPID_DERIVATION_LABEL,
+  VAPID_GRANT_KIND,
+  VAPID_GRANT_VERSION,
+  VAPID_GRANT_WRAP_ALG
+} = require("./constants.cjs");
+
+const P256_ORDER = BigInt("0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551");
+
+function base64url(bytes) {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64url");
+  /* node:coverage ignore next 4 */
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+function fromBase64url(value) {
+  const text = String(value || "");
+  if (typeof Buffer !== "undefined") return Buffer.from(text, "base64url");
+  /* node:coverage ignore next 6 */
+  const base64 = `${text}${"=".repeat((4 - (text.length % 4)) % 4)}`.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+
+function utf8Bytes(value) {
+  if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(value);
+  /* node:coverage ignore next */
+  return Buffer.from(value, "utf8");
+}
+
+function concatBytes(parts) {
+  const length = parts.reduce((total, part) => total + part.byteLength, 0);
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const part of parts) {
+    bytes.set(part, offset);
+    offset += part.byteLength;
+  }
+  return bytes;
+}
+
+function deriveUserVapidScalar(rootKey, label = USER_VAPID_DERIVATION_LABEL) {
+  if (!(rootKey instanceof Uint8Array) || rootKey.byteLength === 0) throw new Error("rootKey must be a non-empty Uint8Array.");
+  const digest = sha256(concatBytes([
+    utf8Bytes("matterhorn.user-vapid.v1"),
+    new Uint8Array([0]),
+    utf8Bytes(label),
+    new Uint8Array([0]),
+    rootKey
+  ]));
+  const hex = Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  const scalar = (BigInt(`0x${hex}`) % (P256_ORDER - 1n)) + 1n;
+  const privateHex = scalar.toString(16).padStart(64, "0");
+  return new Uint8Array(privateHex.match(/../g).map((byte) => Number.parseInt(byte, 16)));
+}
+
+function deriveUserVapidKeys(rootKey, label = USER_VAPID_DERIVATION_LABEL) {
+  const privateKey = deriveUserVapidScalar(rootKey, label);
+  const publicKey = p256.getPublicKey(privateKey, false);
+  return {
+    publicKey: base64url(publicKey),
+    privateKey: base64url(privateKey)
+  };
+}
+
+function vapidPublicKeyFromPrivateKey(privateKeyBase64url) {
+  const privateKeyBytes = fromBase64url(privateKeyBase64url);
+  const publicKeyBytes = p256.getPublicKey(privateKeyBytes, false);
+  return base64url(publicKeyBytes);
+}
+
+function cryptoProvider() {
+  const provider = globalThis.crypto || globalThis.msCrypto;
+  if (!provider?.subtle) throw new Error("WebCrypto is required.");
+  return provider;
+}
+
+function grantAad(grant) {
+  return utf8Bytes(JSON.stringify([
+    "matterhorn.vapid-grant.v1",
+    grant.relayPublicKey,
+    grant.createdAt
+  ]));
+}
+
+async function grantKey(sharedSecret, grant) {
+  const subtle = cryptoProvider().subtle;
+  const key = await subtle.importKey("raw", sharedSecret, "HKDF", false, ["deriveKey"]);
+  return subtle.deriveKey(
+    { name: "HKDF", hash: "SHA-256", salt: grantAad(grant), info: utf8Bytes("matterhorn:vapid-grant:v1") },
+    key,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt"]
+  );
+}
+
+async function publicKeyFromSpkiBase64url(value) {
+  return cryptoProvider().subtle.importKey("spki", fromBase64url(value), { name: "X25519" }, false, []);
+}
+
+async function wrapVapidGrant({ vapidPrivateKey, relayPublicKey }) {
+  if (typeof vapidPrivateKey !== "string" || vapidPrivateKey.length === 0) throw new Error("vapidPrivateKey is required.");
+  if (typeof relayPublicKey !== "string" || relayPublicKey.length === 0) throw new Error("relayPublicKey is required.");
+  const provider = cryptoProvider();
+  const recipientPublicKey = await publicKeyFromSpkiBase64url(relayPublicKey);
+  const ephemeral = await provider.subtle.generateKey({ name: "X25519" }, true, ["deriveBits"]);
+  const sharedSecret = await provider.subtle.deriveBits({ name: "X25519", public: recipientPublicKey }, ephemeral.privateKey, 256);
+  const grant = {
+    kind: VAPID_GRANT_KIND,
+    version: VAPID_GRANT_VERSION,
+    relayPublicKey,
+    createdAt: Date.now(),
+    wrap: {
+      alg: VAPID_GRANT_WRAP_ALG,
+      ephemeralPublicKey: base64url(new Uint8Array(await provider.subtle.exportKey("spki", ephemeral.publicKey)))
+    }
+  };
+  const iv = provider.getRandomValues(new Uint8Array(12));
+  const encrypted = new Uint8Array(await provider.subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: grantAad(grant) },
+    await grantKey(sharedSecret, grant),
+    utf8Bytes(vapidPrivateKey)
+  ));
+  grant.wrap.iv = base64url(iv);
+  grant.wrappedVapidPrivateKey = base64url(encrypted);
+  return grant;
+}
+
+module.exports = {
+  deriveUserVapidKeys,
+  wrapVapidGrant,
+  vapidPublicKeyFromPrivateKey
+};

package/src/browser.d.ts

@@ -0,0 +1,21 @@
+export interface VapidKeys {
+  publicKey: string;
+  privateKey: string;
+}
+
+export interface VapidGrant {
+  kind: string;
+  version: number;
+  relayPublicKey: string;
+  createdAt: number;
+  wrap: {
+    alg: string;
+    ephemeralPublicKey: string;
+    iv?: string;
+  };
+  wrappedVapidPrivateKey?: string;
+}
+
+export function deriveUserVapidKeys(rootKey: Uint8Array, label?: string): VapidKeys;
+export function wrapVapidGrant(input: { vapidPrivateKey: string; relayPublicKey: string }): Promise<VapidGrant>;
+export function vapidPublicKeyFromPrivateKey(privateKeyBase64url: string): string;

package/src/constants.cjs

@@ -0,0 +1,28 @@
+const USER_VAPID_DERIVATION_LABEL = "matterhorn/vapid/v1";
+const VAPID_GRANT_KIND = "matterhorn.vapid-grant";
+const VAPID_GRANT_VERSION = 1;
+const VAPID_GRANT_WRAP_ALG = "x25519+hkdf-sha256+aes-256-gcm";
+const MAX_PUSH_PAYLOAD_BYTES = 3 * 1024;
+const DEFAULT_PUSH_TTL_SECONDS = 60 * 60;
+const DEFAULT_PUSH_URGENCY = "high";
+const PUSH_URGENCY_VALUES = ["very-low", "low", "normal", "high"];
+
+const CLIENT_PUSH_REGISTER = "client/push-register";
+const CLIENT_PUSH_GRANT = "client/push-grant";
+const RELAY_PUSH = "relay.push";
+const PUSH_HOME_RELAYS_EVENT_KIND = "push.home-relays";
+
+module.exports = {
+  CLIENT_PUSH_GRANT,
+  CLIENT_PUSH_REGISTER,
+  DEFAULT_PUSH_TTL_SECONDS,
+  DEFAULT_PUSH_URGENCY,
+  MAX_PUSH_PAYLOAD_BYTES,
+  PUSH_URGENCY_VALUES,
+  PUSH_HOME_RELAYS_EVENT_KIND,
+  RELAY_PUSH,
+  USER_VAPID_DERIVATION_LABEL,
+  VAPID_GRANT_KIND,
+  VAPID_GRANT_VERSION,
+  VAPID_GRANT_WRAP_ALG
+};

package/src/index.cjs

@@ -0,0 +1,160 @@
+const crypto = require("node:crypto");
+const { deriveUserVapidKeys, wrapVapidGrant: wrapVapidGrantBrowser, vapidPublicKeyFromPrivateKey } = require("./browser.cjs");
+const {
+  DEFAULT_PUSH_URGENCY,
+  DEFAULT_PUSH_TTL_SECONDS,
+  PUSH_URGENCY_VALUES,
+  VAPID_GRANT_KIND,
+  VAPID_GRANT_VERSION,
+  VAPID_GRANT_WRAP_ALG
+} = require("./constants.cjs");
+
+function fromBase64url(value) {
+  return Buffer.from(String(value || ""), "base64url");
+}
+
+function publicKeyFromSpkiBase64url(value) {
+  return crypto.createPublicKey({ key: fromBase64url(value), type: "spki", format: "der" });
+}
+
+function privateKeyFromPkcs8Base64url(value) {
+  return crypto.createPrivateKey({ key: fromBase64url(value), type: "pkcs8", format: "der" });
+}
+
+function grantAad(grant) {
+  return Buffer.from(JSON.stringify([
+    "matterhorn.vapid-grant.v1",
+    grant.relayPublicKey,
+    grant.createdAt
+  ]), "utf8");
+}
+
+function grantKey(sharedSecret, grant) {
+  return Buffer.from(crypto.hkdfSync(
+    "sha256",
+    sharedSecret,
+    grantAad(grant),
+    Buffer.from("matterhorn:vapid-grant:v1", "utf8"),
+    32
+  ));
+}
+
+function relayPrivateKeyObject(relayPrivateKey) {
+  if (typeof relayPrivateKey === "string") return privateKeyFromPkcs8Base64url(relayPrivateKey);
+  return relayPrivateKey;
+}
+
+function unwrapVapidGrant({ grant, relayPrivateKey }) {
+  if (!grant || grant.kind !== VAPID_GRANT_KIND || grant.version !== VAPID_GRANT_VERSION) throw new Error("VAPID grant is invalid.");
+  if (grant.wrap?.alg !== VAPID_GRANT_WRAP_ALG) throw new Error("VAPID grant wrap algorithm is invalid.");
+  const privateKey = relayPrivateKeyObject(relayPrivateKey);
+  const ephemeralPublicKey = publicKeyFromSpkiBase64url(grant.wrap.ephemeralPublicKey);
+  const sharedSecret = crypto.diffieHellman({ privateKey, publicKey: ephemeralPublicKey });
+  const bytes = fromBase64url(grant.wrappedVapidPrivateKey);
+  if (bytes.length < 17) throw new Error("VAPID grant ciphertext is invalid.");
+  const ciphertext = bytes.subarray(0, bytes.length - 16);
+  const authTag = bytes.subarray(bytes.length - 16);
+  const decipher = crypto.createDecipheriv("aes-256-gcm", grantKey(sharedSecret, grant), fromBase64url(grant.wrap.iv));
+  decipher.setAAD(grantAad(grant));
+  decipher.setAuthTag(authTag);
+  return {
+    vapidPrivateKey: Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8")
+  };
+}
+
+function wrapVapidGrant(args) {
+  const relayPublicKey = args?.relayPublicKey;
+  if (typeof relayPublicKey !== "string" || relayPublicKey.length === 0) throw new Error("relayPublicKey is required.");
+  const recipientPublicKey = publicKeyFromSpkiBase64url(relayPublicKey);
+  const ephemeral = crypto.generateKeyPairSync("x25519");
+  const sharedSecret = crypto.diffieHellman({ privateKey: ephemeral.privateKey, publicKey: recipientPublicKey });
+  const grant = {
+    kind: VAPID_GRANT_KIND,
+    version: VAPID_GRANT_VERSION,
+    relayPublicKey,
+    createdAt: Date.now(),
+    wrap: {
+      alg: VAPID_GRANT_WRAP_ALG,
+      ephemeralPublicKey: Buffer.from(ephemeral.publicKey.export({ type: "spki", format: "der" })).toString("base64url")
+    }
+  };
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv("aes-256-gcm", grantKey(sharedSecret, grant), iv);
+  cipher.setAAD(grantAad(grant));
+  const encrypted = Buffer.concat([cipher.update(Buffer.from(args.vapidPrivateKey, "utf8")), cipher.final(), cipher.getAuthTag()]);
+  grant.wrap.iv = iv.toString("base64url");
+  grant.wrappedVapidPrivateKey = encrypted.toString("base64url");
+  return grant;
+}
+
+function loadWebPush() {
+  try {
+    return require("web-push");
+  } catch (error) {
+    throw new Error("web-push dependency is required for push egress.");
+  }
+}
+
+function normalizePayload(payload) {
+  if (payload instanceof Uint8Array) return Buffer.from(payload);
+  throw new Error("payload must be a Uint8Array.");
+}
+
+function normalizeTtlSeconds(ttlSeconds) {
+  const ttl = Number(ttlSeconds);
+  if (!Number.isFinite(ttl) || ttl <= 0) return DEFAULT_PUSH_TTL_SECONDS;
+  return Math.floor(ttl);
+}
+
+function normalizeUrgency(urgency) {
+  if (PUSH_URGENCY_VALUES.includes(urgency)) return urgency;
+  return DEFAULT_PUSH_URGENCY;
+}
+
+async function sendWebPush({
+  subscription,
+  vapidPublicKey,
+  vapidPrivateKey,
+  subject,
+  payload,
+  ttlSeconds = DEFAULT_PUSH_TTL_SECONDS,
+  urgency = DEFAULT_PUSH_URGENCY,
+  webPush: injectedWebPush
+}) {
+  const body = normalizePayload(payload);
+  const webPush = injectedWebPush || loadWebPush();
+  webPush.setVapidDetails(subject, vapidPublicKey, vapidPrivateKey);
+  const normalizedUrgency = normalizeUrgency(urgency);
+  try {
+    const result = await webPush.sendNotification(subscription, body, {
+      TTL: normalizeTtlSeconds(ttlSeconds),
+      urgency: normalizedUrgency,
+      headers: { Urgency: normalizedUrgency }
+    });
+    return { statusCode: result.statusCode || 201, gone: false };
+  } catch (error) {
+    const statusCode = Number(error?.statusCode || error?.status || 0);
+    if (statusCode === 404 || statusCode === 410) return { statusCode, gone: true };
+    throw error;
+  }
+}
+
+async function sendToUser({ vapidPublicKey, vapidPrivateKey, subject, subscriptions, payload, ttlSeconds, urgency, webPush }) {
+  const results = [];
+  for (const subscription of subscriptions || []) {
+    const result = await sendWebPush({ subscription, vapidPublicKey, vapidPrivateKey, subject, payload, ttlSeconds, urgency, webPush });
+    results.push({ endpoint: subscription.endpoint, ...result });
+  }
+  return results;
+}
+
+module.exports = {
+  ...require("./constants.cjs"),
+  deriveUserVapidKeys,
+  sendToUser,
+  sendWebPush,
+  unwrapVapidGrant,
+  wrapVapidGrant,
+  wrapVapidGrantBrowser,
+  vapidPublicKeyFromPrivateKey
+};