@joe-broadhead/messaging 0.0.0-stage → 0.7.0

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

@@ -0,0 +1,199 @@
+/**
+ * Consent (spec §6.9), pure: signing and verifying a person's grants, choosing between two copies of one grant,
+ * re-signing the grants of a removed device, and deciding what a receiving person's daemon does with an envelope
+ * from another person. The daemon supplies the facts (the relation, the grants whose signers are current, the
+ * delegation chain) and the clock.
+ */
+import { asMessagingError, parseWith } from "./check.js";
+import { canonicalize } from "./jcs.js";
+import { utf8 } from "./b64u.js";
+import { DOMAIN, LIMITS, PROTOCOL } from "./schema/common.js";
+import { ConsentGrant, grantProblem, } from "./schema/consent.js";
+import { MessagingError } from "./schema/errors.js";
+import { sign, signingInput, verifyInput } from "./sign.js";
+import { ulid } from "./ulid.js";
+/** Signs a new grant with `identity`, a device of `args.person`. Throws `invalid_request` for a grant that breaks a rule. */
+export function signConsentGrant(identity, args) {
+    const unsigned = {
+        v: PROTOCOL,
+        realm: args.realm,
+        id: args.id ?? ulid(args.now),
+        person: args.person,
+        by: identity.machine,
+        ts: args.now,
+        subject: args.subject,
+        ...defined(args.levels),
+    };
+    return finish(identity, unsigned);
+}
+function finish(identity, unsigned) {
+    const problem = grantProblem(unsigned);
+    if (problem)
+        throw new MessagingError("invalid_request", problem);
+    const grant = parseWith(ConsentGrant, { ...unsigned, sig: sign(identity, DOMAIN.grant, unsigned) }, "grant");
+    if (utf8(canonicalize(grant)).length > LIMITS.grantBytes)
+        throw new MessagingError("too_large", `a grant is at most ${LIMITS.grantBytes} bytes`);
+    return grant;
+}
+/**
+ * Checks a grant received from another device: the schema and its rules, the size, the realm, the person when
+ * given, and the signature by `by` over the raw value (so members a newer device adds stay covered). Whether `by`
+ * is a current device of `person` is the caller's: that changes over time (spec §6.9, "Signers"). Throws only
+ * MessagingError: `invalid_request`, `too_large` or `bad_signature`.
+ */
+export function verifyConsentGrant(raw, ctx) {
+    try {
+        const grant = parseWith(ConsentGrant, raw, "grant");
+        // I-JSON within LIMITS.jsonDepth, then the size of the whole grant as received.
+        if (utf8(canonicalize(raw)).length > LIMITS.grantBytes)
+            throw new MessagingError("too_large", `a grant is at most ${LIMITS.grantBytes} bytes`);
+        const { sig, ...unsigned } = raw;
+        const input = signingInput(DOMAIN.grant, unsigned);
+        if (grant.realm !== ctx.realm)
+            throw new MessagingError("invalid_request", "the grant is for another realm");
+        if (ctx.person !== undefined && grant.person !== ctx.person)
+            throw new MessagingError("invalid_request", "the grant is another person's");
+        if (typeof sig !== "string" || !verifyInput(grant.by, input, sig))
+            throw new MessagingError("bad_signature", "the grant's signature is invalid");
+        return grant;
+    }
+    catch (error) {
+        throw asMessagingError(error, "grant");
+    }
+}
+/** The key one grant is stored under: its subject. One grant per subject. */
+export function grantSubjectKey(subject) {
+    return "person" in subject ? `person:${subject.person}` : `channel:${subject.channel}`;
+}
+/**
+ * Of two copies of the grant for one subject, the one that counts (spec §6.9, "Merging"): the newer by `ts`, then
+ * by `id`. Copies that tie on both are one grant signed twice: a copy whose signer is current beats one whose
+ * signer is not; between two current signers (or two removed ones), the signer that sorts first wins, then the
+ * signature. The choice is commutative and idempotent, so devices that see the same copies in any order agree.
+ */
+export function preferGrant(a, b, current) {
+    if (a.ts !== b.ts)
+        return a.ts > b.ts ? a : b;
+    if (a.id !== b.id)
+        return a.id > b.id ? a : b;
+    const ca = current(a.by);
+    const cb = current(b.by);
+    if (ca !== cb)
+        return ca ? a : b;
+    if (a.by !== b.by)
+        return a.by < b.by ? a : b;
+    return a.sig <= b.sig ? a : b;
+}
+/** Levels that narrow reach: blocks never lapse (spec §6.9, "Signers"). */
+export function restrictingLevels(grant) {
+    return defined({
+        chat: grant.chat === "blocked" || grant.chat === "muted" ? grant.chat : undefined,
+        agentMail: grant.agentMail === "blocked" ? grant.agentMail : undefined,
+        ask: grant.ask === "no" ? grant.ask : undefined,
+        discoverable: grant.discoverable === false ? false : undefined,
+    });
+}
+/** Levels that widen reach: they lapse with their signer, into the person's review list. */
+export function wideningLevels(grant) {
+    return defined({
+        chat: grant.chat === "open" ? grant.chat : undefined,
+        agentMail: grant.agentMail === "open" ? grant.agentMail : undefined,
+        ask: grant.ask === "open" || grant.ask === "request" ? grant.ask : undefined,
+        trustedUntil: grant.trustedUntil,
+        discoverable: grant.discoverable === true ? true : undefined,
+    });
+}
+/**
+ * Re-signs a grant whose signer is no longer current with `identity`, a current device of the same person
+ * (spec §6.9, "Signers"). `keep: "all"` (a replacement) keeps every level; `keep: "restricting"` (any other
+ * removal) keeps only the restricting ones, and returns undefined when there are none: the grant lapses whole.
+ * The copy keeps `id` and `ts`, so it never overrides a newer change, and records `resignedAt`.
+ */
+export function resignGrant(identity, grant, opts) {
+    const levels = opts.keep === "all" ? levelsOf(grant) : restrictingLevels(grant);
+    if (opts.keep === "restricting" && Object.keys(levels).length === 0)
+        return undefined;
+    const { v, realm, id, person, ts, subject } = grant;
+    return finish(identity, { v, realm, id, person, by: identity.machine, ts, subject, ...levels, resignedAt: Math.max(opts.now, ts) });
+}
+export function levelsOf(grant) {
+    return defined({ chat: grant.chat, agentMail: grant.agentMail, ask: grant.ask, trustedUntil: grant.trustedUntil, discoverable: grant.discoverable });
+}
+const DEFAULTS = {
+    org: { chat: "open", agentMail: "open", ask: "request" },
+    contact: { chat: "open", agentMail: "blocked", ask: "no" },
+    stranger: { chat: "request_required", agentMail: "blocked", ask: "no" },
+};
+const ASK_RANK = { no: 0, request: 1, open: 2 };
+/**
+ * Spec §6.9, "Effective policy": each level is the person grant's when it sets one; otherwise, for `ask` and
+ * `agentMail`, the most permissive among the grants of channels the sender is in; otherwise the relation's
+ * default. An expired `trustedUntil` reads as absent. The caller passes only grants whose signer is current.
+ */
+export function effectivePolicy(relation, person, channels, now) {
+    const base = DEFAULTS[relation];
+    const channelAsk = channels.map((grant) => grant.ask).filter((level) => level !== undefined);
+    const channelMail = channels.map((grant) => grant.agentMail).filter((level) => level !== undefined);
+    const ask = person?.ask ?? (channelAsk.length > 0 ? channelAsk.reduce((a, b) => (ASK_RANK[b] > ASK_RANK[a] ? b : a)) : undefined);
+    const agentMail = person?.agentMail ?? (channelMail.length > 0 ? (channelMail.includes("open") ? "open" : "blocked") : undefined);
+    const trusted = person?.trustedUntil !== undefined && person.trustedUntil > now && person.ask === "open";
+    return {
+        chat: person?.chat ?? base.chat,
+        agentMail: agentMail ?? base.agentMail,
+        ask: ask ?? base.ask,
+        ...(trusted ? { trustedUntil: person.trustedUntil } : {}),
+        granted: { chat: person?.chat !== undefined, agentMail: agentMail !== undefined, ask: ask !== undefined },
+    };
+}
+/**
+ * Spec §6.9, "Enforcement": step 10 of the receiver order (§5), before the inbound policy of §8.3.
+ * - The person's own traffic is delivered as `self`.
+ * - Answers to the person's own traffic are delivered whatever the grants, so a change never strands a task.
+ * - A `blocked` chat level refuses every other class from the sender.
+ * - A `stranger` reaches the person only through a level a grant opened; otherwise `request_required`.
+ * - Lines follow `chat` (person) or `agentMail` (agent); `muted` delivers silently.
+ * - Asks follow `ask`: `open` delivers guarded, or trusted while the person grant trusts the sender and every person
+ *   in the delegation chain is the sender or the receiver; `request` holds; `no` refuses, `request_required` when
+ *   it is the default of a `contact` or a `stranger`.
+ * - A message request from a `stranger` is held for the person to accept; from anyone else it is a DM line.
+ */
+export function decide(args) {
+    const { inbound } = args;
+    if (args.relation === "self" || args.sender === args.self)
+        return { action: "deliver", consent: "self" };
+    const policy = effectivePolicy(args.relation, args.grant, args.channels, args.now);
+    const trusted = (chain) => policy.trustedUntil !== undefined && chain.every((person) => person === args.sender || person === args.self);
+    if (inbound.kind === "answer")
+        return { action: "deliver", consent: trusted([args.sender]) ? "trusted" : "guarded" };
+    if (policy.chat === "blocked")
+        return { action: "refuse", code: "refused" };
+    const stranger = args.relation === "stranger";
+    switch (inbound.kind) {
+        case "op":
+            if (stranger)
+                return { action: "refuse", code: "request_required" };
+            return { action: "deliver", consent: "guarded" };
+        case "line":
+            if (inbound.agent) {
+                if (policy.agentMail === "open")
+                    return { action: "deliver", consent: "guarded" };
+                return { action: "refuse", code: stranger && !policy.granted.agentMail ? "request_required" : "refused" };
+            }
+            if (policy.chat === "request_required")
+                return { action: "refuse", code: "request_required" };
+            return policy.chat === "muted" ? { action: "deliver", consent: "guarded", silent: true } : { action: "deliver", consent: "guarded" };
+        case "request":
+            if (stranger)
+                return { action: "hold" };
+            return policy.chat === "muted" ? { action: "deliver", consent: "guarded", silent: true } : { action: "deliver", consent: "guarded" };
+        case "ask":
+            if (policy.ask === "open")
+                return { action: "deliver", consent: trusted(inbound.chain) ? "trusted" : "guarded" };
+            if (policy.ask === "request")
+                return { action: "hold" };
+            return { action: "refuse", code: !policy.granted.ask && (stranger || args.relation === "contact") ? "request_required" : "refused" };
+    }
+}
+function defined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}

