@undefineds.co/xpod 0.4.14 → 0.4.16

package/dist/api/handlers/TaskCredentialHandler.d.ts

@@ -0,0 +1,19 @@
+import type { ApiServer } from '../ApiServer';
+import type { AuthResult } from '../auth/Authenticator';
+import { type TaskCredentialStore } from '../tasks/TaskCredentialStore';
+export interface TaskCredentialHandlerOptions {
+    /** The task layer's own credential store; absent when the deployment has no root key. */
+    taskCredentials?: TaskCredentialStore;
+    /** Reuses the configured CSS authenticator; never trusts the claimed owner. */
+    validateClientCredential?: (apiKey: string) => Promise<AuthResult>;
+    /** Issuer the granted credential belongs to; part of the grant identity. */
+    clientCredentialIssuer?: string;
+    jsonBodyLimitBytes?: number;
+}
+/**
+ * Grants the task layer may use while nobody is present.
+ *
+ * The store is the task layer's, so this surface only ever exposes metadata: no endpoint returns a
+ * secret, and every route resolves the grant from the caller's own WebID.
+ */
+export declare function registerTaskCredentialRoutes(server: ApiServer, options: TaskCredentialHandlerOptions): void;

package/dist/api/handlers/TaskCredentialHandler.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTaskCredentialRoutes = registerTaskCredentialRoutes;
+const TaskCredentialStore_1 = require("../tasks/TaskCredentialStore");
+/**
+ * Grants the task layer may use while nobody is present.
+ *
+ * The store is the task layer's, so this surface only ever exposes metadata: no endpoint returns a
+ * secret, and every route resolves the grant from the caller's own WebID.
+ */
+function registerTaskCredentialRoutes(server, options) {
+    const requireOwner = (request, response) => {
+        const auth = request.auth;
+        if (!auth || auth.type !== 'solid' || !auth.webId) {
+            sendJson(response, 401, { error: 'Authentication required' });
+            return undefined;
+        }
+        return auth.webId;
+    };
+    /**
+     * The user's explicit grant: a credential the task layer may use while nobody is present.
+     *
+     * It takes the same `sk-` wrapper registration does, because that wrapper is the user's own
+     * credential; the difference is what is stored - a task-layer grant, not an API-side copy.
+     */
+    server.post('/api/ai/task-credentials', async (request, response) => {
+        const owner = requireOwner(request, response);
+        if (!owner)
+            return;
+        if (!options.taskCredentials) {
+            sendJson(response, 503, { error: 'task_credential_storage_unconfigured' });
+            return;
+        }
+        if (!options.validateClientCredential || !options.clientCredentialIssuer) {
+            sendJson(response, 503, { error: 'task_credential_grant_unavailable' });
+            return;
+        }
+        const body = await readJsonObject(request, response, options.jsonBodyLimitBytes ?? 64 * 1024);
+        if (!body)
+            return;
+        const apiKey = typeof body.apiKey === 'string' ? body.apiKey : '';
+        if (!validClientCredentialWrapper(apiKey)) {
+            sendJson(response, 400, { error: 'A CSS client credential wrapper is required' });
+            return;
+        }
+        const verified = await options.validateClientCredential(apiKey);
+        if (!verified.success || verified.context?.type !== 'solid') {
+            sendJson(response, verified.category === 'service_unavailable' ? 503 : 401, {
+                error: 'CSS client credential verification failed',
+            });
+            return;
+        }
+        if (verified.context.webId !== owner) {
+            sendJson(response, 403, { error: 'CSS client credential belongs to another WebID' });
+            return;
+        }
+        if (!verified.context.clientId || !verified.context.clientSecret) {
+            sendJson(response, 400, { error: 'CSS client credential is incomplete' });
+            return;
+        }
+        try {
+            // The user granted it just now, so it is active immediately; a program that needs the user
+            // to confirm later creates a pending grant instead.
+            const credential = await options.taskCredentials.grant({
+                ownerWebId: owner,
+                issuer: options.clientCredentialIssuer,
+                clientId: verified.context.clientId,
+                clientSecret: verified.context.clientSecret,
+                status: 'active',
+            });
+            sendJson(response, 201, { credential });
+        }
+        catch (error) {
+            sendTaskCredentialError(response, error);
+        }
+    });
+    server.get('/api/ai/task-credentials', async (request, response) => {
+        const owner = requireOwner(request, response);
+        if (!owner)
+            return;
+        if (!options.taskCredentials) {
+            sendJson(response, 503, { error: 'task_credential_storage_unconfigured' });
+            return;
+        }
+        const data = await options.taskCredentials.listForOwner(owner);
+        sendJson(response, 200, { data });
+    });
+    server.post('/api/ai/task-credentials/:credentialRef/activate', async (request, response, params) => {
+        const owner = requireOwner(request, response);
+        if (!owner)
+            return;
+        if (!options.taskCredentials) {
+            sendJson(response, 503, { error: 'task_credential_storage_unconfigured' });
+            return;
+        }
+        const credentialRef = params.credentialRef;
+        if (!await isOwnedBy(options.taskCredentials, credentialRef, owner)) {
+            sendJson(response, 404, { error: TaskCredentialStore_1.TASK_CREDENTIAL_NOT_FOUND });
+            return;
+        }
+        try {
+            const activated = await options.taskCredentials.activate(credentialRef);
+            sendJson(response, 200, { credential: activated });
+        }
+        catch (error) {
+            sendTaskCredentialError(response, error);
+        }
+    });
+    server.delete('/api/ai/task-credentials/:credentialRef', async (request, response, params) => {
+        const owner = requireOwner(request, response);
+        if (!owner)
+            return;
+        if (!options.taskCredentials) {
+            sendJson(response, 503, { error: 'task_credential_storage_unconfigured' });
+            return;
+        }
+        const credentialRef = params.credentialRef;
+        if (!await isOwnedBy(options.taskCredentials, credentialRef, owner)) {
+            sendJson(response, 404, { error: TaskCredentialStore_1.TASK_CREDENTIAL_NOT_FOUND });
+            return;
+        }
+        try {
+            await options.taskCredentials.revoke(credentialRef);
+            sendJson(response, 200, { revoked: credentialRef });
+        }
+        catch (error) {
+            sendTaskCredentialError(response, error);
+        }
+    });
+}
+/** Resolve a grant only when it belongs to the caller; another owner's reference looks absent. */
+async function isOwnedBy(store, credentialRef, ownerWebId) {
+    const grants = await store.listForOwner(ownerWebId);
+    return grants.some((grant) => grant.credentialRef === credentialRef);
+}
+function sendTaskCredentialError(response, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith(TaskCredentialStore_1.TASK_CREDENTIAL_NOT_FOUND)) {
+        sendJson(response, 404, { error: TaskCredentialStore_1.TASK_CREDENTIAL_NOT_FOUND });
+        return;
+    }
+    if (message.startsWith(TaskCredentialStore_1.TASK_CREDENTIAL_NOT_ACTIVE)) {
+        sendJson(response, 409, { error: TaskCredentialStore_1.TASK_CREDENTIAL_NOT_ACTIVE });
+        return;
+    }
+    if (message.startsWith(TaskCredentialStore_1.TASK_CREDENTIAL_VERSION_CONFLICT)) {
+        sendJson(response, 409, { error: TaskCredentialStore_1.TASK_CREDENTIAL_VERSION_CONFLICT });
+        return;
+    }
+    if (message.startsWith(TaskCredentialStore_1.TASK_CREDENTIAL_OWNER_MISMATCH)) {
+        sendJson(response, 403, { error: TaskCredentialStore_1.TASK_CREDENTIAL_OWNER_MISMATCH });
+        return;
+    }
+    sendJson(response, 500, { error: 'task_credential_operation_failed' });
+}
+function sendJson(response, status, data) {
+    response.statusCode = status;
+    response.setHeader('Content-Type', 'application/json');
+    response.end(JSON.stringify(data));
+}
+function validClientCredentialWrapper(value) {
+    if (!value.startsWith('sk-'))
+        return false;
+    const encoded = value.slice(3);
+    const decoded = Buffer.from(encoded, 'base64').toString('utf8');
+    return Buffer.from(decoded, 'utf8').toString('base64') === encoded
+        && /^[^\s\x00-\x1f\x7f:]+:[^\s\x00-\x1f\x7f]+$/u.test(decoded);
+}
+async function readJsonObject(request, response, limitBytes) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        size += buffer.byteLength;
+        if (size > limitBytes) {
+            sendJson(response, 413, { error: 'Request body is too large' });
+            return undefined;
+        }
+        chunks.push(buffer);
+    }
+    if (size === 0) {
+        sendJson(response, 400, { error: 'Request body is required' });
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            sendJson(response, 400, { error: 'Request body must be a JSON object' });
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        sendJson(response, 400, { error: 'Request body must be valid JSON' });
+        return undefined;
+    }
+}
+//# sourceMappingURL=TaskCredentialHandler.js.map

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

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

