@undefineds.co/xpod 0.4.13 → 0.4.15

package/dist/edge/ProbeTargetGuard.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPublicIpAddress = isPublicIpAddress;
+exports.resolveHostAddresses = resolveHostAddresses;
+exports.assertPublicProbeTarget = assertPublicProbeTarget;
+exports.createPinnedHeadProbeRequest = createPinnedHeadProbeRequest;
+const node_http_1 = __importDefault(require("node:http"));
+const node_https_1 = __importDefault(require("node:https"));
+const node_net_1 = require("node:net");
+const node_dns_1 = __importDefault(require("node:dns"));
+/**
+ * Address ranges a Cloud probe must never contact: the probe target comes from node
+ * metadata, so without this an edge node could make the cluster fetch its own private
+ * network, loopback services or the cloud metadata endpoint.
+ */
+const BLOCKED_IPV4 = new node_net_1.BlockList();
+for (const [network, prefix] of [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.0.0.0', 24],
+    ['192.0.2.0', 24],
+    ['192.168.0.0', 16],
+    ['198.18.0.0', 15],
+    ['198.51.100.0', 24],
+    ['203.0.113.0', 24],
+    ['224.0.0.0', 4],
+    ['240.0.0.0', 4],
+]) {
+    BLOCKED_IPV4.addSubnet(network, prefix, 'ipv4');
+}
+// IPv4-mapped addresses are normalized to IPv4 before checking, so the two families stay
+// in separate lists: a mixed list makes `check(ipv4Address, 'ipv4')` match IPv6 rules.
+const BLOCKED_IPV6 = new node_net_1.BlockList();
+for (const [network, prefix] of [
+    ['::', 128],
+    ['::1', 128],
+    ['64:ff9b::', 96],
+    ['fc00::', 7],
+    ['fe80::', 10],
+    ['ff00::', 8],
+    ['2001:db8::', 32],
+]) {
+    BLOCKED_IPV6.addSubnet(network, prefix, 'ipv6');
+}
+/** Whether an address is a public unicast address a Cloud probe may contact. */
+function isPublicIpAddress(address) {
+    const normalized = normalizeMappedIpv4(address);
+    const family = (0, node_net_1.isIP)(normalized);
+    if (family === 4) {
+        return !BLOCKED_IPV4.check(normalized, 'ipv4');
+    }
+    if (family === 6) {
+        return !BLOCKED_IPV6.check(normalized, 'ipv6');
+    }
+    return false;
+}
+function normalizeMappedIpv4(address) {
+    const match = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/iu.exec(address);
+    return match ? match[1] : address;
+}
+/** Resolves every address of a probe hostname; injected in tests. */
+async function resolveHostAddresses(hostname) {
+    const records = await node_dns_1.default.promises.lookup(hostname, { all: true });
+    return records.map((record) => record.address);
+}
+/**
+ * Decides whether a probe target may be contacted.
+ *
+ * Every resolved address has to be public, so a hostname that mixes public and private
+ * records is refused instead of racing whichever record the connection picks.
+ */
+async function assertPublicProbeTarget(url, resolveAddresses = resolveHostAddresses) {
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        return { allowed: false, reason: `unsupported-scheme:${url.protocol}` };
+    }
+    const hostname = url.hostname.replace(/^\[/u, '').replace(/\]$/u, '');
+    if ((0, node_net_1.isIP)(hostname) !== 0) {
+        return isPublicIpAddress(hostname)
+            ? { allowed: true, address: hostname }
+            : { allowed: false, reason: `non-public-address:${hostname}` };
+    }
+    let addresses;
+    try {
+        addresses = await resolveAddresses(hostname);
+    }
+    catch (error) {
+        return { allowed: false, reason: `unresolvable:${error.message}` };
+    }
+    if (addresses.length === 0) {
+        return { allowed: false, reason: 'unresolvable' };
+    }
+    const blocked = addresses.find((address) => !isPublicIpAddress(address));
+    if (blocked) {
+        return { allowed: false, reason: `non-public-address:${blocked}` };
+    }
+    return { allowed: true, address: addresses[0] };
+}
+/**
+ * HEAD request pinned to a validated address.
+ *
+ * Pinning is what makes the DNS check meaningful: without it the client would resolve the
+ * hostname a second time and a rebinding answer could still reach a private address.
+ */
+function createPinnedHeadProbeRequest() {
+    return (url, { address, timeoutMs }) => new Promise((resolve, reject) => {
+        const transport = url.protocol === 'https:' ? node_https_1.default : node_http_1.default;
+        const request = transport.request({
+            protocol: url.protocol,
+            hostname: url.hostname,
+            port: url.port || (url.protocol === 'https:' ? 443 : 80),
+            path: `${url.pathname}${url.search}`,
+            method: 'HEAD',
+            timeout: timeoutMs,
+            lookup: (_hostname, options, callback) => {
+                const entry = { address, family: (0, node_net_1.isIP)(address) === 6 ? 6 : 4 };
+                // Node asks for every family when happy-eyeballs is enabled.
+                if (options && typeof options === 'object' && options.all) {
+                    callback(null, [entry]);
+                    return;
+                }
+                callback(null, entry.address, entry.family);
+            },
+        }, (response) => {
+            response.resume();
+            resolve({
+                status: response.statusCode ?? 0,
+                location: typeof response.headers.location === 'string' ? response.headers.location : undefined,
+            });
+        });
+        request.on('timeout', () => request.destroy(new Error('probe-timeout')));
+        request.on('error', reject);
+        request.end();
+    });
+}
+//# sourceMappingURL=ProbeTargetGuard.js.map

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

