@undefineds.co/xpod 0.4.17 → 0.4.19

package/dist/api/background-service-supervisor.d.ts

@@ -1,63 +0,0 @@
-import { getLoggerFor } from 'global-logger-factory';
-/**
- * Keeps a background service alive instead of starting it once (audit N18).
- *
- * `startBackgroundServices()` ran each service exactly once and logged whatever failed, so a
- * tunnel or DDNS client that could not start (offline at boot, provider hiccup) stayed down for
- * the lifetime of the process, and one that died later was never noticed. This supervisor owns
- * that loop: bounded exponential backoff while starting, a periodic liveness check once it is
- * up, and a stop() that really stops (a pending retry must not resurrect it — the same failure
- * mode the process supervisor had).
- */
-export interface BackgroundServiceSupervisorOptions {
-    name: string;
-    /** Starts the service; may throw. Must be safe to call again after a failure. */
-    start: () => Promise<void> | void;
-    /** Stops the service (used by stop()). */
-    stop?: () => Promise<void> | void;
-    /**
-     * Reports whether the service is still up. When provided, the supervisor restarts it after a
-     * liveness check fails; without it, supervision covers startup only.
-     */
-    isRunning?: () => boolean | Promise<boolean>;
-    retryBaseDelayMs?: number;
-    retryMaxDelayMs?: number;
-    checkIntervalMs?: number;
-    now?: () => Date;
-    logger?: Pick<ReturnType<typeof getLoggerFor>, 'info' | 'warn' | 'error'>;
-}
-export interface BackgroundServiceSupervisorStatus {
-    name: string;
-    state: 'idle' | 'starting' | 'running' | 'retrying' | 'stopped';
-    attempts: number;
-    restarts: number;
-    lastError?: string;
-    startedAt?: string;
-    nextRetryInMs?: number;
-}
-export declare class BackgroundServiceSupervisor {
-    private readonly options;
-    private readonly logger;
-    private readonly now;
-    private readonly retryBaseDelayMs;
-    private readonly retryMaxDelayMs;
-    private readonly checkIntervalMs;
-    private timer?;
-    private running;
-    private inFlight;
-    private consecutiveFailures;
-    private restarts;
-    private status;
-    constructor(options: BackgroundServiceSupervisorOptions);
-    /** Starts supervising; repeated calls are a no-op so a restart cannot double the timers. */
-    start(): void;
-    stop(): Promise<void>;
-    getStatus(): BackgroundServiceSupervisorStatus;
-    /** One start-or-check cycle, exposed so an operator action or a test can drive it. */
-    runOnce(): Promise<BackgroundServiceSupervisorStatus>;
-    nextDelayMs(): number;
-    private attempt;
-    private checkAlive;
-    /** Schedules the next cycle from the current state; the loop owns its own timer. */
-    scheduleNext(): void;
-}

package/dist/api/background-service-supervisor.js

