@undefineds.co/xpod 0.4.14 → 0.4.16

package/dist/api/tasks/TaskCredentialStore.js

@@ -0,0 +1,341 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskCredentialStore = exports.TASK_CREDENTIAL_ENCRYPTION_FAILED = exports.TASK_CREDENTIAL_OWNER_MISMATCH = exports.TASK_CREDENTIAL_VERSION_CONFLICT = exports.TASK_CREDENTIAL_NOT_ACTIVE = exports.TASK_CREDENTIAL_NOT_FOUND = exports.TASK_CREDENTIAL_REF_PREFIX = void 0;
+exports.createTaskCredentialSource = createTaskCredentialSource;
+const node_crypto_1 = require("node:crypto");
+const drizzle_orm_1 = require("drizzle-orm");
+const global_logger_factory_1 = require("global-logger-factory");
+const db_1 = require("../../identity/drizzle/db");
+const TaskCredentialSchema_1 = require("./TaskCredentialSchema");
+/**
+ * Every generated reference starts with this, which is what lets a binding tell "this id names a
+ * task-layer grant" from "this id is a Pod-stored credential".
+ */
+exports.TASK_CREDENTIAL_REF_PREFIX = 'taskcred_';
+exports.TASK_CREDENTIAL_NOT_FOUND = 'task_credential_not_found';
+exports.TASK_CREDENTIAL_NOT_ACTIVE = 'task_credential_not_active';
+exports.TASK_CREDENTIAL_VERSION_CONFLICT = 'task_credential_version_conflict';
+exports.TASK_CREDENTIAL_OWNER_MISMATCH = 'task_credential_owner_mismatch';
+exports.TASK_CREDENTIAL_ENCRYPTION_FAILED = 'task_credential_encryption_failed';
+/**
+ * The task layer's own credential store.
+ *
+ * Reading a lease requires an explicit owner and an `active` row at the expected version, so a
+ * stale task, a revoked grant or another user's reference cannot open somebody else's Pod.
+ */
+class TaskCredentialStore {
+    constructor(options) {
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.db = options.database.db;
+        this.table = options.database.schema.taskCredentials;
+        this.vault = options.vault;
+        this.now = options.now ?? (() => new Date());
+        // One grant per owner and issuer: the reference is derived, so a retried registration lands on
+        // the same row instead of leaving a second credential behind.
+        this.newCredentialRef = options.newCredentialRef
+            ?? ((input) => `${exports.TASK_CREDENTIAL_REF_PREFIX}${(0, node_crypto_1.createHash)('sha256').update(`${input.issuer}\u0000${input.ownerWebId}`).digest('hex').slice(0, 32)}`);
+        this.ready = (0, TaskCredentialSchema_1.ensureTaskCredentialTables)(this.db).catch((error) => {
+            this.initError = error;
+        });
+    }
+    /** Grant, or idempotently re-grant, a credential for one user and issuer. */
+    async grant(input) {
+        await this.ensureReady();
+        const credentialRef = input.credentialRef ?? this.newCredentialRef(input);
+        const existing = await this.findRow(credentialRef);
+        if (existing) {
+            if (String(existing.ownerWebId) !== input.ownerWebId || String(existing.issuer) !== input.issuer) {
+                throw new Error(exports.TASK_CREDENTIAL_OWNER_MISMATCH);
+            }
+            // The same reference with the same secret is a retry, not a rotation: keep the version.
+            const lease = await this.openRow(existing);
+            if (lease.clientId === input.clientId && lease.clientSecret === input.clientSecret) {
+                if (input.status === 'active' && String(existing.status) === 'pending') {
+                    return await this.activate(credentialRef);
+                }
+                return this.toSummary(existing);
+            }
+            return await this.rotate(credentialRef, {
+                clientId: input.clientId,
+                clientSecret: input.clientSecret,
+                expectedVersion: Number(existing.credentialVersion),
+            });
+        }
+        const sealed = await this.seal({ credentialRef, ownerWebId: input.ownerWebId, issuer: input.issuer, clientId: input.clientId, clientSecret: input.clientSecret });
+        const createdAt = (0, db_1.toDbTimestamp)(this.db, this.now());
+        await this.db.insert(this.table).values({
+            credentialId: credentialRef,
+            ownerWebId: input.ownerWebId,
+            issuer: input.issuer,
+            clientId: input.clientId,
+            sealedSecret: sealed.sealedSecret,
+            sealedSecretKeyId: sealed.keyId,
+            credentialVersion: 1,
+            status: input.status ?? 'pending',
+            createdAt,
+            rotatedAt: createdAt,
+            ...(input.expiresAt ? { expiresAt: (0, db_1.toDbTimestamp)(this.db, input.expiresAt) } : {}),
+        });
+        this.logger.info(`Granted a task credential for ${input.ownerWebId} (${input.status ?? 'pending'})`);
+        const created = await this.findRow(credentialRef);
+        if (!created) {
+            throw new Error(exports.TASK_CREDENTIAL_NOT_FOUND);
+        }
+        return this.toSummary(created);
+    }
+    /** Confirm a grant so executions may use it. */
+    async activate(credentialRef) {
+        await this.ensureReady();
+        const row = await this.requireRow(credentialRef);
+        if (String(row.status) === 'revoked' || String(row.status) === 'expired') {
+            throw new Error(exports.TASK_CREDENTIAL_NOT_ACTIVE);
+        }
+        if (String(row.status) !== 'active') {
+            await this.db
+                .update(this.table)
+                .set({ status: 'active' })
+                .where((0, drizzle_orm_1.eq)(this.table.credentialId, credentialRef));
+        }
+        return this.toSummary(await this.requireRow(credentialRef));
+    }
+    /** Replace the secret, bumping the version so older bindings stop matching. */
+    async rotate(credentialRef, input) {
+        await this.ensureReady();
+        const row = await this.requireRow(credentialRef);
+        if (Number(row.credentialVersion) !== input.expectedVersion) {
+            throw new Error(`${exports.TASK_CREDENTIAL_VERSION_CONFLICT}:${row.credentialVersion}`);
+        }
+        const sealed = await this.seal({
+            credentialRef,
+            ownerWebId: String(row.ownerWebId),
+            issuer: String(row.issuer),
+            clientId: input.clientId,
+            clientSecret: input.clientSecret,
+        });
+        const nextVersion = input.expectedVersion + 1;
+        await this.db
+            .update(this.table)
+            .set({
+            clientId: input.clientId,
+            sealedSecret: sealed.sealedSecret,
+            sealedSecretKeyId: sealed.keyId,
+            credentialVersion: nextVersion,
+            status: 'active',
+            rotatedAt: (0, db_1.toDbTimestamp)(this.db, this.now()),
+        })
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(this.table.credentialId, credentialRef), (0, drizzle_orm_1.eq)(this.table.credentialVersion, input.expectedVersion)));
+        const rotated = await this.requireRow(credentialRef);
+        if (Number(rotated.credentialVersion) !== nextVersion) {
+            throw new Error(`${exports.TASK_CREDENTIAL_VERSION_CONFLICT}:${rotated.credentialVersion}`);
+        }
+        this.logger.info(`Rotated task credential ${credentialRef} to version ${nextVersion}`);
+        return this.toSummary(rotated);
+    }
+    /** Stop using a grant without losing its history. */
+    async revoke(credentialRef) {
+        await this.ensureReady();
+        await this.requireRow(credentialRef);
+        await this.db
+            .update(this.table)
+            .set({ status: 'revoked' })
+            .where((0, drizzle_orm_1.eq)(this.table.credentialId, credentialRef));
+    }
+    /**
+     * Open the credential for one execution.
+     *
+     * Everything that makes a grant usable is checked here: the owner the caller claims, the status,
+     * the version the binding froze, and the expiry. A refusal keeps its own reason code so the
+     * caller can tell a revoked grant from a stale one.
+     */
+    async lease(input) {
+        await this.ensureReady();
+        const row = await this.requireRow(input.credentialRef);
+        if (String(row.ownerWebId) !== input.ownerWebId) {
+            throw new Error(exports.TASK_CREDENTIAL_OWNER_MISMATCH);
+        }
+        if (input.version !== undefined && Number(row.credentialVersion) !== input.version) {
+            throw new Error(`${exports.TASK_CREDENTIAL_VERSION_CONFLICT}:${row.credentialVersion}`);
+        }
+        const expiresAt = (0, db_1.fromDbTimestamp)(row.expiresAt);
+        if (expiresAt && expiresAt.getTime() <= this.now().getTime()) {
+            await this.db.update(this.table).set({ status: 'expired' }).where((0, drizzle_orm_1.eq)(this.table.credentialId, input.credentialRef));
+            throw new Error(`${exports.TASK_CREDENTIAL_NOT_ACTIVE}:expired`);
+        }
+        if (String(row.status) !== 'active') {
+            throw new Error(`${exports.TASK_CREDENTIAL_NOT_ACTIVE}:${String(row.status)}`);
+        }
+        if (input.recordUsage !== false) {
+            await this.db
+                .update(this.table)
+                .set({ lastUsedAt: (0, db_1.toDbTimestamp)(this.db, this.now()) })
+                .where((0, drizzle_orm_1.eq)(this.table.credentialId, input.credentialRef));
+        }
+        const opened = await this.openRow(row);
+        return {
+            credentialRef: input.credentialRef,
+            ownerWebId: String(row.ownerWebId),
+            issuer: String(row.issuer),
+            version: Number(row.credentialVersion),
+            clientId: opened.clientId,
+            clientSecret: opened.clientSecret,
+        };
+    }
+    /** Metadata for one user's grants; never a secret. */
+    async listForOwner(ownerWebId) {
+        await this.ensureReady();
+        const rows = await this.db
+            .select()
+            .from(this.table)
+            .where((0, drizzle_orm_1.eq)(this.table.ownerWebId, ownerWebId));
+        return rows.map((row) => this.toSummary(row));
+    }
+    /** The rows whose secret was sealed with a key that is no longer active. */
+    async listNeedingRewrap(activeKeyId) {
+        await this.ensureReady();
+        const rows = await this.db.select().from(this.table);
+        return rows
+            .filter((row) => String(row.sealedSecretKeyId) !== activeKeyId)
+            .map((row) => String(row.credentialId));
+    }
+    async seal(input) {
+        let plaintext;
+        try {
+            plaintext = new TextEncoder().encode(JSON.stringify({
+                clientId: input.clientId,
+                clientSecret: input.clientSecret,
+            }));
+            const envelope = await this.vault.seal(plaintext, {
+                ownerWebId: input.ownerWebId,
+                resourceIri: `urn:xpod:task-credential:${input.credentialRef}`,
+                predicate: 'urn:xpod:taskCredential:sealedSecret',
+                field: 'clientSecret',
+                schemaVersion: 'v1',
+                provider: input.issuer,
+            });
+            return { sealedSecret: JSON.stringify(envelope), keyId: envelope.wrappedDek.keyId };
+        }
+        catch (error) {
+            this.logger.error(`Task credential encryption failed for ${input.ownerWebId}: ${String(error)}`);
+            throw new Error(exports.TASK_CREDENTIAL_ENCRYPTION_FAILED);
+        }
+        finally {
+            plaintext?.fill(0);
+        }
+    }
+    async openRow(row) {
+        let plaintext;
+        try {
+            const envelope = JSON.parse(String(row.sealedSecret));
+            plaintext = await this.vault.open(envelope, {
+                ownerWebId: String(row.ownerWebId),
+                resourceIri: `urn:xpod:task-credential:${String(row.credentialId)}`,
+                predicate: 'urn:xpod:taskCredential:sealedSecret',
+                field: 'clientSecret',
+                schemaVersion: 'v1',
+                provider: String(row.issuer),
+            });
+            const parsed = JSON.parse(new TextDecoder().decode(plaintext));
+            if (typeof parsed.clientId !== 'string' || typeof parsed.clientSecret !== 'string') {
+                throw new Error('decrypted task credential is not a client credential');
+            }
+            return { clientId: parsed.clientId, clientSecret: parsed.clientSecret };
+        }
+        catch (error) {
+            this.logger.error(`Task credential could not be opened for ${String(row.ownerWebId)}: ${String(error)}`);
+            throw new Error(exports.TASK_CREDENTIAL_ENCRYPTION_FAILED);
+        }
+        finally {
+            plaintext?.fill(0);
+        }
+    }
+    async findRow(credentialRef) {
+        const rows = await this.db
+            .select()
+            .from(this.table)
+            .where((0, drizzle_orm_1.eq)(this.table.credentialId, credentialRef))
+            .limit(1);
+        return rows[0];
+    }
+    async requireRow(credentialRef) {
+        const row = await this.findRow(credentialRef);
+        if (!row) {
+            throw new Error(exports.TASK_CREDENTIAL_NOT_FOUND);
+        }
+        return row;
+    }
+    toSummary(row) {
+        return {
+            credentialRef: String(row.credentialId),
+            ownerWebId: String(row.ownerWebId),
+            issuer: String(row.issuer),
+            clientId: String(row.clientId),
+            version: Number(row.credentialVersion),
+            status: String(row.status),
+            createdAt: (0, db_1.fromDbTimestamp)(row.createdAt) ?? this.now(),
+            ...((0, db_1.fromDbTimestamp)(row.rotatedAt) ? { rotatedAt: (0, db_1.fromDbTimestamp)(row.rotatedAt) } : {}),
+            ...((0, db_1.fromDbTimestamp)(row.lastUsedAt) ? { lastUsedAt: (0, db_1.fromDbTimestamp)(row.lastUsedAt) } : {}),
+            ...((0, db_1.fromDbTimestamp)(row.expiresAt) ? { expiresAt: (0, db_1.fromDbTimestamp)(row.expiresAt) } : {}),
+        };
+    }
+    async ensureReady() {
+        await this.ready;
+        if (this.initError) {
+            throw this.initError instanceof Error
+                ? this.initError
+                : new Error(`task_credential_table_unavailable:${String(this.initError)}`);
+        }
+    }
+}
+exports.TaskCredentialStore = TaskCredentialStore;
+/**
+ * The task layer's credentials as Pod access needs them.
+ *
+ * `activeFor` answers "may background work use this owner's grant at all", which is what a
+ * scheduled entry needs; `forRef` answers a task binding that names its credential and version.
+ */
+function createTaskCredentialSource(input) {
+    const { store, issuer } = input;
+    return {
+        async activeFor(ownerWebId) {
+            const grants = await store.listForOwner(ownerWebId);
+            const active = grants
+                .filter((grant) => grant.status === 'active' && grant.issuer === issuer)
+                .sort((left, right) => right.version - left.version)[0];
+            if (!active) {
+                return undefined;
+            }
+            const lease = await store.lease({
+                credentialRef: active.credentialRef,
+                ownerWebId,
+                version: active.version,
+            });
+            return {
+                credentialRef: lease.credentialRef,
+                version: lease.version,
+                clientId: lease.clientId,
+                clientSecret: lease.clientSecret,
+            };
+        },
+        async forRef({ credentialRef, ownerWebId, version }) {
+            try {
+                const lease = await store.lease({
+                    credentialRef,
+                    ownerWebId,
+                    ...(version !== undefined ? { version } : {}),
+                    // A version probe must not look like a use of the credential.
+                    recordUsage: false,
+                });
+                return {
+                    credentialRef: lease.credentialRef,
+                    version: lease.version,
+                    clientId: lease.clientId,
+                    clientSecret: lease.clientSecret,
+                };
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}
+//# sourceMappingURL=TaskCredentialStore.js.map

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

@@ -2,5 +2,8 @@ export { Task, TaskStatus, TaskTriggerKind, type TaskRecord, type TaskStatusType
 export { type TaskListOptions, type TaskRecordData, type TaskStore, } from './store';
 export { TaskMaterializer, type MaterializedTaskRun, type TaskMaterializerOptions, } from './TaskMaterializer';
 export { TaskService, type CreateTaskInput, type CreateTaskResult, type TaskServiceOptions, } from './TaskService';
+export { getTaskCredentialDatabase, resolveTaskCredentialDatabaseUrl, resetTaskCredentialDatabases, type TaskCredentialDatabase, } from './TaskCredentialDatabase';
+export { TASK_CREDENTIAL_ENCRYPTION_FAILED, TASK_CREDENTIAL_NOT_ACTIVE, TASK_CREDENTIAL_NOT_FOUND, TASK_CREDENTIAL_OWNER_MISMATCH, TASK_CREDENTIAL_VERSION_CONFLICT, TaskCredentialStore, type GrantTaskCredentialInput, type TaskCredentialLease, type TaskCredentialRef, type TaskCredentialStatus, type TaskCredentialStoreOptions, type TaskCredentialSummary, } from './TaskCredentialStore';
+export { ensureTaskCredentialTables, taskCredentialSchema, taskCredentialsPg, taskCredentialsSqlite, } from './TaskCredentialSchema';
 export { TASK_AUTH_CREDENTIAL_SERVICE, TaskAuthBindingKind, TaskAuthBindingService, TaskAuthBindingStatus, encodeClientCredentialsApiKey, parseClientCredentialsApiKey, type CreateTaskAuthBindingInput, type TaskAuthBindingKindType, type TaskAuthBindingRepository, type TaskAuthBindingServiceOptions, type TaskAuthBindingSnapshot, type TaskAuthBindingStatusType, type TaskAuthCredentialRecord, } from './TaskAuthBinding';
 export { InngestTaskScheduler, XPOD_TASK_MATERIALIZE_DUE_EVENT, XPOD_TASK_EVENT, XPOD_TASK_EVENT_FUNCTION_ID, XPOD_TASK_MATERIALIZE_DUE_FUNCTION_ID, type XpodTaskMaterializeDueEvent, type XpodTaskMaterializeDueEventData, type XpodTaskEvent, type XpodTaskEventData, type InngestTaskSchedulerOptions, } from './InngestTaskScheduler';

package/dist/api/tasks/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.XPOD_TASK_MATERIALIZE_DUE_FUNCTION_ID = exports.XPOD_TASK_EVENT_FUNCTION_ID = exports.XPOD_TASK_EVENT = exports.XPOD_TASK_MATERIALIZE_DUE_EVENT = exports.InngestTaskScheduler = exports.parseClientCredentialsApiKey = exports.encodeClientCredentialsApiKey = exports.TaskAuthBindingStatus = exports.TaskAuthBindingService = exports.TaskAuthBindingKind = exports.TASK_AUTH_CREDENTIAL_SERVICE = exports.TaskService = exports.TaskMaterializer = exports.TaskTriggerKind = exports.TaskStatus = exports.Task = void 0;
+exports.XPOD_TASK_MATERIALIZE_DUE_FUNCTION_ID = exports.XPOD_TASK_EVENT_FUNCTION_ID = exports.XPOD_TASK_EVENT = exports.XPOD_TASK_MATERIALIZE_DUE_EVENT = exports.InngestTaskScheduler = exports.parseClientCredentialsApiKey = exports.encodeClientCredentialsApiKey = exports.TaskAuthBindingStatus = exports.TaskAuthBindingService = exports.TaskAuthBindingKind = exports.TASK_AUTH_CREDENTIAL_SERVICE = exports.taskCredentialsSqlite = exports.taskCredentialsPg = exports.taskCredentialSchema = exports.ensureTaskCredentialTables = exports.TaskCredentialStore = exports.TASK_CREDENTIAL_VERSION_CONFLICT = exports.TASK_CREDENTIAL_OWNER_MISMATCH = exports.TASK_CREDENTIAL_NOT_FOUND = exports.TASK_CREDENTIAL_NOT_ACTIVE = exports.TASK_CREDENTIAL_ENCRYPTION_FAILED = exports.resetTaskCredentialDatabases = exports.resolveTaskCredentialDatabaseUrl = exports.getTaskCredentialDatabase = exports.TaskService = exports.TaskMaterializer = exports.TaskTriggerKind = exports.TaskStatus = exports.Task = void 0;
 var schema_1 = require("./schema");
 Object.defineProperty(exports, "Task", { enumerable: true, get: function () { return schema_1.Task; } });
 Object.defineProperty(exports, "TaskStatus", { enumerable: true, get: function () { return schema_1.TaskStatus; } });
@@ -9,6 +9,22 @@ var TaskMaterializer_1 = require("./TaskMaterializer");
 Object.defineProperty(exports, "TaskMaterializer", { enumerable: true, get: function () { return TaskMaterializer_1.TaskMaterializer; } });
 var TaskService_1 = require("./TaskService");
 Object.defineProperty(exports, "TaskService", { enumerable: true, get: function () { return TaskService_1.TaskService; } });
+var TaskCredentialDatabase_1 = require("./TaskCredentialDatabase");
+Object.defineProperty(exports, "getTaskCredentialDatabase", { enumerable: true, get: function () { return TaskCredentialDatabase_1.getTaskCredentialDatabase; } });
+Object.defineProperty(exports, "resolveTaskCredentialDatabaseUrl", { enumerable: true, get: function () { return TaskCredentialDatabase_1.resolveTaskCredentialDatabaseUrl; } });
+Object.defineProperty(exports, "resetTaskCredentialDatabases", { enumerable: true, get: function () { return TaskCredentialDatabase_1.resetTaskCredentialDatabases; } });
+var TaskCredentialStore_1 = require("./TaskCredentialStore");
+Object.defineProperty(exports, "TASK_CREDENTIAL_ENCRYPTION_FAILED", { enumerable: true, get: function () { return TaskCredentialStore_1.TASK_CREDENTIAL_ENCRYPTION_FAILED; } });
+Object.defineProperty(exports, "TASK_CREDENTIAL_NOT_ACTIVE", { enumerable: true, get: function () { return TaskCredentialStore_1.TASK_CREDENTIAL_NOT_ACTIVE; } });
+Object.defineProperty(exports, "TASK_CREDENTIAL_NOT_FOUND", { enumerable: true, get: function () { return TaskCredentialStore_1.TASK_CREDENTIAL_NOT_FOUND; } });
+Object.defineProperty(exports, "TASK_CREDENTIAL_OWNER_MISMATCH", { enumerable: true, get: function () { return TaskCredentialStore_1.TASK_CREDENTIAL_OWNER_MISMATCH; } });
+Object.defineProperty(exports, "TASK_CREDENTIAL_VERSION_CONFLICT", { enumerable: true, get: function () { return TaskCredentialStore_1.TASK_CREDENTIAL_VERSION_CONFLICT; } });
+Object.defineProperty(exports, "TaskCredentialStore", { enumerable: true, get: function () { return TaskCredentialStore_1.TaskCredentialStore; } });
+var TaskCredentialSchema_1 = require("./TaskCredentialSchema");
+Object.defineProperty(exports, "ensureTaskCredentialTables", { enumerable: true, get: function () { return TaskCredentialSchema_1.ensureTaskCredentialTables; } });
+Object.defineProperty(exports, "taskCredentialSchema", { enumerable: true, get: function () { return TaskCredentialSchema_1.taskCredentialSchema; } });
+Object.defineProperty(exports, "taskCredentialsPg", { enumerable: true, get: function () { return TaskCredentialSchema_1.taskCredentialsPg; } });
+Object.defineProperty(exports, "taskCredentialsSqlite", { enumerable: true, get: function () { return TaskCredentialSchema_1.taskCredentialsSqlite; } });
 var TaskAuthBinding_1 = require("./TaskAuthBinding");
 Object.defineProperty(exports, "TASK_AUTH_CREDENTIAL_SERVICE", { enumerable: true, get: function () { return TaskAuthBinding_1.TASK_AUTH_CREDENTIAL_SERVICE; } });
 Object.defineProperty(exports, "TaskAuthBindingKind", { enumerable: true, get: function () { return TaskAuthBinding_1.TaskAuthBindingKind; } });

package/dist/cli/commands/start.d.ts

@@ -13,19 +13,19 @@ export declare const startCommand: CommandModule<object, StartArgs>;
 /**
  * Where remote-forwarded traffic lands on this machine.
  *
- * Order: explicit `XPOD_GATEWAY_INGRESS_PORT` → the active SakuraFrp tunnel's assigned local
- * port → an OS-assigned loopback port. The first two are strict, because a tunnel that
- * forwards to a specific port cannot follow us somewhere else.
+ * The decision (explicit pin → the active profile's console declaration → the gateway-derived
+ * entry) lives in `src/runtime/ingress-port.ts`, together with the strict "taken means taken"
+ * check and the occupant naming. This only reports the outcome, so the startup banner says
+ * whether the entry was pinned, adopted from a console, or derived from the gateway port.
  */
-export declare function resolveIngressPort(config: {
-    tunnelProfiles?: Array<{
-        id: string;
+export declare function describeIngressDecision(ingress: {
+    port: number;
+    source: string;
+    declared?: {
         provider: string;
-        credentialEnvKey?: string;
-        credentialConfigured?: boolean;
-    }>;
-    tunnelActiveProfileId?: string;
-}, mainPort: number): Promise<number>;
+        readBack: string;
+    };
+}): string;
 export declare function resolveCliOidcIssuer(env: Record<string, string | undefined>, provisionedIssuer?: string, edition?: string): string | undefined;
 export declare function resolveManagedEdgeAgentConfig(config: Pick<ReturnType<typeof loadConfigFromEnv>, 'cloudApiEndpoint' | 'nodeId' | 'nodeToken'>, gatewayPort: number, ingressPort?: number, runtimeEnv?: Record<string, string | undefined>): {
     signalEndpoint: string;

package/dist/cli/commands/start.js

@@ -4,7 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.startCommand = void 0;
-exports.resolveIngressPort = resolveIngressPort;
+exports.describeIngressDecision = describeIngressDecision;
 exports.resolveCliOidcIssuer = resolveCliOidcIssuer;
 exports.resolveManagedEdgeAgentConfig = resolveManagedEdgeAgentConfig;
 exports.resolveChildDatabaseUrl = resolveChildDatabaseUrl;
@@ -16,7 +16,7 @@ const fs_1 = __importDefault(require("fs"));
 const global_logger_factory_1 = require("global-logger-factory");
 const supervisor_1 = require("../../supervisor");
 const runtime_1 = require("../../runtime");
-const SakuraFrpTunnelProvider_1 = require("../../tunnel/SakuraFrpTunnelProvider");
+const ingress_port_1 = require("../../runtime/ingress-port");
 const css_process_1 = require("../../runtime/css-process");
 const oidc_issuer_1 = require("../../runtime/oidc-issuer");
 const AuthMode_1 = require("../../authorization/AuthMode");
@@ -107,17 +107,30 @@ exports.startCommand = {
         const cssPort = await (0, runtime_1.getFreePortForWildcard)(requestedCssPort);
         const requestedApiPort = resolveServicePort(process.env.API_PORT, cssPort + 1, new Set([mainPort, cssPort]));
         const apiPort = await (0, runtime_1.getFreePortForWildcard)(requestedApiPort);
-        // Remote forwarding (managed tunnels, P2P data plane) terminates on this machine, so
-        // its origin is a dedicated ingress port instead of the gateway port: the Gateway
-        // never treats requests accepted there as local. An explicit override is honoured;
-        // otherwise the OS assigns a loopback port, because neighbouring ports may already
-        // belong to another service this deployment planned.
-        // The port is a fact of whichever tunnel forwards to us: an explicit override pins it,
-        // and the SakuraFrp console's own 本地端口 is read back from the provider, so the
-        // operator never types the same number twice. Only an unmanaged ingress is ephemeral.
-        // A pinned port is taken as-is: silently moving it would leave the tunnel pointing at a
-        // port nobody listens on.
-        const ingressPort = await resolveIngressPort(provisionedConfig, mainPort);
+        // Remote forwarding (managed tunnels, P2P data plane) terminates on this machine, so its
+        // origin is a dedicated ingress port instead of the gateway port: the Gateway never treats
+        // requests accepted there as local.
+        //
+        // Order (see `resolveIngressPort`): an explicit `XPOD_GATEWAY_INGRESS_PORT` wins; otherwise
+        // the *active* profile's provider console decides — for a console-owned tunnel the runtime
+        // adopts the port that console already declares (SakuraFrp's `local_port`, the Cloudflare
+        // dashboard's remote configuration read back through the connector) instead of asking the
+        // operator to edit the console; only an entry nobody declares is derived from the gateway
+        // port (gateway+3..+9).
+        //
+        // Both strict sources are strict: a port that somebody else holds fails the start with the
+        // occupant named (pid, command line, cwd), and nothing is ever signalled or silently moved
+        // to another port - the tunnel forwards to a number, so it must find this runtime there.
+        const ingress = await (0, ingress_port_1.resolveIngressPort)({
+            mainPort,
+            env: process.env,
+            profiles: provisionedConfig.tunnelProfiles ?? [],
+            ...(provisionedConfig.tunnelActiveProfileId
+                ? { activeProfileId: provisionedConfig.tunnelActiveProfileId }
+                : {}),
+            reservedPorts: [mainPort, cssPort, apiPort],
+        });
+        const ingressPort = ingress.port;
         // Published so the API can tell the operator which address a tunnel must forward to.
         process.env.XPOD_GATEWAY_INGRESS_PORT = String(ingressPort);
         const runtimeRoot = path_1.default.join(process.cwd(), '.xpod/runtime/legacy-css');
@@ -143,6 +156,7 @@ exports.startCommand = {
         console.log(`  Gateway: ${baseUrl} (${argv.host}:${mainPort})`);
         console.log(`  CSS (internal): http://localhost:${cssPort}`);
         console.log(`  API (internal): http://localhost:${apiPort}`);
+        console.log(`  Tunnel entry: http://127.0.0.1:${ingressPort} — ${describeIngressDecision(ingress)}`);
         if (externalOidcIssuer) {
             console.log(`  SP mode: Cloud IdP = ${externalOidcIssuer}`);
         }
@@ -235,38 +249,26 @@ exports.startCommand = {
 /**
  * Where remote-forwarded traffic lands on this machine.
  *
- * Order: explicit `XPOD_GATEWAY_INGRESS_PORT` → the active SakuraFrp tunnel's assigned local
- * port → an OS-assigned loopback port. The first two are strict, because a tunnel that
- * forwards to a specific port cannot follow us somewhere else.
+ * The decision (explicit pin → the active profile's console declaration → the gateway-derived
+ * entry) lives in `src/runtime/ingress-port.ts`, together with the strict "taken means taken"
+ * check and the occupant naming. This only reports the outcome, so the startup banner says
+ * whether the entry was pinned, adopted from a console, or derived from the gateway port.
  */
-async function resolveIngressPort(config, mainPort) {
-    const explicit = process.env.XPOD_GATEWAY_INGRESS_PORT?.trim();
-    if (explicit) {
-        return await (0, runtime_1.requireFreePortForWildcard)(Number.parseInt(explicit, 10));
-    }
-    const active = config.tunnelProfiles?.find((profile) => profile.id === config.tunnelActiveProfileId)
-        ?? config.tunnelProfiles?.find((profile) => profile.provider === 'sakura_frp');
-    if (active?.provider === 'sakura_frp') {
-        const credential = active.credentialEnvKey
-            ? process.env[active.credentialEnvKey] ?? process.env.SAKURA_TUNNEL_TOKEN
-            : process.env.SAKURA_TUNNEL_TOKEN;
-        const assigned = await (0, SakuraFrpTunnelProvider_1.resolveSakuraAssignedLocalPort)(credential);
-        if (assigned && assigned !== mainPort) {
-            return await (0, runtime_1.requireFreePortForWildcard)(assigned);
-        }
+function describeIngressDecision(ingress) {
+    if (ingress.source === 'explicit') {
+        return `pinned by XPOD_GATEWAY_INGRESS_PORT`;
     }
-    // The operator copies this address into a provider console, so it has to survive
-    // restarts instead of being a fresh OS-assigned port every time.
-    const stateFile = path_1.default.join(process.cwd(), '.xpod', 'runtime', 'ingress-port');
-    const stable = await (0, runtime_1.resolveStableLoopbackPort)(stateFile);
-    if (stable.changed) {
-        (0, global_logger_factory_1.getLoggerFor)('XpodStart').warn(`The ingress port changed to ${stable.port}; update the tunnel console if it still forwards to the previous port`);
+    if (ingress.source === 'console-declared' && ingress.declared) {
+        return `adopted from the ${ingress.declared.provider} console (${ingress.declared.readBack})`;
     }
-    return stable.port;
+    return 'derived from the gateway port (gateway+3..+9)';
 }
 function resolveCliOidcIssuer(env, provisionedIssuer, edition) {
+    // A remembered loopback issuer is residue from a run that served it; this one does not, so the
+    // local edition falls back to the Cloud identity instead of a port with no listener.
+    const remembered = (0, oidc_issuer_1.isLoopbackIssuer)(provisionedIssuer) ? undefined : provisionedIssuer;
     return (0, oidc_issuer_1.resolveExternalOidcIssuer)(env)
-        ?? (0, oidc_issuer_1.resolveExternalOidcIssuer)({ SOLID_OIDC_ISSUER: provisionedIssuer })
+        ?? (0, oidc_issuer_1.resolveExternalOidcIssuer)({ SOLID_OIDC_ISSUER: remembered })
         ?? (edition === 'local' ? oidc_issuer_1.DEFAULT_LOCAL_OIDC_ISSUER : undefined);
 }
 function resolveManagedEdgeAgentConfig(config, gatewayPort, ingressPort, runtimeEnv = {}) {

package/dist/cli/commands/stop.js

@@ -39,11 +39,17 @@ exports.stopCommand = {
         }
         try {
             const res = await fetch(`${baseUrl}/service/status`);
-            if (!res.ok) {
+            // 503 means the gateway is reachable but degraded (a supervised child is down or gave up).
+            // Stopping a half-dead instance must stay possible, so only other failures are fatal.
+            const degraded = res.status === 503;
+            if (!res.ok && !degraded) {
                 throw new output_1.CliCommandError('server_not_reachable', 'Service not reachable or already stopped.', 1, {
                     status: res.status,
                 });
             }
+            if (degraded && !argv.json) {
+                console.log('Instance is degraded (a supervised service is not running); stopping it anyway.');
+            }
             const statuses = (await res.json());
             const running = statuses.filter((s) => s.status === 'running');
             if (running.length === 0) {

package/dist/components/components.jsonld

@@ -31,7 +31,6 @@
     "undefineds:dist/logging/ConfigurableLoggerFactory.jsonld",
     "undefineds:dist/storage/SparqlUpdateResourceStore.jsonld",
     "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld",
-    "undefineds:dist/http/InternalPodDataHttpHandler.jsonld",
     "undefineds:dist/http/quota/QuotaAdminHttpHandler.jsonld",
     "undefineds:dist/http/ClusterIngressRouter.jsonld",
     "undefineds:dist/http/ClusterWebSocketConfigurator.jsonld",
@@ -134,10 +133,12 @@
     "undefineds:dist/api/reconciler/WakeAgentQueue.jsonld",
     "undefineds:dist/api/reconciler/ServerGroupReconcilerService.jsonld",
     "undefineds:dist/edge/reachability/types.jsonld",
+    "undefineds:dist/edge/reachability/RouteSetBuilder.jsonld",
     "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld",
     "undefineds:dist/edge/reachability/ManagedRouteSelector.jsonld",
     "undefineds:dist/edge/reachability/CanonicalFetch.jsonld",
     "undefineds:dist/edge/reachability/P2PDataPlane.jsonld",
+    "undefineds:dist/edge/reachability/P2PDataPlaneCrypto.jsonld",
     "undefineds:dist/edge/reachability/P2PSignalingClient.jsonld",
     "undefineds:dist/edge/reachability/TcpP2PDataPlaneTransport.jsonld",
     "undefineds:dist/edge/reachability/TcpP2PSignalingSession.jsonld",