@@ -0,0 +1,16 @@
+import type { PodLookupRepository } from '../../identity/drizzle/PodLookupRepository';
+/**
+ * Whether a Solid principal may act on an edge node.
+ *
+ * Reachability sessions expose a node's private candidates, so "is authenticated" is not
+ * enough: the caller has to be related to that node (Pod ownership, or an explicit grant
+ * once one exists).
+ */
+export type NodeAccessResolver = (nodeId: string, webId: string) => Promise<boolean>;
+/**
+ * Authorizes a WebID for a node when one of the node's Pods is owned by that WebID.
+ *
+ * A missing repository resolves to "no access" rather than "no restriction": the caller
+ * decides what to do with an unprovable relationship, and the reachability handler denies.
+ */
+export declare function createPodOwnershipNodeAccessResolver(podLookupRepository: Pick<PodLookupRepository, 'listAllPods'> | undefined): NodeAccessResolver;

package/dist/edge/reachability/NodeAccessResolver.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPodOwnershipNodeAccessResolver = createPodOwnershipNodeAccessResolver;
+const global_logger_factory_1 = require("global-logger-factory");
+/**
+ * Authorizes a WebID for a node when one of the node's Pods is owned by that WebID.
+ *
+ * A missing repository resolves to "no access" rather than "no restriction": the caller
+ * decides what to do with an unprovable relationship, and the reachability handler denies.
+ */
+function createPodOwnershipNodeAccessResolver(podLookupRepository) {
+    const logger = (0, global_logger_factory_1.getLoggerFor)('NodeAccessResolver');
+    return async (nodeId, webId) => {
+        if (!podLookupRepository) {
+            return false;
+        }
+        try {
+            const pods = await podLookupRepository.listAllPods();
+            return pods.some((pod) => {
+                const hosted = pod.nodeId === nodeId || pod.edgeNodeId === nodeId;
+                return hosted && (pod.webId === webId || (pod.webIds ?? []).includes(webId));
+            });
+        }
+        catch (error) {
+            logger.warn(`Failed to resolve node access for ${nodeId}/${webId}: ${error.message}`);
+            return false;
+        }
+    };
+}
+//# sourceMappingURL=NodeAccessResolver.js.map

package/dist/edge/reachability/ReachabilitySessionService.js

@@ -38,7 +38,10 @@ class ReachabilitySessionService {
             throw new P2PCandidateSessionLimitExceededError('P2P candidate session limit exceeded');
         }
         const routeSet = (0, RouteSetBuilder_1.buildRouteSet)(source, {
-            audience: 'managed',
+            // The node publishes its own access points, loopback included: a client on this host
+            // reaches the node there, and a client elsewhere ranks the path out by probing it
+            // (`docs/multi-channel-access.md`).
+            audience: 'local',
             baseStorageDomain: this.options.baseStorageDomain,
             now: createdAt,
         });

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

