@trillboards/edge-sdk 0.2.24 → 0.2.25

package/dist/EnrollClient.d.ts

@@ -0,0 +1,81 @@
+import { type HttpPoster } from './AudienceAnalyzeClient';
+/**
+ * EnrollClient — UNATTENDED first-boot provisioning.
+ *
+ * Exchanges a FLEET enrollment credential (issued once in the portal, shipped
+ * inside the MDM/Intune/SCCM package) for THIS MACHINE's own connector
+ * credential, via `POST {apiBaseUrl}/v2/earner/connectors/enroll`.
+ *
+ * WHY THIS EXISTS. Every other path to a working connector needs a human at the
+ * machine: `pair --code` needs an 8-character claim code typed in, and `setup`
+ * needs a code read off this screen and typed into a browser on another. Neither
+ * can be automated, so before this there was no way to deploy to N machines.
+ *
+ * WHAT COMES BACK, AND WHAT DOES NOT. The response carries a `connectorKey`
+ * scoped to camera registration for one account — NOT the fleet credential, and
+ * NOT any device token. Device tokens are still minted per camera feed, later,
+ * when the cameras this machine finds are registered. That split is deliberate:
+ * the credential that ends up sitting on 200 store PCs must not be able to
+ * enroll a 201st machine.
+ *
+ * THE FLEET CREDENTIAL IS CONSUMED, NOT KEPT. The caller writes `connectorKey`
+ * into the config and DELETES the enrollment file — see `runEnroll` in cli.ts.
+ * A bootstrap credential that outlives its bootstrap is just a credential.
+ *
+ * Auth is `Authorization: Bearer <enrollment token>` — the same platform-key
+ * header the Partner API and the CTV SDK use. Unlike `PairClient`, this request
+ * IS authenticated; unlike `AudienceAnalyzeClient`, it carries no device token,
+ * because at first boot this machine has no device identity yet. That is the
+ * whole point of the exchange.
+ *
+ * Uses the same built-in-http poster as its siblings (no extra dep → survives
+ * bundling; trivially mockable in tests).
+ */
+export interface EnrollClientOptions {
+    /** Base URL, e.g. https://api.trillboards.com (no trailing slash needed). */
+    apiBaseUrl: string;
+    /** Request timeout in ms. Default: 30000. */
+    timeoutMs?: number;
+}
+export interface EnrollRequest {
+    /** The fleet enrollment credential from the MDM package. */
+    enrollmentToken: string;
+    /** This machine's stable fingerprint — `hostFingerprint()` in cli.ts. */
+    machineId: string;
+    /** Free-text install label, e.g. "Store 0417". Optional. */
+    siteLabel?: string;
+    hostname?: string;
+    platform?: string;
+    connectorVersion?: string;
+}
+export interface EnrollResult {
+    ok: boolean;
+    /** Present only when ok. */
+    connectorId?: string;
+    connectorKey?: string;
+    siteLabel?: string | null;
+    reEnrollment?: boolean;
+    remainingEnrollments?: number | null;
+    error?: string;
+    /**
+     * Classification, so the installer wrapper can tell an operator-fixable
+     * problem from a wait-and-retry one WITHOUT parsing prose:
+     *
+     *   'auth'    the credential is wrong, expired, revoked or exhausted. A human
+     *             must issue a new one — retrying forever cannot help, and a
+     *             connector that retries a dead credential every 60s across 200
+     *             stores is a self-inflicted DDoS.
+     *   'network' unreachable / timed out. Retry.
+     *   'server'  5xx or an unparseable body. Retry.
+     *   'invalid' this machine sent something malformed. A bug, not a retry.
+     */
+    kind?: 'auth' | 'network' | 'server' | 'invalid';
+}
+export declare class EnrollClient {
+    private readonly endpoint;
+    private readonly timeoutMs;
+    private readonly poster;
+    constructor(options: EnrollClientOptions, poster?: HttpPoster);
+    enroll(req: EnrollRequest): Promise<EnrollResult>;
+}
+//# sourceMappingURL=EnrollClient.d.ts.map

