@serfab/cadre-host 0.7.1 → 0.9.0

package/dist/orchestrator/types.d.ts

@@ -2,6 +2,7 @@
  * Public + internal types for the HostProcessOrchestrator.
  */
 import type { ChildProcess } from 'node:child_process';
+import type { PushCredentials } from '@serfab/cadre-core';
 /** User-facing configuration for `HostProcessOrchestrator`. */
 export interface HostProcessConfig {
     /** Root directory under which per-container workdirs live. */
@@ -28,6 +29,29 @@ export interface HostProcessConfig {
     spawn?: {
         entrypoint?: string;
     };
+    /**
+     * Resolver for the platform push credentials (FCM/APNs) to inject into a
+     * spawned strand-participating node's `cadre.json` (`config.push`). Called
+     * fresh on EVERY spawn/re-spawn so the secret store stays the source of truth
+     * and no raw private key is ever persisted in `state.json`. Returns `undefined`
+     * when no push credentials are configured (the default — push is opt-in). The
+     * resolver itself is responsible for rejecting a partial credential set.
+     */
+    pushResolver?: PushCredentialsResolver;
+}
+/**
+ * Resolves the push credentials to inject into a node being spawned. Re-invoked
+ * per spawn so a restart re-reads the secret store rather than replaying stale
+ * (or persisted) material. See {@link HostProcessConfig.pushResolver}.
+ */
+export type PushCredentialsResolver = () => Promise<PushCredentials | undefined>;
+/** Per-child allocated ports. `admin` carries the loopback admin channel (6.6). */
+export interface NodePorts {
+    health: number;
+    metrics: number;
+    p2p: number;
+    /** Loopback admin-channel port. Bound only by the owner node. */
+    admin: number;
 }
 /** In-memory record per managed child. */
 export interface Handle {
@@ -36,14 +60,12 @@ export interface Handle {
     pid: number;
     startupToken: string;
     workdir: string;
-    ports: {
-        health: number;
-        metrics: number;
-        p2p: number;
-    };
+    ports: NodePorts;
     spawnedAt: string;
     partyId: string;
     profile: 'storage' | 'transaction';
+    /** True for the admin's owner node (binds the admin channel). */
+    owner?: boolean;
     /** Live ChildProcess reference; absent after re-attach via init(). */
     child?: ChildProcess;
     /** Marked false when init() finds the PID dead or token mismatched. */
@@ -61,11 +83,24 @@ export interface ManagedNodeInfo {
     status: 'running' | 'stopped';
     spawnedAt: string;
     workdir: string;
-    ports: {
-        health: number;
-        metrics: number;
-        p2p: number;
-    };
+    ports: NodePorts;
+    /** True for the admin's owner node. */
+    owner?: boolean;
+}
+/**
+ * Persisted spawn parameters for the admin's owner node. Stored alongside
+ * the handles so an orchestrator restart can re-spawn the owner node from
+ * `/api/nodes/:id/{start,restart}` without the caller re-supplying them.
+ */
+export interface OwnerSpawnConfig {
+    /** Absolute path to the host's libp2p protobuf identity (`identity.key`). */
+    identityPath: string;
+    /** Control-network partyId (the host's installId). */
+    partyId: string;
+    /** External libp2p port — mapped to the child's listen address. */
+    libp2pPort: number;
+    /** Node profile. Defaults to `storage` (the household node holds strands). */
+    profile?: 'storage' | 'transaction';
 }
 /**
  * Listener invoked when a managed node's lifecycle state changes

package/dist/orchestrator/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/orchestrator/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgEH,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,KAAa;IACvD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,GAAG,GAAG,GAAG,eAAe,GAAG,KAAK,EAAE,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IACxC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AACxB,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/orchestrator/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AA8GH,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,KAAa;IACvD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,GAAG,GAAG,GAAG,eAAe,GAAG,KAAK,EAAE,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IACxC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AACxB,CAAC"}

package/dist/owner/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Owner-node delegation surface for cadre-host.
+ *
+ * The manager process spawns the admin's owner cadre node (via
+ * `HostProcessOrchestrator`) and delegates owner/membership/identity
+ * operations to it over the loopback admin channel using
+ * {@link OwnerNodeClient}. See `docs/cadre-host.md` § Control-plane
+ * separation.
+ */
+export { OwnerNodeClient, OwnerNodeUnavailableError } from './owner-node-client.js';
+export type { OwnerNodeClientOptions } from './owner-node-client.js';

package/dist/owner/index.js

@@ -0,0 +1,11 @@
+/**
+ * Owner-node delegation surface for cadre-host.
+ *
+ * The manager process spawns the admin's owner cadre node (via
+ * `HostProcessOrchestrator`) and delegates owner/membership/identity
+ * operations to it over the loopback admin channel using
+ * {@link OwnerNodeClient}. See `docs/cadre-host.md` § Control-plane
+ * separation.
+ */
+export { OwnerNodeClient, OwnerNodeUnavailableError } from './owner-node-client.js';
+//# sourceMappingURL=index.js.map

package/dist/owner/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/owner/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/owner/owner-node-client.d.ts

@@ -0,0 +1,95 @@
+/**
+ * HTTP client for the owner node's loopback admin channel (the 6.6
+ * `cadre-node-admin-channel` contract).
+ *
+ * cadre-host's manager process holds no in-process `CadreNode`; it spawns the
+ * admin's owner node as a managed child (see `HostProcessOrchestrator`)
+ * and delegates all owner/membership/identity operations to it over this
+ * client. The client implements **both** trimmed `CadreNodeLike` interfaces —
+ * the trust-circle one (`auth/trust-circle.ts`) and the NAT one
+ * (`nat/nat-service.ts`) — plus `pushInviteAddresses` and `addDrone` (the
+ * node-donation requester side).
+ *
+ * Transport: `Authorization: Bearer <token>` against
+ * `http://127.0.0.1:<adminPort>`. Every response uses the cadre-provider
+ * envelope `{ ok: true, data }` / `{ ok: false, error: { code, message } }`.
+ * A refused connection, a transport error, or any non-2xx response surfaces
+ * as {@link OwnerNodeUnavailableError}; the trust-circle / NAT services
+ * translate that into a `node_unavailable` domain error so the management API
+ * returns a clear 503 rather than a raw 500.
+ */
+import type { CadreInvite, DroneInitResult } from '@serfab/cadre-core';
+import type { OwnerAdminEndpoint } from '../orchestrator/index.js';
+import type { CadreNodeLike as TrustCircleCadreNodeLike } from '../auth/trust-circle.js';
+import type { CadreNodeLike as NatCadreNodeLike } from '../nat/nat-service.js';
+/**
+ * Raised when the owner node's admin channel can't be reached or returns
+ * a non-success response. Carries the node's stable error `code` when one was
+ * present in the envelope (e.g. `not_ready`, `not_authorized`).
+ */
+export declare class OwnerNodeUnavailableError extends Error {
+    /** The admin-channel error code, when the node answered with an envelope. */
+    readonly nodeCode?: string;
+    constructor(message: string, nodeCode?: string);
+}
+/** Endpoint provided directly or via a getter (so it tracks re-spawns). */
+type EndpointSource = OwnerAdminEndpoint | (() => OwnerAdminEndpoint | undefined) | undefined;
+export interface OwnerNodeClientOptions {
+    /** Fetch override for tests. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+export declare class OwnerNodeClient implements TrustCircleCadreNodeLike, NatCadreNodeLike {
+    private readonly endpointSource;
+    private readonly fetchImpl;
+    /**
+     * @param endpoint Either a fixed `{ baseUrl, token }` or a getter returning
+     *   the current endpoint (pass `orchestrator.getOwnerAdminEndpoint`
+     *   bound, so a restart's new bearer token is picked up automatically).
+     */
+    constructor(endpoint: EndpointSource, opts?: OwnerNodeClientOptions);
+    createInvite(token?: string, expiresInMs?: number): Promise<{
+        invite: CadreInvite;
+        encodedInvite: string;
+    }>;
+    acceptPhone(options: {
+        phonePeerId: string;
+        token?: string;
+    }, issuedInvite?: CadreInvite): Promise<void>;
+    removePeer(peerId: string): Promise<void>;
+    /**
+     * Encode an invite for out-of-band delivery. The admin contract has no
+     * encode route (the mint route already returns `encodedInvite`), so this
+     * mirrors cadre-core's encoding (`base64url(JSON.stringify(invite))`).
+     */
+    encodeInvite(invite: CadreInvite): string;
+    listMembers(): Promise<Array<{
+        peerId: string;
+        multiaddr: string | null;
+    }>>;
+    isMember(peerId: string): Promise<boolean>;
+    /** Authorized-membership surface (excludes self) — see {@link listMembers} for the addressable one. */
+    listAuthorizedMembers(): Promise<Array<{
+        peerId: string;
+        multiaddr: string | null;
+    }>>;
+    isAuthorizedMember(peerId: string): Promise<boolean>;
+    getPeerId(): Promise<string>;
+    getMultiaddrs(): Promise<string[]>;
+    /**
+     * Mint a seed authorizing a drone — a provider-hosted / donated node — to join
+     * this node's cadre. The node signs the seed with its own authority key; only
+     * the signed, public `encodedSeed` is returned (the private key never leaves
+     * the node). This is the requester ("phone") side of the node-donation flow:
+     * the donor host presents the returned seed to the donated node's `POST /seed`.
+     */
+    addDrone(options: {
+        dronePeerId: string;
+        droneMultiaddrs: string[];
+    }): Promise<DroneInitResult>;
+    /** Push the NAT-resolved addresses the node should embed in future invites. */
+    pushInviteAddresses(addresses: string[]): Promise<void>;
+    private resolveEndpoint;
+    private request;
+    private parseEnvelope;
+}
+export {};

package/dist/owner/owner-node-client.js

@@ -0,0 +1,167 @@
+/**
+ * HTTP client for the owner node's loopback admin channel (the 6.6
+ * `cadre-node-admin-channel` contract).
+ *
+ * cadre-host's manager process holds no in-process `CadreNode`; it spawns the
+ * admin's owner node as a managed child (see `HostProcessOrchestrator`)
+ * and delegates all owner/membership/identity operations to it over this
+ * client. The client implements **both** trimmed `CadreNodeLike` interfaces —
+ * the trust-circle one (`auth/trust-circle.ts`) and the NAT one
+ * (`nat/nat-service.ts`) — plus `pushInviteAddresses` and `addDrone` (the
+ * node-donation requester side).
+ *
+ * Transport: `Authorization: Bearer <token>` against
+ * `http://127.0.0.1:<adminPort>`. Every response uses the cadre-provider
+ * envelope `{ ok: true, data }` / `{ ok: false, error: { code, message } }`.
+ * A refused connection, a transport error, or any non-2xx response surfaces
+ * as {@link OwnerNodeUnavailableError}; the trust-circle / NAT services
+ * translate that into a `node_unavailable` domain error so the management API
+ * returns a clear 503 rather than a raw 500.
+ */
+import debug from 'debug';
+const log = debug('cadre:host:owner-client');
+/**
+ * Raised when the owner node's admin channel can't be reached or returns
+ * a non-success response. Carries the node's stable error `code` when one was
+ * present in the envelope (e.g. `not_ready`, `not_authorized`).
+ */
+export class OwnerNodeUnavailableError extends Error {
+    constructor(message, nodeCode) {
+        super(message);
+        this.name = 'OwnerNodeUnavailableError';
+        if (nodeCode !== undefined)
+            this.nodeCode = nodeCode;
+    }
+}
+export class OwnerNodeClient {
+    /**
+     * @param endpoint Either a fixed `{ baseUrl, token }` or a getter returning
+     *   the current endpoint (pass `orchestrator.getOwnerAdminEndpoint`
+     *   bound, so a restart's new bearer token is picked up automatically).
+     */
+    constructor(endpoint, opts = {}) {
+        this.endpointSource = endpoint;
+        this.fetchImpl = opts.fetch ?? fetch;
+    }
+    // --- trust-circle CadreNodeLike ---
+    async createInvite(token, expiresInMs) {
+        const body = {};
+        if (token !== undefined)
+            body.token = token;
+        if (expiresInMs !== undefined)
+            body.expiresInMs = expiresInMs;
+        return await this.request('POST', '/admin/invites', body);
+    }
+    async acceptPhone(options, issuedInvite) {
+        const body = { phonePeerId: options.phonePeerId };
+        if (options.token !== undefined)
+            body.token = options.token;
+        if (issuedInvite !== undefined)
+            body.issuedInvite = issuedInvite;
+        await this.request('POST', '/admin/accept-phone', body);
+    }
+    async removePeer(peerId) {
+        await this.request('DELETE', `/admin/members/${encodeURIComponent(peerId)}`);
+    }
+    /**
+     * Encode an invite for out-of-band delivery. The admin contract has no
+     * encode route (the mint route already returns `encodedInvite`), so this
+     * mirrors cadre-core's encoding (`base64url(JSON.stringify(invite))`).
+     */
+    encodeInvite(invite) {
+        return Buffer.from(JSON.stringify(invite), 'utf8').toString('base64url');
+    }
+    async listMembers() {
+        const data = await this.request('GET', '/admin/members');
+        return data.members;
+    }
+    async isMember(peerId) {
+        const data = await this.request('GET', `/admin/members/${encodeURIComponent(peerId)}`);
+        return data.member;
+    }
+    /** Authorized-membership surface (excludes self) — see {@link listMembers} for the addressable one. */
+    async listAuthorizedMembers() {
+        const data = await this.request('GET', '/admin/authorized-members');
+        return data.members;
+    }
+    async isAuthorizedMember(peerId) {
+        const data = await this.request('GET', `/admin/authorized-members/${encodeURIComponent(peerId)}`);
+        return data.member;
+    }
+    // --- NAT CadreNodeLike ---
+    async getPeerId() {
+        const data = await this.request('GET', '/admin/identity');
+        return data.peerId ?? '';
+    }
+    async getMultiaddrs() {
+        const data = await this.request('GET', '/admin/multiaddrs');
+        return data.multiaddrs;
+    }
+    // --- drone seeding (node-donation requester side) ---
+    /**
+     * Mint a seed authorizing a drone — a provider-hosted / donated node — to join
+     * this node's cadre. The node signs the seed with its own authority key; only
+     * the signed, public `encodedSeed` is returned (the private key never leaves
+     * the node). This is the requester ("phone") side of the node-donation flow:
+     * the donor host presents the returned seed to the donated node's `POST /seed`.
+     */
+    async addDrone(options) {
+        return await this.request('POST', '/admin/add-drone', {
+            dronePeerId: options.dronePeerId,
+            droneMultiaddrs: options.droneMultiaddrs,
+        });
+    }
+    // --- push-model invite addresses ---
+    /** Push the NAT-resolved addresses the node should embed in future invites. */
+    async pushInviteAddresses(addresses) {
+        await this.request('PUT', '/admin/invite-addresses', { addresses });
+    }
+    // --- internals ---
+    resolveEndpoint() {
+        const ep = typeof this.endpointSource === 'function' ? this.endpointSource() : this.endpointSource;
+        if (!ep) {
+            throw new OwnerNodeUnavailableError('Owner node admin endpoint is not available');
+        }
+        return ep;
+    }
+    async request(method, path, body) {
+        const ep = this.resolveEndpoint();
+        const headers = { authorization: `Bearer ${ep.token}` };
+        const init = { method, headers };
+        if (body !== undefined) {
+            headers['content-type'] = 'application/json';
+            init.body = JSON.stringify(body);
+        }
+        let res;
+        try {
+            res = await this.fetchImpl(`${ep.baseUrl}${path}`, init);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log('admin %s %s transport error: %s', method, path, message);
+            throw new OwnerNodeUnavailableError(`Owner node unreachable: ${message}`);
+        }
+        const envelope = await this.parseEnvelope(res);
+        if (!res.ok || !envelope.ok) {
+            const code = envelope.error?.code;
+            const message = envelope.error?.message ?? `admin ${method} ${path} → HTTP ${res.status}`;
+            log('admin %s %s failed: [%s] %s', method, path, code ?? res.status, message);
+            throw new OwnerNodeUnavailableError(message, code);
+        }
+        return envelope.data;
+    }
+    async parseEnvelope(res) {
+        try {
+            const parsed = await res.json();
+            if (parsed && typeof parsed === 'object') {
+                return parsed;
+            }
+        }
+        catch {
+            // Non-JSON body — fall through to an empty envelope; status drives the
+            // ok/non-ok decision in the caller.
+        }
+        return {};
+    }
+}
+//# sourceMappingURL=owner-node-client.js.map

package/dist/owner/owner-node-client.js.map

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

package/dist/push/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Push (FCM/APNs) credential storage + resolution for cadre-host.
+ *
+ * The platform-push secrets a self-hosted deployment provisions live in the host
+ * secret store (keytar with file-store fallback — the same store DDNS tokens use);
+ * the non-secret app-config bits (APNs bundle id / sandbox toggle, cooldown /
+ * debounce) live in `host.config.json` (`PushSettings`). At node-spawn time the
+ * orchestrator's `pushResolver` calls {@link resolvePushCredentials}, which reads
+ * BOTH and merges them into the `PushCredentials` block written into the spawned
+ * node's `cadre.json`.
+ *
+ * Secret hygiene: the FCM service-account fields and the APNs `.p8` key are stored
+ * ONLY in the secret store, never in `host.config.json` and never in `state.json`.
+ * They are re-read on every spawn so a restart picks up rotated keys, and the
+ * resolver redacts on any log line. A partial credential set (a present platform
+ * missing required fields) is rejected — fail fast, not at first push.
+ */
+import type { PushCredentials } from '@serfab/cadre-core';
+import type { SecretsStore } from '../nat/secrets/index.js';
+import type { PushSettings } from '../installer/config.js';
+/** Push platform whose secret bundle lives in the secret store. */
+export type PushSecretPlatform = 'fcm' | 'apns';
+/** Build the secret-store account key for a platform's credential bundle. */
+export declare function pushAccount(platform: PushSecretPlatform): string;
+/** FCM secret bundle persisted in the secret store (the whole set is sensitive). */
+export interface FcmSecret {
+    projectId: string;
+    clientEmail: string;
+    /** Service-account RSA private key, PEM. */
+    privateKey: string;
+}
+/**
+ * APNs secret bundle persisted in the secret store. `bundleId` / `production` are
+ * NOT here — they are non-secret app-config in {@link PushSettings}.
+ */
+export interface ApnsSecret {
+    keyId: string;
+    teamId: string;
+    /** `.p8` ES256 private key, PEM. */
+    privateKey: string;
+}
+/** Store (or replace) the FCM service-account secret bundle. */
+export declare function setFcmSecret(secrets: SecretsStore, secret: FcmSecret): Promise<void>;
+/** Store (or replace) the APNs auth-key secret bundle. */
+export declare function setApnsSecret(secrets: SecretsStore, secret: ApnsSecret): Promise<void>;
+/** Remove a platform's secret bundle. Returns true if one was present. */
+export declare function clearPushSecret(secrets: SecretsStore, platform: PushSecretPlatform): Promise<boolean>;
+/**
+ * Resolve the full {@link PushCredentials} block to inject into a spawned node,
+ * merging the secret-store bundles with the non-secret {@link PushSettings}.
+ *
+ * Returns `undefined` when NO platform is configured (push is opt-in — the node
+ * then constructs no fan-out). Throws when a configured platform is incomplete
+ * (e.g. APNs secret present but `bundleId` unset), so a misconfig surfaces at the
+ * spawn boundary rather than silently at first push.
+ */
+export declare function resolvePushCredentials(secrets: SecretsStore, settings: PushSettings | undefined): Promise<PushCredentials | undefined>;
+/**
+ * A description of which push platforms are configured, for the `push status` CLI
+ * and any UI — derived without exposing any secret material.
+ */
+export interface PushStatus {
+    fcm: boolean;
+    apns: boolean;
+}
+/** Report which platforms have a stored secret bundle (no secret material). */
+export declare function pushStatus(secrets: SecretsStore): Promise<PushStatus>;

package/dist/push/index.js

@@ -0,0 +1,101 @@
+/**
+ * Push (FCM/APNs) credential storage + resolution for cadre-host.
+ *
+ * The platform-push secrets a self-hosted deployment provisions live in the host
+ * secret store (keytar with file-store fallback — the same store DDNS tokens use);
+ * the non-secret app-config bits (APNs bundle id / sandbox toggle, cooldown /
+ * debounce) live in `host.config.json` (`PushSettings`). At node-spawn time the
+ * orchestrator's `pushResolver` calls {@link resolvePushCredentials}, which reads
+ * BOTH and merges them into the `PushCredentials` block written into the spawned
+ * node's `cadre.json`.
+ *
+ * Secret hygiene: the FCM service-account fields and the APNs `.p8` key are stored
+ * ONLY in the secret store, never in `host.config.json` and never in `state.json`.
+ * They are re-read on every spawn so a restart picks up rotated keys, and the
+ * resolver redacts on any log line. A partial credential set (a present platform
+ * missing required fields) is rejected — fail fast, not at first push.
+ */
+import debug from 'debug';
+import { validatePushCredentials } from '@serfab/cadre-core';
+const log = debug('cadre:host:push');
+/** Build the secret-store account key for a platform's credential bundle. */
+export function pushAccount(platform) {
+    return `push:${platform}`;
+}
+/** Store (or replace) the FCM service-account secret bundle. */
+export async function setFcmSecret(secrets, secret) {
+    await secrets.set(pushAccount('fcm'), JSON.stringify(secret));
+}
+/** Store (or replace) the APNs auth-key secret bundle. */
+export async function setApnsSecret(secrets, secret) {
+    await secrets.set(pushAccount('apns'), JSON.stringify(secret));
+}
+/** Remove a platform's secret bundle. Returns true if one was present. */
+export async function clearPushSecret(secrets, platform) {
+    return secrets.delete(pushAccount(platform));
+}
+/** Read a platform's stored secret bundle, or null when unset. */
+async function readSecret(secrets, platform) {
+    const raw = await secrets.get(pushAccount(platform));
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Stored ${platform} push secret is not valid JSON: ${err.message}`, { cause: err });
+    }
+}
+/**
+ * Resolve the full {@link PushCredentials} block to inject into a spawned node,
+ * merging the secret-store bundles with the non-secret {@link PushSettings}.
+ *
+ * Returns `undefined` when NO platform is configured (push is opt-in — the node
+ * then constructs no fan-out). Throws when a configured platform is incomplete
+ * (e.g. APNs secret present but `bundleId` unset), so a misconfig surfaces at the
+ * spawn boundary rather than silently at first push.
+ */
+export async function resolvePushCredentials(secrets, settings) {
+    const fcmSecret = await readSecret(secrets, 'fcm');
+    const apnsSecret = await readSecret(secrets, 'apns');
+    if (!fcmSecret && !apnsSecret)
+        return undefined;
+    const push = {};
+    if (fcmSecret) {
+        const fcm = {
+            projectId: fcmSecret.projectId,
+            clientEmail: fcmSecret.clientEmail,
+            privateKey: fcmSecret.privateKey,
+        };
+        push.fcm = fcm;
+    }
+    if (apnsSecret) {
+        const apns = {
+            keyId: apnsSecret.keyId,
+            teamId: apnsSecret.teamId,
+            bundleId: settings?.apns?.bundleId ?? '',
+            privateKey: apnsSecret.privateKey,
+            ...(settings?.apns?.production !== undefined ? { production: settings.apns.production } : {}),
+        };
+        push.apns = apns;
+    }
+    if (settings?.cooldownMs !== undefined)
+        push.cooldownMs = settings.cooldownMs;
+    if (settings?.debounceMs !== undefined)
+        push.debounceMs = settings.debounceMs;
+    const errors = validatePushCredentials(push);
+    if (errors.length > 0) {
+        throw new Error(`Invalid push credentials: ${errors.join('; ')}`);
+    }
+    log('resolved push credentials (fcm=%s apns=%s)', !!push.fcm, !!push.apns);
+    return push;
+}
+/** Report which platforms have a stored secret bundle (no secret material). */
+export async function pushStatus(secrets) {
+    const accounts = await secrets.list();
+    return {
+        fcm: accounts.includes(pushAccount('fcm')),
+        apns: accounts.includes(pushAccount('apns')),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/push/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/push/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAK7D,MAAM,GAAG,GAAG,KAAK,CAAC,iBAAiB,CAAC,CAAC;AAKrC,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAC,QAA4B;IACtD,OAAO,QAAQ,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAqBD,gEAAgE;AAChE,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAqB,EAAE,MAAiB;IACzE,MAAM,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAqB,EAAE,MAAkB;IAC3E,MAAM,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,0EAA0E;AAC1E,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAqB,EAAE,QAA4B;IACvF,OAAO,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,kEAAkE;AAClE,KAAK,UAAU,UAAU,CAAI,OAAqB,EAAE,QAA4B;IAC9E,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC;IACrD,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,UAAU,QAAQ,mCAAoC,GAAa,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACjH,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAqB,EACrB,QAAkC;IAElC,MAAM,SAAS,GAAG,MAAM,UAAU,CAAY,OAAO,EAAE,KAAK,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,MAAM,UAAU,CAAa,OAAO,EAAE,MAAM,CAAC,CAAC;IAEjE,IAAI,CAAC,SAAS,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAC;IAEhD,MAAM,IAAI,GAAoB,EAAE,CAAC;IACjC,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,GAAG,GAAmB;YAC1B,SAAS,EAAE,SAAS,CAAC,SAAS;YAC9B,WAAW,EAAE,SAAS,CAAC,WAAW;YAClC,UAAU,EAAE,SAAS,CAAC,UAAU;SACjC,CAAC;QACF,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IACD,IAAI,UAAU,EAAE,CAAC;QACf,MAAM,IAAI,GAAoB;YAC5B,KAAK,EAAE,UAAU,CAAC,KAAK;YACvB,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,IAAI,EAAE;YACxC,UAAU,EAAE,UAAU,CAAC,UAAU;YACjC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IACD,IAAI,QAAQ,EAAE,UAAU,KAAK,SAAS;QAAE,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;IAC9E,IAAI,QAAQ,EAAE,UAAU,KAAK,SAAS;QAAE,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;IAE9E,MAAM,MAAM,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,6BAA6B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,GAAG,CAAC,4CAA4C,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3E,OAAO,IAAI,CAAC;AACd,CAAC;AAWD,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAqB;IACpD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;IACtC,OAAO;QACL,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;KAC7C,CAAC;AACJ,CAAC"}

package/dist/server/error-handler.d.ts

@@ -7,6 +7,7 @@
  *       invalid_label, invalid_token             → 400
  *       not_found, already_redeemed              → 404
  *       expired                                  → 410
+ *       node_unavailable                         → 503
  *       storage_error                            → 500
  *   - NatError
  *       invalid_config, ddns_provider_unknown,
@@ -14,12 +15,28 @@
  *       secrets_unavailable, storage_error,
  *       mapping_failed, router_unreachable,
  *       ip_detection_failed, ddns_update_failed  → 500
+ *       node_unavailable                         → 503
  *   - UpdateErrorException
  *       manifest_invalid, no_update_available,
  *       min_previous_version                     → 400
  *       apply_in_progress                        → 409
  *       signature_invalid, unsupported_state_version,
  *       apply_failed, rollback_failed, storage_error → 500
+ *   - GrantError
+ *       invalid_label, invalid_max_nodes,
+ *       invalid_ttl                              → 400
+ *       not_found                                → 404
+ *       storage_error                            → 500
+ *   - DonationError
+ *       invalid_request                          → 400
+ *       unauthorized                             → 401
+ *       forbidden                                → 403
+ *       not_found                                → 404
+ *       invalid_state                            → 409
+ *       quota_exceeded                           → 429
+ *       orchestrator_error, storage_error        → 500
+ *       seed_failed                              → 502
+ *       peer_unavailable                         → 503
  *   - everything else                            → 500 (code "internal")
  */
 import type { FastifyInstance } from 'fastify';