@feralfile/cli 3.0.0 → 4.0.0

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

@@ -0,0 +1,391 @@
+"use strict";
+/**
+ * Owner-initiated registration (ffos-user docs/ff1-control-v1.md §5.6), the
+ * controller side: the `ff1-ctl:1|…` controller QR ff-cli shows, and the
+ * sealed registration result an owner's app sends back over the pairing
+ * channel.
+ *
+ * The result is the pin source for the device profile (§14.1), so it is
+ * checked exactly like the Go reference (control/registration.go
+ * OpenRegistration) and nothing in it is trusted before every check passed:
+ * closed member sets, the channel and pairing secret from our own QR, `ctl`
+ * equal to our own key, and the configured device. A message that fails any
+ * check is not an answer; the caller keeps waiting for a genuine one.
+ *
+ * Cryptography is node:crypto (P-256 ECDH, HKDF-SHA256, AES-256-GCM). The
+ * fixtures in tests/fixtures/ff1-control-v1 pin every byte of it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegistrationForOtherDeviceError = exports.REGISTRATION_SEALED_TYPE = exports.REGISTRATION_TYPE = exports.CONTROLLER_QR_PREFIX = void 0;
+exports.isValidChannelId = isValidChannelId;
+exports.generatePairingMaterial = generatePairingMaterial;
+exports.controllerQrString = controllerQrString;
+exports.controllerQrCtl = controllerQrCtl;
+exports.parseControllerQr = parseControllerQr;
+exports.sealRegistration = sealRegistration;
+exports.openRegistration = openRegistration;
+const node_crypto_1 = require("node:crypto");
+const codec_1 = require("./codec");
+const jwk_1 = require("./jwk");
+const strict_json_1 = require("./strict-json");
+/** CONTROLLER_QR_PREFIX starts every controller QR payload (§5.6.1). */
+exports.CONTROLLER_QR_PREFIX = 'ff1-ctl:1|';
+/** REGISTRATION_TYPE is the plaintext result's type. */
+exports.REGISTRATION_TYPE = 'ff1_controller_registration';
+/** REGISTRATION_SEALED_TYPE is the wire message's type. */
+exports.REGISTRATION_SEALED_TYPE = 'ff1_controller_registration_sealed';
+const REGISTRATION_LABEL = 'ff1-controller-registration/v1';
+const PS_LEN = 16;
+const GCM_IV_LEN = 12;
+const GCM_TAG_LEN = 16;
+const SEC1_POINT_LEN = 65;
+const COORD_LEN = 32;
+// The label is the last of the nine fields after the prefix and may itself
+// contain "|", so the payload is split at most nine times.
+const CONTROLLER_QR_FIELDS = 9;
+const CHANNEL_ID_PATTERN = /^[A-Za-z0-9_-]{16,64}$/;
+const MAX_LABEL_CHARS = 64;
+/**
+ * PROTOCOL_UNSAFE_LABEL is exactly the device's label rule (Go
+ * control/store.go unsafeLabelCharacters). It judges labels and device names
+ * this module READS, so a genuine result is never refused over a character
+ * the device accepts; labels ff-cli sends use the stricter codec.labelProblem.
+ */
+const PROTOCOL_UNSAFE_LABEL = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u202a-\u202e\u2060\u2066-\u2069\u2028\u2029\ufeff]/u;
+/**
+ * RegistrationForOtherDeviceError is a result that passed the channel,
+ * pairing-secret and ctl checks (so it came from someone holding this QR,
+ * normally the owner) but names another FF1 than the configured one.
+ */
+class RegistrationForOtherDeviceError extends strict_json_1.ControlFormatError {
+    dev;
+    constructor(dev) {
+        super('registration result is for another device');
+        this.dev = dev;
+        this.name = 'RegistrationForOtherDeviceError';
+    }
+}
+exports.RegistrationForOtherDeviceError = RegistrationForOtherDeviceError;
+/**
+ * isValidChannelId reports whether a pairing channel ID is valid for the
+ * controller QR (§5.6.1: 16-64 characters of [A-Za-z0-9_-]). The relay
+ * accepts 1-128, so clients check this themselves.
+ *
+ * @param channelId - Candidate channel ID
+ * @returns True when the QR may carry it
+ */
+function isValidChannelId(channelId) {
+    return CHANNEL_ID_PATTERN.test(channelId);
+}
+/**
+ * isProtocolLabel is the §5 label rule as the device applies it: 1-64
+ * characters, none of the control or invisible formatting characters.
+ *
+ * @param value - Candidate label or device name
+ * @returns True when the device would accept it
+ */
+function isProtocolLabel(value) {
+    const length = [...value].length;
+    return length >= 1 && length <= MAX_LABEL_CHARS && !PROTOCOL_UNSAFE_LABEL.test(value);
+}
+/** sec1Of renders a public JWK as b64u(0x04 || X || Y). */
+function sec1Of(key) {
+    return (0, strict_json_1.b64uEncode)(Buffer.concat([
+        Buffer.from([4]),
+        Buffer.from((0, strict_json_1.b64uDecode)(key.x)),
+        Buffer.from((0, strict_json_1.b64uDecode)(key.y)),
+    ]));
+}
+/**
+ * parseSec1Point validates b64u of an uncompressed P-256 point; compressed
+ * and off-curve points are refused (parsePublicJwk runs the on-curve check).
+ */
+function parseSec1Point(value, what) {
+    let bytes;
+    try {
+        bytes = (0, strict_json_1.b64uDecode)(value);
+    }
+    catch {
+        bytes = new Uint8Array();
+    }
+    if (bytes.length !== SEC1_POINT_LEN || bytes[0] !== 4) {
+        throw new strict_json_1.ControlFormatError(`${what} must be b64u of a 65-byte uncompressed P-256 point`);
+    }
+    return (0, jwk_1.parsePublicJwk)({
+        kty: 'EC',
+        crv: 'P-256',
+        x: (0, strict_json_1.b64uEncode)(bytes.subarray(1, 1 + COORD_LEN)),
+        y: (0, strict_json_1.b64uEncode)(bytes.subarray(1 + COORD_LEN)),
+    }, what);
+}
+/**
+ * generatePairingMaterial draws what one pairing attempt shows: a fresh
+ * minter key, a 16-byte pairing secret and a random channel ID, bound to the
+ * controller keys and label the owner will register.
+ *
+ * @param keys - Controller keys to register
+ * @param label - Label the owner sees (already validated)
+ * @param channelId - Pairing channel ID (default: a fresh random UUID)
+ * @returns The QR fields and the minter private key
+ */
+function generatePairingMaterial(keys, label, channelId = (0, node_crypto_1.randomUUID)()) {
+    const minter = (0, jwk_1.generatePrivateJwk)();
+    return {
+        minter,
+        qr: {
+            channelId,
+            minterKey: sec1Of(minter),
+            sig: (0, jwk_1.publicOf)(keys.sig),
+            enc: (0, jwk_1.publicOf)(keys.enc),
+            ps: (0, strict_json_1.b64uEncode)((0, node_crypto_1.randomBytes)(PS_LEN)),
+            platform: 'cli',
+            label,
+        },
+    };
+}
+/**
+ * controllerQrString renders the QR payload.
+ *
+ * @param qr - QR fields
+ * @returns `ff1-ctl:1|channelId|minterKey|sig.x|sig.y|enc.x|enc.y|ps|platform|label`
+ */
+function controllerQrString(qr) {
+    return (exports.CONTROLLER_QR_PREFIX +
+        [
+            qr.channelId,
+            qr.minterKey,
+            qr.sig.x,
+            qr.sig.y,
+            qr.enc.x,
+            qr.enc.y,
+            qr.ps,
+            qr.platform,
+            qr.label,
+        ].join('|'));
+}
+/**
+ * controllerQrCtl is the controller ID the QR's sig key has once registered.
+ *
+ * @param qr - QR fields
+ * @returns thumb(sig)
+ */
+function controllerQrCtl(qr) {
+    return (0, jwk_1.thumbprint)(qr.sig);
+}
+/**
+ * parseControllerQr parses and validates a controller QR payload (§5.6.1).
+ *
+ * @param value - QR text
+ * @returns The QR fields
+ * @throws {ControlFormatError} On anything but a valid payload
+ */
+function parseControllerQr(value) {
+    if (!value.startsWith(exports.CONTROLLER_QR_PREFIX)) {
+        throw new strict_json_1.ControlFormatError('not an ff1-ctl:1 payload');
+    }
+    const fields = [];
+    let rest = value.slice(exports.CONTROLLER_QR_PREFIX.length);
+    while (fields.length < CONTROLLER_QR_FIELDS - 1) {
+        const cut = rest.indexOf('|');
+        if (cut < 0) {
+            throw new strict_json_1.ControlFormatError('controller QR has too few fields');
+        }
+        fields.push(rest.slice(0, cut));
+        rest = rest.slice(cut + 1);
+    }
+    fields.push(rest);
+    const [channelId, minterKey, sigX, sigY, encX, encY, ps, platform, label] = fields;
+    if (!CHANNEL_ID_PATTERN.test(channelId)) {
+        throw new strict_json_1.ControlFormatError('controller QR channelId is invalid');
+    }
+    parseSec1Point(minterKey, 'controller QR minterKey');
+    const sig = (0, jwk_1.parsePublicJwk)({ kty: 'EC', crv: 'P-256', x: sigX, y: sigY }, 'controller QR sig');
+    const enc = (0, jwk_1.parsePublicJwk)({ kty: 'EC', crv: 'P-256', x: encX, y: encY }, 'controller QR enc');
+    let psBytes;
+    try {
+        psBytes = (0, strict_json_1.b64uDecode)(ps);
+    }
+    catch {
+        psBytes = new Uint8Array();
+    }
+    if (psBytes.length !== PS_LEN) {
+        throw new strict_json_1.ControlFormatError('controller QR ps must be b64u of 16 bytes');
+    }
+    if (!codec_1.CONTROL_PLATFORMS.includes(platform)) {
+        throw new strict_json_1.ControlFormatError('controller QR platform is invalid');
+    }
+    if (!isProtocolLabel(label)) {
+        throw new strict_json_1.ControlFormatError('controller QR label is invalid');
+    }
+    return {
+        channelId,
+        minterKey,
+        sig,
+        enc,
+        ps,
+        platform: platform,
+        label,
+    };
+}
+/** registrationKey derives the AES-256-GCM key and AAD of §5.6.2. */
+function registrationKey(own, peer, channelId, minterKey, epk) {
+    const z = (0, node_crypto_1.diffieHellman)({
+        privateKey: (0, node_crypto_1.createPrivateKey)({ key: { ...own }, format: 'jwk' }),
+        publicKey: (0, node_crypto_1.createPublicKey)({ key: { ...(0, jwk_1.publicOf)(peer) }, format: 'jwk' }),
+    });
+    const salt = (0, node_crypto_1.createHash)('sha256')
+        .update(exports.CONTROLLER_QR_PREFIX + channelId, 'utf8')
+        .digest();
+    const key = Buffer.from((0, node_crypto_1.hkdfSync)('sha256', z, salt, REGISTRATION_LABEL, 32));
+    const aad = Buffer.from(`${REGISTRATION_LABEL}|${channelId}|${minterKey}|${epk}`, 'utf8');
+    return { key, aad };
+}
+/**
+ * sealRegistration is the owner side of §5.6.2, used by tests and as the
+ * reference for the app: encrypt an exact plaintext to the QR's minter key
+ * under the ephemeral key with iv (12 bytes, never reused for one epk).
+ *
+ * @param qr - The controller QR
+ * @param plaintext - Exact result JSON
+ * @param ephemeral - Owner's fresh P-256 key
+ * @param iv - 12-byte nonce
+ * @returns The wire message JSON
+ */
+function sealRegistration(qr, plaintext, ephemeral = (0, jwk_1.generatePrivateJwk)(), iv = (0, node_crypto_1.randomBytes)(GCM_IV_LEN)) {
+    if (iv.length !== GCM_IV_LEN) {
+        throw new Error('registration iv must be 12 bytes');
+    }
+    const minter = parseSec1Point(qr.minterKey, 'minterKey');
+    const epk = sec1Of(ephemeral);
+    const { key, aad } = registrationKey(ephemeral, minter, qr.channelId, qr.minterKey, epk);
+    const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', key, iv);
+    cipher.setAAD(aad);
+    const ct = Buffer.concat([
+        cipher.update(typeof plaintext === 'string' ? Buffer.from(plaintext, 'utf8') : plaintext),
+        cipher.final(),
+        cipher.getAuthTag(),
+    ]);
+    return `{"v":1,"type":${JSON.stringify(exports.REGISTRATION_SEALED_TYPE)},"epk":${JSON.stringify(epk)},"iv":${JSON.stringify((0, strict_json_1.b64uEncode)(iv))},"ct":${JSON.stringify((0, strict_json_1.b64uEncode)(ct))}}`;
+}
+/**
+ * openRegistration is the controller side of §5.6.3: decrypt a sealed result
+ * with the minter key behind qr and check every binding, in the spec's order.
+ *
+ * @param material - The QR this controller showed and its minter key
+ * @param wire - The wire message (relay frame payload)
+ * @param wantDev - The configured device ID; profile.dev must equal it
+ * @param now - Unix seconds, bounding expiresAt
+ * @returns The verified result
+ * @throws {ControlFormatError} When the message is not a genuine result for this QR
+ */
+function openRegistration(material, wire, wantDev, now) {
+    const { qr, minter } = material;
+    if (sec1Of(minter) !== qr.minterKey) {
+        throw new strict_json_1.ControlFormatError('minter key does not match the QR');
+    }
+    const sealed = (0, strict_json_1.strictObject)((0, strict_json_1.parseStrictJson)(wire), ['v', 'type', 'epk', 'iv', 'ct'], [], 'sealed registration');
+    if ((0, strict_json_1.uintMember)(sealed, 'v') !== 1 || sealed.type !== exports.REGISTRATION_SEALED_TYPE) {
+        throw new strict_json_1.ControlFormatError('sealed registration has the wrong v or type');
+    }
+    const epkB64 = (0, strict_json_1.stringMember)(sealed, 'epk');
+    const epk = parseSec1Point(epkB64, 'sealed registration epk');
+    const iv = (0, strict_json_1.b64uDecode)((0, strict_json_1.stringMember)(sealed, 'iv'));
+    if (iv.length !== GCM_IV_LEN) {
+        throw new strict_json_1.ControlFormatError('sealed registration iv must be 12 bytes');
+    }
+    const ct = (0, strict_json_1.b64uDecode)((0, strict_json_1.stringMember)(sealed, 'ct'));
+    if (ct.length < GCM_TAG_LEN) {
+        throw new strict_json_1.ControlFormatError('sealed registration does not decrypt');
+    }
+    const { key, aad } = registrationKey(minter, epk, qr.channelId, qr.minterKey, epkB64);
+    let plaintext;
+    try {
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', key, iv);
+        decipher.setAAD(aad);
+        decipher.setAuthTag(ct.subarray(ct.length - GCM_TAG_LEN));
+        plaintext = Buffer.concat([
+            decipher.update(ct.subarray(0, ct.length - GCM_TAG_LEN)),
+            decipher.final(),
+        ]);
+    }
+    catch {
+        throw new strict_json_1.ControlFormatError('sealed registration does not decrypt');
+    }
+    return parseRegistrationResult(qr, plaintext, wantDev, now);
+}
+/** parseRegistrationResult checks the decrypted plaintext (§5.6.2, §5.6.3 steps 2-4). */
+function parseRegistrationResult(qr, plaintext, wantDev, now) {
+    const base = ['v', 'type', 'channelId', 'ps', 'ctl', 'outcome'];
+    const obj = (0, strict_json_1.strictObject)((0, strict_json_1.parseStrictJson)(plaintext), base, ['profile', 'deviceName', 'role', 'expiresAt', 'topicId'], 'registration result');
+    if ((0, strict_json_1.uintMember)(obj, 'v') !== 1 || obj.type !== exports.REGISTRATION_TYPE) {
+        throw new strict_json_1.ControlFormatError('registration result has the wrong v or type');
+    }
+    if (obj.channelId !== qr.channelId) {
+        throw new strict_json_1.ControlFormatError('registration result is for another channel');
+    }
+    const ps = (0, strict_json_1.stringMember)(obj, 'ps');
+    const psBytes = Buffer.from(ps, 'utf8');
+    const wantPs = Buffer.from(qr.ps, 'utf8');
+    if (psBytes.length !== wantPs.length || !(0, node_crypto_1.timingSafeEqual)(psBytes, wantPs)) {
+        throw new strict_json_1.ControlFormatError('registration result ps does not match');
+    }
+    const ctl = controllerQrCtl(qr);
+    if (obj.ctl !== ctl) {
+        throw new strict_json_1.ControlFormatError('registration result is for another controller');
+    }
+    const outcome = (0, strict_json_1.stringMember)(obj, 'outcome');
+    const result = {
+        v: 1,
+        type: exports.REGISTRATION_TYPE,
+        channelId: qr.channelId,
+        ps,
+        ctl,
+        outcome: 'rejected',
+    };
+    if (outcome === 'rejected') {
+        if (Object.keys(obj).length !== base.length) {
+            throw new strict_json_1.ControlFormatError('a rejected registration carries no grant members');
+        }
+        return result;
+    }
+    if (outcome !== 'approved') {
+        throw new strict_json_1.ControlFormatError('registration result outcome is invalid');
+    }
+    for (const member of ['profile', 'deviceName', 'role']) {
+        if (!Object.prototype.hasOwnProperty.call(obj, member)) {
+            throw new strict_json_1.ControlFormatError(`an approved registration needs ${member}`);
+        }
+    }
+    if (!(0, strict_json_1.isPlainObject)(obj.profile) || (0, strict_json_1.uintMember)(obj.profile, 'v') !== 1) {
+        throw new strict_json_1.ControlFormatError('registration result profile is invalid');
+    }
+    const profile = (0, codec_1.parseProfile)(obj.profile);
+    if (profile.dev !== wantDev) {
+        throw new RegistrationForOtherDeviceError(profile.dev);
+    }
+    const deviceName = (0, strict_json_1.stringMember)(obj, 'deviceName');
+    if (!isProtocolLabel(deviceName)) {
+        throw new strict_json_1.ControlFormatError('registration result deviceName is invalid');
+    }
+    const role = (0, strict_json_1.stringMember)(obj, 'role');
+    if (role !== 'owner' && role !== 'controller') {
+        throw new strict_json_1.ControlFormatError('registration result role is invalid');
+    }
+    Object.assign(result, { outcome, profile, deviceName, role });
+    if (Object.prototype.hasOwnProperty.call(obj, 'expiresAt')) {
+        const expiresAt = (0, strict_json_1.uintMember)(obj, 'expiresAt');
+        // An owner grant never expires (§5.5), and an expiry in the past is no grant.
+        if (expiresAt <= now || role === 'owner') {
+            throw new strict_json_1.ControlFormatError('registration result expiresAt is invalid');
+        }
+        result.expiresAt = expiresAt;
+    }
+    if (Object.prototype.hasOwnProperty.call(obj, 'topicId')) {
+        const topicId = obj.topicId;
+        if (typeof topicId !== 'string' || topicId === '') {
+            throw new strict_json_1.ControlFormatError('registration result topicId must be a non-empty string');
+        }
+        result.topicId = topicId;
+    }
+    return result;
+}