package/dist/EnrollClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnrollClient.d.ts","sourceRoot":"","sources":["../src/EnrollClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,eAAe,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,4BAA4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;CAClD;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;gBAExB,OAAO,EAAE,mBAAmB,EAAE,MAAM,GAAE,UAA8B;IAU1E,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;CAqFxD"}

package/dist/EnrollClient.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnrollClient = void 0;
+const AudienceAnalyzeClient_1 = require("./AudienceAnalyzeClient");
+class EnrollClient {
+    constructor(options, poster = AudienceAnalyzeClient_1.defaultHttpPoster) {
+        if (!options?.apiBaseUrl) {
+            throw new Error('EnrollClient requires an apiBaseUrl');
+        }
+        const base = options.apiBaseUrl.replace(/\/+$/, '');
+        this.endpoint = `${base}/v2/earner/connectors/enroll`;
+        this.timeoutMs = options.timeoutMs ?? 30000;
+        this.poster = poster;
+    }
+    async enroll(req) {
+        const token = (req?.enrollmentToken ?? '').trim();
+        if (!token) {
+            return { ok: false, error: 'enroll() requires a non-empty enrollmentToken', kind: 'invalid' };
+        }
+        if (!req?.machineId) {
+            return { ok: false, error: 'enroll() requires a machineId', kind: 'invalid' };
+        }
+        const body = { machineId: req.machineId };
+        if (req.siteLabel)
+            body.siteLabel = req.siteLabel;
+        if (req.hostname)
+            body.hostname = req.hostname;
+        if (req.platform)
+            body.platform = req.platform;
+        if (req.connectorVersion)
+            body.connectorVersion = req.connectorVersion;
+        let response;
+        try {
+            response = await this.poster(this.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                    Authorization: `Bearer ${token}`,
+                },
+                timeoutMs: this.timeoutMs,
+            }, JSON.stringify(body));
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: `enrollment request failed: ${err?.message ?? 'unknown error'}`,
+                kind: 'network',
+            };
+        }
+        let parsed = null;
+        try {
+            parsed = JSON.parse(response.body);
+        }
+        catch {
+            parsed = null;
+        }
+        const code = response.statusCode;
+        if (code < 200 || code >= 300) {
+            // 401/403 is terminal: the credential is wrong, spent, expired or revoked.
+            // The server deliberately does not say WHICH — see consumeKeyUse — so the
+            // connector cannot tell either, and must not retry as if it could.
+            const kind = code === 401 || code === 403
+                ? 'auth'
+                : code === 400
+                    ? 'invalid'
+                    : 'server';
+            const message = parsed?.error
+                || parsed?.message
+                || `enrollment failed (HTTP ${code})`;
+            return { ok: false, error: message, kind };
+        }
+        const connectorKey = typeof parsed?.connectorKey === 'string' ? parsed.connectorKey : '';
+        const connectorId = typeof parsed?.connectorId === 'string' ? parsed.connectorId : '';
+        if (!connectorKey || !connectorId) {
+            // A 2xx that carries no credential is the ingestion-endpoint trap in
+            // reverse: treating it as success would leave a "provisioned" machine with
+            // nothing to authenticate with, and the failure would only surface much
+            // later as a camera that never registers.
+            return {
+                ok: false,
+                error: 'enrollment response did not contain a connector credential',
+                kind: 'server',
+            };
+        }
+        return {
+            ok: true,
+            connectorId,
+            connectorKey,
+            siteLabel: parsed?.siteLabel ?? null,
+            reEnrollment: parsed?.reEnrollment === true,
+            remainingEnrollments: typeof parsed?.remainingEnrollments === 'number' ? parsed.remainingEnrollments : null,
+        };
+    }
+}
+exports.EnrollClient = EnrollClient;
+//# sourceMappingURL=EnrollClient.js.map

package/dist/EnrollClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnrollClient.js","sourceRoot":"","sources":["../src/EnrollClient.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -26,4 +26,53 @@ export declare function configWritePermissionMessage(resolvedConfigPath: string)
 export declare function writePairedConfig(resolvedConfigPath: string, serialized: string, writeFile?: (p: string, data: string, opts: {
     mode: number;
 }) => void): void;
