@undefineds.co/xpod 0.4.15 → 0.4.16

package/dist/api/auth/ClientCredentialsAuthenticator.js

@@ -1,11 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClientCredentialsAuthenticator = void 0;
-const node_crypto_1 = require("node:crypto");
-const solid_client_authn_core_1 = require("@inrupt/solid-client-authn-core");
 const global_logger_factory_1 = require("global-logger-factory");
-const TokenEndpointRoute_1 = require("./TokenEndpointRoute");
-const TokenIdentity_1 = require("./TokenIdentity");
+const SolidSessionFactory_1 = require("./SolidSessionFactory");
 /**
  * Authenticator for CSS client credentials wrapped in sk-xxx transport format.
  *
@@ -20,11 +17,7 @@ const TokenIdentity_1 = require("./TokenIdentity");
 class ClientCredentialsAuthenticator {
     constructor(options) {
         this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
-        this.tokenCache = options.tokenCache;
-        const route = (0, TokenEndpointRoute_1.resolveTokenEndpointRoute)(options.tokenEndpoint, options.publicBaseUrl);
-        this.tokenEndpoint = route.url;
-        this.tokenEndpointHeaders = route.headers;
-        this.tokenEndpointProofUrl = route.proofUrl;
+        this.sessions = options.sessions;
     }
     canAuthenticate(request) {
         const auth = request.headers.authorization;
@@ -79,51 +72,34 @@ class ClientCredentialsAuthenticator {
                 // Non sk- format is intentionally unsupported; Xpod does not keep an API key mirror table.
                 return { success: false, error: 'Invalid client credentials wrapper: must start with sk-' };
             }
-            const credentialKey = (0, node_crypto_1.createHash)('sha256')
-                .update(JSON.stringify([this.tokenEndpoint, this.tokenEndpointProofUrl, clientId, clientSecret]))
-                .digest('hex');
-            // A client ID alone is public identification, not authentication evidence.
-            if (this.tokenCache) {
-                const cached = await this.tokenCache.get(credentialKey);
-                if (cached && cached.expiresAt > new Date()) {
-                    this.logger.debug(`Using cached token for ${clientId.slice(0, 8)}...`);
-                    return {
-                        success: true,
-                        context: {
-                            type: 'solid',
-                            webId: cached.webId,
-                            accountId: cached.webId,
-                            clientId,
-                            clientSecret,
-                            accessToken: cached.token,
-                            tokenType: cached.tokenType ?? 'Bearer',
-                            viaApiKey: true,
-                        },
-                    };
-                }
+            // One exchange per credential: the factory keeps the token together with the DPoP key it
+            // is bound to, so outbound Pod access reuses this session instead of exchanging again.
+            let session;
+            try {
+                session = await this.sessions.session({ clientId, clientSecret });
             }
-            // Exchange for token at CSS endpoint
-            this.logger.debug(`Exchanging client credentials at ${this.tokenEndpoint}`);
-            const tokenResult = await this.exchangeForToken(clientId, clientSecret);
-            this.logger.debug(`Token exchange result: success=${tokenResult.success}, webId=${tokenResult.webId}, error=${tokenResult.error}`);
-            if (!tokenResult.success || !tokenResult.webId || !tokenResult.token) {
-                return { success: false, error: tokenResult.error || 'Token exchange failed' };
+            catch (error) {
+                const status = error instanceof SolidSessionFactory_1.SolidSessionError ? error.status : undefined;
+                const unavailable = status === undefined || status >= 500;
+                this.logger.warn(`Client credentials exchange failed for ${clientId.slice(0, 8)}...: ${String(error)}`);
+                return unavailable
+                    ? { success: false, error: 'Token exchange temporarily unavailable', category: 'service_unavailable', statusCode: 503, cause: error }
+                    : { success: false, error: `Token exchange failed: ${status ?? 'unknown'}`, cause: error };
             }
-            // Cache the token
-            if (this.tokenCache && tokenResult.expiresAt) {
-                await this.tokenCache.set(credentialKey, tokenResult.token, tokenResult.webId, tokenResult.expiresAt, tokenResult.tokenType);
+            if (!session.webId) {
+                return { success: false, error: 'Could not determine webId from token response' };
             }
             const context = {
                 type: 'solid',
-                webId: tokenResult.webId,
-                accountId: tokenResult.webId,
+                webId: session.webId,
+                accountId: session.webId,
                 clientId,
                 clientSecret,
-                accessToken: tokenResult.token,
-                tokenType: tokenResult.tokenType ?? 'Bearer',
+                accessToken: session.accessToken,
+                tokenType: session.tokenType,
                 viaApiKey: true,
             };
-            this.logger.debug(`Authenticated client credentials for webId: ${tokenResult.webId}`);
+            this.logger.debug(`Authenticated client credentials for webId: ${session.webId}`);
             return { success: true, context };
         }
         catch (error) {
@@ -131,50 +107,6 @@ class ClientCredentialsAuthenticator {
             return { success: false, error: 'Authentication failed' };
         }
     }
-    async exchangeForToken(clientId, clientSecret) {
-        try {
-            const dpopKey = await (0, solid_client_authn_core_1.generateDpopKeyPair)();
-            const response = await fetch(this.tokenEndpoint, {
-                method: 'POST',
-                headers: {
-                    Accept: 'application/json',
-                    'Content-Type': 'application/x-www-form-urlencoded',
-                    Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`, 'utf8').toString('base64')}`,
-                    DPoP: await (0, solid_client_authn_core_1.createDpopHeader)(this.tokenEndpointProofUrl, 'POST', dpopKey),
-                    ...this.tokenEndpointHeaders,
-                },
-                body: new URLSearchParams({
-                    grant_type: 'client_credentials',
-                    scope: 'webid',
-                }),
-            });
-            if (!response.ok) {
-                const error = await response.text();
-                this.logger.warn(`Token exchange failed: ${response.status} ${error}`);
-                return { success: false, error: `Token exchange failed: ${response.status}` };
-            }
-            const data = await response.json();
-            // Extract webId from token response or decode from JWT
-            const webId = (0, TokenIdentity_1.extractAuthoritativeWebIdFromTokenResponse)(data);
-            if (!webId) {
-                return { success: false, error: 'Could not determine webId from token response' };
-            }
-            const expiresAt = data.expires_in
-                ? new Date(Date.now() + data.expires_in * 1000 - 60000) // 1 min buffer
-                : new Date(Date.now() + 3600000); // Default 1 hour
-            return {
-                success: true,
-                token: data.access_token,
-                tokenType: data.token_type?.toUpperCase() === 'DPOP' ? 'DPoP' : 'Bearer',
-                webId,
-                expiresAt,
-            };
-        }
-        catch (error) {
-            this.logger.error(`Token exchange error: ${error}`);
-            return { success: false, error: 'Token exchange failed' };
-        }
-    }
 }
 exports.ClientCredentialsAuthenticator = ClientCredentialsAuthenticator;
 //# sourceMappingURL=ClientCredentialsAuthenticator.js.map

package/dist/api/auth/SolidSessionFactory.d.ts

@@ -0,0 +1,81 @@
+import { type KeyPair } from '@inrupt/solid-client-authn-core';
+/** The caller's own CSS client credentials, in the clear, for the length of one call. */
+export interface SolidClientCredential {
+    clientId: string;
+    clientSecret: string;
+    /**
+     * The credential's version, when the caller tracks rotation. It is part of the cache
+     * identity, so a rotated secret never reuses the previous session.
+     */
+    version?: string;
+}
+/**
+ * One exchanged credential: the token, the key it is bound to, and when it stops being usable.
+ *
+ * The key is kept because a DPoP token is only usable by whoever can prove possession: a caller
+ * that discards the key holds a token it cannot spend on the Pod.
+ */
+export interface SolidSession {
+    accessToken: string;
+    tokenType: 'Bearer' | 'DPoP';
+    dpopKey?: KeyPair;
+    expiresAt: number;
+    /** WebID the issuer bound this credential to, when it reports one. */
+    webId?: string;
+}
+export interface SolidSessionFactoryOptions {
+    /** Token endpoint of the Solid interface that issues these credentials. */
+    tokenEndpoint: string;
+    /** Canonical base URL of that interface, used to keep the DPoP proof canonical. */
+    publicBaseUrl?: string;
+    fetch?: typeof fetch;
+    now?: () => number;
+    /** Upper bound on remembered sessions; the oldest is dropped first. */
+    maxEntries?: number;
+}
+/**
+ * Exchanges CSS client credentials for Solid tokens, once per credential.
+ *
+ * Inbound authentication and outbound Pod access share this cache, so one request that arrives
+ * with an `sk-` wrapper and then reads the Pod performs a single token exchange and keeps the
+ * key the token is bound to. Cache identity is the issuer, the complete credential and its
+ * version - never just the owner or the client id, which are public identification rather than
+ * authentication evidence.
+ */
+export declare class SolidSessionFactory {
+    private readonly logger;
+    private readonly route;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly maxEntries;
+    private readonly sessions;
+    /** Cache keys per client id, so a revoked credential can be forgotten without its secret. */
+    private readonly keysByClientId;
+    private readonly clientIdByKey;
+    constructor(options: SolidSessionFactoryOptions);
+    /** A usable session for this credential, exchanging it when the cached one is spent. */
+    session(credential: SolidClientCredential): Promise<SolidSession>;
+    /**
+     * Forget every cached session for one client.
+     *
+     * Revocation happens at the issuer, which this process cannot observe, so the record that
+     * represents the credential has to say so: without this an already-issued token keeps
+     * authenticating the wrapper until it expires, and a deleted API Key looks like it still works.
+     */
+    invalidateClientCredential(clientId: string): void;
+    private remember;
+    /** Drop one cache entry and its client-id index, whichever path removed it. */
+    private forgetKey;
+    /**
+     * Forget a credential's session, because the Pod or the issuer stopped accepting it.
+     *
+     * The caller retries with a fresh exchange rather than a different identity: a rejected token
+     * says nothing about who the caller is.
+     */
+    invalidate(credential: SolidClientCredential): void;
+    private exchange;
+}
+export declare class SolidSessionError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}

