@joe-broadhead/messaging 0.0.0-stage → 0.7.1

package/dist/lib/modules/core/jelly-host.js

@@ -0,0 +1,211 @@
+/**
+ * What a daemon in `deployment: "jelly"` verifies of its host (spec §8.11): action grants (`jelly-act+jwt`) on
+ * human- and admin-tier calls, and session tickets (`jelly-session+jwt`) at `session.register`. Both are compact
+ * JWS signed with EdDSA by the host's action key. Pure: the caller supplies the key, the clock and the record of
+ * spent `jti`s.
+ */
+import { verify as ed25519Verify } from "node:crypto";
+import { b64u, utf8 } from "./b64u.js";
+import { sha256 } from "./hash.js";
+import { canonicalize } from "./jcs.js";
+import { assertEd25519PublicKey, publicKeyFromRaw } from "./keys.js";
+import { parseWire } from "./wire.js";
+import { MessagingError } from "./schema/errors.js";
+import { ActKeyJwk, JELLY_SERVICE_AUDIENCE, JellyActClaims, JellyActHeader, JellySessionClaims, JellySessionHeader, Jws, } from "./schema/jelly.js";
+import { ADMIN_METHODS, HUMAN_METHODS } from "./schema/ipc.js";
+/** A method grant lives at most 60 s (`exp - iat`). */
+export const ACT_GRANT_MAX_S = 60;
+/** A host-scope grant lives at most ten minutes. */
+export const HOST_GRANT_MAX_S = 600;
+/** A session ticket lives at most seven days: the engine's lifetime. */
+export const SESSION_TICKET_MAX_S = 7 * 24 * 60 * 60;
+/** The clock skew allowed on `iat` and `exp`. */
+export const JELLY_HOST_SKEW_S = 5;
+/** `chat`: the person's own lines and read state. */
+const CHAT_METHODS = ["person.send", "conv.markRead", "notice.ack"];
+/**
+ * `view`: the read-only methods a Jelly section reads with (`section.rpc`): the read-only human-tier methods, and
+ * `device.list`, the one admin-tier read a section shows. A preview is not one of them: it takes its action's class
+ * (`local`), since it tells what a `local` action would do (`contact.request.preview` says whether an email has an
+ * account). Every method that writes is `chat` or `local`.
+ */
+const VIEW_METHODS = [
+    "conv.list",
+    "conv.read",
+    "conv.subscribe",
+    "people.search",
+    "people.get",
+    "grant.list",
+    "request.list",
+    "agents.list",
+    "agents.read",
+    "notice.subscribe",
+    "notice.list",
+    "device.list",
+];
+const classOf = (method) => CHAT_METHODS.includes(method) ? "chat" : VIEW_METHODS.includes(method) ? "view" : "local";
+/**
+ * The class a method grant must name in `cls` for each human- and admin-tier method (spec §8.11): `chat` for
+ * `person.send`, `conv.markRead` and `notice.ack`, `view` for the read-only human-tier methods, `local` for every
+ * other. A plugin's `jelly` declaration gives each action and read the same class; a test there checks one against
+ * the other.
+ */
+export const ACTION_CLASSES = Object.freeze(Object.fromEntries([...HUMAN_METHODS, ...ADMIN_METHODS].map((method) => [method, classOf(method)])));
+/** The class of `method` (`ACTION_CLASSES`); `local` for a method not in the table. */
+export function actionClass(method) {
+    return Object.hasOwn(ACTION_CLASSES, method) ? ACTION_CLASSES[method] : "local";
+}
+/** `in`: base64url SHA-256 of the JCS of a call's params (absent params are `{}`). */
+export function grantInput(params) {
+    return sha256(canonicalize(params ?? {}));
+}
+function decode(token, fail) {
+    if (!Jws.safeParse(token).success)
+        throw fail("is not a compact JWS");
+    const [header, payload, signature] = token.split(".");
+    const segment = (text, what) => {
+        try {
+            return parseWire(new TextDecoder("utf-8", { fatal: true }).decode(b64u.decode(text)), { maxBytes: 8192 });
+        }
+        catch {
+            throw fail(`${what} is not base64url JSON`);
+        }
+    };
+    let sig;
+    try {
+        sig = b64u.decode(signature);
+    }
+    catch {
+        throw fail("signature is not base64url");
+    }
+    if (sig.length !== 64)
+        throw fail("signature is not 64 bytes");
+    return { header: segment(header, "header"), claims: segment(payload, "claims"), input: utf8(`${header}.${payload}`), signature: sig };
+}
+function checkSignature(decoded, kid, key, fail) {
+    if (key.kid !== undefined && kid !== key.kid)
+        throw fail("names another key");
+    let ok = false;
+    try {
+        ok = ed25519Verify(null, decoded.input, publicKeyFromRaw("ed25519", key.x), decoded.signature);
+    }
+    catch {
+        ok = false;
+    }
+    if (!ok)
+        throw fail("signature does not verify");
+}
+function checkTimes(iat, exp, max, nowMs, fail) {
+    const now = Math.floor(nowMs / 1000);
+    if (exp <= iat || exp - iat > max)
+        throw fail(`lifetime is not in (0, ${max}] seconds`);
+    if (iat > now + JELLY_HOST_SKEW_S)
+        throw fail("is issued in the future");
+    if (exp + JELLY_HOST_SKEW_S <= now)
+        throw fail("has expired");
+}
+/**
+ * Verifies an action grant for one call (spec §8.11): the header, the signature by the action key, `aud`, then
+ * either `act` = the method with `in` = `grantInput(params)` and a lifetime of at most 60 s, or `act: "host"` for a
+ * method of the host-scope list with a lifetime of at most ten minutes. A method grant names the method's class in
+ * `cls` (`actionClass`); a host-scope grant names none. `mbr` is returned for the log and gives no authority. It does not spend the `jti`: the caller does, once per method grant. Throws `grant_invalid`; the message
+ * names the reason and never quotes the grant.
+ */
+export function verifyActGrant(token, check) {
+    const fail = (why) => new MessagingError("grant_invalid", `the action grant ${why}`);
+    const decoded = decode(token, fail);
+    const header = JellyActHeader.safeParse(decoded.header);
+    if (!header.success)
+        throw fail("header is not EdDSA jelly-act+jwt with a key id");
+    const parsed = JellyActClaims.safeParse(decoded.claims);
+    if (!parsed.success)
+        throw fail(`claims are malformed at ${parsed.error.issues[0]?.path.map(String).join(".") || "(root)"}`);
+    checkSignature(decoded, header.data.kid, check.key, fail);
+    const claims = parsed.data;
+    if (claims.aud !== JELLY_SERVICE_AUDIENCE)
+        throw fail("is for another audience");
+    if (claims.act === "host") {
+        if (!check.hostScope(check.method))
+            throw fail(`is host scope, which does not allow ${check.method}`);
+        checkTimes(claims.iat, claims.exp, HOST_GRANT_MAX_S, check.now, fail);
+    }
+    else {
+        if (claims.act !== check.method)
+            throw fail("is for another method");
+        if (claims.in === undefined || claims.in !== grantInput(check.params))
+            throw fail("is for other params");
+        checkTimes(claims.iat, claims.exp, ACT_GRANT_MAX_S, check.now, fail);
+    }
+    if (claims.act === "host") {
+        if (claims.cls !== undefined)
+            throw fail("is host scope, which names no action class");
+    }
+    else {
+        if (claims.cls === undefined)
+            throw fail("names no action class");
+        if (claims.cls !== actionClass(check.method))
+            throw fail(`names action class ${claims.cls}, not ${actionClass(check.method)}`);
+    }
+    return { scope: claims.act === "host" ? "host" : "action", jti: claims.jti, exp: claims.exp, dev: claims.dev, mbr: claims.mbr };
+}
+/**
+ * Verifies a session ticket (spec §8.11): the header, the signature by the action key, `aud`, and a lifetime of at
+ * most seven days. Throws `ticket_invalid`; the message never quotes the ticket.
+ */
+export function verifySessionTicket(token, key, now) {
+    const fail = (why) => new MessagingError("ticket_invalid", `the session ticket ${why}`);
+    const decoded = decode(token, fail);
+    const header = JellySessionHeader.safeParse(decoded.header);
+    if (!header.success)
+        throw fail("header is not EdDSA jelly-session+jwt with a key id");
+    const parsed = JellySessionClaims.safeParse(decoded.claims);
+    if (!parsed.success)
+        throw fail(`claims are malformed at ${parsed.error.issues[0]?.path.map(String).join(".") || "(root)"}`);
+    checkSignature(decoded, header.data.kid, key, fail);
+    const claims = parsed.data;
+    if (claims.aud !== JELLY_SERVICE_AUDIENCE)
+        throw fail("is for another audience");
+    checkTimes(claims.iat, claims.exp, SESSION_TICKET_MAX_S, now, fail);
+    return { agt: claims.agt, name: claims.name, exp: claims.exp };
+}
+/** Reads `--act-key`'s text: exactly a public Ed25519 JWK (`ActKeyJwk`), a usable point. Throws `invalid_request`. */
+export function parseActKey(text) {
+    let value;
+    try {
+        value = parseWire(text, { maxBytes: 4096 });
+    }
+    catch {
+        throw new MessagingError("invalid_request", "the action key is not JSON");
+    }
+    const parsed = ActKeyJwk.safeParse(value);
+    if (!parsed.success)
+        throw new MessagingError("invalid_request", "the action key is not exactly a public Ed25519 JWK");
+    try {
+        assertEd25519PublicKey(parsed.data.x, "action key");
+    }
+    catch {
+        throw new MessagingError("invalid_request", "the action key is not a usable Ed25519 key");
+    }
+    return parsed.data;
+}
+/**
+ * Reads a wake ticket's header and claims without verifying it: a compact JWS whose header is `jelly-wake+jwt`, with
+ * an integer `exp` and, when present, a string `aud` and `sub`. A relay holds the ticket only to present it to Jelly
+ * ID, which verifies the signature, the host and the single use; it reads `exp` to expire it and `aud` to check that the
+ * ticket is for the URL it is armed with. Throws `invalid_request`; the message never quotes the ticket.
+ */
+export function readWakeTicket(token) {
+    const fail = (why) => new MessagingError("invalid_request", `the wake ticket ${why}`);
+    const decoded = decode(token, fail);
+    const header = decoded.header;
+    if (typeof header !== "object" || header === null || header.typ !== "jelly-wake+jwt" || header.alg !== "EdDSA")
+        throw fail("header is not EdDSA jelly-wake+jwt");
+    const claims = decoded.claims;
+    if (typeof claims !== "object" || claims === null || typeof claims.exp !== "number" || !Number.isSafeInteger(claims.exp))
+        throw fail("has no exp");
+    if (claims.aud !== undefined && typeof claims.aud !== "string")
+        throw fail("aud is not one string");
+    if (claims.sub !== undefined && typeof claims.sub !== "string")
+        throw fail("sub is not a string");
+    return { exp: claims.exp, aud: claims.aud, sub: claims.sub };
+}

