@serfab/cadre-host 0.7.1 → 0.9.0

package/dist/bin/host.js

@@ -17,14 +17,18 @@ import { dirname, join, resolve } from 'node:path';
 import { Command } from 'commander';
 import { parseDuration } from '../auth/duration.js';
 import { Installer } from '../installer/index.js';
-import { readHostConfig, updateHostConfig } from '../installer/config.js';
+import { readHostConfig, updateHostConfig, hostOwnsCadre } from '../installer/config.js';
 import { configPath as resolveConfigPath, defaultDataDir, defaultHostJs, defaultServiceDir, identityPath as resolveIdentityPath, } from '../installer/paths.js';
 import { detectPlatform } from '../installer/platform.js';
 import { createServiceHost } from '../installer/service-host/index.js';
 import { UpdateService } from '../update/index.js';
 import { HostProcessOrchestrator } from '../orchestrator/index.js';
 import { TrustCircleService, TrustCircleStore } from '../auth/index.js';
+import { GrantService, GrantStore, DonationService, DonationStore, DONATION_AWAITING_SEED_TTL_MS, DONATION_REAP_SWEEP_MS, } from '../donation/index.js';
 import { NatService } from '../nat/index.js';
+import { createSecretsStore } from '../nat/secrets/index.js';
+import { resolvePushCredentials, setFcmSecret, setApnsSecret, clearPushSecret, pushStatus, } from '../push/index.js';
+import { OwnerNodeClient } from '../owner/index.js';
 import { createLocalUiServer, HostSettingsStore } from '../server/index.js';
 import { openBrowser } from '../installer/browser.js';
 const DEFAULT_PORT = Number(process.env.CADRE_HOST_PORT ?? '8765');
@@ -36,7 +40,6 @@ function looksLikePeerId(id) {
 function resolvePort(raw) {
     const n = Number(raw);
     if (!Number.isFinite(n) || n <= 0 || n > 65535) {
-        // eslint-disable-next-line no-console
         console.error(`Invalid --port: ${raw}`);
         process.exit(1);
     }
@@ -60,6 +63,7 @@ program
     .option('--no-upnp', 'Disable UPnP/NAT-PMP probing on first run')
     .option('--no-browser', 'Do not open a browser after install')
     .option('--no-invite', 'Skip generating the first enrollment invite')
+    .option('--own-cadre', 'Also run the host\'s own personal cadre here (founder persona; default: donor-only)')
     .option('--system', 'System-wide install (not yet supported in v1)')
     .option('--node-path <path>', 'Override the node binary embedded in the service unit')
     .action(async (opts) => {
@@ -73,16 +77,13 @@ program
             noUpnp: opts.upnp === false,
             openBrowser: opts.browser !== false,
             noInvite: opts.invite === false,
+            ownCadre: opts.ownCadre === true,
             system: Boolean(opts.system),
             ...(opts.nodePath ? { nodePath: opts.nodePath } : {}),
         });
-        // eslint-disable-next-line no-console
         console.log(`cadre-host installed.`);
-        // eslint-disable-next-line no-console
         console.log(`  Data dir:     ${result.dataDir}`);
-        // eslint-disable-next-line no-console
         console.log(`  UI:           ${result.uiUrl}`);
-        // eslint-disable-next-line no-console
         console.log(`  Service:      ${result.serviceName}`);
         if (result.enrollmentInvite) {
             printEnrollmentInvite(result.enrollmentInvite);
@@ -90,7 +91,6 @@ program
         process.exit(0);
     }
     catch (err) {
-        // eslint-disable-next-line no-console
         console.error(`install failed: ${err.message}`);
         process.exit(1);
     }
@@ -129,12 +129,10 @@ program
             removeData: Boolean(opts.removeData),
             ...(opts.dataDir ? { dataDir: opts.dataDir } : {}),
         });
-        // eslint-disable-next-line no-console
         console.log('cadre-host uninstalled.');
         process.exit(0);
     }
     catch (err) {
-        // eslint-disable-next-line no-console
         console.error(`uninstall failed: ${err.message}`);
         process.exit(1);
     }
@@ -149,14 +147,11 @@ program
     const installer = new Installer();
     try {
         const status = await installer.status();
-        // eslint-disable-next-line no-console
         console.log(`Service installed: ${status.installed ? 'yes' : 'no'}`);
-        // eslint-disable-next-line no-console
         console.log(`Service running:   ${status.running ? 'yes' : 'no'}`);
         process.exit(0);
     }
     catch (err) {
-        // eslint-disable-next-line no-console
         console.error(`status failed: ${err.message}`);
         process.exit(1);
     }
