@undefineds.co/xpod 0.4.15 → 0.4.17

package/dist/api/handlers/AiGatewayManagementHandler.js

@@ -5,7 +5,6 @@ const node_crypto_1 = require("node:crypto");
 const global_logger_factory_1 = require("global-logger-factory");
 const readBoundedJsonBody_1 = require("../http/readBoundedJsonBody");
 const GatewayPrincipal_1 = require("../ai-gateway/auth/GatewayPrincipal");
-const AuthContext_1 = require("../auth/AuthContext");
 const models_1 = require("../ai-gateway/models");
 const AiConnectionsServiceAccess_1 = require("../ai-gateway/service-access/AiConnectionsServiceAccess");
 const OwnerPodAccess_1 = require("../ai-gateway/pod/OwnerPodAccess");
@@ -119,15 +118,10 @@ function registerAiGatewayManagementRoutes(server, options) {
                 sendJson(response, 403, { error: 'CSS client credential belongs to another WebID' });
                 return;
             }
-            if ((0, AuthContext_1.hasSolidClientCredentialsAuthority)(verified.context)) {
-                // Sealed before the record is written, because writing the record is the first thing
-                // that needs it: background components reach this Pod through the standard interface
-                // as the owner, never through the caller's network position.
-                await options.podInterfaceKeys?.saveKey(owner, {
-                    clientId: verified.context.clientId,
-                    clientSecret: verified.context.clientSecret,
-                });
-            }
+            // Registering an application is about that application's own credential - where it is in
+            // effect, and how to revoke it. Background Pod access is a separate, explicit grant the user
+            // makes where they manage index/embedding work (`POST /api/ai/task-credentials`), so nothing
+            // about it is written here.
             const name = normalizeOptionalString(body.name) ?? 'Xpod API Key';
             const keyId = repository.createKeyId(owner, options.deployment);
             const createdAt = new Date();
