@feralfile/cli 2.10.1 → 4.0.0

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

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * P-256 JWK handling for the FF1 control protocol v1 (§2).
+ *
+ * Every key the protocol carries (device, controller, ephemeral) is a P-256
+ * JWK with EXACTLY the members kty, crv, x, y. A private `d` in a public slot
+ * is an error, never ignored: a client that ships its private key has a bug
+ * this module must not paper over. The Go reference is control/jwk.go.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePublicJwk = parsePublicJwk;
+exports.parsePrivateJwk = parsePrivateJwk;
+exports.publicOf = publicOf;
+exports.canonicalJwkJson = canonicalJwkJson;
+exports.thumbprint = thumbprint;
+exports.isThumbprint = isThumbprint;
+exports.generatePrivateJwk = generatePrivateJwk;
+exports.sameKey = sameKey;
+const node_crypto_1 = require("node:crypto");
+const strict_json_1 = require("./strict-json");
+const COORD_LEN = 32;
+/**
+ * parsePublicJwk validates a parsed JWK object: exact member set, `EC`/`P-256`,
+ * 32-byte canonical base64url coordinates, and a point on the curve (Node's
+ * key import runs the SEC 1 on-curve check and rejects the identity).
+ *
+ * @param value - Parsed JSON value (from parseStrictJson or a trusted literal)
+ * @param what - Name used in error messages
+ * @returns The key in canonical member order
+ * @throws {ControlFormatError} When the key is malformed or off-curve
+ */
+function parsePublicJwk(value, what = 'JWK') {
+    const obj = (0, strict_json_1.strictObject)(value, ['kty', 'crv', 'x', 'y'], [], what);
+    if ((0, strict_json_1.stringMember)(obj, 'kty') !== 'EC' || (0, strict_json_1.stringMember)(obj, 'crv') !== 'P-256') {
+        throw new strict_json_1.ControlFormatError(`${what} is not an EC P-256 key`);
+    }
+    const x = (0, strict_json_1.stringMember)(obj, 'x');
+    const y = (0, strict_json_1.stringMember)(obj, 'y');
+    if (!(0, strict_json_1.isB64uOfLength)(x, COORD_LEN) || !(0, strict_json_1.isB64uOfLength)(y, COORD_LEN)) {
+        throw new strict_json_1.ControlFormatError(`${what} coordinates must be 32-byte base64url`);
+    }
+    const jwk = { crv: 'P-256', kty: 'EC', x, y };
+    try {
+        (0, node_crypto_1.createPublicKey)({ key: { ...jwk }, format: 'jwk' });
+    }
+    catch {
+        throw new strict_json_1.ControlFormatError(`${what} is not a point on P-256`);
+    }
+    return jwk;
+}
+/**
+ * parsePrivateJwk validates a stored private JWK: exact members kty, crv, x,
+ * y, d, and `d` must reproduce `x`,`y`. A mismatch means the file was edited
+ * or corrupted, and trusting either half would sign with a key the device does
+ * not have on record.
+ *
+ * @param value - Parsed JSON value
+ * @param what - Name used in error messages
+ * @returns The private key
+ * @throws {ControlFormatError} When malformed or inconsistent
+ */
+function parsePrivateJwk(value, what = 'private JWK') {
+    const obj = (0, strict_json_1.strictObject)(value, ['kty', 'crv', 'x', 'y', 'd'], [], what);
+    const pub = parsePublicJwk({ kty: obj.kty, crv: obj.crv, x: obj.x, y: obj.y }, what);
+    const d = (0, strict_json_1.stringMember)(obj, 'd');
+    if (!(0, strict_json_1.isB64uOfLength)(d, COORD_LEN)) {
+        throw new strict_json_1.ControlFormatError(`${what} d must be 32-byte base64url`);
+    }
+    let derived;
+    try {
+        derived = (0, node_crypto_1.createPublicKey)((0, node_crypto_1.createPrivateKey)({ key: { ...pub, d }, format: 'jwk' })).export({
+            format: 'jwk',
+        });
+    }
+    catch {
+        throw new strict_json_1.ControlFormatError(`${what} is not a valid P-256 private key`);
+    }
+    if (derived.x !== pub.x || derived.y !== pub.y) {
+        throw new strict_json_1.ControlFormatError(`${what} d does not match x,y`);
+    }
+    return { ...pub, d };
+}
+/**
+ * publicOf strips a private JWK down to its canonical public members.
+ *
+ * @param key - Private or public JWK
+ * @returns The public JWK in thumbprint member order
+ */
+function publicOf(key) {
+    return { crv: 'P-256', kty: 'EC', x: key.x, y: key.y };
+}
+/**
+ * canonicalJwkJson is the RFC 7638 required-member serialization, which is
+ * also the wire form this CLI emits, so a JWK it writes is byte-identical to
+ * the input of its own thumbprint (§2 "SHOULD emit in thumbprint order").
+ *
+ * @param key - JWK
+ * @returns `{"crv":"P-256","kty":"EC","x":"…","y":"…"}`
+ */
+function canonicalJwkJson(key) {
+    return `{"crv":"P-256","kty":"EC","x":${JSON.stringify(key.x)},"y":${JSON.stringify(key.y)}}`;
+}
+/**
+ * thumbprint is the RFC 7638 JWK thumbprint of §2: b64u(SHA-256) of the
+ * canonical member serialization. It is always 43 characters.
+ *
+ * @param key - JWK (private members are ignored)
+ * @returns The thumbprint
+ */
+function thumbprint(key) {
+    return (0, strict_json_1.b64uEncode)((0, node_crypto_1.createHash)('sha256').update(canonicalJwkJson(key), 'utf8').digest());
+}
+/**
+ * isThumbprint reports whether value is thumbprint-shaped (b64u of 32 bytes).
+ *
+ * @param value - Candidate value
+ * @returns True for a 43-character base64url SHA-256
+ */
+function isThumbprint(value) {
+    return typeof value === 'string' && value.length === 43 && (0, strict_json_1.isB64uOfLength)(value, 32);
+}
+/**
+ * generatePrivateJwk creates a fresh P-256 key pair as a private JWK.
+ *
+ * @returns A private JWK in canonical member order plus `d`
+ */
+function generatePrivateJwk() {
+    const { privateKey } = (0, node_crypto_1.generateKeyPairSync)('ec', { namedCurve: 'P-256' });
+    const jwk = privateKey.export({ format: 'jwk' });
+    return { crv: 'P-256', kty: 'EC', x: jwk.x, y: jwk.y, d: jwk.d };
+}
+/**
+ * sameKey reports whether two JWKs are the same point.
+ *
+ * @param a - First key
+ * @param b - Second key
+ * @returns True when x and y match
+ */
+function sameKey(a, b) {
+    return a.x === b.x && a.y === b.y;
+}

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

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * The pairing channel of owner-initiated registration
+ * (ffos-user docs/ff1-control-v1.md §5.6 step 1): a relay channel named by
+ * the random channelId in the controller QR, on which the owner's app sends
+ * the sealed registration result.
+ *
+ * ff-cli only consumes this interface. The relay v2 carrier
+ * (`/v2/channels/{channelId}/connections`) is implemented by
+ * relay-pairing-channel.ts, which plugs in with setPairingChannelOpener at
+ * startup when a v2 endpoint is configured. Without one (or with invalid
+ * relayer settings) the default opener
+ * fails with PairingTransportUnavailableError, so the CLI says so instead of
+ * waiting on nothing.
+ *
+ * The channel is untrusted: anyone who saw the QR can join it and send bytes.
+ * Every message is opened and checked by registration.ts before it means
+ * anything; the channel carries no authority of its own.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PairingTransportUnavailableError = void 0;
+exports.setPairingChannelOpener = setPairingChannelOpener;
+exports.pairingChannelOpener = pairingChannelOpener;
+/** PairingTransportUnavailableError is thrown when relay v2 is off, so no pairing channel is installed. */
+class PairingTransportUnavailableError extends Error {
+    constructor() {
+        super('owner-initiated pairing needs the relay v2 pairing channel, and relay v2 is turned off (check ff1Relayer.v2Endpoint, FF1_RELAY_V2_ENDPOINT and ff1Relayer.baseUrl)');
+        this.name = 'PairingTransportUnavailableError';
+    }
+}
+exports.PairingTransportUnavailableError = PairingTransportUnavailableError;
+const unavailableOpener = async () => {
+    throw new PairingTransportUnavailableError();
+};
+let currentOpener = unavailableOpener;
+/**
+ * setPairingChannelOpener installs the relay adapter's opener; undefined
+ * restores the default (unavailable) one.
+ *
+ * @param opener - Opener to use for `ff-cli device pair`
+ */
+function setPairingChannelOpener(opener) {
+    currentOpener = opener ?? unavailableOpener;
+}
+/**
+ * pairingChannelOpener returns the installed opener.
+ *
+ * @returns The opener `device pair` uses unless a caller injects one
+ */
+function pairingChannelOpener() {
+    return currentOpener;
+}

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