@@ -176,7 +171,6 @@ program
         const dataDir = opts.dataDir ?? process.env.CADRE_HOST_DATA_DIR ?? defaultDataDir(platform);
         const cfgPath = resolveConfigPath(dataDir);
         if (!existsSync(cfgPath)) {
-            // eslint-disable-next-line no-console
             console.error(`cadre-host start: ${cfgPath} not found. ` +
                 `Run \`cadre-host install\` first (or pass --data-dir to an existing install).`);
             process.exit(1);
@@ -185,12 +179,10 @@ program
         const cfg = readHostConfig(cfgPath);
         const idPath = resolveIdentityPath(cfg.dataDir);
         if (!existsSync(idPath)) {
-            // eslint-disable-next-line no-console
             console.error(`cadre-host start: identity file not found at ${idPath}. Re-run \`cadre-host install\`.`);
             process.exit(1);
             return;
         }
-        // eslint-disable-next-line no-console
         console.log(`cadre-host starting (dataDir=${cfg.dataDir}, uiPort=${cfg.uiPort})`);
         // Update flow: notify-by-default; auto-apply opt-in via host.config.json.
         // The local-UI ticket (6.5) wires the handlers into HTTP routes; here we
@@ -223,72 +215,163 @@ program
                 updateHostConfig(cfgPath, { updates: next });
             }
             catch (err) {
-                // eslint-disable-next-line no-console
                 console.error(`failed to persist updated settings to ${cfgPath}: ${err.message}`);
             }
         });
         // Don't block startup on the network round-trip — call and forget.
         void updateService.check();
         updateService.start();