@@ -213,6 +207,9 @@ function registerAiGatewayManagementRoutes(server, options) {
             // This removes the saved client configuration only. The Account host
             // revokes CSS credentials before requesting this companion cleanup.
             await repository.delete(record.id, { auth: request.auth });
+            if (record.clientCredentialId) {
+                options.invalidateClientCredential?.(record.clientCredentialId);
+            }
             sendJson(response, 200, {
                 deleted: true,
                 record: publicGatewayAccessKeyRecord(record, false),
@@ -1341,6 +1338,7 @@ function sendCredentialPoolError(response, error) {
 function sendGatewayAccessKeyError(response, error) {
     const message = error instanceof Error ? error.message : String(error);
     if ((0, OwnerPodAccess_1.isPodAccessFailure)(message)) {
+        logger.warn(`Gateway API Key operation refused: ${(0, AiClientConfigurationService_1.redactSecretText)(message)}`);
         sendJson(response, 403, { error: 'service_access_missing' });
         return;
     }

package/dist/api/handlers/ChatKitHandler.js

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerChatKitRoutes = registerChatKitRoutes;
 const global_logger_factory_1 = require("global-logger-factory");
 const AuthContext_1 = require("../auth/AuthContext");
+const PodAccessFailureResponse_1 = require("./PodAccessFailureResponse");
 /**
  * Register ChatKit routes on the API server
  */
@@ -56,6 +57,10 @@ function registerChatKitRoutes(server, options) {
             }
         }
         catch (error) {
+            // A Pod this process cannot open is the caller's state to fix, not an internal failure.
+            if (!response.headersSent && (0, PodAccessFailureResponse_1.sendPodAccessFailure)(response, error)) {
+                return;
+            }
             logger.error(`ChatKit request failed: ${error}`);
             if (!response.headersSent) {
                 sendJsonError(response, 500, 'internal_error', error.message || 'Internal server error');

package/dist/api/handlers/ChatKitV1Handler.js

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerChatKitV1Routes = registerChatKitV1Routes;
 const types_1 = require("../chatkit/types");
 const AuthContext_1 = require("../auth/AuthContext");
+const PodAccessFailureResponse_1 = require("./PodAccessFailureResponse");
 function registerChatKitV1Routes(server, options) {
     const { store } = options;
     const buildContext = (request) => {
@@ -22,7 +23,7 @@ function registerChatKitV1Routes(server, options) {
         return { userId, auth };
     };
     // GET /v1/chatkit/threads
-    server.get('/v1/chatkit/threads', async (request, response) => {
+    server.get('/v1/chatkit/threads', (0, PodAccessFailureResponse_1.guardPodAccessRoute)(async (request, response) => {
         const url = new URL(request.url ?? '', `http://${request.headers.host}`);
         const limit = parseOptionalInt(url.searchParams.get('limit')) ?? 20;
         const after = url.searchParams.get('after') ?? undefined;
@@ -35,9 +36,9 @@ function registerChatKitV1Routes(server, options) {
             has_more: page.has_more,
             after: page.after,
         });
-    });
+    }));
     // GET /v1/chatkit/threads/:thread_id
-    server.get('/v1/chatkit/threads/:thread_id', async (request, response, params) => {
+    server.get('/v1/chatkit/threads/:thread_id', (0, PodAccessFailureResponse_1.guardPodAccessRoute)(async (request, response, params) => {
         const threadRef = getThreadRefFromRequest(request, response, params.thread_id);
         if (!threadRef) {
             return;
@@ -54,9 +55,9 @@ function registerChatKitV1Routes(server, options) {
                 data: items.data.map((it) => ({ ...it, object: 'chatkit.thread_item' })),
             },
         });
-    });
+    }));
     // DELETE /v1/chatkit/threads/:thread_id
-    server.delete('/v1/chatkit/threads/:thread_id', async (request, response, params) => {
+    server.delete('/v1/chatkit/threads/:thread_id', (0, PodAccessFailureResponse_1.guardPodAccessRoute)(async (request, response, params) => {
         const threadRef = getThreadRefFromRequest(request, response, params.thread_id);
         if (!threadRef) {
             return;
@@ -64,9 +65,9 @@ function registerChatKitV1Routes(server, options) {
         await store.deleteThread(threadRef, buildContext(request));
         // OpenAI style: return a success object (keep simple)
         sendJson(response, 200, { success: true });
-    });
+    }));
     // GET /v1/chatkit/threads/:thread_id/items
-    server.get('/v1/chatkit/threads/:thread_id/items', async (request, response, params) => {
+    server.get('/v1/chatkit/threads/:thread_id/items', (0, PodAccessFailureResponse_1.guardPodAccessRoute)(async (request, response, params) => {
         const url = new URL(request.url ?? '', `http://${request.headers.host}`);
         const threadRef = getThreadRefFromRequest(request, response, params.thread_id);
         if (!threadRef) {
@@ -83,7 +84,7 @@ function registerChatKitV1Routes(server, options) {
             has_more: page.has_more,
             after: page.after,
         });
-    });
+    }));
 }
 function parseOptionalInt(value) {
     if (!value) {

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

@@ -1,4 +1,7 @@
 import { getLoggerFor } from 'global-logger-factory';
+import { type EndpointReachabilityResult } from '../network/EndpointReachabilityProbe';
+import { type TunnelClientInspection } from '../../tunnel/TunnelClientManager';
+import type { TunnelProviderId } from '../../tunnel/TunnelProviderCatalog';
 import type { ApiServer } from '../ApiServer';
 import type { AuthContext } from '../auth/AuthContext';
 import { type TunnelProviderDescriptor } from '../../tunnel/TunnelProviderCatalog';
@@ -109,7 +112,15 @@ export interface NetworkDiagnosticCheckResult {
     label: string;
     status: DiagnosticStatus;
     detail?: string;
-    durationMs?: number;
+    /**
+     * How long the check itself took — **not** a network latency (audit N12).
+     *
+     * These checks read local state (is an address configured, what does the TLS/DNS/tunnel
+     * capability say); a duration here says nothing about reachability, so it is named after the
+     * check and consumers must not render it as a round-trip time. A real probe would have to add
+     * its own measurement.
+     */
+    checkDurationMs?: number;
     checkedAt?: string;
 }
 export interface NetworkDiagnosticCheck {
@@ -150,6 +161,25 @@ export interface NetworkPublicAddressReaderOptions {
 }
 export interface NetworkSettingsHandlerOptions {
     endpoint: string | (() => string | undefined);
+    /**
+     * On-demand reachability probe for the declared public entry (audit N12).
+     *
+     * It runs only when the operator triggers a diagnose pass — never on a timer — and defaults to
+     * the public-address-only probe; tests inject a stub.
+     */
+    endpointReachabilityProbe?: (endpoint: string) => Promise<EndpointReachabilityResult>;
+    /**
+     * Tunnel-client plugin actions for the settings page (audit N16): list where each provider's
+     * client would come from, and install one on request. Injectable for tests.
+     */
+    tunnelClients?: {
+        inspectAll: () => Promise<TunnelClientInspection[]>;
+        install: (provider: TunnelProviderId) => Promise<{
+            installedPath: string;
+            version?: string;
+            sourceUrl: string;
+        }>;
+    };
     localAddresses?: () => string[];
     lanAddresses?: () => string[];
     publicAddresses?: () => string[];

package/dist/api/handlers/NetworkSettingsHandler.js

@@ -12,6 +12,8 @@ exports.createCertificateCapability = createCertificateCapability;
 exports.redactSecretText = redactSecretText;
 const node_os_1 = require("node:os");
 const global_logger_factory_1 = require("global-logger-factory");
+const EndpointReachabilityProbe_1 = require("../network/EndpointReachabilityProbe");
+const TunnelClientManager_1 = require("../../tunnel/TunnelClientManager");
 const readBoundedJsonBody_1 = require("../http/readBoundedJsonBody");
 const AdminHandler_1 = require("./AdminHandler");
 const TunnelProviderCatalog_1 = require("../../tunnel/TunnelProviderCatalog");
@@ -66,6 +68,46 @@ function registerNetworkSettingsRoutes(server, options) {
             sendJson(response, 500, { error: 'Failed to run network diagnostics' });
         }
     }, { optionalAuth: true });
+    // The tunnel-client plugin actions live next to the tunnel configuration they serve: one
+    // "check" that says where each client comes from, one "download" that installs it (N16).
+    server.get('/api/network/settings/tunnel-clients', async (request, response) => {
+        if (!await requireNetworkPermission(request, response, authorizer, 'read', options.internalAdminAuthSecret)) {
+            return;
+        }
+        try {
+            const manager = options.tunnelClients ?? new TunnelClientManager_1.TunnelClientManager();
+            sendJson(response, 200, { clients: await manager.inspectAll() });
+        }
+        catch (error) {
+            logger.error(`Failed to inspect tunnel clients: ${redactSecretText(error)}`);
+            sendJson(response, 500, { error: 'Failed to inspect tunnel clients' });
+        }
+    }, { optionalAuth: true });
+    server.post('/api/network/settings/tunnel-clients/:provider/install', async (request, response, params) => {
+        const provider = String(params?.provider ?? '');
+        const known = ['ngrok', 'cloudflare', 'sakura_frp', 'frp'].includes(provider);
+        if (!known) {
+            sendJson(response, 404, { error: `Unknown tunnel provider: ${provider}` });
+            return;
+        }
+        if (!await requireNetworkPermission(request, response, authorizer, 'write', options.internalAdminAuthSecret)) {
+            return;
+        }
+        try {
+            const manager = options.tunnelClients ?? new TunnelClientManager_1.TunnelClientManager();
+            const installed = await manager.install(provider);
+            sendJson(response, 200, {
+                installed,
+                clients: await manager.inspectAll(),
+            });
+        }
+        catch (error) {
+            // A refused download is a normal answer (no pinned asset), not a server fault.
+            const message = redactSecretText(error);
+            logger.warn(`Tunnel client install refused for ${provider}: ${message}`);
+            sendJson(response, 400, { error: message });
+        }
+    }, { optionalAuth: true });
     if (options.certificateRenewer) {
         server.post('/api/network/settings/certificate/renew', async (request, response) => {
             if (!await requireNetworkPermission(request, response, authorizer, 'write', options.internalAdminAuthSecret)) {
@@ -344,6 +386,28 @@ function buildDefaultDiagnostics(options, logger) {
                     : { status: 'unsupported', detail: 'endpoint_unavailable' };
             },
         },
+        {
+            // Only runs because the operator asked for a diagnose pass; it never polls. The verdict
+            // is deliberately "from this node": a node reaching its own public entry says nothing
+            // about a remote user's path (NAT hairpin), so the wording keeps that distinction.
+            id: 'endpoint-reachability',
+            label: 'Endpoint reachability from this node',
+            run: async () => {
+                const endpoint = normalizeEndpoint(resolveValue(options.endpoint));
+                if (!endpoint) {
+                    return { status: 'unsupported', detail: 'endpoint_unavailable' };
+                }
+                const probe = options.endpointReachabilityProbe ?? EndpointReachabilityProbe_1.probeEndpointReachability;
+                const result = await probe(endpoint);
+                if (result.verdict === 'reachable-from-this-node') {
+                    return { status: 'ok', detail: result.detail };
+                }
+                if (result.verdict === 'blocked') {
+                    return { status: 'unsupported', detail: result.detail };
+                }
+                return { status: 'warning', detail: result.detail };
+            },
+        },
         {
             id: 'tls',
             label: 'TLS',
@@ -363,7 +427,7 @@ function buildDefaultDiagnostics(options, logger) {
 }
 async function runDiagnostic(check, logger) {
     const startedAt = Date.now();
-    const evidence = () => ({ durationMs: Math.max(0, Date.now() - startedAt), checkedAt: new Date().toISOString() });
+    const evidence = () => ({ checkDurationMs: Math.max(0, Date.now() - startedAt), checkedAt: new Date().toISOString() });
     try {
         const result = await check.run();
         if (typeof result === 'string') {
@@ -382,14 +446,23 @@ async function runDiagnostic(check, logger) {
         return { id: check.id, label: check.label, status: 'error', detail: redactSecretText(error), ...evidence() };
     }
 }
+/**
+ * Maps a provider capability onto a diagnostic level.
+ *
+ * Only statuses that positively mean "verified" become `ok`, and known-bad ones become `error`
+ * (an invalid or expired certificate is a failure, not something to warn about). Anything else
+ * stays a warning: a status we cannot place must never be rendered as a pass (audit N12).
+ */
+const VERIFIED_CAPABILITY_STATUSES = new Set(['active', 'valid', 'synced', 'direct', 'ready']);
+const FAILED_CAPABILITY_STATUSES = new Set(['error', 'invalid', 'failed', 'expired', 'untrusted', 'mismatch']);
 function capabilityToDiagnostic(capability) {
     if (!capability.supported) {
         return { status: 'unsupported', detail: capability.status };
     }
-    if (capability.status === 'active' || capability.status === 'valid' || capability.status === 'synced' || capability.status === 'direct') {
+    if (VERIFIED_CAPABILITY_STATUSES.has(capability.status)) {
         return { status: 'ok', detail: capability.status };
     }
-    if (capability.status === 'error') {
+    if (FAILED_CAPABILITY_STATUSES.has(capability.status)) {
         return { status: 'error', detail: capability.status };
     }
     return { status: 'warning', detail: capability.status };

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

@@ -0,0 +1,24 @@
+import type { ServerResponse } from 'node:http';
+import type { RouteHandler } from '../ApiServer';
+/** The wire code callers already report when Xpod cannot open the Pod for them. */
+export declare const SERVICE_ACCESS_MISSING = "service_access_missing";
+export interface PodAccessFailureResponse {
+    status: number;
+    error: string;
+}
+/**
+ * Status and code for a Pod access failure, or undefined when the error is something else.
+ *
+ * A Pod-backed surface that cannot reach the Pod has to say so. Answering an empty list instead
+ * leaves the caller with a state it cannot act on, and the reason codes exist precisely so the
+ * caller can tell "sign in" from "grant this app access to your Pod".
+ */
+export declare function podAccessFailureResponse(error: unknown): PodAccessFailureResponse | undefined;
+/** Answer with the mapped failure. Returns false when the error is not a Pod access failure. */
+export declare function sendPodAccessFailure(response: ServerResponse, error: unknown): boolean;
+/**
+ * Wrap a route so a Pod access failure answers with the mapped status instead of a generic 500.
+ *
+ * Anything else keeps propagating, so unrelated bugs are not reported as missing Pod access.
+ */
+export declare function guardPodAccessRoute(handler: RouteHandler): RouteHandler;

package/dist/api/handlers/PodAccessFailureResponse.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVICE_ACCESS_MISSING = void 0;
+exports.podAccessFailureResponse = podAccessFailureResponse;
+exports.sendPodAccessFailure = sendPodAccessFailure;
+exports.guardPodAccessRoute = guardPodAccessRoute;
+const CallerPodAccess_1 = require("../ai-gateway/auth/CallerPodAccess");
+const OwnerPodAccess_1 = require("../ai-gateway/pod/OwnerPodAccess");
+/** The wire code callers already report when Xpod cannot open the Pod for them. */
+exports.SERVICE_ACCESS_MISSING = 'service_access_missing';
+/**
+ * Status and code for a Pod access failure, or undefined when the error is something else.
+ *
+ * A Pod-backed surface that cannot reach the Pod has to say so. Answering an empty list instead
+ * leaves the caller with a state it cannot act on, and the reason codes exist precisely so the
+ * caller can tell "sign in" from "grant this app access to your Pod".
+ */
+function podAccessFailureResponse(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!(0, OwnerPodAccess_1.isPodAccessFailure)(message)) {
+        return undefined;
+    }
+    if (message.startsWith(CallerPodAccess_1.CALLER_POD_ACCESS_UNAVAILABLE)) {
+        return { status: 401, error: 'authentication_required' };
+    }
+    if (message.startsWith(CallerPodAccess_1.CALLER_OWNER_MISMATCH)) {
+        return { status: 403, error: 'pod_owner_mismatch' };
+    }
+    return { status: 403, error: exports.SERVICE_ACCESS_MISSING };
+}
+/** Answer with the mapped failure. Returns false when the error is not a Pod access failure. */
+function sendPodAccessFailure(response, error) {
+    const mapped = podAccessFailureResponse(error);
+    if (!mapped) {
+        return false;
+    }
+    response.statusCode = mapped.status;
+    response.setHeader('Content-Type', 'application/json');
+    response.end(JSON.stringify({ error: mapped.error }));
+    return true;
+}
+/**
+ * Wrap a route so a Pod access failure answers with the mapped status instead of a generic 500.
+ *
+ * Anything else keeps propagating, so unrelated bugs are not reported as missing Pod access.
+ */
+function guardPodAccessRoute(handler) {
+    return async (request, response, params) => {
+        try {
+            await handler(request, response, params);
+        }
+        catch (error) {
+            if (!sendPodAccessFailure(response, error)) {
+                throw error;
+            }
+        }
+    };
+}
+//# sourceMappingURL=PodAccessFailureResponse.js.map

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

@@ -3,6 +3,7 @@ import type { ApiServer } from '../ApiServer';
 import type { PodLookupRepository } from '../../identity/drizzle/PodLookupRepository';
 import type { UsageRepository } from '../../storage/quota/UsageRepository';
 import type { PodAccessFetchProvider } from '../ai-gateway/pod/OwnerPodAccess';
+import type { AuthContext } from '../auth/AuthContext';
 export interface PodSettingsStatus {
     identity: {
         webId: string;
@@ -43,9 +44,15 @@ export type PodAiConnectionsStatus = {
     reason: string;
 };
 export interface PodAiConnectionsStatusReader {
+    /**
+     * `auth` is the caller's own context. A signed-in user's status has to be read with the
+     * credential that user presented; without one this reports `not_configured` instead of
+     * borrowing the deployment's stored owner key.
+     */
     read(input: {
         webId: string;
         podUrl?: string;
+        auth?: AuthContext;
     }): Promise<PodAiConnectionsStatus>;
 }
 export interface PodSettingsHandlerOptions {
@@ -65,9 +72,10 @@ export declare class DrizzlePodAiConnectionsStatusReader implements PodAiConnect
         podUrl: string;
         fetch: typeof fetch;
     }) => Promise<AiConnectionsStatusDb>);
-    read({ webId, podUrl }: {
+    read({ webId, podUrl, auth }: {
         webId: string;
         podUrl?: string;
+        auth?: AuthContext;
     }): Promise<PodAiConnectionsStatus>;
 }
 type AiConnectionsStatusDb = {

package/dist/api/handlers/PodSettingsHandler.js

@@ -22,7 +22,7 @@ function registerPodSettingsRoutes(server, options) {
             const podUrl = pod?.storageUrl ?? pod?.baseUrl;
             const [storage, aiConnection] = await Promise.all([
                 readStorageStatus(options.usageRepo, pod),
-                aiConnectionStatusReader.read({ webId, podUrl }).catch((error) => {
+                aiConnectionStatusReader.read({ webId, podUrl, auth: request.auth }).catch((error) => {
                     const reason = safeAiConnectionsFailureReason(error);
                     logger.warn(`Failed to read Pod AI Connection status: ${reason}`);
                     return { status: 'error', reason };
@@ -82,8 +82,8 @@ class DrizzlePodAiConnectionsStatusReader {
         this.deployment = deployment;
         this.dbFactory = dbFactory;
     }
-    async read({ webId, podUrl }) {
-        const trustedFetch = await this.podAccess?.getPodFetch(webId);
+    async read({ webId, podUrl, auth }) {
+        const trustedFetch = await this.podAccess?.getPodFetch(webId, auth ? { auth } : {});
         if (!trustedFetch) {
             return { status: 'unsupported', reason: 'not_configured' };
         }

package/dist/api/handlers/ReachabilityHandler.js

@@ -64,6 +64,7 @@ function registerReachabilityRoutes(server, options) {
                     ...(access.kind === 'solid' ? { owner: { type: 'solid', webId: access.webId } } : {}),
                     capabilities: Array.isArray(body.capabilities) ? body.capabilities.filter((entry) => typeof entry === 'string') : [],
                     candidates: enrichP2PCandidatesWithObservedAddress(Array.isArray(body.candidates) ? body.candidates : [], resolveObservedAddress(request)),
+                    ...(typeof body.dataPlaneSecret === 'string' ? { dataPlaneSecret: body.dataPlaneSecret } : {}),
                 });
                 sendJson(response, 201, session);
             }
@@ -76,6 +77,10 @@ function registerReachabilityRoutes(server, options) {
                     sendJson(response, 429, { error: 'P2P active session limit exceeded' });
                     return;
                 }
+                if (error instanceof ReachabilitySessionService_1.InvalidP2PSessionRequestError) {
+                    sendJson(response, 400, { error: error.message });
+                    return;
+                }
                 if (error instanceof ReachabilitySessionService_1.P2PCandidateUpdateLimitExceededError) {
                     sendJson(response, 429, { error: 'P2P candidate update limit exceeded' });
                     return;

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;