@@ -0,0 +1,416 @@
+"use strict";
+/**
+ * Controller pairing for ff-cli: owner-initiated registration
+ * (ffos-user docs/ff1-control-v1.md §5.6, §14.8; feral-file#3551).
+ *
+ * Sequence:
+ * 1. chooseControllerKeys: this computer's existing keys for the FF1 when it
+ *    has a readable controller file (so a re-pair after revocation, a role
+ *    change or a factory reset keeps one controllerId on the device instead
+ *    of orphaning a grant), else the pairing keys saved before the QR was
+ *    first shown (so a retry after a timeout or Ctrl-C completes a grant an
+ *    owner already registered), else new pairing keys, saved before use.
+ * 2. The caller shows the controller QR (registration.ts) and waits on the
+ *    pairing channel for a sealed result that passes every §5.6.3 check.
+ * 3. prepareRegisteredController pins the result's profile: on the existing
+ *    record when it is the same keys and identity, else on a new record that
+ *    replaces an existing one only once enrolled (the staging store).
+ * 4. enrollRegistered sends a protected op:enroll without inv (§5.3) and
+ *    stores role, nk and expiry from the verified reply.
+ *
+ * State is always consistent on interruption: before a verified result only
+ * the pairing keys are written, the record is written atomically before the first
+ * request, every counter is persisted before it is sent, and the grant is
+ * written only from a verified enroll reply. A record with a verified result
+ * that has not enrolled yet is finished by `ff-cli device pair --resume`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTROL_PROBE_NAME_TIMEOUT_MS = exports.CONTROL_PROBE_TIMEOUT_MS = exports.ENROLL_RETRY_MS = exports.ENROLL_ATTEMPTS = exports.MAX_PAIR_TIMEOUT_MS = exports.DEFAULT_PAIR_TIMEOUT_MS = void 0;
+exports.defaultControllerLabel = defaultControllerLabel;
+exports.chooseControllerKeys = chooseControllerKeys;
+exports.lanReadTimeoutMs = lanReadTimeoutMs;
+exports.probeControlSupport = probeControlSupport;
+exports.registrationRecordOf = registrationRecordOf;
+exports.prepareRegisteredController = prepareRegisteredController;
+exports.enrollRegistered = enrollRegistered;
+const node_os_1 = __importDefault(require("node:os"));
+const http_1 = require("../http");
+const codec_1 = require("./codec");
+const jwk_1 = require("./jwk");
+const controller_store_1 = require("./controller-store");
+const secure_transport_1 = require("./secure-transport");
+const control_errors_1 = require("./control-errors");
+const strict_json_1 = require("./strict-json");
+/** DEFAULT_PAIR_TIMEOUT_MS is how long `device pair` waits for an owner by default. */
+exports.DEFAULT_PAIR_TIMEOUT_MS = 5 * 60_000;
+/** MAX_PAIR_TIMEOUT_MS bounds `--timeout`: the relay keeps nothing, so a QR is a short-lived offer. */
+exports.MAX_PAIR_TIMEOUT_MS = 10 * 60_000;
+/** ENROLL_ATTEMPTS bounds the enroll retries after a verified result (network blips). */
+exports.ENROLL_ATTEMPTS = 5;
+/** ENROLL_RETRY_MS is the pause between enroll attempts. */
+exports.ENROLL_RETRY_MS = 2_000;
+/**
+ * defaultControllerLabel is the label the owner sees when adding ff-cli:
+ * this machine's hostname, trimmed to the protocol's 64 characters.
+ *
+ * @returns A 1-64 character label
+ */
+function defaultControllerLabel() {
+    const cleaned = (0, codec_1.stripUnsafeLabelCharacters)(node_os_1.default.hostname()).trim();
+    const label = [...cleaned].slice(0, 64).join('').trim();
+    return label || 'ff-cli';
+}
+/**
+ * chooseControllerKeys picks the keys the controller QR shows, always keys
+ * already on disk: those of the device's controller file when it is readable
+ * (enrolled or not), else the saved pairing keys (created and saved now when
+ * there are none). A corrupt controller file is moved aside, never written
+ * over, once a result arrives. An unreadable file throws: its keys may be
+ * fine, so nothing may pair past it.
+ *
+ * @param deviceId - FF1 device ID
+ * @param options - Main store options
+ * @returns The keys, whether they were already saved, and whether they are
+ *   the controller file's (else the pairing keys file's)
+ */
+function chooseControllerKeys(deviceId, options = {}) {
+    let existing = null;
+    try {
+        existing = (0, controller_store_1.loadController)(deviceId, options);
+    }
+    catch (error) {
+        if (!(error instanceof controller_store_1.ControllerFileCorruptError)) {
+            throw error;
+        }
+    }
+    if (existing) {
+        return { keys: existing.keys, reused: true, fromRecord: true };
+    }
+    return { ...(0, controller_store_1.pairingKeys)(deviceId, options), fromRecord: false };
+}
+/** CONTROL_PROBE_TIMEOUT_MS bounds the LAN status read that picks the pairing path. */
+exports.CONTROL_PROBE_TIMEOUT_MS = 5_000;
+/**
+ * CONTROL_PROBE_NAME_TIMEOUT_MS bounds the read by a `.local` name. macOS answers such a lookup
+ * after about 5 s, the whole of CONTROL_PROBE_TIMEOUT_MS, so the name gets room for the lookup.
+ */
+exports.CONTROL_PROBE_NAME_TIMEOUT_MS = 12_000;
+/**
+ * lanReadTimeoutMs is the deadline for one LAN read of host: a `.local` name gets room for the
+ * macOS lookup (CONTROL_PROBE_NAME_TIMEOUT_MS), anything else shortMs.
+ *
+ * @param host - Device base URL, e.g. http://ff1-abcd1234.local:1111
+ * @param shortMs - Deadline for an address or a unicast name
+ * @returns Milliseconds
+ */
+function lanReadTimeoutMs(host, shortMs = exports.CONTROL_PROBE_TIMEOUT_MS) {
+    try {
+        return new URL(host).hostname.toLowerCase().endsWith('.local')
+            ? exports.CONTROL_PROBE_NAME_TIMEOUT_MS
+            : shortMs;
+    }
+    catch {
+        return shortMs;
+    }
+}
+/**
+ * probeBases lists where to read the status: for a `.local` host, an address discovery
+ * recorded comes first (no name lookup; IPv4 preferred, since a first-listed IPv6 entry may be
+ * link-local or unreachable), then the name itself.
+ *
+ * Trade-off: unlike the name, which carries the device ID, a stale address may now belong to
+ * another FF1 in the same home, whose answer then picks the UI. That is a wrong prompt, never
+ * a grant: the status only chooses which pairing to offer, and both paths verify the device.
+ * The read carries the configured API key, so such a device would see it, as one answering on
+ * a reused name would.
+ * Worst case before the code shows: CONTROL_PROBE_TIMEOUT_MS + CONTROL_PROBE_NAME_TIMEOUT_MS.
+ */
+function probeBases(device) {
+    let url = null;
+    try {
+        url = new URL(device.host);
+    }
+    catch {
+        url = null;
+    }
+    const byName = url !== null && url.hostname.toLowerCase().endsWith('.local');
+    const bases = [];
+    const recorded = byName ? (device.addresses ?? []).filter((value) => value.trim() !== '') : [];
+    const address = recorded.find((value) => !value.includes(':')) ?? recorded[0];
+    if (url && address) {
+        const host = address.includes(':') ? `[${address}]` : address;
+        bases.push({
+            base: `${url.protocol}//${host}${url.port ? `:${url.port}` : ''}`,
+            byName: false,
+        });
+    }
+    bases.push({ base: device.host, byName });
+    return bases;
+}
+/**
+ * probeControlSupport reads `getDeviceStatus` in plaintext over the LAN
+ * (§11: the `control` block is the capability signal). An owned FF1 refuses
+ * plaintext with a public `enrollment_required` (§7.2), which also means
+ * secure. The answer is unauthenticated and only picks the pairing UI; no
+ * profile is ever taken from it.
+ *
+ * A `.local` host is read at the address discovery recorded first, then by
+ * name (see probeBases); the first read that is not `unknown` decides.
+ *
+ * @param device - Device with host, optional addresses and API key
+ * @param fetchFn - Fetch (tests); defaults to a per-read deadline
+ * @returns The pairing path the status points to
+ */
+async function probeControlSupport(device, fetchFn) {
+    let support = 'unknown';
+    for (const { base, byName } of probeBases(device)) {
+        const fetchAt = fetchFn ??
+            ((input, init) => (0, http_1.fetchWithTimeout)(input, init ?? {}, byName ? lanReadTimeoutMs(base) : exports.CONTROL_PROBE_TIMEOUT_MS));
+        support = await probeControlSupportAt(device, base, fetchAt);
+        if (support !== 'unknown') {
+            return support;
+        }
+    }
+    return support;
+}
+/** probeControlSupportAt is one status read at base (see probeControlSupport). */
+async function probeControlSupportAt(device, base, fetchFn) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (device.apiKey) {
+        headers['API-KEY'] = device.apiKey;
+    }
+    let body;
+    let ok;
+    try {
+        const response = await fetchFn(`${base}/api/cast`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ command: 'getDeviceStatus', request: {} }),
+        });
+        ok = response.ok;
+        body = JSON.parse(await response.text());
+    }
+    catch {
+        return 'unknown';
+    }
+    if (!(0, strict_json_1.isPlainObject)(body)) {
+        return 'unknown';
+    }
+    const error = body.error;
+    if ((0, strict_json_1.isPlainObject)(error) && typeof error.code === 'string') {
+        return ['enrollment_required', 'envelope_required', 'locked'].includes(error.code)
+            ? 'secure'
+            : 'unknown';
+    }
+    // The LAN hub answers with the bare status object (FF OS 2.0.12 and
+    // later); a relayer-shaped `{message: status}` is accepted too.
+    const status = (0, strict_json_1.isPlainObject)(body.message) ? body.message : body;
+    if (!ok || status.ok === false) {
+        return 'unknown';
+    }
+    if (status.control === undefined) {
+        return 'plaintext';
+    }
+    return (0, strict_json_1.isPlainObject)(status.control) && status.control.state === 'legacy'
+        ? 'plaintext'
+        : 'secure';
+}
+/**
+ * registrationRecordOf keeps the facts of a verified approved result.
+ *
+ * @param result - Verified approved result
+ * @param now - Unix seconds
+ * @returns The facts stored in the controller file
+ */
+function registrationRecordOf(result, now) {
+    const registration = {
+        channelId: result.channelId,
+        deviceName: result.deviceName,
+        role: result.role,
+        receivedAt: now,
+    };
+    if (result.expiresAt !== undefined) {
+        registration.expiresAt = result.expiresAt;
+    }
+    if (result.topicId !== undefined) {
+        registration.topicId = result.topicId;
+    }
+    return registration;
+}
+/**
+ * prepareRegisteredController pins a verified approved result. The existing
+ * record keeps its file (and counter) when it is the same keys under the same
+ * identity. Otherwise the result goes to a new record: the main file when
+ * there is none (a corrupt one is moved aside first, it may hold the only
+ * copy of an owner key), else the staging store, which replaces the existing
+ * record only once enrolled, so a failed pairing never costs a grant.
+ *
+ * @param input - Pinned profile, the keys the owner registered, label and result facts
+ * @param options - Main store options
+ * @returns The record and whether it is staged
+ */
+function prepareRegisteredController(input, options = {}) {
+    const deviceId = input.profile.dev;
+    let existing = null;
+    try {
+        existing = (0, controller_store_1.loadController)(deviceId, options);
+    }
+    catch (error) {
+        if (!(error instanceof controller_store_1.ControllerFileCorruptError)) {
+            throw error; // unreadable: its keys may be fine, never write over them
+        }
+        (0, controller_store_1.setAsideCorruptController)(deviceId, options);
+    }
+    if (existing &&
+        (0, jwk_1.sameKey)(existing.keys.sig, input.keys.sig) &&
+        (0, jwk_1.sameKey)(existing.keys.enc, input.keys.enc) &&
+        (0, controller_store_1.sameIdentity)(existing.profile, input.profile)) {
+        // A staged record left by an abandoned replacement pairing is superseded
+        // by this result, and --resume must not pick it up later.
+        (0, controller_store_1.dropStagedController)(deviceId, false, options);
+        const record = (0, controller_store_1.recordRegistration)(deviceId, { label: input.label, registration: input.registration }, options);
+        return { record, staged: false };
+    }
+    const staged = existing !== null;
+    const record = (0, controller_store_1.createController)({
+        profile: input.profile,
+        label: input.label,
+        keys: input.keys,
+        registration: input.registration,
+        exclusive: !staged,
+    }, staged ? (0, controller_store_1.stagingStore)(options) : options);
+    return { record, staged };
+}
+/** enrollObject builds the §5 enroll claim for this controller. */
+function enrollObject(record) {
+    return {
+        sig: (0, jwk_1.publicOf)(record.keys.sig),
+        enc: (0, jwk_1.publicOf)(record.keys.enc),
+        label: record.label,
+        platform: 'cli',
+    };
+}
+function asRole(value) {
+    return value === 'owner' || value === 'controller' ? value : undefined;
+}
+/**
+ * parseGrant validates an enroll success `res` (§5.3): role, nk, optional
+ * expiresAt, and a profile that must be the pinned one (a device whose
+ * profile changed under the same keys is a bug or an attack; either way
+ * nothing is stored).
+ */
+function parseGrant(res, pinned) {
+    if (!(0, strict_json_1.isPlainObject)(res)) {
+        return 'enroll reply has no grant';
+    }
+    const role = asRole(res.role);
+    if (!role || !(0, strict_json_1.isB64uOfLength)(res.nk, 32)) {
+        return 'enroll reply has an invalid role or nk';
+    }
+    const expiresAt = res.expiresAt;
+    if (expiresAt !== undefined && (!Number.isSafeInteger(expiresAt) || expiresAt < 0)) {
+        return 'enroll reply has an invalid expiresAt';
+    }
+    const profile = res.profile;
+    if (!profile ||
+        profile.gen !== pinned.gen ||
+        profile.dev !== pinned.dev ||
+        !profile.sig ||
+        !(0, jwk_1.sameKey)(profile.sig, pinned.sig) ||
+        !profile.enc ||
+        !(0, jwk_1.sameKey)(profile.enc, pinned.enc)) {
+        return 'enroll reply carries a different FF1 profile than the one the owner sent';
+    }
+    const grant = {
+        role,
+        nk: res.nk,
+    };
+    if (expiresAt !== undefined) {
+        grant.expiresAt = expiresAt;
+    }
+    return grant;
+}
+/** failureFrom maps a non-success outcome to a failure. */
+function failureFrom(outcome, label) {
+    if (outcome.kind === 'failed') {
+        return { code: outcome.code ?? 'failed', error: outcome.error, details: outcome.details };
+    }
+    const code = outcome.kind === 'public' ? outcome.code : (outcome.reply.code ?? 'unknown');
+    return (0, control_errors_1.describeControlCode)(code, label);
+}
+/**
+ * enrollRegistered sends op:enroll (no inv) until the FF1 returns the grant
+ * an owner registered, a definite refusal arrives, the attempts run out, or
+ * the user cancels. Each attempt is a new request with a new counter; enroll
+ * is idempotent (§5.3), so a lost reply is simply asked again.
+ *
+ * @param device - Device with ID
+ * @param record - Controller record with a pinned profile
+ * @param deps - Transport seams; controllerStore is the store the record is in
+ * @param options - Attempt tuning
+ * @returns The enrolled record or why enrollment stopped
+ */
+async function enrollRegistered(device, record, deps = {}, options = {}) {
+    const attempts = options.attempts ?? exports.ENROLL_ATTEMPTS;
+    const wait = deps.waitFn ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const label = device.name || device.id;
+    let last = null;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        if (options.cancelled?.()) {
+            return { status: 'cancelled' };
+        }
+        const outcome = await (0, secure_transport_1.sendSecureRequest)({ device, op: 'enroll', enroll: enrollObject(record), relayerFallback: true, retry: false }, record, { ...deps, noticeFn: () => undefined });
+        const step = interpretEnrollOutcome(outcome, record, label, options.storeOptions);
+        if (step.status !== 'transient') {
+            return step;
+        }
+        last = { status: 'failed', failure: step.failure };
+        if (attempt < attempts) {
+            await wait(options.retryMs ?? exports.ENROLL_RETRY_MS);
+        }
+    }
+    return last;
+}
+/** interpretEnrollOutcome returns a final result, or a transient failure worth asking again. */
+function interpretEnrollOutcome(outcome, record, label, storeOptions) {
+    if (outcome.kind === 'reply' && outcome.reply.ok) {
+        const grant = parseGrant(outcome.reply.res, record.profile);
+        if (typeof grant === 'string') {
+            return { status: 'failed', failure: { code: 'invalid_grant', error: grant } };
+        }
+        return { status: 'enrolled', record: (0, controller_store_1.markEnrolled)(record.deviceId, grant, storeOptions) };
+    }
+    // busy (§4.4): the FF1 was authenticating too many envelopes and did not
+    // run this one; the next attempt is a new request anyway.
+    if (outcome.kind === 'public' && outcome.code === 'busy') {
+        return { status: 'transient', failure: failureFrom(outcome, label) };
+    }
+    if (outcome.kind === 'reply') {
+        const code = outcome.reply.code;
+        if (code === 'rate_limited' || code === 'internal_error') {
+            return { status: 'transient', failure: failureFrom(outcome, label) };
+        }
+        if (code === 'not_approved' || code === 'pending') {
+            return {
+                status: 'failed',
+                failure: {
+                    code,
+                    error: 'The FF1 has no grant for ff-cli, although an owner’s Feral File app reported adding it.',
+                    details: `An owner may have removed it again. Run \`${(0, control_errors_1.pairCommand)(label)}\` to show a new code.`,
+                },
+            };
+        }
+    }
+    // The FF1 or the relayer may come back (Wi-Fi blip, relayer restart).
+    // Protocol answers (codes) are never transient.
+    if (outcome.kind === 'failed' &&
+        (outcome.unreachable ||
+            outcome.timedOut || // enroll is idempotent (§5.3): asking again is safe
+            (outcome.transport === 'relayer' && !outcome.code))) {
+        return { status: 'transient', failure: failureFrom(outcome, label) };
+    }
+    return { status: 'failed', failure: failureFrom(outcome, label) };
+}