-        // Wire the long-lived HTTP management server. The trust-circle and
-        // NAT services depend on a libp2p `CadreNodeLike`; v1 has no node-
-        // spawning path yet (that's a follow-up ticket), so we inject minimal
-        // stubs that fail loudly if a real call is attempted. The /auth/* and
-        // /nat/* routes are still mounted so the CLI's existing HTTP contract
-        // is intact — operations that genuinely need the libp2p node will
-        // surface a NatError / TrustCircleError, mapped to 500 by the server.
-        const orchestrator = new HostProcessOrchestrator({ rootDir: join(cfg.dataDir, 'orchestrator') });
-        await orchestrator.init();
-        const trustCircle = new TrustCircleService({
-            cadreNode: missingCadreNodeStub('trust-circle'),
-            store: new TrustCircleStore(cfg.dataDir),
+        // Wire the long-lived HTTP management server. cadre-host's primary role
+        // is **node donor**: it spawns generic cadre nodes for *other people's*
+        // cadres on request (the donation grant layer below) and never needs an
+        // owner node of its own for that. Running the host's **own** personal
+        // cadre here — the "founder" persona — is opt-in via `ownCadre.enabled`
+        // (see docs/cadre-host.md § Two roles: donor and founder). Only when it
+        // is enabled do we spawn the owner node and bring up trust-circle + NAT.
+        // The manager never joins the control network (docs/cadre-host.md
+        // § Control-plane separation).
+        // Push (FCM/APNs) credentials are resolved fresh on every node spawn so a
+        // restart re-reads the secret store (rotated keys) and nothing raw is
+        // persisted in state.json. The non-secret bits (bundle id / sandbox toggle,
+        // cooldown/debounce) are re-read from host.config.json each call too.
+        const pushSecrets = await createSecretsStore(cfg.dataDir);
+        const orchestrator = new HostProcessOrchestrator({
+            rootDir: join(cfg.dataDir, 'orchestrator'),
+            pushResolver: () => resolvePushCredentials(pushSecrets, readHostConfig(cfgPath).push),
         });
-        const natService = new NatService({
-            rootDir: cfg.dataDir,
-            cadreNode: missingNatNodeStub(),
+        await orchestrator.init();
+        // Donation grant layer — the always-on donor surface. Local-only:
+        // issue/validate/revoke are pure store ops (no node round-trip), so it
+        // needs no owner-node handle. The loopback `/grants-admin` surface is
+        // mounted by createLocalUiServer regardless of the founder persona.
+        const grantService = new GrantService({ store: new GrantStore(cfg.dataDir) });
+        // Donation lifecycle service — consumes a validated grant to actually
+        // spawn a donated node into the requester's cadre. Drives the
+        // grantee-facing `/grants` surface (mounted by createLocalUiServer below).
+        const donationService = new DonationService({
+            orchestrator,
+            grants: grantService,
+            store: new DonationStore(cfg.dataDir),
         });
-        // Best-effort NAT start. Failures here aren't fatal — the local UI
-        // can still serve the trust circle, settings, etc.
-        try {
-            await natService.start();
+        // Reap orphaned donations: a requester that provisioned a node but never
+        // presented a seed leaves an `awaiting_seed` child holding host ports.
+        // Sweep once at startup (for records recovered from disk by
+        // orchestrator.init()), then periodically.
+        const reapStale = () => {
+            void donationService
+                .reapStaleAwaitingSeed(DONATION_AWAITING_SEED_TTL_MS)
+                .catch((err) => console.error(`donation reap failed: ${err.message}`));
+        };
+        reapStale();
+        const reapTimer = setInterval(reapStale, DONATION_REAP_SWEEP_MS);
+        reapTimer.unref();
+        // Founder stack (opt-in). Absent `ownCadre.enabled`, cadre-host is a pure
+        // donor: no owner node, and the /auth + /nat surfaces stay unmounted
+        // (they 404). Per-donated-node WAN reachability is deferred to
+        // backlog/feat-cadre-host-wan-grant-reachability, so v1 donor mode is
+        // loopback-only — nothing for NatService to map without an owner node.
+        let trustCircle;
+        let natService;
+        if (hostOwnsCadre(cfg)) {
+            // Spawn the owner node. Best-effort: a spawn failure leaves the
+            // management API up (trust-circle listing degrades to local labels,
+            // owner ops return 503) rather than taking down the whole process.
+            try {
+                await orchestrator.ensureOwnerNode({
+                    identityPath: idPath,
+                    partyId: cfg.installId,
+                    libp2pPort: cfg.libp2pPort,
+                });
+                console.log('cadre-host: owner node spawned (host-own-cadre enabled)');
+            }
+            catch (err) {
+                console.error(`owner node spawn failed: ${err.message}`);
+            }
+            // The client reads the admin endpoint lazily so a node restart's fresh
+            // bearer token is picked up automatically.
+            const owner = new OwnerNodeClient(() => orchestrator.getOwnerAdminEndpoint());
+            trustCircle = new TrustCircleService({
+                cadreNode: owner,
+                store: new TrustCircleStore(cfg.dataDir),
+            });
+            natService = new NatService({
+                rootDir: cfg.dataDir,
+                cadreNode: owner,
+            });
+            // Push NAT-resolved invite addresses to the node on every NAT change.
+            // NatService.start() also fires this once as an initial push, retried
+            // until the freshly spawned owner node accepts it (bounded; the
+            // management API that mints invites comes up only after start() resolves).
+            natService.onAddressesChanged(async (addresses) => {
+                if (addresses.length === 0)
+                    return;
+                try {
+                    await owner.pushInviteAddresses(addresses);
+                }
+                catch (err) {
+                    console.error(`invite-address push failed: ${err.message}`);
+                }
+            });
+            // Best-effort NAT start. Failures here aren't fatal — the local UI
+            // can still serve the trust circle, settings, etc.
+            try {
+                await natService.start();
+            }
+            catch (err) {
+                console.error(`NAT start failed: ${err.message}`);
+            }
         }
-        catch (err) {
-            // eslint-disable-next-line no-console
-            console.error(`NAT start failed: ${err.message}`);
+        else {
+            // Donor-only. If ownCadre was toggled off after a prior founder run,
+            // orchestrator.init() re-attaches the still-running owner child (it would
+            // otherwise linger in listNodes with no trustCircle/nat wired, serving
+            // the host's own cadre despite being disabled). Reap it now so a disabled
+            // own-cadre is actually stopped — its workdir + control-DB persist on
+            // disk, so toggling ownCadre back on re-spawns it from saved config.
+            try {
+                await orchestrator.stopOwnerNode();
+            }
+            catch (err) {
+                console.error(`owner node reap failed: ${err.message}`);
+            }
+            console.log('cadre-host: node-donor mode (host-own-cadre disabled — no owner node; /auth + /nat inactive)');
         }
         const settingsStore = new HostSettingsStore({ dataDir: cfg.dataDir });
         const server = createLocalUiServer({
             uiPort: cfg.uiPort,
             dataDir: cfg.dataDir,
             orchestrator,
-            trustCircle,
-            nat: natService,
+            ...(trustCircle ? { trustCircle } : {}),
+            ...(natService ? { nat: natService } : {}),
             update: updateService,
+            grants: grantService,
+            donations: donationService,
             settingsStore,
         });
         const { url, port } = await server.start();
         if (port !== cfg.uiPort) {
-            // eslint-disable-next-line no-console
             console.log(`(configured port ${cfg.uiPort} was in use — bound on ${port} instead)`);
         }
-        // eslint-disable-next-line no-console
         console.log(`cadre-host local UI: ${url}`);
         await waitForTermination();
+        clearInterval(reapTimer);
         try {
             await server.stop();
         }
         catch { /* ignore */ }
         try {
-            await natService.stop();
+            await natService?.stop();
+        }
+        catch { /* ignore */ }
+        try {
+            await orchestrator.stopOwnerNode();
         }
         catch { /* ignore */ }
         updateService.stop();
-        // eslint-disable-next-line no-console
         console.log('cadre-host stopped.');
         process.exit(0);
     }
     catch (err) {
-        // eslint-disable-next-line no-console
         console.error(`start failed: ${err.message}`);
         process.exit(1);
     }
@@ -307,30 +390,25 @@ program
         const dataDir = opts.dataDir ?? process.env.CADRE_HOST_DATA_DIR ?? defaultDataDir(platform);
         const cfgPath = resolveConfigPath(dataDir);
         if (!existsSync(cfgPath)) {
-            // eslint-disable-next-line no-console
             console.error(`cadre-host ui: ${cfgPath} not found. Run \`cadre-host install\` first.`);
             process.exit(1);
             return;
         }
         const cfg = readHostConfig(cfgPath);
         const url = `http://127.0.0.1:${cfg.uiPort}`;
-        // eslint-disable-next-line no-console
         console.log(url);
         if (opts.browser !== false) {
             const res = openBrowser(url);
             if (res.spawned) {
-                // eslint-disable-next-line no-console
                 console.log('(Opening in your default browser...)');
             }
             else if (res.error) {
-                // eslint-disable-next-line no-console
                 console.error(`(unable to launch browser: ${res.error})`);
             }
         }
         process.exit(0);
     }
     catch (err) {
-        // eslint-disable-next-line no-console
         console.error(`ui failed: ${err.message}`);
         process.exit(1);
     }
@@ -355,28 +433,6 @@ function readPackageVersionForStart() {
         return '0.0.0-unknown';
     }
 }
-/**
- * Returns a `CadreNodeLike` for TrustCircleService that fails loudly on any
- * libp2p call. cadre-host v1 doesn't yet spawn the host's own cadre node —
- * that ticket is separate. The trust-circle HTTP endpoints still load the
- * local labels/pending file (listing works), but issuing/redeeming an invite
- * requires a real node and surfaces a 500.
- */
-function missingCadreNodeStub(name) {
-    return {
-        async createInvite() { throw new Error(`${name}: cadre-host v1 has no inline cadre node — cannot issue invite`); },
-        async acceptPhone() { throw new Error(`${name}: cadre-host v1 has no inline cadre node — cannot redeem`); },
-        async removePeer() { throw new Error(`${name}: cadre-host v1 has no inline cadre node — cannot remove peer`); },
-        encodeInvite() { throw new Error(`${name}: cadre-host v1 has no inline cadre node — cannot encode invite`); },
-        getControlDatabase() { return null; },
-    };
-}
-function missingNatNodeStub() {
-    return {
-        getPeerId() { return ''; },
-        getMultiaddrs() { return []; },
-    };
-}
 function waitForTermination() {
     return new Promise((resolveTerm) => {
         const done = () => resolveTerm();
@@ -398,26 +454,37 @@ async function confirmDestructive(message) {
 const requireForQr = createRequire(import.meta.url);
 function printEnrollmentInvite(invite) {
     // Best-effort QR render — fall back to the bare token if the lib chokes.
-    // eslint-disable-next-line no-console
     console.log('\nEnroll your first device with this invite:');
     try {
         const qr = requireForQr('qrcode-terminal');
         qr.generate(invite.encodedInvite, { small: true }, (rendered) => {
-            // eslint-disable-next-line no-console
             console.log(rendered);
         });
     }
     catch (err) {
-        // eslint-disable-next-line no-console
         console.error(`(qrcode-terminal unavailable: ${err.message})`);
     }
-    // eslint-disable-next-line no-console
     console.log(`  ${invite.encodedInvite}`);
     if (invite.expiresAt) {
-        // eslint-disable-next-line no-console
         console.log(`  (expires ${invite.expiresAt})`);
     }
 }
+function printGrantToken(token, withQr) {
+    if (withQr) {
+        // Best-effort QR render — fall back to the bare token if the lib chokes.
+        try {
+            const qr = requireForQr('qrcode-terminal');
+            qr.generate(token, { small: true }, (rendered) => {
+                console.error(rendered);
+            });
+        }
+        catch (err) {
+            console.error(`(qrcode-terminal unavailable: ${err.message})`);
+        }
+    }
+    // The token goes to stdout alone so it can be piped/copied; metadata to stderr.
+    console.log(token);
+}
 program
     .command('invite')
     .description('Generate an invite to add a member to the trust circle')
@@ -431,7 +498,6 @@ program
         ttlMs = parseDuration(opts.ttl);
     }
     catch (err) {
-        // eslint-disable-next-line no-console
         console.error(`Invalid --ttl: ${err.message}`);
         process.exit(1);
         return;
@@ -447,7 +513,6 @@ program
         });
     }
     catch (err) {
-        // eslint-disable-next-line no-console
         console.error(`Failed to reach cadre-host at ${url}: ${err.message}\n` +
             `Hint: is cadre-host running? Try \`cadre-host start\`.`);
         process.exit(2);
@@ -455,22 +520,18 @@ program
     }
     if (!response.ok) {
         const text = await response.text().catch(() => '');
-        // eslint-disable-next-line no-console
         console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
         process.exit(1);
         return;
     }
     const body = await response.json();
     if (!body.encodedInvite) {
-        // eslint-disable-next-line no-console
         console.error('cadre-host returned malformed response (missing encodedInvite)');
         process.exit(1);
         return;
     }
-    // eslint-disable-next-line no-console
     console.log(body.encodedInvite);
     if (body.expiresAt) {
-        // eslint-disable-next-line no-console
         console.error(`(expires at ${body.expiresAt})`);
     }
     process.exit(0);
@@ -490,41 +551,33 @@ trust
         response = await fetch(url);
     }
     catch (err) {
-        // eslint-disable-next-line no-console
         console.error(`Failed to reach cadre-host at ${url}: ${err.message}`);
         process.exit(2);
         return;
     }
     if (!response.ok) {
-        // eslint-disable-next-line no-console
         console.error(`cadre-host returned ${response.status}: ${response.statusText}`);
         process.exit(1);
         return;
     }
     const body = await response.json();
-    // eslint-disable-next-line no-console
     console.log('Members:');
     if (body.members.length === 0) {
-        // eslint-disable-next-line no-console
         console.log('  (none)');
     }
     else {
         for (const m of body.members) {
             const self = m.self ? ' [self]' : '';
-            // eslint-disable-next-line no-console
             console.log(`  ${m.peerId}  ${m.label}${self}`);
         }
     }
-    // eslint-disable-next-line no-console
     console.log('\nPending invites:');
     if (body.pending.length === 0) {
-        // eslint-disable-next-line no-console
         console.log('  (none)');
     }
     else {
         for (const p of body.pending) {
             const expires = p.expiresAt ? ` (expires ${p.expiresAt})` : '';
-            // eslint-disable-next-line no-console
             console.log(`  ${p.token}  ${p.label}${expires}`);
         }
     }
@@ -550,23 +603,147 @@ trust
         response = await fetch(`${base}${path}`, { method: 'DELETE' });
     }
     catch (err) {
-        // eslint-disable-next-line no-console
         console.error(`Failed to reach cadre-host at ${base}: ${err.message}`);
         process.exit(2);
         return;
     }
     if (!response.ok) {
         const text = await response.text().catch(() => '');
-        // eslint-disable-next-line no-console
         console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
         process.exit(1);
         return;
     }
-    // eslint-disable-next-line no-console
     console.log(`revoked ${kind}: ${id}`);
     process.exit(0);
 });
 // ============================================================================