package/dist/lib/modules/core/contact-card.js

@@ -0,0 +1,74 @@
+/**
+ * Contact cards (spec §6.9, "Contact cards"), pure: what a person tells another person they may send them, signed by
+ * one of the person's devices. A card is advice for the sender's surfaces; the person's own daemon enforces the
+ * grants, which may be newer.
+ */
+import { utf8 } from "./b64u.js";
+import { asMessagingError, parseWith } from "./check.js";
+import { effectivePolicy } from "./consent.js";
+import { canonicalize } from "./jcs.js";
+import { DOMAIN, LIMITS, PROTOCOL } from "./schema/common.js";
+import { cardProblem, ContactCard } from "./schema/consent.js";
+import { MessagingError } from "./schema/errors.js";
+import { sign, signingInput, verifyInput } from "./sign.js";
+/** Signs a card with `identity`, a device of `args.from`. Throws `invalid_request` or `too_large`. */
+export function signContactCard(identity, args) {
+    const unsigned = {
+        v: PROTOCOL,
+        realm: args.realm,
+        from: args.from,
+        to: args.to,
+        by: identity.machine,
+        seq: args.seq,
+        ts: args.now,
+        ...(args.grantId !== undefined ? { grantId: args.grantId } : {}),
+        can: { chat: args.can.chat, agentMail: args.can.agentMail, ask: args.can.ask, ...(args.can.trustedUntil !== undefined ? { trustedUntil: args.can.trustedUntil } : {}) },
+    };
+    const problem = cardProblem(unsigned);
+    if (problem)
+        throw new MessagingError("invalid_request", problem);
+    const card = parseWith(ContactCard, { ...unsigned, sig: sign(identity, DOMAIN.card, unsigned) }, "card");
+    if (utf8(canonicalize(card)).length > LIMITS.cardBytes)
+        throw new MessagingError("too_large", `a card is at most ${LIMITS.cardBytes} bytes`);
+    return card;
+}
+/**
+ * Checks a card received from another person: the schema and its rules, the size, the realm, its two persons, and
+ * the signature by `by` over the raw value. Whether `by` is a current device of `from` is the caller's: a card
+ * whose signer was removed counts as absent. Throws only MessagingError: `invalid_request`, `too_large` or
+ * `bad_signature`.
+ */
+export function verifyContactCard(raw, ctx) {
+    try {
+        const card = parseWith(ContactCard, raw, "card");
+        if (utf8(canonicalize(raw)).length > LIMITS.cardBytes)
+            throw new MessagingError("too_large", `a card is at most ${LIMITS.cardBytes} bytes`);
+        const { sig, ...unsigned } = raw;
+        const input = signingInput(DOMAIN.card, unsigned);
+        if (card.realm !== ctx.realm)
+            throw new MessagingError("invalid_request", "the card is for another realm");
+        if (card.from !== ctx.from)
+            throw new MessagingError("invalid_request", "the card is not its sender's");
+        if (card.to !== ctx.to)
+            throw new MessagingError("invalid_request", "the card is for another person");
+        if (typeof sig !== "string" || !verifyInput(card.by, input, sig))
+            throw new MessagingError("bad_signature", "the card's signature is invalid");
+        return card;
+    }
+    catch (error) {
+        throw asMessagingError(error, "card");
+    }
+}
+/**
+ * What a card says for a sender of `relation` with the person grant `grant` (spec §6.9, "Contact cards"): the
+ * person grant over the relation's defaults. Channel grants are not on a card: the sender knows its own channels.
+ */
+export function cardCan(relation, grant, now) {
+    const policy = effectivePolicy(relation, grant, [], now);
+    return {
+        chat: policy.chat === "open" || policy.chat === "muted",
+        agentMail: policy.agentMail === "open",
+        ask: policy.ask,
+        ...(policy.trustedUntil !== undefined ? { trustedUntil: policy.trustedUntil } : {}),
+    };
+}

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