+/** Show a credential's SHAPE without showing the credential. */
+export declare function maskConnectorKey(key: string | undefined | null): string;
+/**
+ * Read the enrollment token for an unattended install, in precedence order.
+ *
+ * 1. `--enrollment-token <value>` — for a scripted/manual run.
+ * 2. `TRILLBOARDS_ENROLLMENT_TOKEN` — the Docker/systemd path.
+ * 3. `--enrollment-file <path>` / the default bootstrap file next to the config
+ *    — what the Windows installer writes from `/ENROLLMENT_TOKEN=`.
+ *
+ * The FILE is the preferred form for MDM and the reason this function exists:
+ * an argument shows up in the process table and an env var is inherited by every
+ * child process, while a file can be read once and DELETED. That deletion is not
+ * hygiene, it is the design — the fleet credential must not outlive the
+ * bootstrap, or every store PC keeps something that can enroll more machines.
+ */
+export declare function readEnrollmentToken(args: string[], configPath: string, env?: NodeJS.ProcessEnv, readFile?: (p: string) => string, exists?: (p: string) => boolean): {
+    token: string | null;
+    source: 'flag' | 'env' | 'file' | null;
+    filePath: string | null;
+};
+/**
+ * UNATTENDED first-boot provisioning — the MDM/Intune/SCCM path.
+ *
+ *   trillboards-edge enroll [--enrollment-token T | --enrollment-file P]
+ *                           [--site "Store 0417"] [--config PATH] [--api-base URL]
+ *
+ * Exchanges the FLEET enrollment credential shipped in the deployment package
+ * for THIS MACHINE's own connector credential and writes it to the config. No
+ * human touches the machine, which is the entire point: `pair` needs a code
+ * typed in and `setup` needs a code read off the screen, so neither can be
+ * automated across N stores.
+ *
+ * IDEMPOTENT BY DESIGN. Re-running on an already-enrolled machine is safe and
+ * FREE — the server keys on `machineId` and does not spend another use of the
+ * bounded fleet credential. MDM re-pushes packages; if a re-push cost a use, a
+ * 200-use credential would die partway through a 200-store rollout.
+ *
+ * ON SUCCESS THE ENROLLMENT FILE IS DELETED. See readEnrollmentToken.
+ *
+ * Exit codes (the install wrappers branch on these — keep stable, and note they
+ * mirror `pair`'s so a wrapper can treat the two paths alike):
+ *   0  enrolled (or already enrolled), config written
+ *   1  the credential was rejected — wrong, expired, revoked or exhausted. A
+ *      human must issue a new one; retrying cannot help.
+ *   4  no enrollment token was supplied at all (not an unattended install)
+ *   6  network/server failure — the credential is UNSPENT. Retry later.
+ */
+export declare function runEnroll(args: string[]): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAkcA;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAKvD;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAW/E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,kBAAkB,EAAE,MAAM,EAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,KAAK,IAC/B,GAChC,IAAI,CAWN"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAscA;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAKvD;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAW/E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,kBAAkB,EAAE,MAAM,EAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,KAAK,IAC/B,GAChC,IAAI,CAWN;AAUD,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CASvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,QAAQ,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAA2C,EACpE,MAAM,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAiC,GACvD;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAyB3F;AAgGD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA+K7D"}

package/dist/cli.js

@@ -37,6 +37,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isPermissionError = isPermissionError;
 exports.configWritePermissionMessage = configWritePermissionMessage;
 exports.writePairedConfig = writePairedConfig;
+exports.maskConnectorKey = maskConnectorKey;
+exports.readEnrollmentToken = readEnrollmentToken;
+exports.runEnroll = runEnroll;
 const config_1 = require("./config");
 const autoSense_1 = require("./autoSense");
 const sensingRunMode_1 = require("./sensingRunMode");