+// grant subcommands — donation grant tokens (who may ask this host for a node)
+// ============================================================================
+//
+// A grant token lets one grantee (friend/family) present a Bearer credential to
+// ask this host to donate cadre nodes, up to a per-grantee cap. These commands
+// are thin HTTP clients of the loopback `/grants-admin` admin surface — no
+// bearer (same-machine admin), same posture as `invite` / `trust`. The
+// grantee-facing provisioning surface lands in the donation-service ticket.
+const grant = program
+    .command('grant')
+    .description('Manage donation grant tokens (who may ask this host to donate a node)');
+grant
+    .command('issue')
+    .description('Issue a grant token for one grantee (prints the token + QR)')
+    .argument('<label>', 'Display label for the grantee (e.g. "Alice\'s cadre")')
+    .option('--max-nodes <n>', 'Max concurrently-live donated nodes this grant may hold', parseIntArg)
+    .option('--ttl <duration>', 'Grant lifetime (e.g. 30d, 12h); omit for no expiry')
+    .option('--no-qr', 'Print only the token, no QR code')
+    .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
+    .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
+    .action(async (label, opts) => {
+    const payload = { label };
+    if (typeof opts.maxNodes === 'number')
+        payload.maxNodes = opts.maxNodes;
+    if (opts.ttl) {
+        try {
+            payload.ttlMs = parseDuration(opts.ttl);
+        }
+        catch (err) {
+            console.error(`Invalid --ttl: ${err.message}`);
+            process.exit(1);
+            return;
+        }
+    }
+    const url = `http://${opts.host}:${resolvePort(opts.port)}/grants-admin`;
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch (err) {
+        console.error(`Failed to reach cadre-host at ${url}: ${err.message}\n` +
+            `Hint: is cadre-host running? Try \`cadre-host start\`.`);
+        process.exit(2);
+        return;
+    }
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
+        process.exit(1);
+        return;
+    }
+    const body = await response.json();
+    const issued = body.grant;
+    if (!issued?.token) {
+        console.error('cadre-host returned malformed response (missing grant token)');
+        process.exit(1);
+        return;
+    }
+    printGrantToken(issued.token, opts.qr !== false);
+    console.error(`(maxNodes ${issued.maxNodes ?? '?'}${issued.expiresAt ? `, expires ${issued.expiresAt}` : ', no expiry'})`);
+    process.exit(0);
+});
+grant
+    .command('list')
+    .description('List issued grant tokens')
+    .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
+    .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
+    .action(async (opts) => {
+    const url = `http://${opts.host}:${resolvePort(opts.port)}/grants-admin`;
+    let response;
+    try {
+        response = await fetch(url);
+    }
+    catch (err) {
+        console.error(`Failed to reach cadre-host at ${url}: ${err.message}`);
+        process.exit(2);
+        return;
+    }
+    if (!response.ok) {
+        console.error(`cadre-host returned ${response.status}: ${response.statusText}`);
+        process.exit(1);
+        return;
+    }
+    const body = await response.json();
+    console.log('Grants:');
+    if (body.grants.length === 0) {
+        console.log('  (none)');
+    }
+    else {
+        for (const g of body.grants) {
+            const state = g.revokedAt ? ' [revoked]' : (g.expiresAt ? ` (expires ${g.expiresAt})` : '');
+            console.log(`  ${g.token}  ${g.label}  max=${g.maxNodes}${state}`);
+        }
+    }
+    process.exit(0);
+});
+grant
+    .command('revoke')
+    .description('Revoke a grant token (blocks future requests; live nodes are not torn down)')
+    .argument('<token>', 'Grant token to revoke')
+    .option('--port <port>', 'cadre-host management API port', String(DEFAULT_PORT))
+    .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
+    .action(async (token, opts) => {
+    const base = `http://${opts.host}:${resolvePort(opts.port)}`;
+    let response;
+    try {
+        response = await fetch(`${base}/grants-admin/${encodeURIComponent(token)}`, { method: 'DELETE' });
+    }
+    catch (err) {
+        console.error(`Failed to reach cadre-host at ${base}: ${err.message}`);
+        process.exit(2);
+        return;
+    }
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
+        process.exit(1);
+        return;
+    }
+    console.log(`revoked grant: ${token}`);
+    process.exit(0);
+});
+// ============================================================================
 // nat subcommands
 // ============================================================================
 const nat = program