@@ -1,2 +1,19 @@
-import type { BuildRouteSetOptions, BuildRouteSetSource, RouteSet } from './types';
+import type { AccessRoute, BuildRouteSetOptions, BuildRouteSetSource, RouteSet } from './types';
 export declare function buildRouteSet(source: BuildRouteSetSource, options?: BuildRouteSetOptions): RouteSet;
+export interface BuildPublicAccessRoutesOptions {
+    /** The node's canonical public URL, when it has one. */
+    canonicalUrl?: string;
+    /** A provider confirmed the canonical URL is proxy-ready right now. */
+    publicRouteAvailable?: boolean;
+    /** Endpoint of the user's own tunnel, when one is connected. */
+    tunnelEndpoint?: string;
+}
+/**
+ * Access points a node can prove from its own configuration: the canonical public
+ * URL and the user's tunnel endpoint.
+ *
+ * Loopback and LAN are deliberately absent: whether either works depends on where
+ * the client stands, so the client derives them from its own position instead of
+ * being told about paths it may not have (`docs/multi-channel-access.md`).
+ */
+export declare function buildPublicAccessRoutes(options: BuildPublicAccessRoutesOptions): AccessRoute[];

package/dist/edge/reachability/RouteSetBuilder.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildRouteSet = buildRouteSet;
+exports.buildPublicAccessRoutes = buildPublicAccessRoutes;
 const DEFAULT_PRIORITY = {
     loopback: 10,
     lan: 20,
@@ -34,6 +35,44 @@ function buildRouteSet(source, options = {}) {
         routes,
     };
 }
+/**
+ * Access points a node can prove from its own configuration: the canonical public
+ * URL and the user's tunnel endpoint.
+ *
+ * Loopback and LAN are deliberately absent: whether either works depends on where
+ * the client stands, so the client derives them from its own position instead of
+ * being told about paths it may not have (`docs/multi-channel-access.md`).
+ */
+function buildPublicAccessRoutes(options) {
+    const canonicalUrl = normalizeUrlString(options.canonicalUrl);
+    const tunnelEndpoint = normalizeUrlString(options.tunnelEndpoint);
+    const routes = [];
+    if (canonicalUrl) {
+        routes.push({
+            id: 'public-direct',
+            kind: 'public-direct',
+            canonicalUrl,
+            targetUrl: canonicalUrl,
+            priority: DEFAULT_PRIORITY['public-direct'],
+            requiresManagedClient: false,
+            visibility: 'public',
+            health: options.publicRouteAvailable ? 'healthy' : 'unknown',
+        });
+    }
+    if (tunnelEndpoint && tunnelEndpoint !== canonicalUrl) {
+        routes.push({
+            id: 'user-tunnel',
+            kind: 'user-tunnel',
+            canonicalUrl: canonicalUrl ?? tunnelEndpoint,
+            targetUrl: tunnelEndpoint,
+            priority: DEFAULT_PRIORITY['user-tunnel'],
+            requiresManagedClient: false,
+            visibility: 'public',
+            health: 'healthy',
+        });
+    }
+    return routes;
+}
 function routesFromMetadata(source, canonicalUrl, metadata) {
     const rawRoutes = Array.isArray(metadata.routes) ? metadata.routes : [];
     return rawRoutes
@@ -165,6 +204,14 @@ function defaultVisibility(kind) {
     return PUBLIC_KINDS.has(kind) ? 'public' : 'authorized-client';
 }
 function isVisibleToAudience(route, audience) {
+    if (audience === 'local') {
+        return true;
+    }
+    // `local-only` means loopback: usable on the node's own host and nowhere else,
+    // so it is never offered to a client on another machine.
+    if (route.visibility === 'local-only') {
+        return false;
+    }
     if (audience === 'managed') {
         return true;
     }

package/dist/edge/reachability/RouteSetBuilder.jsonld

@@ -0,0 +1,29 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/edge/reachability/RouteSetBuilder.jsonld#BuildPublicAccessRoutesOptions",
+      "@type": "AbstractClass",
+      "requireElement": "BuildPublicAccessRoutesOptions",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/reachability/RouteSetBuilder.jsonld#BuildPublicAccessRoutesOptions__member_canonicalUrl",
+          "memberFieldName": "canonicalUrl"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/RouteSetBuilder.jsonld#BuildPublicAccessRoutesOptions__member_publicRouteAvailable",
+          "memberFieldName": "publicRouteAvailable"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/RouteSetBuilder.jsonld#BuildPublicAccessRoutesOptions__member_tunnelEndpoint",
+          "memberFieldName": "tunnelEndpoint"
+        }
+      ],
+      "constructorArguments": []
+    }
+  ]
+}

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