package/dist/api/auth/SolidSessionFactory.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SolidSessionError = exports.SolidSessionFactory = void 0;
+const node_crypto_1 = require("node:crypto");
+const solid_client_authn_core_1 = require("@inrupt/solid-client-authn-core");
+const global_logger_factory_1 = require("global-logger-factory");
+const TokenEndpointRoute_1 = require("./TokenEndpointRoute");
+const TokenIdentity_1 = require("./TokenIdentity");
+const TOKEN_EXPIRY_SKEW_MS = 30_000;
+const DEFAULT_TOKEN_LIFETIME_SECONDS = 300;
+const DEFAULT_MAX_ENTRIES = 256;
+/**
+ * Exchanges CSS client credentials for Solid tokens, once per credential.
+ *
+ * Inbound authentication and outbound Pod access share this cache, so one request that arrives
+ * with an `sk-` wrapper and then reads the Pod performs a single token exchange and keeps the
+ * key the token is bound to. Cache identity is the issuer, the complete credential and its
+ * version - never just the owner or the client id, which are public identification rather than
+ * authentication evidence.
+ */
+class SolidSessionFactory {
+    constructor(options) {
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.sessions = new Map();
+        /** Cache keys per client id, so a revoked credential can be forgotten without its secret. */
+        this.keysByClientId = new Map();
+        this.clientIdByKey = new Map();
+        this.route = (0, TokenEndpointRoute_1.resolveTokenEndpointRoute)(options.tokenEndpoint, options.publicBaseUrl);
+        this.fetchImpl = options.fetch ?? fetch;
+        this.now = options.now ?? Date.now;
+        this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    }
+    /** A usable session for this credential, exchanging it when the cached one is spent. */
+    async session(credential) {
+        const key = cacheKey(this.route, credential);
+        const cached = this.sessions.get(key);
+        if (cached && cached.expiresAt > this.now() + TOKEN_EXPIRY_SKEW_MS) {
+            return cached;
+        }
+        this.forgetKey(key);
+        const session = await this.exchange(credential);
+        this.remember(key, credential.clientId, session);
+        return session;
+    }
+    /**
+     * Forget every cached session for one client.
+     *
+     * Revocation happens at the issuer, which this process cannot observe, so the record that
+     * represents the credential has to say so: without this an already-issued token keeps
+     * authenticating the wrapper until it expires, and a deleted API Key looks like it still works.
+     */
+    invalidateClientCredential(clientId) {
+        const keys = this.keysByClientId.get(clientId);
+        if (!keys) {
+            return;
+        }
+        for (const key of keys) {
+            this.sessions.delete(key);
+            this.clientIdByKey.delete(key);
+        }
+        this.keysByClientId.delete(clientId);
+    }
+    remember(key, clientId, session) {
+        this.sessions.set(key, session);
+        const keys = this.keysByClientId.get(clientId) ?? new Set();
+        keys.add(key);
+        this.keysByClientId.set(clientId, keys);
+        this.clientIdByKey.set(key, clientId);
+        pruneOldest(this.sessions, this.maxEntries, (evicted) => this.forgetKey(evicted));
+    }
+    /** Drop one cache entry and its client-id index, whichever path removed it. */
+    forgetKey(key) {
+        this.sessions.delete(key);
+        const clientId = this.clientIdByKey.get(key);
+        if (!clientId) {
+            return;
+        }
+        this.clientIdByKey.delete(key);
+        const tracked = this.keysByClientId.get(clientId);
+        if (!tracked) {
+            return;
+        }
+        tracked.delete(key);
+        if (tracked.size === 0) {
+            this.keysByClientId.delete(clientId);
+        }
+    }
+    /**
+     * Forget a credential's session, because the Pod or the issuer stopped accepting it.
+     *
+     * The caller retries with a fresh exchange rather than a different identity: a rejected token
+     * says nothing about who the caller is.
+     */
+    invalidate(credential) {
+        this.forgetKey(cacheKey(this.route, credential));
+    }
+    async exchange(credential) {
+        const dpopKey = await (0, solid_client_authn_core_1.generateDpopKeyPair)();
+        const response = await this.fetchImpl(this.route.url, {
+            method: 'POST',
+            headers: {
+                accept: 'application/json',
+                'content-type': 'application/x-www-form-urlencoded',
+                authorization: `Basic ${Buffer.from(`${credential.clientId}:${credential.clientSecret}`, 'utf8').toString('base64')}`,
+                DPoP: await (0, solid_client_authn_core_1.createDpopHeader)(this.route.proofUrl, 'POST', dpopKey),
+                ...this.route.headers,
+            },
+            body: new URLSearchParams({ grant_type: 'client_credentials', scope: 'webid' }),
+        });
+        const body = await response.text().catch(() => '');
+        if (!response.ok) {
+            this.logger.warn(`Solid client credential refused for ${credential.clientId.slice(0, 8)}...: ${response.status}`);
+            throw new SolidSessionError(`token_exchange_failed:${response.status}`, response.status);
+        }
+        const parsed = parseTokenResponse(body);
+        if (!parsed) {
+            this.logger.warn(`Solid client credential exchange returned no access token for ${credential.clientId.slice(0, 8)}...`);
+            throw new SolidSessionError('token_exchange_invalid_response');
+        }
+        const webId = (0, TokenIdentity_1.extractAuthoritativeWebIdFromTokenResponse)(parsed.raw);
+        return {
+            accessToken: parsed.accessToken,
+            tokenType: parsed.dpopBound ? 'DPoP' : 'Bearer',
+            ...(parsed.dpopBound ? { dpopKey } : {}),
+            expiresAt: this.now() + parsed.expiresInSeconds * 1000,
+            ...(webId ? { webId } : {}),
+        };
+    }
+}
+exports.SolidSessionFactory = SolidSessionFactory;
+class SolidSessionError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.name = 'SolidSessionError';
+        this.status = status;
+    }
+}
+exports.SolidSessionError = SolidSessionError;
+function cacheKey(route, credential) {
+    // The secret never appears in the key, and the key never leaves this object.
+    return [
+        route.url,
+        route.proofUrl,
+        credential.clientId,
+        credential.version ?? '',
+        fingerprintSecret(credential.clientSecret),
+    ].join('\u0000');
+}
+/** A stable, non-reversible fingerprint: two different secrets must never share a session. */
+function fingerprintSecret(secret) {
+    return (0, node_crypto_1.createHash)('sha256').update(secret).digest('hex');
+}
+function pruneOldest(cache, limit, onEvict) {
+    while (cache.size > limit) {
+        const oldest = cache.keys().next();
+        if (oldest.done)
+            return;
+        cache.delete(oldest.value);
+        onEvict?.(oldest.value);
+    }
+}
+function parseTokenResponse(body) {
+    let raw;
+    try {
+        raw = JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+    const accessToken = typeof raw.access_token === 'string' ? raw.access_token : undefined;
+    if (!accessToken) {
+        return undefined;
+    }
+    const expiresIn = typeof raw.expires_in === 'number' && raw.expires_in > 0
+        ? raw.expires_in
+        : DEFAULT_TOKEN_LIFETIME_SECONDS;
+    return {
+        accessToken,
+        dpopBound: String(raw.token_type ?? 'DPoP').toUpperCase() !== 'BEARER',
+        expiresInSeconds: expiresIn,
+        raw,
+    };
+}
+//# sourceMappingURL=SolidSessionFactory.js.map

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

@@ -0,0 +1,63 @@
+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

@@ -0,0 +1,144 @@
+"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/chatkit/pod-store.d.ts

@@ -47,6 +47,10 @@ export declare class PodChatKitStore implements ChatKitStore<StoreContext>, RunS
     }): Promise<StoreContext>;
     /**
      * 获取认证后的 drizzle 实例 (缓存到 context 中)
+     *
+     * The Pod holds the only copy of this data, so a caller without a usable Pod credential is
+     * told why instead of being handed an empty result: a chat screen that answers "no threads"
+     * for a Pod it could not open reports a state the user cannot act on.
      */
     private getDb;
     /**