@@ -1,144 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.BackgroundServiceSupervisor = void 0;
-const global_logger_factory_1 = require("global-logger-factory");
-const DEFAULT_RETRY_BASE_DELAY_MS = 5_000;
-const DEFAULT_RETRY_MAX_DELAY_MS = 5 * 60_000;
-const DEFAULT_CHECK_INTERVAL_MS = 30_000;
-class BackgroundServiceSupervisor {
-    constructor(options) {
-        this.options = options;
-        this.running = false;
-        this.inFlight = false;
-        this.consecutiveFailures = 0;
-        this.restarts = 0;
-        this.logger = options.logger ?? (0, global_logger_factory_1.getLoggerFor)('BackgroundServiceSupervisor');
-        this.now = options.now ?? (() => new Date());
-        this.retryBaseDelayMs = positive(options.retryBaseDelayMs, DEFAULT_RETRY_BASE_DELAY_MS);
-        this.retryMaxDelayMs = positive(options.retryMaxDelayMs, DEFAULT_RETRY_MAX_DELAY_MS);
-        this.checkIntervalMs = positive(options.checkIntervalMs, DEFAULT_CHECK_INTERVAL_MS);
-        this.status = { name: options.name, state: 'idle', attempts: 0, restarts: 0 };
-    }
-    /** Starts supervising; repeated calls are a no-op so a restart cannot double the timers. */
-    start() {
-        if (this.running) {
-            return;
-        }
-        this.running = true;
-        this.status = { ...this.status, state: 'starting', nextRetryInMs: undefined };
-        // One cycle now, then the loop keeps its own timer.
-        void this.runOnce().then(() => this.scheduleNext());
-    }
-    async stop() {
-        this.running = false;
-        if (this.timer) {
-            clearTimeout(this.timer);
-            this.timer = undefined;
-        }
-        this.status = { ...this.status, state: 'stopped', nextRetryInMs: undefined };
-        try {
-            await this.options.stop?.();
-        }
-        catch (error) {
-            this.logger.warn(`${this.options.name}: stop failed: ${message(error)}`);
-        }
-    }
-    getStatus() {
-        return { ...this.status };
-    }
-    /** One start-or-check cycle, exposed so an operator action or a test can drive it. */
-    async runOnce() {
-        if (this.inFlight) {
-            return this.getStatus();
-        }
-        this.inFlight = true;
-        try {
-            if (this.status.state === 'running') {
-                return await this.checkAlive();
-            }
-            return await this.attempt();
-        }
-        finally {
-            this.inFlight = false;
-        }
-    }
-    nextDelayMs() {
-        if (this.consecutiveFailures === 0) {
-            return this.checkIntervalMs;
-        }
-        const exponent = Math.max(0, this.consecutiveFailures - 1);
-        return Math.min(this.retryBaseDelayMs * 2 ** exponent, this.retryMaxDelayMs);
-    }
-    async attempt() {
-        this.status = { ...this.status, attempts: this.status.attempts + 1 };
-        try {
-            await this.options.start();
-            this.consecutiveFailures = 0;
-            this.status = {
-                ...this.status,
-                state: 'running',
-                lastError: undefined,
-                startedAt: this.now().toISOString(),
-            };
-            this.logger.info(`${this.options.name}: started`);
-            return this.getStatus();
-        }
-        catch (error) {
-            this.consecutiveFailures += 1;
-            const delay = this.nextDelayMs();
-            this.status = {
-                ...this.status,
-                state: 'retrying',
-                lastError: message(error),
-                nextRetryInMs: delay,
-            };
-            this.logger.warn(`${this.options.name}: start failed (attempt ${this.status.attempts}), retrying in ${delay}ms: ${message(error)}`);
-            return this.getStatus();
-        }
-    }
-    async checkAlive() {
-        if (!this.options.isRunning) {
-            return this.getStatus();
-        }
-        let alive;
-        try {
-            alive = await this.options.isRunning();
-        }
-        catch (error) {
-            alive = false;
-            this.logger.warn(`${this.options.name}: liveness check failed: ${message(error)}`);
-        }
-        if (alive) {
-            return this.getStatus();
-        }
-        this.restarts += 1;
-        this.consecutiveFailures = 0;
-        this.status = { ...this.status, restarts: this.restarts };
-        this.logger.warn(`${this.options.name}: not running any more; restarting (restart ${this.restarts})`);
-        // Restart in this cycle rather than waiting for the next check.
-        return await this.attempt();
-    }
-    /** Schedules the next cycle from the current state; the loop owns its own timer. */
-    scheduleNext() {
-        if (!this.running) {
-            return;
-        }
-        const delay = this.status.state === 'running' && this.options.isRunning
-            ? this.checkIntervalMs
-            : this.nextDelayMs();
-        this.status = { ...this.status, nextRetryInMs: delay };
-        this.timer = setTimeout(() => {
-            this.timer = undefined;
-            void this.runOnce().then(() => this.scheduleNext());
-        }, delay);
-        this.timer.unref?.();
-    }
-}
-exports.BackgroundServiceSupervisor = BackgroundServiceSupervisor;
-function message(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-function positive(value, fallback) {
-    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
-}
-//# sourceMappingURL=background-service-supervisor.js.map

package/dist/api/network/EndpointReachabilityProbe.d.ts

@@ -1,40 +0,0 @@
-import { type HeadProbeRequest, type ResolveAddresses } from '../../edge/ProbeTargetGuard';
-/**
- * "Is my public entry actually serving?" — asked on demand, never on a timer (audit N12).
- *
- * The settings page used to answer only "the address is configured". The operator now gets a
- * real measurement, but the probe is deliberately narrow, because it makes the node issue an
- * outbound request to a configured address:
- *
- *   - it only ever runs when the operator asks (the diagnose action), never periodically;
- *   - only `https` targets are accepted: an entry that serves plaintext is a configuration
- *     error, and probing it would put the operator's traffic on the wire unencrypted;
- *   - every resolved address must be public (the same guard the Cloud probe uses), so the
- *     entry cannot bounce the node into loopback, RFC1918, link-local or the metadata
- *     endpoint, and each redirect hop is validated again;
- *   - the connection is pinned to the address that was validated, so a second DNS answer
- *     cannot swap in a private address between check and connect;
- *   - the verdict says "reachable from this node" and nothing more: many networks do not
- *     support NAT hairpin, so a node failing to reach its own public entry is not proof that
- *     remote users cannot, and vice versa.
- */
-export interface EndpointReachabilityProbeOptions {
-    resolveAddresses?: ResolveAddresses;
-    headRequest?: HeadProbeRequest;
-    timeoutMs?: number;
-    maxRedirects?: number;
-    now?: () => Date;
-}
-export type EndpointReachabilityVerdict = 'reachable-from-this-node' | 'unreachable' | 'blocked';
-export interface EndpointReachabilityResult {
-    target: string;
-    verdict: EndpointReachabilityVerdict;
-    /** Present whenever the entry answered at all (including 4xx: the entry is serving). */
-    httpStatus?: number;
-    /** Time from the first request to the final answer, including redirects. */
-    latencyMs?: number;
-    reason?: string;
-    detail: string;
-    checkedAt: string;
-}
-export declare function probeEndpointReachability(endpoint: string, options?: EndpointReachabilityProbeOptions): Promise<EndpointReachabilityResult>;

package/dist/api/network/EndpointReachabilityProbe.js

@@ -1,129 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.probeEndpointReachability = probeEndpointReachability;
-const ProbeTargetGuard_1 = require("../../edge/ProbeTargetGuard");
-const DEFAULT_TIMEOUT_MS = 5_000;
-const DEFAULT_MAX_REDIRECTS = 3;
-async function probeEndpointReachability(endpoint, options = {}) {
-    const now = options.now ?? (() => new Date());
-    const checkedAt = now().toISOString();
-    const timeoutMs = positive(options.timeoutMs, DEFAULT_TIMEOUT_MS);
-    const maxRedirects = Math.max(0, Math.trunc(options.maxRedirects ?? DEFAULT_MAX_REDIRECTS));
-    const resolveAddresses = options.resolveAddresses;
-    const headRequest = options.headRequest ?? (0, ProbeTargetGuard_1.createPinnedHeadProbeRequest)();
-    const startUrl = parseEndpointUrl(endpoint);
-    if (!startUrl) {
-        return {
-            target: endpoint,
-            verdict: 'blocked',
-            reason: 'invalid-url',
-            detail: 'cannot probe: the address is not a usable URL',
-            checkedAt,
-        };
-    }
-    // Plaintext entries are not probed: the point of the check is the entry users reach, and an
-    // operator needs to fix the scheme before anything else is meaningful.
-    if (startUrl.protocol !== 'https:') {
-        return {
-            target: startUrl.toString(),
-            verdict: 'blocked',
-            reason: `insecure-scheme:${startUrl.protocol}`,
-            detail: 'not probed: only https entries are probed',
-            checkedAt,
-        };
-    }
-    const startedAt = Date.now();
-    let url = startUrl;
-    for (let hop = 0; hop <= maxRedirects; hop += 1) {
-        const decision = await (0, ProbeTargetGuard_1.assertPublicProbeTarget)(url, resolveAddresses);
-        if (!decision.allowed) {
-            return {
-                target: startUrl.toString(),
-                verdict: 'blocked',
-                reason: `blocked-target:${decision.reason}`,
-                detail: `not probed: ${decision.reason}（只对公网地址发探测）`,
-                checkedAt,
-            };
-        }
-        let response;
-        try {
-            response = await headRequest(url, { address: decision.address, timeoutMs });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            const timedOut = /timed? ?out|ETIMEDOUT|aborted/iu.test(message);
-            return {
-                target: startUrl.toString(),
-                verdict: 'unreachable',
-                reason: timedOut ? 'timeout' : `connection-error:${message}`,
-                latencyMs: Date.now() - startedAt,
-                detail: timedOut
-                    ? `unreachable from this node: no answer within ${timeoutMs}ms`
-                    : `unreachable from this node: ${message}`,
-                checkedAt,
-            };
-        }
-        if (response.status >= 300 && response.status < 400 && response.location) {
-            const next = safeUrl(response.location, url);
-            if (!next) {
-                return {
-                    target: startUrl.toString(),
-                    verdict: 'unreachable',
-                    reason: 'invalid-redirect',
-                    latencyMs: Date.now() - startedAt,
-                    detail: 'unreachable from this node: the entry redirected to an unusable address',
-                    checkedAt,
-                };
-            }
-            url = next;
-            continue;
-        }
-        const latencyMs = Date.now() - startedAt;
-        return {
-            target: startUrl.toString(),
-            verdict: 'reachable-from-this-node',
-            httpStatus: response.status,
-            latencyMs,
-            detail: `reachable from this node: HTTP ${response.status} in ${latencyMs}ms`
-                + '（网络可能不支持回环，不代表外部用户可达）',
-            checkedAt,
-        };
-    }
-    return {
-        target: startUrl.toString(),
-        verdict: 'unreachable',
-        reason: 'too-many-redirects',
-        latencyMs: Date.now() - startedAt,
-        detail: `unreachable from this node: more than ${maxRedirects} redirects`,
-        checkedAt,
-    };
-}
-function parseEndpointUrl(value) {
-    const trimmed = value.trim();
-    if (!trimmed) {
-        return undefined;
-    }
-    try {
-        return new URL(trimmed);
-    }
-    catch {
-        try {
-            return new URL(`https://${trimmed}`);
-        }
-        catch {
-            return undefined;
-        }
-    }
-}
-function safeUrl(value, base) {
-    try {
-        return new URL(value, base);
-    }
-    catch {
-        return undefined;
-    }
-}
-function positive(value, fallback) {
-    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.trunc(value) : fallback;
-}
-//# sourceMappingURL=EndpointReachabilityProbe.js.map

package/dist/edge/acme/CertificateRenewalScheduler.d.ts

@@ -1,67 +0,0 @@
-import { getLoggerFor } from 'global-logger-factory';
-/**
- * Renews a certificate before it expires, without a human in the loop (audit N15).
- *
- * The runtime could already read a certificate's status and renew on demand, but nothing drove
- * that: a node that stayed up long enough simply served an expired certificate until someone
- * called the admin endpoint. This keeps a single timer that checks the status, renews when the
- * status says it is due, and backs off when renewal fails instead of hammering the CA.
- *
- * It is deliberately provider-agnostic (status reader + renewer) so the ACME manager and the
- * cluster-mode manager can share it, and so tests need no certificates at all.
- */
-export type CertificateRenewalStatus = 'valid' | 'renewal_due' | 'missing' | 'invalid';
-export interface CertificateRenewalState {
-    status: CertificateRenewalStatus;
-    expiresAt?: string;
-}
-export interface CertificateRenewalSchedulerOptions {
-    readStatus: () => Promise<CertificateRenewalState>;
-    renew: () => Promise<void>;
-    /** How often to look when everything is fine. */
-    intervalMs?: number;
-    /** First retry delay after a failed renewal; doubles up to `retryMaxDelayMs`. */
-    retryBaseDelayMs?: number;
-    retryMaxDelayMs?: number;
-    now?: () => Date;
-    logger?: Pick<ReturnType<typeof getLoggerFor>, 'info' | 'warn' | 'error'>;
-}
-export interface CertificateRenewalSchedulerStatus {
-    running: boolean;
-    /** What the last check saw. */
-    lastStatus?: CertificateRenewalStatus;
-    lastCheckedAt?: string;
-    lastRenewedAt?: string;
-    lastError?: string;
-    consecutiveFailures: number;
-    /** Delay before the next check, so a crash loop is visible instead of implied. */
-    nextCheckInMs?: number;
-}
-export declare class CertificateRenewalScheduler {
-    private readonly options;
-    private readonly logger;
-    private readonly now;
-    private readonly intervalMs;
-    private readonly retryBaseDelayMs;
-    private readonly retryMaxDelayMs;
-    private timer?;
-    private running;
-    private inFlight;
-    private consecutiveFailures;
-    private status;
-    constructor(options: CertificateRenewalSchedulerOptions);
-    /** Starts the loop; repeated calls are a no-op, so a restart cannot double the timers. */
-    start(): void;
-    stop(): void;
-    getStatus(): CertificateRenewalSchedulerStatus;
-    /**
-     * One check-and-renew cycle.
-     *
-     * Exposed so an operator action or a test can drive it directly; concurrent calls share the
-     * in-flight run instead of renewing twice.
-     */
-    runOnce(): Promise<CertificateRenewalSchedulerStatus>;
-    /** Delay before the next check: the normal interval, or a growing retry after failures. */
-    nextDelayMs(): number;
-    private schedule;
-}

package/dist/edge/acme/CertificateRenewalScheduler.js

@@ -1,116 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CertificateRenewalScheduler = void 0;
-const global_logger_factory_1 = require("global-logger-factory");
-const DEFAULT_INTERVAL_MS = 6 * 60 * 60 * 1_000;
-const DEFAULT_RETRY_BASE_DELAY_MS = 60 * 1_000;
-const DEFAULT_RETRY_MAX_DELAY_MS = 60 * 60 * 1_000;
-class CertificateRenewalScheduler {
-    constructor(options) {
-        this.options = options;
-        this.running = false;
-        this.inFlight = false;
-        this.consecutiveFailures = 0;
-        this.status = { running: false, consecutiveFailures: 0 };
-        this.logger = options.logger ?? (0, global_logger_factory_1.getLoggerFor)('CertificateRenewalScheduler');
-        this.now = options.now ?? (() => new Date());
-        this.intervalMs = positive(options.intervalMs, DEFAULT_INTERVAL_MS);
-        this.retryBaseDelayMs = positive(options.retryBaseDelayMs, DEFAULT_RETRY_BASE_DELAY_MS);
-        this.retryMaxDelayMs = positive(options.retryMaxDelayMs, DEFAULT_RETRY_MAX_DELAY_MS);
-    }
-    /** Starts the loop; repeated calls are a no-op, so a restart cannot double the timers. */
-    start() {
-        if (this.running) {
-            return;
-        }
-        this.running = true;
-        this.status = { ...this.status, running: true };
-        this.schedule(0);
-    }
-    stop() {
-        this.running = false;
-        if (this.timer) {
-            clearTimeout(this.timer);
-            this.timer = undefined;
-        }
-        this.status = { ...this.status, running: false, nextCheckInMs: undefined };
-    }
-    getStatus() {
-        return { ...this.status };
-    }
-    /**
-     * One check-and-renew cycle.
-     *
-     * Exposed so an operator action or a test can drive it directly; concurrent calls share the
-     * in-flight run instead of renewing twice.
-     */
-    async runOnce() {
-        if (this.inFlight) {
-            return this.getStatus();
-        }
-        this.inFlight = true;
-        try {
-            const current = await this.options.readStatus();
-            this.status = {
-                ...this.status,
-                lastStatus: current.status,
-                lastCheckedAt: this.now().toISOString(),
-            };
-            if (current.status === 'valid') {
-                this.consecutiveFailures = 0;
-                this.status = { ...this.status, consecutiveFailures: 0, lastError: undefined };
-                return this.getStatus();
-            }
-            this.logger.info(`certificate status is ${current.status}; renewing`);
-            await this.options.renew();
-            this.consecutiveFailures = 0;
-            this.status = {
-                ...this.status,
-                consecutiveFailures: 0,
-                lastError: undefined,
-                lastRenewedAt: this.now().toISOString(),
-            };
-            this.logger.info('certificate renewed');
-            return this.getStatus();
-        }
-        catch (error) {
-            this.consecutiveFailures += 1;
-            const message = error instanceof Error ? error.message : String(error);
-            this.status = {
-                ...this.status,
-                consecutiveFailures: this.consecutiveFailures,
-                lastError: message,
-            };
-            this.logger.error(`certificate renewal failed (attempt ${this.consecutiveFailures}): ${message}`);
-            return this.getStatus();
-        }
-        finally {
-            this.inFlight = false;
-        }
-    }
-    /** Delay before the next check: the normal interval, or a growing retry after failures. */
-    nextDelayMs() {
-        if (this.consecutiveFailures === 0) {
-            return this.intervalMs;
-        }
-        const exponent = Math.max(0, this.consecutiveFailures - 1);
-        return Math.min(this.retryBaseDelayMs * 2 ** exponent, this.retryMaxDelayMs);
-    }
-    schedule(delayMs) {
-        if (!this.running) {
-            return;
-        }
-        this.status = { ...this.status, nextCheckInMs: delayMs };
-        this.timer = setTimeout(() => {
-            this.timer = undefined;
-            void this.runOnce().then(() => this.schedule(this.nextDelayMs()));
-        }, delayMs);
-        // A renewal timer must not keep the process alive on its own.
-        this.timer.unref?.();
-    }
-}
-exports.CertificateRenewalScheduler = CertificateRenewalScheduler;
-function positive(value, fallback) {
-    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
-}
-//# sourceMappingURL=CertificateRenewalScheduler.js.map

package/dist/edge/reachability/P2PDataPlaneCrypto.d.ts

@@ -1,42 +0,0 @@
-/**
- * Authenticated encryption for the raw TCP data plane (audit N03).
- *
- * The data plane used to be plaintext JSON over a hole-punched TCP socket: anyone who could
- * reach the port could read, forge or replay Pod traffic, and the node could not tell which
- * session a connection belonged to. Both sides now share a per-session secret that travels
- * only over the authenticated signaling API, derive direction-separated keys from it, and seal
- * every frame with AES-256-GCM — so a peer without the secret cannot produce a frame the other
- * side accepts, and a frame cannot be replayed into a different session or direction.
- */
-export declare const P2P_DATA_PLANE_KEY_BYTES = 32;
-export declare const P2P_DATA_PLANE_NONCE_BYTES = 12;
-/** Distinct from protocol errors so callers can close the connection instead of retrying. */
-export declare class P2PDataPlaneSecurityError extends Error {
-    constructor(message: string);
-}
-export type P2PDataPlaneDirection = 'client-to-server' | 'server-to-client';
-export interface P2PDataPlaneKeys {
-    clientToServer: Buffer;
-    serverToClient: Buffer;
-}
-/** A fresh per-session secret, base64 so it can travel inside the session record. */
-export declare function createDataPlaneSecret(): string;
-/** Decode a session secret, rejecting anything that is not exactly one key long. */
-export declare function decodeDataPlaneSecret(value: string): Buffer;
-export declare function createDataPlaneNonce(): Buffer;
-/**
- * Direction-separated keys.
- *
- * Both nonces and the session id go into the derivation, so a frame sealed for one session (or
- * for one direction inside it) cannot be replayed into another.
- */
-export declare function deriveDataPlaneKeys(secret: Buffer, sessionId: string, clientNonce: Buffer, serverNonce: Buffer): P2PDataPlaneKeys;
-export declare function keyForDirection(keys: P2PDataPlaneKeys, direction: P2PDataPlaneDirection): Buffer;
-export interface SealedDataPlaneFrame {
-    /** Monotonic per direction: the receiver refuses anything but the next value, so replays fail. */
-    sequence: number;
-    nonce: string;
-    ciphertext: string;
-}
-export declare function sealDataPlaneFrame(key: Buffer, sessionId: string, direction: P2PDataPlaneDirection, sequence: number, plaintext: Buffer): SealedDataPlaneFrame;
-export declare function openDataPlaneFrame(key: Buffer, sessionId: string, direction: P2PDataPlaneDirection, sealed: SealedDataPlaneFrame, expectedSequence: number): Buffer;