@@ -0,0 +1,129 @@
+"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/api/runtime.d.ts

@@ -17,6 +17,8 @@ export interface ApiServiceHandle {
     inngestRuntimeConfig?: EmbeddedInngestRuntimeConfig;
     stop: () => Promise<void>;
 }
+/** One source of truth for the Cloud identity: the local edition's default issuer. */
+export declare const OFFICIAL_CLOUD_IDENTITY_ORIGIN: string;
 export declare function autoProvisionFirstRunLocal(config: ApiContainerConfig, logger: ReturnType<typeof getLoggerFor>): Promise<ApiContainerConfig>;
 /**
  * Port a managed tunnel forwards to.
@@ -26,5 +28,14 @@ export declare function autoProvisionFirstRunLocal(config: ApiContainerConfig, l
  * would let forwarded remote requests inherit local trust. Falls back to the
  * historical gateway port only when no ingress listener was provisioned.
  */
+/**
+ * The port a remote tunnel forwards to: the Gateway's tunnel entry.
+ *
+ * The runtime records the listener it actually bound in `XPOD_GATEWAY_INGRESS_PORT`, and the
+ * Gateway's own port is only the fallback for an embedding that started no tunnel entry. The
+ * gate is structural - anything arriving on that listener is remote whatever it claims - so a
+ * tunnel pointed at the Gateway port by mistake still has the forwarding-header check behind
+ * it rather than inheriting local trust.
+ */
 export declare function resolveTunnelIngressPort(env?: NodeJS.ProcessEnv): number;
 export declare function startApiService(options?: StartApiServiceOptions): Promise<ApiServiceHandle>;