@@ -180,6 +183,9 @@ async function main() {
         case 'pair':
             await runPair(args.slice(1));
             break;
+        case 'enroll':
+            await runEnroll(args.slice(1));
+            break;
         case 'setup': {
             // Validate-first onboarding (direction-inverted pairing): WE display a
             // short code, the owner claims it in the portal, the portal drives
@@ -490,6 +496,318 @@ function writePairedConfig(resolvedConfigPath, serialized, writeFile = (p, data,
         throw err;
     }
 }
+/** Show a credential's SHAPE without showing the credential. */
+function maskConnectorKey(key) {
+    if (!key)
+        return '(none)';
+    const s = String(key);
+    // Prefix identifies the key family; last 4 lets an admin match it to the
+    // portal row. Everything between is what must never reach a log, a support
+    // bundle, or a screenshot of this terminal.
+    const head = s.slice(0, 7);
+    const tail = s.length > 4 ? s.slice(-4) : '';
+    return `${head}…${tail}`;
+}
+/**
+ * Read the enrollment token for an unattended install, in precedence order.
+ *
+ * 1. `--enrollment-token <value>` — for a scripted/manual run.
+ * 2. `TRILLBOARDS_ENROLLMENT_TOKEN` — the Docker/systemd path.
+ * 3. `--enrollment-file <path>` / the default bootstrap file next to the config
+ *    — what the Windows installer writes from `/ENROLLMENT_TOKEN=`.
+ *
+ * The FILE is the preferred form for MDM and the reason this function exists:
+ * an argument shows up in the process table and an env var is inherited by every
+ * child process, while a file can be read once and DELETED. That deletion is not
+ * hygiene, it is the design — the fleet credential must not outlive the
+ * bootstrap, or every store PC keeps something that can enroll more machines.
+ */
+function readEnrollmentToken(args, configPath, env = process.env, readFile = (p) => fs.readFileSync(p, 'utf-8'), exists = (p) => fs.existsSync(p)) {
+    const fromFlag = getArg(args, '--enrollment-token');
+    if (fromFlag && fromFlag.trim())
+        return { token: fromFlag.trim(), source: 'flag', filePath: null };
+    const fromEnv = env.TRILLBOARDS_ENROLLMENT_TOKEN;
+    if (fromEnv && fromEnv.trim())
+        return { token: fromEnv.trim(), source: 'env', filePath: null };
+    const filePath = path.resolve(getArg(args, '--enrollment-file')
+        || path.join(path.dirname(path.resolve(configPath)), 'trillboards.enrollment'));
+    if (exists(filePath)) {
+        try {
+            // The installer writes the bare token, but tolerate a trailing newline and
+            // a `TOKEN=` prefix — an admin editing this file by hand should not have
+            // their rollout fail on a shell habit.
+            const raw = readFile(filePath).trim();
+            const token = raw.replace(/^TRILLBOARDS_ENROLLMENT_TOKEN\s*=\s*/i, '').replace(/^["']|["']$/g, '').trim();
+            if (token)
+                return { token, source: 'file', filePath };
+        }
+        catch {
+            // Unreadable is the same as absent for the caller; the missing-token
+            // message below is the right thing to print either way.
+        }
+    }
+    return { token: null, source: null, filePath };
+}
+/**
+ * Find the feeds on this machine's LAN and hand them to the server, returning
+ * the `cameras[]` this connector will run on.
+ *
+ * WHY CREDENTIALS ARE REQUIRED HERE, and why "no credentials" is not an error:
+ * this product targets cheap analog DVRs whose channels are behind a recorder
+ * password. Registering a channel we cannot open would mint a screen that never
+ * sees a frame — a camera board full of feeds that are permanently dark, which
+ * is worse than an empty one. So with no credentials we register NOTHING and say
+ * so plainly; the operator finishes in the portal exactly as before.
+ *
+ * The recorder credentials never leave this machine: only a stable `cameraKey`
+ * and a display name go to the server, and the credentialed URLs are matched
+ * back to the returned device tokens locally.
+ */
+async function discoverAndRegisterFeeds(opts) {
+    if (!opts.nvrUser || !opts.nvrPass) {
+        return {
+            feeds: [],
+            discovered: 0,
+            reason: 'no recorder credentials were supplied (--nvr-user / --nvr-pass), so no feeds were registered',
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const discovery = require('./discovery');
+    const recorders = await discovery.sweepLanForRecorders({});
+    if (!recorders.length) {
+        return { feeds: [], discovered: 0, reason: 'no recorders answered on this network' };
+    }
+    // The XM/DVRIP handshake makes a recorder state its OWN channel count, which
+    // is the difference between "a socket accepted a connection" and "a 16-channel
+    // recorder, expand it". Hosts that do not answer keep their port-open shape and
+    // fall back to a single channel below.
+    const annotated = await discovery.annotateXmRecorders(recorders);
+    const brand = (opts.brand || 'generic');
+    const discovered = [];
+    for (const rec of annotated) {
+        const xm = rec.xm;
+        const channels = Number(xm?.channelNum) > 0 ? Number(xm.channelNum) : 1;
+        const expanded = discovery.expandChannelRange({
+            brand,
+            host: rec.host,
+            count: channels,
+            username: opts.nvrUser,
+            password: opts.nvrPass,
+            namePrefix: opts.siteLabel ? `${opts.siteLabel} channel` : 'Channel',
+        });
+        for (const cam of expanded)
+            discovered.push(cam);
+    }
+    if (!discovered.length) {
+        return { feeds: [], discovered: 0, reason: 'recorders answered but no channels could be expanded' };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { ConnectorCameraClient, buildCameraFeeds, MAX_CAMERAS_PER_CALL } = require('./ConnectorCameraClient');
+    const client = new ConnectorCameraClient({ apiBaseUrl: opts.apiBaseUrl, connectorKey: opts.connectorKey });
+    // The server caps one call; a 64-channel recorder is a real configuration, so
+    // page rather than silently truncating (the claim-code path's `.slice(0, 64)`
+    // is exactly the bug this avoids).
+    const feeds = [];
+    for (let i = 0; i < discovered.length; i += MAX_CAMERAS_PER_CALL) {
+        const page = discovered.slice(i, i + MAX_CAMERAS_PER_CALL);
+        // eslint-disable-next-line no-await-in-loop
+        const result = await client.registerCameras(page.map((c) => ({ cameraKey: c.cameraKey, name: c.name })));
+        if (!result.ok) {
+            // Partial success is kept: the feeds already registered are real and their
+            // tokens work. Reporting zero would throw away provisioning that happened.
+            return {
+                feeds,
+                discovered: discovered.length,
+                reason: `camera registration failed after ${feeds.length} feed(s): ${result.error}`,
+            };
+        }
+        for (const feed of buildCameraFeeds(result.cameras, discovered))
+            feeds.push(feed);
+    }
+    return { feeds, discovered: discovered.length };
+}
+/**
+ * UNATTENDED first-boot provisioning — the MDM/Intune/SCCM path.
+ *
+ *   trillboards-edge enroll [--enrollment-token T | --enrollment-file P]
+ *                           [--site "Store 0417"] [--config PATH] [--api-base URL]
+ *
+ * Exchanges the FLEET enrollment credential shipped in the deployment package
+ * for THIS MACHINE's own connector credential and writes it to the config. No
+ * human touches the machine, which is the entire point: `pair` needs a code
+ * typed in and `setup` needs a code read off the screen, so neither can be
+ * automated across N stores.
+ *
+ * IDEMPOTENT BY DESIGN. Re-running on an already-enrolled machine is safe and
+ * FREE — the server keys on `machineId` and does not spend another use of the
+ * bounded fleet credential. MDM re-pushes packages; if a re-push cost a use, a
+ * 200-use credential would die partway through a 200-store rollout.
+ *
+ * ON SUCCESS THE ENROLLMENT FILE IS DELETED. See readEnrollmentToken.
+ *
+ * Exit codes (the install wrappers branch on these — keep stable, and note they
+ * mirror `pair`'s so a wrapper can treat the two paths alike):
+ *   0  enrolled (or already enrolled), config written
+ *   1  the credential was rejected — wrong, expired, revoked or exhausted. A
+ *      human must issue a new one; retrying cannot help.
+ *   4  no enrollment token was supplied at all (not an unattended install)
+ *   6  network/server failure — the credential is UNSPENT. Retry later.
+ */
+async function runEnroll(args) {
+    const configPath = getArg(args, '--config') || 'trillboards.config.json';
+    const resolvedConfigPath = path.resolve(configPath);
+    const apiBaseUrl = getArg(args, '--api-base')
+        || process.env.TRILLBOARDS_API_BASE
+        || 'https://api.trillboards.com';
+    const siteLabel = getArg(args, '--site') || process.env.TRILLBOARDS_SITE || undefined;
+    const { token, source, filePath } = readEnrollmentToken(args, resolvedConfigPath);
+    if (!token) {
+        console.error('No enrollment credential found.\n' +
+            '  Pass --enrollment-token <token>, set TRILLBOARDS_ENROLLMENT_TOKEN,\n' +
+            `  or place the token in ${filePath ?? 'trillboards.enrollment'}.\n` +
+            '  Create one in the portal under Cameras → Deploy connectors.');
+        process.exit(4);
+        return;
+    }
+    const machineId = hostFingerprint();
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { EnrollClient } = require('./EnrollClient');
+    const client = new EnrollClient({ apiBaseUrl });
+    const result = await client.enroll({
+        enrollmentToken: token,
+        machineId,
+        siteLabel,
+        hostname: os.hostname(),
+        platform: process.platform,
+        connectorVersion: VERSION,
+    });
+    if (!result.ok) {
+        console.error(`Enrollment failed: ${result.error}`);
+        if (result.kind === 'auth') {
+            console.error('The enrollment credential was rejected. It may be expired, revoked, or it may\n' +
+                'have already enrolled every machine it was issued for. Issue a new one in the\n' +
+                'portal — retrying with this one cannot succeed.');
+            process.exit(1);
+            return;
+        }
+        if (result.kind === 'invalid') {
+            process.exit(1);
+            return;
+        }
+        console.error('This is a network or server failure — the credential was NOT spent. Retry later.');
+        process.exit(6);
+        return;
+    }
+    // Merge into any existing config rather than replacing it. A machine may be
+    // re-enrolled after cameras are already registered, and clobbering
+    // `cameras[]` would drop every device token on the box.
+    let existing = {};
+    if (fs.existsSync(resolvedConfigPath)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(resolvedConfigPath, 'utf-8'));
+        }
+        catch {
+            console.warn(`Existing config at ${resolvedConfigPath} is not valid JSON — writing a fresh one.`);
+            existing = {};
+        }
+    }
+    // Now that this machine has a credential, find its feeds and register them.
+    // Enrollment without this leaves the box with an identity and no cameras, and
+    // `auto-sense` exits through its no-feeds path — an install that reports
+    // success while a human still has to run the interactive camera setup.
+    let registration = {
+        feeds: [],
+        discovered: 0,
+        reason: 'camera registration was skipped',
+    };
+    try {
+        registration = await discoverAndRegisterFeeds({
+            apiBaseUrl,
+            connectorKey: result.connectorKey,
+            nvrUser: getArg(args, '--nvr-user') || process.env.TRILLBOARDS_NVR_USER,
+            nvrPass: getArg(args, '--nvr-pass') || process.env.TRILLBOARDS_NVR_PASS,
+            brand: getArg(args, '--brand'),
+            siteLabel: result.siteLabel || siteLabel,
+        });
+    }
+    catch (err) {
+        // A discovery failure must never lose the credential we just obtained: the
+        // enrollment itself SUCCEEDED and its use is spent, so write the config and
+        // let the operator (or the next-logon retry) finish the camera half.
+        registration = {
+            feeds: [],
+            discovered: 0,
+            reason: `camera discovery failed: ${err?.message ?? 'unknown error'}`,
+        };
+    }
+    const existingCameras = Array.isArray(existing.cameras)
+        ? (existing.cameras)
+        : [];
+    // Merge by screenId so a re-run refreshes a feed's token rather than
+    // duplicating it, and never drops a feed the operator added by hand.
+    const mergedCameras = registration.feeds.length > 0
+        ? [
+            ...registration.feeds,
+            ...existingCameras.filter((c) => !registration.feeds.some((f) => f.screenId && f.screenId === c.screenId)),
+        ]
+        : existingCameras;
+    const merged = {
+        ...existing,
+        apiBaseUrl,
+        ...(mergedCameras.length > 0 ? { cameras: mergedCameras } : {}),
+        connector: {
+            id: result.connectorId,
+            key: result.connectorKey,
+            machineId,
+            ...(result.siteLabel ? { siteLabel: result.siteLabel } : {}),
+            enrolledAt: new Date().toISOString(),
+        },
+    };
+    fs.mkdirSync(path.dirname(resolvedConfigPath), { recursive: true });
+    writePairedConfig(resolvedConfigPath, JSON.stringify(merged, null, 2) + '\n');
+    // `mode` on writeFileSync only applies on CREATE, so an existing 0644 config —
+    // exactly what `trillboards-edge init` leaves behind — would keep its
+    // permissions and this credential would land world-readable. Tighten
+    // explicitly, as setupMode.ts does for the same reason.
+    try {
+        fs.chmodSync(resolvedConfigPath, 0o600);
+    }
+    catch {
+        // Windows has no POSIX modes; %LOCALAPPDATA% is the per-user boundary there.
+    }
+    // The fleet credential has done its one job. Anything left on disk that can
+    // enroll another machine is a skeleton key sitting in a store.
+    if (source === 'file' && filePath) {
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch (err) {
+            console.warn(`WARNING: enrolled successfully but could not delete the enrollment file at ${filePath}: ` +
+                `${err?.message}. Delete it manually — it can enroll further machines.`);
+        }
+    }
+    console.log(`${result.reEnrollment ? 'Re-enrolled' : 'Enrolled'} connector ${result.connectorId}` +
+        (result.siteLabel ? ` (${result.siteLabel})` : '') +
+        `\n  machine:   ${machineId}` +
+        `\n  credential: ${maskConnectorKey(result.connectorKey)}` +
+        (result.remainingEnrollments != null
+            ? `\n  remaining enrollments on this credential: ${result.remainingEnrollments}`
+            : '') +
+        `\n  cameras:   ${mergedCameras.length} registered` +
+        (registration.reason ? ` (${registration.reason})` : ''));
+    // Exit 5 = provisioned but NOT sensing. A distinct code, because "enrolled"
+    // and "enrolled and actually watching something" are different outcomes and
+    // collapsing them into 0 is how an installer reports success on a machine that
+    // still needs a human.
+    if (mergedCameras.length === 0) {
+        console.log('This connector is provisioned but has no camera feeds yet. Supply recorder\n' +
+            'credentials (--nvr-user / --nvr-pass, or /NVR_USER= /NVR_PASS= at install)\n' +
+            'and re-run, or finish in the portal.');
+        process.exit(5);
+        return;
+    }
+    process.exit(0);
+}
 /**
  * First-run pairing: exchange a portal claim code for the connector config and
  * write trillboards.config.json. The device token is delivered ONLY here (never
@@ -749,6 +1067,20 @@ Usage:
   trillboards-edge setup [--config <path>]         Validate-first onboarding: opens the portal and keeps a code fallback
   trillboards-edge pair --code <XXXX-XXXX>         Pair with a portal claim code (writes config)
   trillboards-edge pair --qr <image.png>           Pair by scanning a screenshot/photo of the portal QR
+  trillboards-edge enroll [--site "Store 0417"] [--nvr-user U --nvr-pass P]
+                                          Unattended provisioning for MDM/Intune/SCCM — no
+                                          human at the machine. Reads the fleet enrollment
+                                          credential from --enrollment-token, the
+                                          TRILLBOARDS_ENROLLMENT_TOKEN env var, or the
+                                          trillboards.enrollment file, exchanges it for THIS
+                                          machine's own credential, deletes the file, then
+                                          discovers recorders on the LAN and registers their
+                                          channels (recorder credentials required for that
+                                          half — without them the machine provisions its
+                                          identity and registers no feeds).
+                                          Safe to re-run: a re-push does not consume another
+                                          enrollment. (exit 0=ok 1=credential rejected
+                                          4=no token 5=enrolled but no feeds 6=network, retry)
   trillboards-edge verify-connection [--config p]  Prove the saved pairing works (exit 0=ok 2=network 3=auth 4=no config)
   trillboards-edge discover                         Find cameras on your network (ONVIF) or expand an NVR's channels
   trillboards-edge status [--host h] [--port p]    Show agent status dashboard