package/dist/src/utilities/control/relay-pairing-channel.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * The relay v2 opener for the owner-initiated pairing channel
+ * (ffos-user docs/ff1-control-v1.md §5.6 step 1). It adapts TemporaryChannel
+ * (`/v2/channels/{channelId}/connections`) to the PairingChannel interface
+ * that `ff-cli device pair` consumes, and is installed at startup by
+ * installRelayPairingChannel when a v2 endpoint is configured.
+ *
+ * The channel carries no authority: every message is untrusted bytes that
+ * registration.ts opens and checks. This adapter only queues them.
+ *
+ * A relay drop ends the pairing wait (no reconnect: a new connection would
+ * get a new connection ID the owner's app does not know); `device pair` says
+ * the channel closed and the user shows a new code.
+ *
+ * Limit: TemporaryChannel does not reassemble `relayChunk` transfers, so a
+ * sealed registration result must fit one relay frame (about 32 KiB of
+ * payload). Results are about 1 KiB; a chunked one would arrive as fragments
+ * that fail to open and are ignored like any other stray message.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relayPairingChannelOpener = relayPairingChannelOpener;
+exports.installRelayPairingChannel = installRelayPairingChannel;
+const config_1 = require("../../config");
+const logger = __importStar(require("../../logger"));
+const temporary_channel_1 = require("../temporary-channel");
+const pairing_1 = require("./pairing");
+const pairing_channel_1 = require("./pairing-channel");
+const registration_1 = require("./registration");
+/**
+ * PAIRING_CHANNEL_TIMEOUT_MS is TemporaryChannel's own deadline. It only has
+ * to outlast the longest `device pair --timeout`; the caller's AbortSignal
+ * is what actually ends the wait.
+ */
+const PAIRING_CHANNEL_TIMEOUT_MS = pairing_1.MAX_PAIR_TIMEOUT_MS + 60_000;
+/**
+ * MAX_QUEUED_MESSAGES bounds unread messages. Anyone who saw the QR can write
+ * to the channel; the pairing loop drains each message at once, so only a
+ * flood fills the queue. Then NEW messages are dropped: evicting the oldest
+ * would let a flood push out an owner's result that is already queued.
+ */
+const MAX_QUEUED_MESSAGES = 64;
+/**
+ * MessageQueue is a single-consumer async iterable of channel payloads that
+ * ends when the channel closes.
+ */
+class MessageQueue {
+    items = [];
+    waiter;
+    ended = false;
+    /** push queues one payload, or hands it to a waiting reader. */
+    push(item) {
+        if (this.ended) {
+            return;
+        }
+        if (this.waiter) {
+            const waiter = this.waiter;
+            this.waiter = undefined;
+            waiter({ value: item, done: false });
+            return;
+        }
+        if (this.items.length < MAX_QUEUED_MESSAGES) {
+            this.items.push(item);
+        }
+    }
+    /** end finishes the iteration once queued payloads are read. */
+    end() {
+        this.ended = true;
+        if (this.waiter && !this.items.length) {
+            const waiter = this.waiter;
+            this.waiter = undefined;
+            waiter({ value: undefined, done: true });
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const item = this.items.shift();
+                if (item) {
+                    return Promise.resolve({ value: item, done: false });
+                }
+                if (this.ended) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve) => {
+                    this.waiter = resolve;
+                });
+            },
+        };
+    }
+}
+/**
+ * relayPairingChannelOpener returns an opener that joins the pairing channel
+ * on the relay v2 endpoint.
+ *
+ * The payload handler is attached before `ready` is awaited, so a result
+ * sent right after the relay's hello is not lost. Aborting the signal closes
+ * the channel, which ends the message iteration.
+ *
+ * @param endpoint - Relay v2 origin
+ * @param socketFactory - WebSocket constructor seam for tests
+ * @returns The opener for setPairingChannelOpener
+ */
+function relayPairingChannelOpener(endpoint, socketFactory) {
+    return async (channelId, signal) => {
+        if (!(0, registration_1.isValidChannelId)(channelId)) {
+            throw new Error('invalid pairing channel ID');
+        }
+        signal.throwIfAborted();
+        const channel = new temporary_channel_1.TemporaryChannel(endpoint, channelId, PAIRING_CHANNEL_TIMEOUT_MS, socketFactory);
+        const queue = new MessageQueue();
+        // The frame payload is a view into the relay frame; keep a private copy.
+        channel.onPayload = (_from, payload) => queue.push(payload.slice());
+        channel.onClose = () => queue.end();
+        const onAbort = () => channel.close(new Error('Pairing cancelled'));
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            await channel.ready;
+        }
+        catch (error) {
+            signal.removeEventListener('abort', onAbort);
+            throw error;
+        }
+        return pairingChannel(channel, queue, () => signal.removeEventListener('abort', onAbort));
+    };
+}
+/** pairingChannel exposes a joined TemporaryChannel as a receive-only PairingChannel. */
+function pairingChannel(channel, queue, detach) {
+    return {
+        channelId: channel.channelId,
+        messages: () => queue,
+        close: async () => {
+            detach();
+            channel.close();
+        },
+    };
+}
+/**
+ * installRelayPairingChannel installs the relay opener when a v2 endpoint is
+ * configured (ff1Relayer.v2Endpoint, FF1_RELAY_V2_ENDPOINT, or the default
+ * derived from the relayer). Without one, or with an invalid relayer config,
+ * `device pair` keeps the default opener, which says pairing is unavailable.
+ *
+ * @param getConfig - Relayer config source (tests inject one)
+ */
+function installRelayPairingChannel(getConfig = config_1.getFF1RelayerConfig) {
+    let endpoint;
+    try {
+        endpoint = getConfig().v2Endpoint;
+    }
+    catch (error) {
+        logger.debug(`Relay pairing channel not installed: ${error.message}`);
+        return;
+    }
+    if (endpoint) {
+        (0, pairing_channel_1.setPairingChannelOpener)(relayPairingChannelOpener(endpoint));
+    }
+}