@undefineds.co/xpod 0.4.14 → 0.4.16

package/dist/api/auth/ClientCredentialsAuthenticator.js

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

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

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

package/dist/api/auth/SolidSessionFactory.js

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

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

@@ -0,0 +1,18 @@
+/**
+ * Where an OIDC token request is sent, versus the URL its DPoP proof must be made for.
+ *
+ * Xpod reaches the Solid interface over a loopback alias while the canonical URL never changes
+ * (`docs/multi-channel-access.md`). An internal loopback token endpoint therefore needs two
+ * things at once: the request goes to the alias, and the receiver is told which canonical origin
+ * it is really serving, so the proof verifies against the canonical URL.
+ */
+export interface TokenEndpointRoute {
+    /** Request target: where the token request is actually sent. */
+    url: string;
+    /** URL the DPoP proof is bound to (`htu`). */
+    proofUrl: string;
+    /** Headers that make the receiver serve the canonical origin for this request. */
+    headers: Record<string, string>;
+}
+export declare function resolveTokenEndpointRoute(tokenEndpoint: string, publicBaseUrl?: string): TokenEndpointRoute;
+export declare function isLoopbackHostname(hostname: string): boolean;

package/dist/api/auth/TokenEndpointRoute.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTokenEndpointRoute = resolveTokenEndpointRoute;
+exports.isLoopbackHostname = isLoopbackHostname;
+function resolveTokenEndpointRoute(tokenEndpoint, publicBaseUrl) {
+    const headers = canonicalRoutingHeaders(tokenEndpoint, publicBaseUrl);
+    if (!publicBaseUrl || Object.keys(headers).length === 0) {
+        return { url: tokenEndpoint, proofUrl: tokenEndpoint, headers };
+    }
+    return {
+        url: tokenEndpoint,
+        proofUrl: new URL('/.oidc/token', publicBaseUrl).toString(),
+        headers,
+    };
+}
+function isLoopbackHostname(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+function canonicalRoutingHeaders(tokenEndpoint, publicBaseUrl) {
+    if (!publicBaseUrl)
+        return {};
+    try {
+        const internal = new URL(tokenEndpoint);
+        const canonical = new URL(publicBaseUrl);
+        if (internal.origin === canonical.origin || !isLoopbackHostname(internal.hostname))
+            return {};
+        return {
+            'X-Forwarded-Host': canonical.host,
+            'X-Forwarded-Proto': canonical.protocol.slice(0, -1),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=TokenEndpointRoute.js.map

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

@@ -0,0 +1,63 @@
+import { getLoggerFor } from 'global-logger-factory';
+/**
+ * Keeps a background service alive instead of starting it once (audit N18).
+ *
+ * `startBackgroundServices()` ran each service exactly once and logged whatever failed, so a
+ * tunnel or DDNS client that could not start (offline at boot, provider hiccup) stayed down for
+ * the lifetime of the process, and one that died later was never noticed. This supervisor owns
+ * that loop: bounded exponential backoff while starting, a periodic liveness check once it is
+ * up, and a stop() that really stops (a pending retry must not resurrect it — the same failure
+ * mode the process supervisor had).
+ */
+export interface BackgroundServiceSupervisorOptions {
+    name: string;
+    /** Starts the service; may throw. Must be safe to call again after a failure. */
+    start: () => Promise<void> | void;
+    /** Stops the service (used by stop()). */
+    stop?: () => Promise<void> | void;
+    /**
+     * Reports whether the service is still up. When provided, the supervisor restarts it after a
+     * liveness check fails; without it, supervision covers startup only.
+     */
+    isRunning?: () => boolean | Promise<boolean>;
+    retryBaseDelayMs?: number;
+    retryMaxDelayMs?: number;
+    checkIntervalMs?: number;
+    now?: () => Date;
+    logger?: Pick<ReturnType<typeof getLoggerFor>, 'info' | 'warn' | 'error'>;
+}
+export interface BackgroundServiceSupervisorStatus {
+    name: string;
+    state: 'idle' | 'starting' | 'running' | 'retrying' | 'stopped';
+    attempts: number;
+    restarts: number;
+    lastError?: string;
+    startedAt?: string;
+    nextRetryInMs?: number;
+}
+export declare class BackgroundServiceSupervisor {
+    private readonly options;
+    private readonly logger;
+    private readonly now;
+    private readonly retryBaseDelayMs;
+    private readonly retryMaxDelayMs;
+    private readonly checkIntervalMs;
+    private timer?;
+    private running;
+    private inFlight;
+    private consecutiveFailures;
+    private restarts;
+    private status;
+    constructor(options: BackgroundServiceSupervisorOptions);
+    /** Starts supervising; repeated calls are a no-op so a restart cannot double the timers. */
+    start(): void;
+    stop(): Promise<void>;
+    getStatus(): BackgroundServiceSupervisorStatus;
+    /** One start-or-check cycle, exposed so an operator action or a test can drive it. */
+    runOnce(): Promise<BackgroundServiceSupervisorStatus>;
+    nextDelayMs(): number;
+    private attempt;
+    private checkAlive;
+    /** Schedules the next cycle from the current state; the loop owns its own timer. */
+    scheduleNext(): void;
+}