package/dist/api/runtime.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OFFICIAL_CLOUD_IDENTITY_ORIGIN = void 0;
 exports.autoProvisionFirstRunLocal = autoProvisionFirstRunLocal;
 exports.resolveTunnelIngressPort = resolveTunnelIngressPort;
 exports.startApiService = startApiService;
@@ -9,12 +10,14 @@ const ConfigurableLoggerFactory_1 = require("../logging/ConfigurableLoggerFactor
 const log_file_1 = require("../logging/log-file");
 const container_1 = require("./container");
 const routes_1 = require("./container/routes");
+const background_service_supervisor_1 = require("./background-service-supervisor");
 const OpenAuthMiddleware_1 = require("./middleware/OpenAuthMiddleware");
 const EmbeddedInngestService_1 = require("./runs/EmbeddedInngestService");
 const LocalProvisionState_1 = require("../provision/LocalProvisionState");
 const oidc_issuer_1 = require("../runtime/oidc-issuer");
 const OFFICIAL_CLOUD_API_ORIGIN = 'https://api.undefineds.co';
-const OFFICIAL_CLOUD_IDENTITY_ORIGIN = 'https://id.undefineds.co';
+/** One source of truth for the Cloud identity: the local edition's default issuer. */
+exports.OFFICIAL_CLOUD_IDENTITY_ORIGIN = new URL(oidc_issuer_1.DEFAULT_LOCAL_OIDC_ISSUER).origin;
 function ensureTrailingSlash(url) {
     return url.endsWith('/') ? url : `${url}/`;
 }
@@ -250,7 +253,7 @@ function resolveCloudIdentityUrl(config) {
     try {
         const endpoint = new URL(config.cloudApiEndpoint ?? OFFICIAL_CLOUD_API_ORIGIN);
         const official = new URL(OFFICIAL_CLOUD_API_ORIGIN);
-        return endpoint.hostname === official.hostname ? OFFICIAL_CLOUD_IDENTITY_ORIGIN : undefined;
+        return endpoint.hostname === official.hostname ? exports.OFFICIAL_CLOUD_IDENTITY_ORIGIN : undefined;
     }
     catch {
         return undefined;
@@ -274,6 +277,27 @@ function normalizeUrl(value) {
         return value.trim();
     }
 }
+/**
+ * Move the API's legacy owner keys into the task layer before anything serves traffic.
+ *
+ * A failure here is reported and left for the next boot: the legacy table stays readable, and the
+ * migration is idempotent, so a half-done run is repeatable rather than a data loss.
+ */
+async function migrateLegacyPodKeys(container, logger) {
+    const migrate = container.resolve('legacyPodKeyMigration', { allowUnregistered: true });
+    if (!migrate) {
+        return;
+    }
+    try {
+        const result = await migrate();
+        if (result.migrated > 0 || result.failed > 0) {
+            logger.info(`Legacy Pod keys migrated into the task layer: ${JSON.stringify(result)}`);
+        }
+    }
+    catch (error) {
+        logger.warn(`Legacy Pod key migration failed: ${String(error)}`);
+    }
+}
 async function registerPrimaryServiceToken(container, config, logger) {
     try {
         const serviceToken = config.serviceToken;
@@ -323,11 +347,31 @@ async function reconcileLocalOwnerRoles(container, config, logger) {
  * would let forwarded remote requests inherit local trust. Falls back to the
  * historical gateway port only when no ingress listener was provisioned.
  */
+/**
+ * The port a remote tunnel forwards to: the Gateway's tunnel entry.
+ *
+ * The runtime records the listener it actually bound in `XPOD_GATEWAY_INGRESS_PORT`, and the
+ * Gateway's own port is only the fallback for an embedding that started no tunnel entry. The
+ * gate is structural - anything arriving on that listener is remote whatever it claims - so a
+ * tunnel pointed at the Gateway port by mistake still has the forwarding-header check behind
+ * it rather than inheriting local trust.
+ */
 function resolveTunnelIngressPort(env = process.env) {
-    const raw = env.XPOD_GATEWAY_INGRESS_PORT ?? env.XPOD_MAIN_PORT ?? env.CSS_PORT ?? env.PORT ?? '3000';
-    const parsed = Number.parseInt(raw, 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : 3000;
+    for (const value of [env.XPOD_GATEWAY_INGRESS_PORT, env.XPOD_MAIN_PORT, env.XPOD_PORT, env.PORT]) {
+        const parsed = Number.parseInt(value ?? '', 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return 3000;
 }
+/**
+ * 后台服务由 supervisor 接管（审计 N18）。
+ *
+ * 此前每个服务只 start 一次，失败只写日志：开机时断网、provider 抖动的隧道会一直躺着，
+ * 跑着跑着死掉的也没人发现。现在启动失败按退避重试，起来之后按间隔复查存活。
+ */
+const backgroundSupervisors = [];
 async function startBackgroundServices(container, logger) {
     try {
         const localNetworkManager = container.resolve('localNetworkManager', { allowUnregistered: true });
@@ -341,8 +385,18 @@ async function startBackgroundServices(container, logger) {
     try {
         const ddnsManager = container.resolve('ddnsManager', { allowUnregistered: true });
         if (ddnsManager) {
-            await ddnsManager.start();
-            logger.info('DDNS Manager started');
+            const supervisor = new background_service_supervisor_1.BackgroundServiceSupervisor({
+                name: 'ddns',
+                start: async () => {
+                    await ddnsManager.start();
+                },
+                stop: async () => {
+                    ddnsManager.stop?.();
+                },
+                logger,
+            });
+            backgroundSupervisors.push(supervisor);
+            supervisor.start();
         }
     }
     catch (error) {
@@ -352,13 +406,25 @@ async function startBackgroundServices(container, logger) {
         const localTunnelProvider = container.resolve('localTunnelProvider', { allowUnregistered: true });
         if (localTunnelProvider) {
             logger.info('Starting local tunnel provider...');
-            const config = await localTunnelProvider.setup({
-                subdomain: 'local',
-                localPort: resolveTunnelIngressPort(),
-                localProtocol: 'http',
+            const supervisor = new background_service_supervisor_1.BackgroundServiceSupervisor({
+                name: `tunnel:${String(localTunnelProvider.name ?? 'local')}`,
+                start: async () => {
+                    const config = await localTunnelProvider.setup({
+                        subdomain: 'local',
+                        localPort: resolveTunnelIngressPort(),
+                        localProtocol: 'http',
+                    });
+                    await localTunnelProvider.start(config);
+                },
+                stop: async () => {
+                    await localTunnelProvider.stop?.();
+                },
+                // 隧道进程退出后 provider 自己知道状态，supervisor 据此重启。
+                isRunning: () => Boolean(localTunnelProvider.getStatus?.().running),
+                logger,
             });
-            await localTunnelProvider.start(config);
-            logger.info('Local tunnel provider started');
+            backgroundSupervisors.push(supervisor);
+            supervisor.start();
         }
     }
     catch (error) {
@@ -366,12 +432,10 @@ async function startBackgroundServices(container, logger) {
     }
 }
 async function stopBackgroundServices(container) {
-    try {
-        const ddnsManager = container.resolve('ddnsManager', { allowUnregistered: true });
-        ddnsManager?.stop();
-    }
-    catch {
-        // ignore shutdown errors
+    // 先停监督器：否则一次关停会被自己排的重试撤销（ddns/tunnel 的 stop 由它们负责调用）。
+    while (backgroundSupervisors.length > 0) {
+        const supervisor = backgroundSupervisors.pop();
+        await supervisor?.stop();
     }
     try {
         const localNetworkManager = container.resolve('localNetworkManager', { allowUnregistered: true });
@@ -380,13 +444,8 @@ async function stopBackgroundServices(container) {
     catch {
         // ignore shutdown errors
     }
-    try {
-        const localTunnelProvider = container.resolve('localTunnelProvider', { allowUnregistered: true });
-        await localTunnelProvider?.stop();
-    }
-    catch {
-        // ignore shutdown errors
-    }
+    // The tunnel provider's stop is owned by its supervisor above; stopping it twice would kill
+    // the same process twice and make the shutdown path look like it did more than it did.
 }
 async function stopApiRuntimeServices(container) {
     try {
@@ -472,6 +531,7 @@ async function startApiService(options = {}) {
         (0, routes_1.registerRoutes)(container);
         server = container.resolve('apiServer');
         await container.resolve('rdfEngine', { allowUnregistered: true })?.open?.();
+        await migrateLegacyPodKeys(container, logger);
         await registerPrimaryServiceToken(container, config, logger);
         await reconcileLocalOwnerRoles(container, config, logger);
         await startBackgroundServices(container, logger);

package/dist/api/tasks/PodInterfaceKeyMigration.d.ts

@@ -0,0 +1,27 @@
+import type { PodInterfaceKeySource } from '../ai-gateway/pod/PodInterfaceKeyStore';
+import type { TaskCredentialStore } from './TaskCredentialStore';
+export interface PodInterfaceKeyMigrationResult {
+    scanned: number;
+    migrated: number;
+    skipped: number;
+    failed: number;
+}
+export interface MigratePodInterfaceKeysOptions {
+    /** Legacy store: one sealed owner key per WebID. Read-only here. */
+    keys: PodInterfaceKeySource & {
+        listOwners(): Promise<string[]>;
+    };
+    /** Where the rows are moved to. */
+    taskCredentials: TaskCredentialStore;
+    /** Issuer the legacy rows belong to. */
+    issuer: string;
+}
+/**
+ * Move the deployment's stored owner keys into the task layer.
+ *
+ * Runs once per boot and is safe to repeat: a row that is already a grant of the same owner and
+ * issuer resolves to the same reference, and the grant is idempotent when the secret matches. A
+ * row that cannot be opened is reported and left alone - the legacy table stays readable, which is
+ * what keeps a failed migration reversible.
+ */
+export declare function migratePodInterfaceKeysToTaskCredentials(options: MigratePodInterfaceKeysOptions): Promise<PodInterfaceKeyMigrationResult>;