@feralfile/cli 2.10.1 → 4.0.0

package/dist/src/utilities/control/codec.js

@@ -0,0 +1,578 @@
+"use strict";
+/**
+ * FF1 control protocol v1 codec (ffos-user docs/ff1-control-v1.md), the
+ * controller side: seal requests (§3), open replies (§4) and sealed
+ * notifications (§9), and the approval code (§5.4).
+ *
+ * This is the TypeScript implementation that spec §12 requires to round-trip
+ * the Go reference's fixtures (tests/fixtures/ff1-control-v1). Cryptography is
+ * done by `jose` (panva); everything jose is lenient about is checked here
+ * first, because the spec is stricter than RFC 7515/7516:
+ *
+ * - Every protected header has a CLOSED member set. jose would accept a `zip`,
+ *   `jku` or extra member; this module rejects them before jose sees the token.
+ * - Duplicate members and non-canonical integers are rejected (strict-json.ts).
+ * - Only ES256 (raw 64-byte r||s), ECDH-ES (direct) and dir with A256GCM.
+ *
+ * Do not "simplify" a check here into a jose option: the closed-set rules are
+ * the protocol, and two implementations disagreeing on them is the bug class
+ * the spec exists to prevent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationOrder = exports.CONTROL_PLATFORMS = exports.DEFAULT_REQUEST_LIFETIME_SECONDS = exports.MAX_ENVELOPE_COMPACT_BYTES = exports.MAX_HEADER_BYTES = exports.MAX_COMPACT_BYTES = void 0;
+exports.parseProfile = parseProfile;
+exports.approvalCode = approvalCode;
+exports.controllerIdOf = controllerIdOf;
+exports.encodeRequestClaims = encodeRequestClaims;
+exports.buildRequestClaims = buildRequestClaims;
+exports.labelProblem = labelProblem;
+exports.stripUnsafeLabelCharacters = stripUnsafeLabelCharacters;
+exports.signRequest = signRequest;
+exports.encryptRequest = encryptRequest;
+exports.checkRequestHeader = checkRequestHeader;
+exports.sealRequest = sealRequest;
+exports.openReply = openReply;
+exports.openNotification = openNotification;
+exports.envelopeCastBody = envelopeCastBody;
+const node_crypto_1 = require("node:crypto");
+const jose_1 = require("jose");
+const strict_json_1 = require("./strict-json");
+const jwk_1 = require("./jwk");
+/** MAX_COMPACT_BYTES bounds a whole compact object before any decoding (§3.1). */
+exports.MAX_COMPACT_BYTES = 4 * 1024 * 1024;
+/** MAX_HEADER_BYTES bounds the base64url protected-header segment (§3.1). */
+exports.MAX_HEADER_BYTES = 4 * 1024;
+/**
+ * MAX_ENVELOPE_COMPACT_BYTES is what ff-cli lets a request grow to: the LAN
+ * hub caps the whole cast BODY at 4 MiB (§10), so the compact leaves room for
+ * the `{"command":"ff1Envelope","request":{"v":1,"jwe":…}}` wrapper.
+ */
+exports.MAX_ENVELOPE_COMPACT_BYTES = exports.MAX_COMPACT_BYTES - 1024;
+/** DEFAULT_REQUEST_LIFETIME_SECONDS is exp - iat; the spec allows [1, 120]. */
+exports.DEFAULT_REQUEST_LIFETIME_SECONDS = 60;
+const TYP_REQ_JWE = 'ff1-req+jwe';
+const TYP_REQ_JWS = 'ff1-req+jws';
+const TYP_RES_JWE = 'ff1-res+jwe';
+const TYP_RES_JWS = 'ff1-res+jws';
+const TYP_NTF_JWE = 'ff1-ntf+jwe';
+const GCM_IV_LEN = 12;
+const GCM_TAG_LEN = 16;
+const KEY_LEN = 32;
+const ES256_SIG_LEN = 64;
+const RID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const MAX_LABEL_CHARS = 64;
+/** CONTROL_PLATFORMS are the enroll.platform values of §5. */
+exports.CONTROL_PLATFORMS = ['ios', 'android', 'cli', 'other'];
+/**
+ * parseProfile validates a device profile `{v:1,dev,gen,sig,enc}` (§2) with
+ * a closed member set. The profile is the pin source, so it is never trusted
+ * partially.
+ *
+ * @param value - Parsed JSON value
+ * @returns The profile with canonical JWKs
+ * @throws {ControlFormatError} When malformed
+ */
+function parseProfile(value) {
+    const obj = (0, strict_json_1.strictObject)(value, ['v', 'dev', 'gen', 'sig', 'enc'], [], 'profile');
+    if (obj.v !== 1) {
+        throw new strict_json_1.ControlFormatError('profile v must be 1');
+    }
+    const dev = (0, strict_json_1.stringMember)(obj, 'dev');
+    const gen = (0, strict_json_1.stringMember)(obj, 'gen');
+    if (!dev) {
+        throw new strict_json_1.ControlFormatError('profile dev is empty');
+    }
+    if (!(0, strict_json_1.isB64uOfLength)(gen, 16)) {
+        throw new strict_json_1.ControlFormatError('profile gen must be b64u(16 bytes)');
+    }
+    return {
+        v: 1,
+        dev,
+        gen,
+        sig: (0, jwk_1.parsePublicJwk)(obj.sig, 'profile sig'),
+        enc: (0, jwk_1.parsePublicJwk)(obj.enc, 'profile enc'),
+    };
+}
+/**
+ * approvalCode is §5.4: the first 4 bytes of
+ * SHA-256("ff1-approval-code/v1|" + ctl + "|" + sigPin) as a big-endian
+ * uint32, mod 1,000,000, zero-padded to 6 digits. sigPin is thumb(devSig) as
+ * THIS controller pinned it, so a LAN man-in-the-middle serving a fake
+ * profile produces a code that differs from the one the real device shows
+ * the owner.
+ *
+ * @param ctl - controllerId (thumb(ctlSig))
+ * @param sigPin - thumb(devSig) of the pinned profile
+ * @returns Six decimal digits
+ */
+function approvalCode(ctl, sigPin) {
+    const digest = (0, node_crypto_1.createHash)('sha256')
+        .update(`ff1-approval-code/v1|${ctl}|${sigPin}`, 'utf8')
+        .digest();
+    return String(digest.readUInt32BE(0) % 1_000_000).padStart(6, '0');
+}
+/**
+ * controllerIdOf returns thumb(ctlSig), the controllerId (§2).
+ *
+ * @param keys - Controller keys
+ * @returns The controllerId
+ */
+function controllerIdOf(keys) {
+    return (0, jwk_1.thumbprint)(keys.sig);
+}
+/**
+ * encodeRequestClaims serializes claims in the reference member order. Order
+ * is not significant to the device, but a stable order makes the payload
+ * byte-comparable with the Go fixtures.
+ *
+ * @param c - Claims to encode
+ * @returns JSON text
+ */
+function encodeRequestClaims(c) {
+    const parts = [
+        `"v":1`,
+        `"dev":${JSON.stringify(c.dev)}`,
+        `"gen":${JSON.stringify(c.gen)}`,
+        `"ctl":${JSON.stringify(c.ctl)}`,
+        `"rid":${JSON.stringify(c.rid)}`,
+        `"ctr":${c.ctr}`,
+        `"iat":${c.iat}`,
+        `"exp":${c.exp}`,
+        `"op":${JSON.stringify(c.op)}`,
+        `"rk":${JSON.stringify(c.rk)}`,
+    ];
+    if (c.cmd !== undefined) {
+        parts.push(`"cmd":${JSON.stringify(c.cmd)}`, `"req":${JSON.stringify(c.req ?? {})}`);
+    }
+    if (c.enroll) {
+        const e = c.enroll;
+        const enroll = [
+            `"sig":${(0, jwk_1.canonicalJwkJson)(e.sig)}`,
+            `"enc":${(0, jwk_1.canonicalJwkJson)(e.enc)}`,
+            `"label":${JSON.stringify(e.label)}`,
+            `"platform":${JSON.stringify(e.platform)}`,
+        ];
+        if (e.inv !== undefined) {
+            enroll.push(`"inv":${JSON.stringify(e.inv)}`);
+        }
+        parts.push(`"enroll":{${enroll.join(',')}}`);
+    }
+    return `{${parts.join(',')}}`;
+}
+/**
+ * buildRequestClaims assembles and validates §3.3 claims. It refuses to build
+ * a request the device would answer `invalid_request`, so such a bug surfaces
+ * locally instead of burning a counter on the device.
+ *
+ * @param input - Request input
+ * @param rk - Reply key bytes
+ * @returns The claims
+ * @throws {Error} When the input breaks a §3.3 rule
+ */
+function buildRequestClaims(input, rk) {
+    const now = input.now ?? Math.floor(Date.now() / 1000);
+    const lifetime = input.lifetimeSeconds ?? exports.DEFAULT_REQUEST_LIFETIME_SECONDS;
+    const rid = input.rid ?? (0, strict_json_1.b64uEncode)((0, node_crypto_1.randomBytes)(16));
+    if (!Number.isSafeInteger(input.ctr) || input.ctr < 1) {
+        throw new Error('ctr must be a positive integer');
+    }
+    if (!RID_PATTERN.test(rid) || rk.length !== KEY_LEN) {
+        throw new Error('rid or rk is malformed');
+    }
+    if (!Number.isInteger(lifetime) || lifetime < 1 || lifetime > 120) {
+        throw new Error('request lifetime must be 1-120 seconds');
+    }
+    const claims = {
+        v: 1,
+        dev: input.profile.dev,
+        gen: input.profile.gen,
+        ctl: controllerIdOf(input.keys),
+        rid,
+        ctr: input.ctr,
+        iat: now,
+        exp: now + lifetime,
+        op: input.op,
+        rk: (0, strict_json_1.b64uEncode)(rk),
+    };
+    if (input.op === 'cmd') {
+        assertCommand(input.cmd, input.req, input.enroll);
+        claims.cmd = input.cmd;
+        claims.req = input.req ?? {};
+    }
+    else {
+        assertEnroll(input.op, input.enroll, input.cmd, claims.ctl);
+        claims.enroll = input.enroll;
+    }
+    return claims;
+}
+/**
+ * UNSAFE_LABEL_CHARACTERS are characters a controller label must not contain:
+ * C0/C1 controls, every Unicode format character (Cf: zero-width spaces and
+ * joiners, bidi marks and isolates, the BOM, soft hyphen, …) and the line and
+ * paragraph separators. The device rejects the C0/C1 controls and its own
+ * invisible/bidi set (ffos-user devicename.HasUnsafeCharacters) with
+ * `invalid_request`; this set is a superset of that, so ff-cli never sends a
+ * label the device would refuse, and the owner's approval sheet cannot be
+ * spoofed with invisible or reordering characters.
+ */
+const UNSAFE_LABEL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f\p{Cf}\u2028\u2029]/u;
+/**
+ * labelProblem explains why a controller label is not acceptable (§5), or
+ * returns undefined when it is.
+ *
+ * @param label - Candidate label
+ * @returns A reason, or undefined
+ */
+function labelProblem(label) {
+    const length = [...label].length;
+    if (length < 1 || length > MAX_LABEL_CHARS) {
+        return 'must be 1-64 characters';
+    }
+    if (UNSAFE_LABEL_CHARACTERS.test(label)) {
+        return 'must not contain control characters or invisible formatting (bidi, zero-width) characters';
+    }
+    return undefined;
+}
+/**
+ * stripUnsafeLabelCharacters removes what labelProblem rejects, for deriving
+ * a default label from the hostname.
+ *
+ * @param value - Raw text
+ * @returns Text without unsafe characters
+ */
+function stripUnsafeLabelCharacters(value) {
+    return value.replace(new RegExp(UNSAFE_LABEL_CHARACTERS.source, 'gu'), '');
+}
+function assertCommand(cmd, req, enroll) {
+    if (typeof cmd !== 'string' || cmd.length === 0 || Buffer.byteLength(cmd) > 64) {
+        throw new Error('cmd must be a 1-64 byte command name');
+    }
+    if (req !== undefined && !(0, strict_json_1.isPlainObject)(req)) {
+        throw new Error('req must be a JSON object');
+    }
+    if (enroll !== undefined) {
+        throw new Error('op=cmd forbids enroll');
+    }
+}
+function assertEnroll(op, enroll, cmd, ctl) {
+    if (op !== 'enroll') {
+        throw new Error(`unknown op ${String(op)}`);
+    }
+    if (!enroll || cmd !== undefined) {
+        throw new Error(`op=${op} requires enroll and forbids cmd/req`);
+    }
+    if ((0, jwk_1.thumbprint)(enroll.sig) !== ctl) {
+        throw new Error('enroll.sig must be the signing key');
+    }
+    const problem = labelProblem(enroll.label);
+    if (problem) {
+        throw new Error(`enroll label ${problem}`);
+    }
+    if (!exports.CONTROL_PLATFORMS.includes(enroll.platform)) {
+        throw new Error('enroll platform is invalid');
+    }
+}
+/**
+ * signRequest produces the §3.2 inner JWS: header exactly
+ * `{"alg":"ES256","kid":ctl,"typ":"ff1-req+jws"}`, raw r||s signature.
+ *
+ * @param ctlSig - Controller signing key
+ * @param payload - Encoded claims
+ * @returns Compact JWS
+ */
+async function signRequest(ctlSig, payload) {
+    const key = await (0, jose_1.importJWK)({ ...ctlSig }, 'ES256');
+    return new jose_1.CompactSign(new TextEncoder().encode(payload))
+        .setProtectedHeader({ alg: 'ES256', kid: (0, jwk_1.thumbprint)(ctlSig), typ: TYP_REQ_JWS })
+        .sign(key);
+}
+/**
+ * encryptRequest wraps a JWS in the §3.1 request JWE (ECDH-ES direct, A256GCM)
+ * for the pinned devEnc.
+ *
+ * jose appends `epk` to the protected header itself. jose writes its members
+ * in the order x, crv, kty, y rather than the thumbprint order the spec
+ * RECOMMENDS (SHOULD); the device accepts any order (MUST), so the header is
+ * re-parsed and checked for the exact member set and a valid epk instead of
+ * hand-rolling the key agreement. That check is what guards against a jose
+ * upgrade adding a member (apu/apv/zip) the device would reject.
+ *
+ * @param devEnc - Pinned device encryption key
+ * @param jws - Inner compact JWS
+ * @param fixed - Test seam for a fixed ephemeral key and IV
+ * @returns Compact JWE
+ */
+async function encryptRequest(devEnc, jws, fixed = {}) {
+    const recipient = await (0, jose_1.importJWK)({ ...(0, jwk_1.publicOf)(devEnc) }, 'ECDH-ES');
+    const builder = new jose_1.CompactEncrypt(new TextEncoder().encode(jws)).setProtectedHeader({
+        alg: 'ECDH-ES',
+        enc: 'A256GCM',
+        kid: (0, jwk_1.thumbprint)(devEnc),
+        typ: TYP_REQ_JWE,
+        cty: TYP_REQ_JWS,
+    });
+    if (fixed.ephemeralKey) {
+        const epk = await (0, jose_1.importJWK)({ ...fixed.ephemeralKey, ext: true }, 'ECDH-ES', {
+            extractable: true,
+        });
+        builder.setKeyManagementParameters({ epk: epk });
+    }
+    if (fixed.iv) {
+        builder.setInitializationVector(fixed.iv);
+    }
+    const compact = await builder.encrypt(recipient);
+    checkRequestHeader(compact.split('.')[0], (0, jwk_1.thumbprint)(devEnc));
+    return compact;
+}
+/**
+ * checkRequestHeader asserts a request JWE header is exactly the §3.1 shape.
+ *
+ * @param segment - Base64url protected header
+ * @param devEncKid - Expected kid
+ * @returns The ephemeral public key
+ * @throws {ControlFormatError} When the header deviates
+ */
+function checkRequestHeader(segment, devEncKid) {
+    const header = parseHeader(segment, {
+        alg: 'ECDH-ES',
+        enc: 'A256GCM',
+        kid: devEncKid,
+        typ: TYP_REQ_JWE,
+        cty: TYP_REQ_JWS,
+        epk: null,
+    });
+    return (0, jwk_1.parsePublicJwk)(header.epk, 'epk');
+}
+/**
+ * sealRequest builds a complete request: claims, inner JWS, outer JWE.
+ * A fresh rk, rid, epk and IV are drawn for every call, which is what makes
+ * "never resend the same request" structural: callers retry by sealing again.
+ *
+ * @param input - Request input
+ * @returns The sealed request and its reply key
+ * @throws {Error} When claims are invalid or the result exceeds 4 MiB
+ */
+async function sealRequest(input) {
+    const rk = input.rk ?? new Uint8Array((0, node_crypto_1.randomBytes)(KEY_LEN));
+    const claims = buildRequestClaims(input, rk);
+    const jws = await signRequest(input.keys.sig, encodeRequestClaims(claims));
+    const compact = await encryptRequest(input.profile.enc, jws, {
+        ephemeralKey: input.ephemeralKey,
+        iv: input.iv,
+    });
+    if (compact.length > exports.MAX_ENVELOPE_COMPACT_BYTES) {
+        throw new Error(`the encrypted request is ${compact.length} bytes, over the FF1 limit of ${exports.MAX_ENVELOPE_COMPACT_BYTES}; host large playlists by URL instead`);
+    }
+    return { compact, jws, claims, rk };
+}
+/**
+ * parseHeader decodes a protected header and checks its exact member set and
+ * the exact string value of each member whose expected value is a string. A
+ * null expectation means "present; the caller checks it".
+ */
+function parseHeader(segment, expected) {
+    if (!segment || segment.length > exports.MAX_HEADER_BYTES) {
+        throw new strict_json_1.ControlFormatError('protected header size');
+    }
+    const header = (0, strict_json_1.strictObject)((0, strict_json_1.parseStrictJson)((0, strict_json_1.b64uDecode)(segment)), Object.keys(expected), [], 'protected header');
+    for (const [key, want] of Object.entries(expected)) {
+        if (want !== null && header[key] !== want) {
+            throw new strict_json_1.ControlFormatError(`protected header ${key} is not ${JSON.stringify(want)}`);
+        }
+    }
+    return header;
+}
+/**
+ * splitJwe checks the five-part compact form shared by both dir profiles:
+ * size, empty encrypted key, 12-byte IV, 16-byte tag, exact header.
+ */
+function splitJwe(compact, expected) {
+    if (typeof compact !== 'string' || compact.length > exports.MAX_COMPACT_BYTES) {
+        throw new strict_json_1.ControlFormatError('compact JWE size');
+    }
+    const parts = compact.split('.');
+    if (parts.length !== 5 || parts[1] !== '') {
+        throw new strict_json_1.ControlFormatError('compact JWE shape');
+    }
+    parseHeader(parts[0], expected);
+    if ((0, strict_json_1.b64uDecode)(parts[2]).length !== GCM_IV_LEN || (0, strict_json_1.b64uDecode)(parts[4]).length !== GCM_TAG_LEN) {
+        throw new strict_json_1.ControlFormatError('JWE IV or tag length');
+    }
+    (0, strict_json_1.b64uDecode)(parts[3]);
+}
+/** decryptDir opens a dir/A256GCM JWE whose shape splitJwe already checked. */
+async function decryptDir(compact, key) {
+    if (key.length !== KEY_LEN) {
+        throw new strict_json_1.ControlFormatError('content key length');
+    }
+    try {
+        const { plaintext } = await (0, jose_1.compactDecrypt)(compact, key, {
+            keyManagementAlgorithms: ['dir'],
+            contentEncryptionAlgorithms: ['A256GCM'],
+        });
+        return plaintext;
+    }
+    catch {
+        throw new strict_json_1.ControlFormatError('JWE authentication failed');
+    }
+}
+/**
+ * verifyReplyJws checks the §4.1 inner JWS against the PINNED devSig and
+ * returns its payload bytes.
+ */
+async function verifyReplyJws(jws, devSig) {
+    const parts = jws.split('.');
+    if (parts.length !== 3) {
+        throw new strict_json_1.ControlFormatError('compact JWS shape');
+    }
+    const header = parseHeader(parts[0], { alg: 'ES256', kid: null, typ: TYP_RES_JWS });
+    if (!(0, jwk_1.isThumbprint)(header.kid) || header.kid !== (0, jwk_1.thumbprint)(devSig)) {
+        throw new strict_json_1.ControlFormatError('reply kid is not the pinned devSig');
+    }
+    // A DER, truncated or padded signature is never r||s (§3.2).
+    if ((0, strict_json_1.b64uDecode)(parts[2]).length !== ES256_SIG_LEN) {
+        throw new strict_json_1.ControlFormatError('reply signature length');
+    }
+    // Decode the payload segment strictly ourselves (§1: no padding, no
+    // non-zero trailing bits): jose's decoder is lenient, and two segments
+    // that decode to the same claims must not both be accepted.
+    const strictPayload = (0, strict_json_1.b64uDecode)(parts[1]);
+    let payload;
+    try {
+        const key = await (0, jose_1.importJWK)({ ...(0, jwk_1.publicOf)(devSig) }, 'ES256');
+        ({ payload } = await (0, jose_1.compactVerify)(jws, key, { algorithms: ['ES256'] }));
+    }
+    catch {
+        throw new strict_json_1.ControlFormatError('reply signature');
+    }
+    if (Buffer.compare(Buffer.from(payload), Buffer.from(strictPayload)) !== 0) {
+        throw new strict_json_1.ControlFormatError('reply payload decoding mismatch');
+    }
+    return strictPayload;
+}
+/**
+ * parseReplyClaims applies the §4.1 closed member set; `code` is present
+ * exactly when `ok` is false.
+ */
+function parseReplyClaims(payload) {
+    const obj = (0, strict_json_1.strictObject)((0, strict_json_1.parseStrictJson)(payload), ['v', 'dev', 'gen', 'ctl', 'rid', 'iat', 'ok'], ['code', 'res'], 'reply claims');
+    if ((0, strict_json_1.uintMember)(obj, 'v') !== 1) {
+        throw new strict_json_1.ControlFormatError('reply v');
+    }
+    const ok = (0, strict_json_1.boolMember)(obj, 'ok');
+    const hasCode = Object.prototype.hasOwnProperty.call(obj, 'code');
+    if (hasCode === ok) {
+        throw new strict_json_1.ControlFormatError('reply code must be present exactly when ok is false');
+    }
+    const claims = {
+        v: 1,
+        dev: (0, strict_json_1.stringMember)(obj, 'dev'),
+        gen: (0, strict_json_1.stringMember)(obj, 'gen'),
+        ctl: (0, strict_json_1.stringMember)(obj, 'ctl'),
+        rid: (0, strict_json_1.stringMember)(obj, 'rid'),
+        iat: (0, strict_json_1.uintMember)(obj, 'iat'),
+        ok,
+    };
+    if (hasCode) {
+        claims.code = (0, strict_json_1.stringMember)(obj, 'code');
+    }
+    if (Object.prototype.hasOwnProperty.call(obj, 'res')) {
+        claims.res = (0, strict_json_1.toPlainJson)(obj.res);
+    }
+    return claims;
+}
+/**
+ * openReply is §4.1-4.2 in full: exact headers, decryption with the request's
+ * rk, ES256 against the pinned devSig, strict claims, and the dev/gen/ctl/rid
+ * binding. Any failure means "no valid reply"; a reply is never trusted
+ * partially, so the caller gets either verified claims or an exception.
+ *
+ * @param compact - Reply compact JWE
+ * @param rk - Reply key from the request
+ * @param devSig - Pinned device signing key
+ * @param bind - The request's dev/gen/ctl/rid
+ * @returns Verified claims
+ * @throws {ControlFormatError} On any failure
+ */
+async function openReply(compact, rk, devSig, bind) {
+    splitJwe(compact, { alg: 'dir', enc: 'A256GCM', typ: TYP_RES_JWE, cty: TYP_RES_JWS });
+    const jws = new TextDecoder().decode(await decryptDir(compact, rk));
+    const claims = parseReplyClaims(await verifyReplyJws(jws, devSig));
+    if (claims.dev !== bind.dev ||
+        claims.gen !== bind.gen ||
+        claims.ctl !== bind.ctl ||
+        claims.rid !== bind.rid) {
+        throw new strict_json_1.ControlFormatError('reply is not bound to this request');
+    }
+    return claims;
+}
+/**
+ * openNotification is the controller side of §9: exact header with
+ * kid = our controllerId, decryption under nk, the closed claim set, ctl equal
+ * to kid, and dev/gen equal to the pins. Notifications are NOT signed; the
+ * caller must only use them to inform UI and never act on one automatically.
+ *
+ * @param compact - Notification compact JWE
+ * @param ctl - This controller's controllerId
+ * @param nk - This controller's notification key
+ * @param pins - The pinned dev/gen; omit only in conformance tests
+ * @returns Claims
+ * @throws {ControlFormatError} On any failure
+ */
+async function openNotification(compact, ctl, nk, pins) {
+    splitJwe(compact, { alg: 'dir', enc: 'A256GCM', typ: TYP_NTF_JWE, kid: ctl });
+    const obj = (0, strict_json_1.strictObject)((0, strict_json_1.parseStrictJson)(await decryptDir(compact, nk)), ['v', 'dev', 'gen', 'ctl', 'ep', 'seq', 'iat', 'type', 'body'], [], 'notification claims');
+    if ((0, strict_json_1.uintMember)(obj, 'v') !== 1) {
+        throw new strict_json_1.ControlFormatError('notification v');
+    }
+    const claims = {
+        v: 1,
+        dev: (0, strict_json_1.stringMember)(obj, 'dev'),
+        gen: (0, strict_json_1.stringMember)(obj, 'gen'),
+        ctl: (0, strict_json_1.stringMember)(obj, 'ctl'),
+        ep: (0, strict_json_1.stringMember)(obj, 'ep'),
+        seq: (0, strict_json_1.uintMember)(obj, 'seq'),
+        iat: (0, strict_json_1.uintMember)(obj, 'iat'),
+        type: (0, strict_json_1.stringMember)(obj, 'type'),
+        body: (0, strict_json_1.toPlainJson)(obj.body),
+    };
+    if (claims.ctl !== ctl) {
+        throw new strict_json_1.ControlFormatError('notification ctl does not match kid');
+    }
+    // §9: ep is b64u(8 random bytes), strict (no padding), as in the Go reference.
+    if (!(0, strict_json_1.isB64uOfLength)(claims.ep, 8)) {
+        throw new strict_json_1.ControlFormatError('notification ep must be b64u(8 bytes)');
+    }
+    if (pins && (claims.dev !== pins.dev || claims.gen !== pins.gen)) {
+        throw new strict_json_1.ControlFormatError('notification is for another device or generation');
+    }
+    return claims;
+}
+/**
+ * NotificationOrder implements the §9 ordering rule: within one `ep` keep
+ * only increasing `seq`; an `ep` never seen before starts a new daemon run and
+ * is accepted. `iat` is not used for ordering because device clocks can step.
+ */
+class NotificationOrder {
+    highest = new Map();
+    /**
+     * accept reports whether a notification is newer than everything seen in its
+     * run, and records it when it is.
+     *
+     * @param n - Opened notification claims
+     * @returns True when the notification should be shown
+     */
+    accept(n) {
+        const seen = this.highest.get(n.ep);
+        if (seen !== undefined && n.seq <= seen) {
+            return false;
+        }
+        this.highest.set(n.ep, n.seq);
+        return true;
+    }
+}
+exports.NotificationOrder = NotificationOrder;
+/** envelopeCastBody is the §10 LAN and legacy-relayer request body. */
+function envelopeCastBody(compact) {
+    return { command: 'ff1Envelope', request: { v: 1, jwe: compact } };
+}