@@ -582,7 +759,6 @@ nat
     const url = `http://${opts.host}:${resolvePort(opts.port)}/nat/status`;
     const body = await getJson(url);
     if (opts.json) {
-        // eslint-disable-next-line no-console
         console.log(JSON.stringify(body, null, 2));
     }
     else {
@@ -600,7 +776,6 @@ nat
     const url = `http://${opts.host}:${resolvePort(opts.port)}/nat/test`;
     const body = await postJson(url, {});
     if (opts.json) {
-        // eslint-disable-next-line no-console
         console.log(JSON.stringify(body, null, 2));
     }
     else {
@@ -645,7 +820,6 @@ ddns
     .option('--host <host>', 'cadre-host management API host', '127.0.0.1')
     .action(async (provider, opts) => {
     if (!opts.hostname) {
-        // eslint-disable-next-line no-console
         console.error('--hostname is required');
         process.exit(1);
         return;
@@ -655,7 +829,6 @@ ddns
         config.token = opts.token;
     if (!config.token) {
         if (!process.stdin.isTTY) {
-            // eslint-disable-next-line no-console
             console.error('Missing --token for provider "' + provider + '" and stdin is not a TTY. ' +
                 'Re-run with --token <secret>.');
             process.exit(1);
@@ -665,7 +838,6 @@ ddns
             config.token = await readSecretLine('DDNS token: ');
         }
         catch (err) {
-            // eslint-disable-next-line no-console
             console.error('Failed to read token: ' + err.message);
             process.exit(1);
             return;
@@ -699,6 +871,160 @@ ddns
     printNatStatus(body);
     process.exit(0);
 });
+// ============================================================================
+// push subcommands — provision FCM/APNs credentials for strand-wake delivery
+// ============================================================================
+//
+// These operate directly on the data dir's secret store + host.config.json (they
+// do NOT go through the running management API). Private keys land in the OS
+// keychain (keytar) or the 0600 file-store fallback; the non-secret bits (APNs
+// bundle id / sandbox toggle, cooldown/debounce) land in host.config.json. New
+// credentials take effect on the next owner-node (re)spawn — run
+// `cadre-host` restart (or restart the service) to apply them immediately.
+const push = program
+    .command('push')
+    .description('Configure FCM/APNs push credentials for mobile strand-wake delivery');
+push
+    .command('fcm')
+    .description('Store Firebase Cloud Messaging (Android) service-account credentials')
+    .requiredOption('--project-id <id>', 'GCP / Firebase project id')
+    .requiredOption('--client-email <email>', 'Service-account email')
+    .option('--private-key-file <path>', 'Path to the service-account private key (PEM)')
+    .option('--private-key <pem>', 'Inline PEM private key (prefer --private-key-file)')
+    .option('--data-dir <path>', 'Override the data directory (env: CADRE_HOST_DATA_DIR)')
+    .action(async (opts) => {
+    const { dataDir } = resolveHostPaths(opts.dataDir);
+    const privateKey = readPrivateKeyArg(opts.privateKeyFile, opts.privateKey, 'FCM');
+    const secrets = await createSecretsStore(dataDir);
+    await setFcmSecret(secrets, {
+        projectId: opts.projectId,
+        clientEmail: opts.clientEmail,
+        privateKey,
+    });
+    console.log('✓ FCM credentials stored. Restart cadre-host to apply on the owner node.');
+    process.exit(0);
+});
+push
+    .command('apns')
+    .description('Store Apple Push Notification service (iOS) auth-key credentials')
+    .requiredOption('--key-id <id>', 'APNs key id (the .p8 key identifier)')
+    .requiredOption('--team-id <id>', 'Apple developer team id')
+    .requiredOption('--bundle-id <id>', 'App bundle id (becomes the apns-topic)')
+    .option('--private-key-file <path>', 'Path to the .p8 auth key (PEM)')
+    .option('--private-key <pem>', 'Inline .p8 PEM key (prefer --private-key-file)')
+    .option('--production', 'Target the production APNs host (default: sandbox)')
+    .option('--data-dir <path>', 'Override the data directory (env: CADRE_HOST_DATA_DIR)')
+    .action(async (opts) => {
+    const { dataDir, cfgPath } = resolveHostPaths(opts.dataDir);
+    const privateKey = readPrivateKeyArg(opts.privateKeyFile, opts.privateKey, 'APNs');
+    const secrets = await createSecretsStore(dataDir);
+    // Secret bits → secret store; non-secret app-config → host.config.json.
+    await setApnsSecret(secrets, { keyId: opts.keyId, teamId: opts.teamId, privateKey });
+    const current = readHostConfig(cfgPath);
+    updateHostConfig(cfgPath, {
+        push: {
+            ...current.push,
+            apns: { bundleId: opts.bundleId, production: opts.production === true },
+        },
+    });
+    console.log(`✓ APNs credentials stored (${opts.production ? 'production' : 'sandbox'}). ` +
+        `Restart cadre-host to apply on the owner node.`);
+    process.exit(0);
+});
+push
+    .command('options')
+    .description('Set non-secret push tuning (anti-spam cooldown / burst-coalesce window)')
+    .option('--cooldown-ms <ms>', 'Per-(peer,strand) minimum gap between wakes', parseIntArg)
+    .option('--debounce-ms <ms>', 'Per-strand burst-coalescing window', parseIntArg)
+    .option('--data-dir <path>', 'Override the data directory (env: CADRE_HOST_DATA_DIR)')
+    .action((opts) => {
+    const { cfgPath } = resolveHostPaths(opts.dataDir);
+    const current = readHostConfig(cfgPath);
+    const nextPush = { ...current.push };
+    if (typeof opts.cooldownMs === 'number')
+        nextPush.cooldownMs = opts.cooldownMs;
+    if (typeof opts.debounceMs === 'number')
+        nextPush.debounceMs = opts.debounceMs;
+    updateHostConfig(cfgPath, { push: nextPush });
+    console.log('✓ Push options updated.');
+    process.exit(0);
+});
+push
+    .command('clear')
+    .description('Remove stored push credentials')
+    .argument('<target>', 'Which to clear: "fcm", "apns", or "all"')
+    .option('--data-dir <path>', 'Override the data directory (env: CADRE_HOST_DATA_DIR)')
+    .action(async (target, opts) => {
+    if (!['fcm', 'apns', 'all'].includes(target)) {
+        console.error(`push clear: target must be one of fcm | apns | all (got "${target}")`);
+        process.exit(1);
+        return;
+    }
+    const { dataDir, cfgPath } = resolveHostPaths(opts.dataDir);
+    const secrets = await createSecretsStore(dataDir);
+    if (target === 'fcm' || target === 'all')
+        await clearPushSecret(secrets, 'fcm');
+    if (target === 'apns' || target === 'all') {
+        await clearPushSecret(secrets, 'apns');
+        const current = readHostConfig(cfgPath);
+        if (current.push?.apns) {
+            const { apns: _drop, ...rest } = current.push;
+            updateHostConfig(cfgPath, { push: rest });
+        }
+    }
+    console.log(`✓ Cleared push credentials: ${target}. Restart cadre-host to apply.`);
+    process.exit(0);
+});
+push
+    .command('status')
+    .description('Show which push platforms are configured (no secret material)')
+    .option('--data-dir <path>', 'Override the data directory (env: CADRE_HOST_DATA_DIR)')
+    .action(async (opts) => {
+    const { dataDir, cfgPath } = resolveHostPaths(opts.dataDir);
+    const secrets = await createSecretsStore(dataDir);
+    const status = await pushStatus(secrets);
+    const cfg = readHostConfig(cfgPath);
+    console.log('Push credentials:');
+    console.log(`  FCM:  ${status.fcm ? 'configured' : 'not configured'}`);
+    const prod = cfg.push?.apns?.production ? 'production' : 'sandbox';
+    const bundle = cfg.push?.apns?.bundleId ? ` bundle=${cfg.push.apns.bundleId} (${prod})` : '';
+    console.log(`  APNs: ${status.apns ? `configured${bundle}` : 'not configured'}`);
+    if (cfg.push?.cooldownMs !== undefined)
+        console.log(`  cooldownMs: ${cfg.push.cooldownMs}`);
+    if (cfg.push?.debounceMs !== undefined)
+        console.log(`  debounceMs: ${cfg.push.debounceMs}`);
+    process.exit(0);
+});
+/** Resolve the data dir + config path for a direct-on-disk push subcommand. */
+function resolveHostPaths(dataDirOpt) {
+    const platform = detectPlatform();
+    const dataDir = dataDirOpt ?? process.env.CADRE_HOST_DATA_DIR ?? defaultDataDir(platform);
+    const cfgPath = resolveConfigPath(dataDir);
+    if (!existsSync(cfgPath)) {
+        console.error(`${cfgPath} not found. Run \`cadre-host install\` first (or pass --data-dir).`);
+        process.exit(1);
+    }
+    // Resolve the real data dir from the persisted config (handles default-dir installs).
+    const cfg = readHostConfig(cfgPath);
+    return { dataDir: cfg.dataDir, cfgPath };
+}
+/** Read a private key from a file or inline flag; exit with a clear error if neither. */
+function readPrivateKeyArg(file, inline, label) {
+    if (file) {
+        try {
+            return readFileSync(file, 'utf8');
+        }
+        catch (err) {
+            console.error(`Failed to read ${label} private key file ${file}: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    if (inline)
+        return inline;
+    console.error(`${label}: supply --private-key-file <path> (or --private-key <pem>).`);
+    process.exit(1);
+    throw new Error('unreachable');
+}
 async function getJson(url) {
     return await callJson(url, 'GET');
 }
@@ -719,7 +1045,6 @@ async function callJson(url, method, body) {
         response = await fetch(url, init);
     }
     catch (err) {
-        // eslint-disable-next-line no-console
         console.error(`Failed to reach cadre-host at ${url}: ${err.message}\n` +
             `Hint: is cadre-host running? Try \`cadre-host start\`.`);
         process.exit(2);
@@ -727,7 +1052,6 @@ async function callJson(url, method, body) {
     }
     if (!response.ok) {
         const text = await response.text().catch(() => '');
-        // eslint-disable-next-line no-console
         console.error(`cadre-host returned ${response.status}: ${text || response.statusText}`);
         process.exit(1);
         throw new Error('non-ok');
@@ -737,36 +1061,26 @@ async function callJson(url, method, body) {
     return await response.json();
 }
 function printNatStatus(s) {
-    // eslint-disable-next-line no-console
     console.log(`Port mapping: ${s.portMode ?? '?'} (external ${s.externalPort ?? '?'} → internal ${s.internalPort ?? '?'})`);
     if (s.routerExternalIp) {
-        // eslint-disable-next-line no-console
         console.log(`Router IP:    ${s.routerExternalIp}`);
     }
-    // eslint-disable-next-line no-console
     console.log(`External IP:  ${s.externalIp ?? '(unknown)'}${s.cgnatDetected ? '  [CGNAT detected]' : ''}`);
-    // eslint-disable-next-line no-console
     console.log(`Reachability: ${s.directReachability ?? 'unknown'}${s.lastTestedAt ? `  (tested ${s.lastTestedAt})` : ''}`);
     if (s.mappingLeaseExpiresAt) {
-        // eslint-disable-next-line no-console
         console.log(`Lease expires: ${s.mappingLeaseExpiresAt}`);
     }
     const ddns = s.ddns ?? {};
     if (ddns.providerId || ddns.hostname) {
-        // eslint-disable-next-line no-console
         console.log(`\nDDNS:`);
-        // eslint-disable-next-line no-console
         console.log(`  Provider:   ${ddns.providerId ?? '(none)'}${ddns.externallyManaged ? '  [externally managed]' : ''}`);
-        // eslint-disable-next-line no-console
         console.log(`  Hostname:   ${ddns.hostname ?? '(unset)'}`);
         if (ddns.lastUpdateAt) {
             const ok = ddns.lastUpdateOk ? 'OK' : 'FAIL';
-            // eslint-disable-next-line no-console
             console.log(`  Last update: ${ok} at ${ddns.lastUpdateAt}${ddns.lastError ? `  — ${ddns.lastError}` : ''}`);
         }
     }
     else {
-        // eslint-disable-next-line no-console
         console.log('\nDDNS: not configured');
     }
 }
@@ -822,5 +1136,5 @@ function readSecretLine(prompt) {
         stdin.on('data', onData);
     });
 }
-program.parseAsync();
+void program.parseAsync();
 //# sourceMappingURL=host.js.map