@@ -3,7 +3,8 @@ export type AccessRouteVisibility = 'local-only' | 'same-account' | 'authorized-
 export type AccessRouteHealth = 'unknown' | 'healthy' | 'degraded' | 'unreachable';
 export interface AccessRoute {
     id: string;
-    nodeId: string;
+    /** Absent while the node has no identity yet, as on a standalone Local runtime. */
+    nodeId?: string;
     canonicalUrl: string;
     kind: AccessRouteKind;
     targetUrl: string;
@@ -21,7 +22,12 @@ export interface RouteSet {
     generatedAt: string;
     routes: AccessRoute[];
 }
-export type RouteAudience = 'public' | 'managed';
+/**
+ * Who is asking for routes. `local` is the node's own host, which is the only
+ * place a loopback access point means anything; `managed` is an authorized
+ * client elsewhere, and `public` is unauthenticated discovery.
+ */
+export type RouteAudience = 'public' | 'managed' | 'local';
 export interface BuildRouteSetSource {
     nodeId: string;
     canonicalUrl?: string;

package/dist/http/SubgraphSparqlHttpHandler.d.ts

@@ -1,5 +1,5 @@
 import { HttpHandler } from '@solid/community-server';
-import type { HttpHandlerInput, HttpRequest, HttpResponse } from '@solid/community-server';
+import type { HttpHandlerInput } from '@solid/community-server';
 import type { ActivityEmitter, CredentialsExtractor, PermissionReader, Authorizer } from '@solid/community-server';
 import { SubgraphQueryEngine } from '../storage/sparql/SubgraphQueryEngine';
 import { MixDataAccessor } from '../storage/accessors/MixDataAccessor';
@@ -14,22 +14,6 @@ interface SubgraphSparqlHttpHandlerOptions {
     usageDbUrl?: string;
     defaultAccountBandwidthLimitBps?: number | null;
 }
-export interface TrustedSubgraphSparqlHandler {
-    handleTrustedInternalSelect(input: {
-        ownerWebId: string;
-        endpointUrl: string;
-        query: string;
-        request: HttpRequest;
-        response: HttpResponse;
-    }): Promise<void>;
-    handleTrustedInternalUpdate(input: {
-        ownerWebId: string;
-        endpointUrl: string;
-        query: string;
-        request: HttpRequest;
-        response: HttpResponse;
-    }): Promise<void>;
-}
 export declare class SubgraphSparqlHttpHandler extends HttpHandler {
     protected readonly logger: import("global-logger-factory").Logger<unknown>;
     private readonly engine;
@@ -47,14 +31,6 @@ export declare class SubgraphSparqlHttpHandler extends HttpHandler {
     constructor(queryEngine: SubgraphQueryEngine, credentialsExtractor: CredentialsExtractor, permissionReader: PermissionReader, authorizer: Authorizer, options?: SubgraphSparqlHttpHandlerOptions, updateAuthority?: MixDataAccessor, emitter?: ActivityEmitter);
     canHandle({ request }: HttpHandlerInput): Promise<void>;
     handle({ request, response }: HttpHandlerInput): Promise<void>;
-    /**
-     * Execute the model collection SELECT after InternalPodDataHttpHandler has
-     * verified the signed owner intent. This is deliberately not reachable from
-     * the normal HTTP routing path and performs its own exact owner/endpoint
-     * validation before bypassing caller credentials.
-     */
-    handleTrustedInternalSelect(input: Parameters<TrustedSubgraphSparqlHandler['handleTrustedInternalSelect']>[0]): Promise<void>;
-    handleTrustedInternalUpdate(input: Parameters<TrustedSubgraphSparqlHandler['handleTrustedInternalUpdate']>[0]): Promise<void>;
     private sendErrorResponse;
     private acceptsJson;
     private executeSelect;

package/dist/http/SubgraphSparqlHttpHandler.js

@@ -14,7 +14,6 @@ const db_1 = require("../identity/drizzle/db");
 const PodLookupRepository_1 = require("../identity/drizzle/PodLookupRepository");
 const UsageRepository_1 = require("../storage/quota/UsageRepository");
 const BandwidthThrottleTransform_1 = require("../util/stream/BandwidthThrottleTransform");
-const AiConnectionsServiceAccess_1 = require("../api/ai-gateway/service-access/AiConnectionsServiceAccess");
 const ALLOWED_METHODS = ['GET', 'POST', 'OPTIONS'];
 const MODEL_COLLECTION_SUFFIX = '/settings/providers/-/sparql';
 const SETTINGS_COLLECTION_SUFFIX = '/settings/-/sparql';
@@ -141,64 +140,6 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
             throw error;
         }
     }
-    /**
-     * Execute the model collection SELECT after InternalPodDataHttpHandler has
-     * verified the signed owner intent. This is deliberately not reachable from
-     * the normal HTTP routing path and performs its own exact owner/endpoint
-     * validation before bypassing caller credentials.
-     */
-    async handleTrustedInternalSelect(input) {
-        const target = trustedSelectTarget(input.ownerWebId, input.endpointUrl);
-        if (!target) {
-            throw new community_server_2.BadRequestHttpError('Trusted SPARQL endpoint is outside the owner Pod.');
-        }
-        const query = input.query.trim();
-        if (!query || (target.query && query !== target.query)) {
-            throw new community_server_2.BadRequestHttpError('A trusted SPARQL query is required.');
-        }
-        const parsed = new sparqljs_1.Parser({ baseIRI: target.baseUrl }).parse(query);
-        if (parsed.type !== 'query' || parsed.queryType !== 'SELECT') {
-            throw new community_server_2.BadRequestHttpError('Trusted SPARQL access only supports SELECT queries.');
-        }
-        const context = await this.resolveUsageContext(target.basePath);
-        await this.recordBandwidth(context, Buffer.byteLength(query, 'utf8'), 0);
-        await this.executeSelect(input.request, {
-            basePath: target.basePath,
-            baseUrl: target.baseUrl,
-            ...(target.sourceUri === undefined ? {} : { sourceUri: target.sourceUri }),
-            defaultDataset: target.defaultDataset,
-            query,
-            origin: target.origin,
-            method: 'GET',
-            ingressBytes: Buffer.byteLength(query, 'utf8'),
-        }, input.response, context, true);
-    }
-    async handleTrustedInternalUpdate(input) {
-        const target = trustedSettingsCollectionTarget(input.ownerWebId, input.endpointUrl, false);
-        if (!target) {
-            throw new community_server_2.BadRequestHttpError('Trusted settings update endpoint is outside the owner Pod.');
-        }
-        const query = input.query.trim();
-        if (!query) {
-            throw new community_server_2.BadRequestHttpError('A trusted settings update is required.');
-        }
-        const parsed = new sparqljs_1.Parser({ baseIRI: target.baseUrl }).parse(query);
-        if (parsed.type !== 'update') {
-            throw new community_server_2.BadRequestHttpError('Trusted settings access only supports UPDATE operations.');
-        }
-        const context = await this.resolveUsageContext(target.basePath);
-        const ingressBytes = Buffer.byteLength(query, 'utf8');
-        await this.recordBandwidth(context, ingressBytes, 0);
-        await this.executeUpdate({
-            basePath: target.basePath,
-            baseUrl: target.baseUrl,
-            defaultDataset: target.defaultDataset,
-            query,
-            origin: target.origin,
-            method: 'POST',
-            ingressBytes,
-        }, parsed, input.request, input.response, context, true);
-    }
     sendErrorResponse(request, response, statusCode, message, jsonPayload) {
         response.statusCode = statusCode;
         if (this.acceptsJson(request)) {
@@ -1127,47 +1068,6 @@ class SubgraphSparqlHttpHandler extends community_server_1.HttpHandler {
 }
 exports.SubgraphSparqlHttpHandler = SubgraphSparqlHttpHandler;
 SubgraphSparqlHttpHandler.XSD_STRING = 'http://www.w3.org/2001/XMLSchema#string';
-function trustedSelectTarget(ownerWebId, endpointUrl) {
-    return trustedGatewayAccessKeyDocumentTarget(ownerWebId, endpointUrl) ??
-        trustedModelCollectionTarget(ownerWebId, endpointUrl) ??
-        trustedSettingsCollectionTarget(ownerWebId, endpointUrl, true);
-}
-function trustedGatewayAccessKeyDocumentTarget(ownerWebId, endpointUrl) {
-    let owner;
-    let endpoint;
-    try {
-        owner = new URL(ownerWebId);
-        endpoint = new URL(endpointUrl);
-    }
-    catch {
-        return undefined;
-    }
-    if ((owner.protocol !== 'http:' && owner.protocol !== 'https:') ||
-        owner.hash !== '#me' || !owner.pathname.endsWith('/profile/card') ||
-        endpoint.username || endpoint.password || endpoint.hash ||
-        !(0, AiConnectionsServiceAccess_1.isGatewayAccessKeySparqlEndpoint)(ownerWebId, endpoint)) {
-        return undefined;
-    }
-    const keys = Array.from(endpoint.searchParams.keys());
-    if (keys.length > 0 && (keys.length !== 1 || keys[0] !== 'query' || !endpoint.searchParams.get('query')?.trim())) {
-        return undefined;
-    }
-    const basePath = endpoint.pathname.slice(0, -'/-/sparql'.length);
-    return {
-        basePath,
-        baseUrl: `${endpoint.origin}${basePath}`,
-        sourceUri: `${endpoint.origin}${basePath}`,
-        defaultDataset: 'exactSource',
-        origin: endpoint.origin,
-        query: endpoint.searchParams.get('query')?.trim() ?? '',
-    };
-}
-function trustedModelCollectionTarget(ownerWebId, endpointUrl) {
-    return trustedCollectionTarget(ownerWebId, endpointUrl, MODEL_COLLECTION_SUFFIX, true);
-}
-function trustedSettingsCollectionTarget(ownerWebId, endpointUrl, allowQuery) {
-    return trustedCollectionTarget(ownerWebId, endpointUrl, SETTINGS_COLLECTION_SUFFIX, allowQuery);
-}
 function trustedCollectionTarget(ownerWebId, endpointUrl, suffix, allowQuery) {
     let owner;
     let endpoint;

package/dist/http/SubgraphSparqlHttpHandler.jsonld

@@ -200,14 +200,6 @@
           "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_handle",
           "memberFieldName": "handle"
         },
-        {
-          "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_handleTrustedInternalSelect",
-          "memberFieldName": "handleTrustedInternalSelect"
-        },
-        {
-          "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_handleTrustedInternalUpdate",
-          "memberFieldName": "handleTrustedInternalUpdate"
-        },
         {
           "@id": "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld#SubgraphSparqlHttpHandler__member_sendErrorResponse",
           "memberFieldName": "sendErrorResponse"

package/dist/identity/drizzle/PodInterfaceKeyRepository.d.ts

@@ -0,0 +1,33 @@
+import type { IdentityDatabase } from './db';
+/**
+ * The interface access key a Pod grants its owner's server-side components.
+ *
+ * It is an ordinary Pod credential - the same kind a browser holds - so the server reaches the
+ * Pod through the standard interface as that user. The ciphertext lives here rather than in the
+ * Pod, because this key is what opens the Pod.
+ */
+export interface PodInterfaceKeyRecord {
+    ownerWebId: string;
+    clientId: string;
+    /** Vault-sealed JSON `{ clientSecret }`. */
+    sealedSecret: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface PodInterfaceKeyRepositoryPort {
+    read(ownerWebId: string): Promise<PodInterfaceKeyRecord | undefined>;
+    write(record: Omit<PodInterfaceKeyRecord, 'createdAt' | 'updatedAt'>): Promise<void>;
+    remove(ownerWebId: string): Promise<void>;
+}
+export declare class PodInterfaceKeyRepository implements PodInterfaceKeyRepositoryPort {
+    private readonly db;
+    private readonly logger;
+    private readonly schema;
+    private readonly ready;
+    private initError?;
+    constructor(db: IdentityDatabase);
+    read(ownerWebId: string): Promise<PodInterfaceKeyRecord | undefined>;
+    write(record: Omit<PodInterfaceKeyRecord, 'createdAt' | 'updatedAt'>): Promise<void>;
+    remove(ownerWebId: string): Promise<void>;
+    private ensureReady;
+}

package/dist/identity/drizzle/PodInterfaceKeyRepository.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PodInterfaceKeyRepository = void 0;
+const drizzle_orm_1 = require("drizzle-orm");
+const global_logger_factory_1 = require("global-logger-factory");
+const db_1 = require("./db");
+class PodInterfaceKeyRepository {
+    constructor(db) {
+        this.db = db;
+        this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
+        this.schema = (0, db_1.getSchema)(db);
+        // Bootstrap is lazy, and its failure belongs to the first caller that needs the table.
+        // Leaving the rejection unobserved would surface as an unhandled rejection from a
+        // constructor nobody awaits, which is both louder and less useful than a read error.
+        this.ready = (0, db_1.ensurePodInterfaceKeyTable)(db).catch((error) => {
+            this.initError = error;
+        });
+    }
+    async read(ownerWebId) {
+        await this.ensureReady();
+        const rows = await this.db
+            .select()
+            .from(this.schema.podInterfaceKeys)
+            .where((0, drizzle_orm_1.eq)(this.schema.podInterfaceKeys.ownerWebId, ownerWebId))
+            .limit(1);
+        const row = rows[0];
+        if (!row) {
+            return undefined;
+        }
+        return {
+            ownerWebId: String(row.ownerWebId),
+            clientId: String(row.clientId),
+            sealedSecret: String(row.sealedSecret),
+            createdAt: (0, db_1.fromDbTimestamp)(row.createdAt) ?? new Date(),
+            updatedAt: (0, db_1.fromDbTimestamp)(row.updatedAt) ?? new Date(),
+        };
+    }
+    async write(record) {
+        await this.ensureReady();
+        const existing = await this.read(record.ownerWebId);
+        if (existing) {
+            await this.db
+                .update(this.schema.podInterfaceKeys)
+                .set({
+                clientId: record.clientId,
+                sealedSecret: record.sealedSecret,
+                updatedAt: (0, db_1.toDbTimestamp)(this.db, new Date()),
+            })
+                .where((0, drizzle_orm_1.eq)(this.schema.podInterfaceKeys.ownerWebId, record.ownerWebId));
+            this.logger.info(`Rotated the Pod interface key for ${record.ownerWebId}`);
+            return;
+        }
+        await this.db.insert(this.schema.podInterfaceKeys).values({
+            ownerWebId: record.ownerWebId,
+            clientId: record.clientId,
+            sealedSecret: record.sealedSecret,
+            createdAt: (0, db_1.toDbTimestamp)(this.db, new Date()),
+            updatedAt: (0, db_1.toDbTimestamp)(this.db, new Date()),
+        });
+        this.logger.info(`Stored a Pod interface key for ${record.ownerWebId}`);
+    }
+    async remove(ownerWebId) {
+        await this.ensureReady();
+        await this.db
+            .delete(this.schema.podInterfaceKeys)
+            .where((0, drizzle_orm_1.eq)(this.schema.podInterfaceKeys.ownerWebId, ownerWebId));
+    }
+    async ensureReady() {
+        await this.ready;
+        if (this.initError) {
+            throw this.initError instanceof Error
+                ? this.initError
+                : new Error(`pod_interface_key_table_unavailable:${String(this.initError)}`);
+        }
+    }
+}
+exports.PodInterfaceKeyRepository = PodInterfaceKeyRepository;
+//# sourceMappingURL=PodInterfaceKeyRepository.js.map

package/dist/identity/drizzle/db.d.ts

@@ -58,6 +58,13 @@ export declare function executeQuery<T = Record<string, unknown>>(db: IdentityDa
  */
 export declare function executeStatement(db: IdentityDatabase, query: SQL): Promise<void>;
 export declare function executePostgresLockedStatements(db: IdentityDatabase, lockKey: number, statements: string[]): Promise<void>;
+/**
+ * Creates the per-owner interface-key table.
+ *
+ * The table holds the owner's Pod credential, which the runtime needs *before* it can read
+ * anything inside that Pod, so it is created on first use rather than by a Pod-side migration.
+ */
+export declare function ensurePodInterfaceKeyTable(db: IdentityDatabase): Promise<void>;
 export declare function ensureCloudClusterTables(db: IdentityDatabase): Promise<void>;
 /**
  * Convert a Date to a value suitable for the database.