@@ -0,0 +1,174 @@
+import { utf8 } from "./b64u.js";
+import { parseAddress } from "./address.js";
+import { asMessagingError, parseWith } from "./check.js";
+import { sha256 } from "./hash.js";
+import { canonicalize } from "./jcs.js";
+import { DOMAIN, LIMITS } from "./schema/common.js";
+import { DelegationChain, DelegationGrant } from "./schema/delegation.js";
+import { MessagingError } from "./schema/errors.js";
+import { sign, signingInput, verifyInput } from "./sign.js";
+/** SHA-256 of the JCS form of the full grant, including `sig`: the next grant's `parent`. */
+export function grantHash(grant) {
+    return sha256(canonicalize(grant));
+}
+/**
+ * Signs one grant with the machine key (spec §6.7): a root, or the next hop after `parent`. The new grant
+ * may narrow the parent's scope and maxDepth, never widen them, and expires no later than the parent.
+ * It does not check the chain as a whole; run `verifyChain` on the extended chain for that.
+ * Throws only MessagingError: `invalid_request` for bad arguments, `forbidden` for a widening, `expired`
+ * for a parent that has expired.
+ */
+export function createGrant(identity, args) {
+    try {
+        return grant(identity, args);
+    }
+    catch (error) {
+        throw asMessagingError(error, "delegation grant");
+    }
+}
+function grant(identity, args) {
+    const now = args.now ?? Date.now();
+    const ttl = args.ttlMs ?? LIMITS.ttlMs;
+    if (!Number.isSafeInteger(now))
+        throw new MessagingError("invalid_request", "now must be an integer");
+    if (!Number.isSafeInteger(ttl) || ttl <= 0 || ttl > LIMITS.ttlMs)
+        throw new MessagingError("invalid_request", "ttlMs out of range");
+    const raw = args.parent;
+    const parent = raw === undefined ? undefined : parseWith(DelegationGrant, raw, "parent grant");
+    if (parent !== undefined) {
+        if (parent.to !== args.from)
+            throw new MessagingError("invalid_request", "a grant extends the grant to its delegating session");
+    }
+    const maxDepth = args.maxDepth ?? parent?.maxDepth ?? LIMITS.delegationDepth;
+    const scope = args.scope ?? parent?.scope;
+    if (parent !== undefined) {
+        if (maxDepth > parent.maxDepth)
+            throw new MessagingError("forbidden", "maxDepth would widen the parent grant");
+        if (!narrows(scope, parent.scope))
+            throw new MessagingError("forbidden", "scope would widen the parent grant");
+    }
+    const exp = parent === undefined ? now + ttl : Math.min(now + ttl, parent.exp);
+    if (exp <= now)
+        throw new MessagingError("expired", "the parent grant has expired");
+    const unsigned = {
+        realm: args.realm,
+        task: args.task,
+        from: args.from,
+        to: args.to,
+        by: identity.machine,
+        ts: now,
+        exp,
+        maxDepth,
+        ...(scope !== undefined ? { scope: [...scope] } : {}),
+        ...(raw !== undefined ? { parent: grantHash(raw) } : {}),
+    };
+    parseWith(DelegationGrant.omit({ sig: true }), unsigned, "delegation grant");
+    return { ...unsigned, sig: sign(identity, DOMAIN.delegation, unsigned) };
+}
+/**
+ * Verifies a delegation chain for the hop it arrived on (spec §6.7), against the locally verified realm.
+ * Checks, in order, stopping at the first failure:
+ *
+ * 1. schema, I-JSON and 1…`LIMITS.delegationDepth` grants (`invalid_request`); JCS within
+ *    `LIMITS.delegationBytes` (`too_large`);
+ * 2. for each grant, root first: this realm (`invalid_request`); the time window, as for envelopes
+ *    (`expired`); `by` a current member whose person and label `from` names (`not_member`); the
+ *    signature over the raw grant (`bad_signature`); linkage, no `parent` on the root and `from = previous.to`,
+ *    `parent = grantHash(previous)` after it (`invalid_request`); narrowing of scope, maxDepth and exp
+ *    (`forbidden`);
+ * 3. at most the smallest maxDepth grants (`forbidden`);
+ * 4. no session twice (`forbidden`);
+ * 5. the last grant is for this hop (`forbidden`).
+ *
+ * Throws only MessagingError, and never quotes the chain.
+ */
+export function verifyChain(raw, ctx) {
+    try {
+        return check(raw, ctx);
+    }
+    catch (error) {
+        throw asMessagingError(error, "delegation chain");
+    }
+}
+function check(raw, ctx) {
+    const { realm, now, hop } = ctx;
+    if (!Number.isSafeInteger(now))
+        throw new MessagingError("invalid_request", "now must be an integer");
+    parseWith(DelegationChain, raw, "delegation chain");
+    // The raw value, so unknown fields stay covered; canonicalizing it also requires I-JSON.
+    const grants = raw;
+    if (utf8(canonicalize(grants)).length > LIMITS.delegationBytes)
+        throw new MessagingError("too_large", `a delegation chain is limited to ${LIMITS.delegationBytes} bytes`);
+    let maxDepth = LIMITS.delegationDepth;
+    let previous;
+    for (const grant of grants) {
+        const { sig, ...unsigned } = grant;
+        const input = signingInput(DOMAIN.delegation, unsigned);
+        if (grant.realm !== realm.realm)
+            throw new MessagingError("invalid_request", "a grant is for another realm");
+        if (grant.ts > grant.exp)
+            throw new MessagingError("expired", "a grant's ts is after its exp");
+        if (grant.ts > now + LIMITS.clockSkewMs)
+            throw new MessagingError("expired", "a grant's timestamp is in the future");
+        if (grant.exp <= now)
+            throw new MessagingError("expired", "a grant has expired");
+        if (grant.exp - grant.ts > LIMITS.ttlMs)
+            throw new MessagingError("expired", "a grant's lifetime exceeds the maximum");
+        const signer = realm.device(grant.by);
+        if (!signer)
+            throw new MessagingError("not_member", "a grant's signer is not a current member");
+        const from = parseAddress(grant.from);
+        if (signer.person !== from.person || signer.label !== from.label) {
+            throw new MessagingError("not_member", "a grant's from does not name its signer");
+        }
+        if (!verifyInput(grant.by, input, sig))
+            throw new MessagingError("bad_signature", "a grant signature is invalid");
+        if (previous === undefined) {
+            if (grant.parent !== undefined)
+                throw new MessagingError("invalid_request", "a root grant has no parent");
+        }
+        else {
+            if (grant.from !== previous.to)
+                throw new MessagingError("invalid_request", "a grant does not extend the previous grant's recipient");
+            if (grant.parent !== grantHash(previous))
+                throw new MessagingError("invalid_request", "a grant's parent is not the previous grant");
+            if (!narrows(grant.scope, previous.scope))
+                throw new MessagingError("forbidden", "a grant widens the previous grant's scope");
+            if (grant.maxDepth > previous.maxDepth)
+                throw new MessagingError("forbidden", "a grant raises the previous grant's maxDepth");
+            if (grant.exp > previous.exp)
+                throw new MessagingError("forbidden", "a grant outlives the previous grant");
+        }
+        maxDepth = Math.min(maxDepth, grant.maxDepth);
+        previous = grant;
+    }
+    if (grants.length > maxDepth)
+        throw new MessagingError("forbidden", "the chain is deeper than its maxDepth allows");
+    const root = grants[0];
+    const last = grants[grants.length - 1];
+    const addresses = [root.from, ...grants.map((grant) => grant.to)];
+    if (new Set(addresses).size !== addresses.length)
+        throw new MessagingError("forbidden", "a session appears twice in the chain");
+    if (last.by !== hop.by || last.from !== hop.from || last.to !== hop.to || last.task !== hop.task) {
+        throw new MessagingError("forbidden", "the chain does not authorize this request");
+    }
+    return {
+        grants: structuredClone(grants),
+        summary: {
+            addresses,
+            depth: grants.length,
+            maxDepth,
+            ...(last.scope !== undefined ? { scope: [...last.scope] } : {}),
+            exp: Math.min(...grants.map((grant) => grant.exp)),
+        },
+    };
+}
+/** Whether `child` names nothing `parent` does not. An absent scope is unrestricted. */
+function narrows(child, parent) {
+    if (parent === undefined)
+        return true;
+    if (child === undefined)
+        return false;
+    const allowed = new Set(parent);
+    return child.every((label) => allowed.has(label));
+}