package/dist/lib/modules/core/keys.js

@@ -0,0 +1,79 @@
+import { createPrivateKey, createPublicKey, KeyObject } from "node:crypto";
+import { b64u } from "./b64u.js";
+import { MessagingError } from "./schema/errors.js";
+const CURVE = { ed25519: "Ed25519", x25519: "X25519" };
+// PKCS#8 DER header for a raw 32-byte private key (RFC 8410).
+const PKCS8_HEADER = {
+    ed25519: Buffer.from("302e020100300506032b657004220420", "hex"),
+    x25519: Buffer.from("302e020100300506032b656e04220420", "hex"),
+};
+// libsodium's Ed25519 small-order blocklist, compared without the sign bit (bit 255): the encodings of
+// the eight points of order 1, 2, 4 and 8, and the non-canonical encodings p and p + 1 of 0 and 1.
+// With such a key one signature verifies for every message.
+const SMALL_ORDER = [
+    "0000000000000000000000000000000000000000000000000000000000000000",
+    "0100000000000000000000000000000000000000000000000000000000000000",
+    "26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc05",
+    "c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a",
+    "ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f",
+    "edffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f",
+    "eeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f",
+].map((hex) => Buffer.from(hex, "hex"));
+/** A private key from its raw 32 bytes (the JWK `d`). */
+export function privateKeyFromRaw(type, raw) {
+    if (raw.length !== 32)
+        throw new MessagingError("invalid_request", `${type} private key must be 32 bytes`);
+    return createPrivateKey({ key: Buffer.concat([PKCS8_HEADER[type], raw]), format: "der", type: "pkcs8" });
+}
+/** A public key from its raw 32 bytes in base64url (the JWK `x`). Ed25519 keys must pass `assertEd25519PublicKey`. */
+export function publicKeyFromRaw(type, x) {
+    if (type === "ed25519")
+        assertEd25519PublicKey(x, "Ed25519 public key");
+    else if (b64u.decode(x).length !== 32)
+        throw new MessagingError("invalid_request", `${type} public key must be 32 bytes`);
+    return createPublicKey({ key: { kty: "OKP", crv: CURVE[type], x }, format: "jwk" });
+}
+/**
+ * Throws `invalid_request` unless `x` is 32 bytes of base64url encoding y < p (canonical) and not of
+ * small order, as libsodium checks before verifying (spec §3).
+ */
+export function assertEd25519PublicKey(x, what) {
+    const raw = b64u.decode(x);
+    if (raw.length !== 32)
+        throw new MessagingError("invalid_request", `${what} must be 32 bytes`);
+    if (!isCanonical(raw))
+        throw new MessagingError("invalid_request", `${what} is not a canonical encoding`);
+    if (SMALL_ORDER.some((weak) => sameIgnoringSign(raw, weak)))
+        throw new MessagingError("invalid_request", `${what} has small order`);
+}
+/** y (the low 255 bits, little-endian) is below p = 2^255 − 19, i.e. not in [p, 2^255 − 1]. */
+function isCanonical(raw) {
+    if ((raw[31] & 0x7f) !== 0x7f)
+        return true;
+    for (let i = 30; i > 0; i--)
+        if (raw[i] !== 0xff)
+            return true;
+    return raw[0] < 0xed;
+}
+function sameIgnoringSign(raw, weak) {
+    for (let i = 0; i < 31; i++)
+        if (raw[i] !== weak[i])
+            return false;
+    return (raw[31] & 0x7f) === weak[31];
+}
+/** Raw public key (base64url) of a private or public key. */
+export function rawPublicKey(key) {
+    const x = (key.type === "public" ? key : createPublicKey(key)).export({ format: "jwk" }).x;
+    if (typeof x !== "string")
+        throw new MessagingError("internal", "key has no raw public form");
+    return x;
+}
+export function rawPrivateKey(key) {
+    const d = key.export({ format: "jwk" }).d;
+    if (typeof d !== "string")
+        throw new MessagingError("internal", "key has no raw private form");
+    return d;
+}
+export function isPrivateKey(key, type) {
+    return key instanceof KeyObject && key.type === "private" && key.asymmetricKeyType === type;
+}