@undefineds.co/xpod 0.4.28 → 0.4.30

package/dist/api/ApiServer.js

@@ -4,6 +4,7 @@ exports.ApiServer = void 0;
 const node_http_1 = require("node:http");
 const global_logger_factory_1 = require("global-logger-factory");
 const NodeRuntimeHost_1 = require("../runtime/host/node/NodeRuntimeHost");
+const PodAccessFailureResponse_1 = require("./handlers/PodAccessFailureResponse");
 const task_model_diagnostics_1 = require("../util/task-model-diagnostics");
 /**
  * Standalone API Server
@@ -226,6 +227,8 @@ class ApiServer {
             await route.handler(authRequest, response, params);
         }
         catch (error) {
+            if (!response.headersSent && (0, PodAccessFailureResponse_1.sendPodAccessFailure)(response, error))
+                return;
             const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
             const causes = [];
             let cause = error instanceof Error ? error.cause : undefined;
@@ -333,6 +336,7 @@ class ApiServer {
             'Content-Type',
             'Accept',
             'DPoP',
+            'X-Xpod-Pod-Url',
             'Origin',
             'X-Requested-With',
             'If-Match',

package/dist/api/ai-gateway/AiGatewayService.d.ts

@@ -14,6 +14,31 @@ export interface StoredGatewayCredential extends GatewayCredentialCandidate {
     secretPayload?: string;
     version?: number;
     runtimeCredential?: ProviderRuntimeCredential;
+    /**
+     * Stored session expiry. Lets the gateway ask the credential lifecycle to renew an expired
+     * OAuth session before it is used, without an extra read of the credential row.
+     */
+    expiresAt?: Date;
+}
+/**
+ * Why the runtime asked for a renewal. `expired` is the proactive path (the stored session is
+ * already past its expiry); `authentication_failed` is the reactive path (upstream just rejected
+ * a credential the store still considered usable).
+ */
+export type GatewayCredentialRenewalReason = 'expired' | 'authentication_failed';
+export interface GatewayCredentialRenewalRequest {
+    webId: string;
+    deployment: string;
+    provider: string;
+    credentialId: string;
+    credentialIri: string;
+    /**
+     * Version the caller observed. A different row version means a concurrent caller already
+     * renewed the credential, so the caller can retry with the freshly stored secret.
+     */
+    observedVersion?: number;
+    reason: GatewayCredentialRenewalReason;
+    auth?: AuthContext;
 }
 export interface GatewayCredentialStore {
     listCredentials(input: {
@@ -31,6 +56,13 @@ export interface GatewayCredentialStore {
         encryptedSecret: EncryptedCredentialSecret;
         auth?: AuthContext;
     }): Promise<boolean>;
+    /**
+     * Shared credential lifecycle hook. Renews the stored OAuth session (re-reading the declared
+     * local session source or refreshing the stored refresh token) and reports whether the caller
+     * may retry with the credential that is now stored. Absent or false leaves the existing
+     * failure/failover behaviour untouched.
+     */
+    renewCredential?(input: GatewayCredentialRenewalRequest): Promise<boolean>;
 }
 export interface GatewayCredentialHealthRecord {
     webId: string;
@@ -122,6 +154,29 @@ export declare class AiGatewayService {
     private executeWithCredentialFailover;
     private recordUsage;
     private findFailoverRoute;
+    /**
+     * Asks the shared credential lifecycle for a usable session whenever the stored one is already
+     * past its expiry. Non-OAuth credentials and stores without a lifecycle hook are left alone.
+     */
+    private renewCredentialIfExpired;
+    /**
+     * Renews at most once per credential per request; returns whether a retry may proceed. A typed
+     * reauthorization requirement is rethrown so the caller surfaces it instead of issuing another
+     * provider request with a session that is already known to be invalid.
+     */
+    private tryRenewCredential;
+    /**
+     * Re-reads the renewed row so the next attempt uses the new secret and its version. The reload
+     * must land on the same credential identity and the row must still be currently eligible: a
+     * concurrent disable, revoke or reauth between the lifecycle write and this read must not hand a
+     * revoked session back to the provider. Returns undefined when the credential is no longer usable.
+     */
+    private reloadCredential;
+    /**
+     * Swaps the reloaded row into the route. Throws when the renewed row cannot be observed, because
+     * retrying with the stale secret would repeat the request the provider just rejected.
+     */
+    private applyRenewedCredential;
     private openApiKey;
     private runtimeCredentialFor;
     private offeringRuntimeCredential;

package/dist/api/ai-gateway/AiGatewayService.js

@@ -204,11 +204,25 @@ class AiGatewayService {
         let route = input.route;
         let firstClientEventEmitted = false;
         const attempted = new Set();
+        // A single request may renew a given credential at most once, so a credential the provider
+        // keeps rejecting cannot turn into a refresh loop.
+        const renewalAttempted = new Set();
         for (;;) {
+            // A request that is already cancelled must not start a renewal or another upstream attempt.
+            if (input.signal?.aborted)
+                throw abortError();
             attempted.add(route.credential.id);
-            const credential = route.credential;
+            let credential = route.credential;
             try {
                 let finalUsage;
+                if (await this.renewCredentialIfExpired(input.principal, credential, input.auth, renewalAttempted)) {
+                    // The stored secret was replaced; reload the same row so the provider call below opens the
+                    // renewed token instead of the stale route snapshot.
+                    route = await this.applyRenewedCredential(input.principal, input.auth, route, credential);
+                    credential = route.credential;
+                }
+                if (input.signal?.aborted)
+                    throw abortError();
                 const apiKey = await this.openApiKey(input.principal, route, credential, input.auth);
                 const adapter = this.runtimes.get(route.provider.id);
                 const upstream = adapter.execute({
@@ -235,6 +249,23 @@ class AiGatewayService {
                 return;
             }
             catch (error) {
+                // A cancelled request must not renew, record health, or issue another provider request.
+                if (input.signal?.aborted)
+                    throw abortError();
+                // Renew before recording health: a recoverable rejection must not be recorded as a
+                // credential failure that disables the session.
+                const renewed = !firstClientEventEmitted
+                    && isCredentialAuthenticationFailure(error)
+                    && await this.tryRenewCredential(input.principal, credential, input.auth, 'authentication_failed', renewalAttempted);
+                if (renewed) {
+                    const fresh = await this.reloadCredential(input.principal, input.auth, credential);
+                    // Only retry once the renewed row is observable; retrying with the stale secret would
+                    // repeat the exact request the provider just rejected.
+                    if (fresh) {
+                        route = { ...route, credential: fresh };
+                        continue;
+                    }
+                }
                 await this.recordRouteFailure(input.principal.webId, route, error, input.auth);
                 if (!firstClientEventEmitted && this.router.canFailOver(route) && isCredentialFailoverError(error)) {
                     const nextRoute = await this.findFailoverRoute(input.principal.webId, input.auth, input.request, route, attempted);
@@ -293,6 +324,85 @@ class AiGatewayService {
             throw error;
         }
     }
+    /**
+     * Asks the shared credential lifecycle for a usable session whenever the stored one is already
+     * past its expiry. Non-OAuth credentials and stores without a lifecycle hook are left alone.
+     */
+    async renewCredentialIfExpired(principal, credential, auth, renewalAttempted) {
+        const expiresAt = credential.expiresAt?.getTime();
+        if (expiresAt === undefined || expiresAt > this.now().getTime()) {
+            return false;
+        }
+        return this.tryRenewCredential(principal, credential, auth, 'expired', renewalAttempted);
+    }
+    /**
+     * Renews at most once per credential per request; returns whether a retry may proceed. A typed
+     * reauthorization requirement is rethrown so the caller surfaces it instead of issuing another
+     * provider request with a session that is already known to be invalid.
+     */
+    async tryRenewCredential(principal, credential, auth, reason, renewalAttempted) {
+        const renew = this.credentials.renewCredential;
+        if (!renew || credential.authMode !== 'deviceCodeOAuth' || renewalAttempted.has(credential.id)) {
+            return false;
+        }
+        renewalAttempted.add(credential.id);
+        try {
+            return await renew.call(this.credentials, {
+                webId: principal.webId,
+                deployment: this.deployment,
+                provider: credential.provider,
+                credentialId: credential.id,
+                credentialIri: credential.credentialIri,
+                observedVersion: credential.version,
+                reason,
+                auth,
+            });
+        }
+        catch (error) {
+            if (isReauthRequiredError(error))
+                throw error;
+            // Log a typed safe code only: a raw error message could carry upstream token/response text.
+            this.logger.warn(`Credential renewal failed for provider ${credential.provider}: ${renewalFailureCode(error)}`);
+            return false;
+        }
+    }
+    /**
+     * Re-reads the renewed row so the next attempt uses the new secret and its version. The reload
+     * must land on the same credential identity and the row must still be currently eligible: a
+     * concurrent disable, revoke or reauth between the lifecycle write and this read must not hand a
+     * revoked session back to the provider. Returns undefined when the credential is no longer usable.
+     */
+    async reloadCredential(principal, auth, expected) {
+        try {
+            const credentials = await this.credentials.listCredentials({
+                webId: principal.webId,
+                deployment: this.deployment,
+                auth,
+            });
+            const candidate = credentials.find((row) => row.id === expected.id
+                && row.credentialIri === expected.credentialIri
+                && (0, ProviderRegistry_1.normalizeProviderId)(row.provider) === (0, ProviderRegistry_1.normalizeProviderId)(expected.provider));
+            return candidate && this.router.isCredentialEligible(candidate) ? candidate : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Swaps the reloaded row into the route. Throws when the renewed row cannot be observed, because
+     * retrying with the stale secret would repeat the request the provider just rejected.
+     */
+    async applyRenewedCredential(principal, auth, route, credential) {
+        const fresh = await this.reloadCredential(principal, auth, credential);
+        if (!fresh) {
+            throw new errors_1.GatewayProtocolError('Renewed credential could not be reloaded', {
+                code: 'credential_unavailable',
+                status: 401,
+                details: { credentialId: credential.id },
+            });
+        }
+        return { ...route, credential: fresh };
+    }
     async openApiKey(principal, route, credential, auth) {
         if (credential.storageMode === 'plaintext-v1') {
             const secret = (0, PlaintextCredentialPayload_1.decodePlaintextCredential)(credential);
@@ -413,11 +523,7 @@ class AiGatewayService {
         };
     }
     async recordRouteFailure(webId, route, error, auth) {
-        const status = typeof error?.status === 'number'
-            ? error.status
-            : error instanceof errors_1.GatewayProtocolError
-                ? error.status
-                : undefined;
+        const status = providerFailureStatus(error);
         const occurredAt = this.now();
         const normalized = (0, errors_1.normalizeGatewayError)(error);
         const failureCode = stringMetadata(normalized.error.details, 'classification') ?? (0, ProviderRuntimeAdapter_1.classifyProviderStatus)(status ?? 502);
@@ -593,6 +699,39 @@ function healthRecord(webId, deployment, route) {
         expectedVersion: route.credential.version,
     };
 }
+/** Upstream status carried by a provider failure, if any. */
+function providerFailureStatus(error) {
+    if (typeof error?.status === 'number') {
+        return error.status;
+    }
+    return error instanceof errors_1.GatewayProtocolError ? error.status : undefined;
+}
+/** A cancelled request stops the failover loop without touching credential health. */
+function abortError() {
+    const error = new Error('Request aborted');
+    error.name = 'AbortError';
+    return error;
+}
+/** A typed reauthorization requirement that must reach the caller instead of being swallowed. */
+function isReauthRequiredError(error) {
+    return error instanceof errors_1.GatewayProtocolError
+        && error.details?.reauthRequired === true;
+}
+/** Safe, non-secret renewal failure code for logs. */
+function renewalFailureCode(error) {
+    return error instanceof errors_1.GatewayProtocolError ? error.code : 'renewal_failed';
+}
+/** True when the failure is an upstream authentication rejection that a renewal could recover. */
+function isCredentialAuthenticationFailure(error) {
+    const status = providerFailureStatus(error);
+    if (status === undefined) {
+        return false;
+    }
+    const classification = error instanceof errors_1.GatewayProtocolError
+        ? stringMetadata(error.details, 'classification')
+        : undefined;
+    return (classification ?? (0, ProviderRuntimeAdapter_1.classifyProviderStatus)(status)) === 'authentication';
+}
 function isCredentialFailoverError(error) {
     if (!(error instanceof errors_1.GatewayProtocolError)) {
         const normalized = (0, errors_1.normalizeGatewayError)(error);

package/dist/api/ai-gateway/auth/AiConnectionsInvocationKeyIssuer.js

@@ -60,7 +60,8 @@ class AiConnectionsInvocationKeyIssuer {
     }
     async issueScoped(auth, scopes, model) {
         const webId = (0, InvocationTokenCodec_1.requireCanonicalWebId)(auth.webId);
-        const cacheKey = `${webId}\n${scopes.join(' ')}`;
+        const podUrl = auth.authorizedPodUrl;
+        const cacheKey = `${webId}\n${podUrl ?? ''}\n${scopes.join(' ')}`;
         const now = this.now();
         const cached = this.cache.get(cacheKey);
         if (cached && cached.expiresAt.getTime() - now.getTime() >= this.reuseSafetyMarginMs) {
@@ -68,7 +69,7 @@ class AiConnectionsInvocationKeyIssuer {
         }
         let pending = this.pending.get(cacheKey);
         if (!pending) {
-            pending = Promise.resolve().then(() => this.createInvocation(cacheKey, webId, scopes, now));
+            pending = Promise.resolve().then(() => this.createInvocation(cacheKey, webId, scopes, now, podUrl));
             this.pending.set(cacheKey, pending);
             const clearPending = () => {
                 if (this.pending.get(cacheKey) === pending) {
@@ -80,7 +81,7 @@ class AiConnectionsInvocationKeyIssuer {
         const issued = await pending;
         return this.toInvocationConfig(issued, model);
     }
-    createInvocation(cacheKey, webId, scopes, createdAt) {
+    createInvocation(cacheKey, webId, scopes, createdAt, podUrl) {
         this.pruneCache(createdAt);
         const expiresAt = new Date(createdAt.getTime() + this.ttlMs);
         const plaintext = this.codec.encode({
@@ -88,6 +89,7 @@ class AiConnectionsInvocationKeyIssuer {
             audience: this.audience,
             issuer: this.issuer,
             webId,
+            ...(podUrl ? { podUrl } : {}),
             scopes,
             issuedAt: createdAt,
             expiresAt,

package/dist/api/ai-gateway/auth/GatewayApiKeyAuthenticator.d.ts

@@ -1,53 +1,22 @@
 import type { IncomingMessage } from 'node:http';
 import type { Authenticator, AuthResult } from '../../auth/Authenticator';
-import type { AuthContext } from '../../auth/AuthContext';
-import { type GatewayDeployment } from './GatewayApiKey';
-import type { InvocationTokenCodec } from './InvocationTokenCodec';
-export interface GatewayAccessKeyRecord {
-    id: string;
-    /** CSS credentials are saved configuration, never legacy Gateway authentication records. */
-    kind?: 'client-credentials';
-    credentialResource?: string;
-    owner: string;
-    secretHash: string;
-    deployment: GatewayDeployment;
-    scopes: string[];
-    createdAt: Date;
-    expiresAt?: Date;
-    lastUsedAt?: Date;
-    disabledAt?: Date;
-    revokedAt?: Date;
-    name?: string;
-    plaintext?: string;
-    /** CSS/OIDC client id of an issued credential; an external runtime identifier. */
-    clientCredentialId?: string;
-    status?: string;
-    appliedTo?: string;
-    appliedOn?: string;
-    appliedAt?: Date;
-}
-export declare const LEGACY_GATEWAY_KEY_AUTHENTICATION = "legacy-gateway-key-authentication";
-export type GatewayAccessKeyRepositoryInternalAccessReason = typeof LEGACY_GATEWAY_KEY_AUTHENTICATION | 'gateway-key-verifier';
-export interface GatewayAccessKeyRepositoryContext {
-    auth?: AuthContext;
-    /** Set when the gateway itself is verifying a key, rather than serving an owner request. */
-    gatewayKeyVerification?: {
-        reason: GatewayAccessKeyRepositoryInternalAccessReason;
-    };
-}
-export interface GatewayAccessKeyRepository {
-    createKeyId?(owner: string, deployment: GatewayDeployment): string;
-    create(record: GatewayAccessKeyRecord, context?: GatewayAccessKeyRepositoryContext): Promise<GatewayAccessKeyRecord>;
-    findById(id: string, context?: GatewayAccessKeyRepositoryContext): Promise<GatewayAccessKeyRecord | undefined>;
-    listByOwner(owner: string, context?: GatewayAccessKeyRepositoryContext): Promise<GatewayAccessKeyRecord[]>;
-    setEnabled(id: string, enabled: boolean, changedAt: Date, context?: GatewayAccessKeyRepositoryContext): Promise<GatewayAccessKeyRecord | undefined>;
-    revoke(id: string, revokedAt: Date, context?: GatewayAccessKeyRepositoryContext): Promise<GatewayAccessKeyRecord | undefined>;
-    delete(id: string, context?: GatewayAccessKeyRepositoryContext): Promise<boolean>;
-    revealPlaintext(id: string, context?: GatewayAccessKeyRepositoryContext): Promise<string | undefined>;
-    touchLastUsed(id: string, lastUsedAt: Date, context?: GatewayAccessKeyRepositoryContext): Promise<void>;
-}
+import type { GatewayDeployment, InvocationTokenCodec } from './InvocationTokenCodec';
+/**
+ * Verifies AI-Connections invocation tokens for the model gateway.
+ *
+ * This used to verify two kinds of bearer: an `xpod_gw_v1.*` Gateway API Key looked up in its
+ * owner's Pod, and an `xpod_inv_v1.*` invocation token. The Gateway API Key half is gone: no code
+ * issues those keys any more, and a key holder was already refused Pod access. Only the invocation
+ * half remains, unchanged.
+ *
+ * The name and the `viaGatewayApiKey` context flag it sets are kept deliberately. The flag is how
+ * `GatewayPrincipal.isGatewayApiKeyPrincipal`, `AiGatewayService.isGatewayKeySolidPrincipal`,
+ * `CallerPodAccess`, `AiConfigHandler` and `AiConnectionsInvocationKeyIssuer` recognise an
+ * invocation principal, so renaming it here would ripple through the very path this file must keep
+ * working. The `Invalid gateway API key` error text is likewise the wire behaviour invocation
+ * failures already produce.
+ */
 export interface GatewayApiKeyAuthenticatorOptions {
-    repository?: GatewayAccessKeyRepository;
     deployment: GatewayDeployment;
     requiredScopes?: string[];
     invocationTokenCodec?: InvocationTokenCodec;
@@ -58,7 +27,6 @@ export interface GatewayApiKeyAuthenticatorOptions {
 }
 export declare const DEFAULT_GATEWAY_API_KEY_SCOPES: readonly ["models:read", "inference:write"];
 export declare class GatewayApiKeyAuthenticator implements Authenticator {
-    private readonly repository?;
     private readonly deployment;
     private readonly requiredScopes;
     private readonly invocationTokenCodec?;
@@ -66,7 +34,6 @@ export declare class GatewayApiKeyAuthenticator implements Authenticator {
     private readonly invocationTokenIssuer?;
     private readonly now;
     private readonly maxClockSkewMs;
-    private readonly dummyHash;
     constructor(options: GatewayApiKeyAuthenticatorOptions);
     canAuthenticate(request: IncomingMessage): boolean;
     authenticate(request: IncomingMessage): Promise<AuthResult>;

package/dist/api/ai-gateway/auth/GatewayApiKeyAuthenticator.js

@@ -1,15 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GatewayApiKeyAuthenticator = exports.DEFAULT_GATEWAY_API_KEY_SCOPES = exports.LEGACY_GATEWAY_KEY_AUTHENTICATION = void 0;
+exports.GatewayApiKeyAuthenticator = exports.DEFAULT_GATEWAY_API_KEY_SCOPES = void 0;
 const node_crypto_1 = require("node:crypto");
-const GatewayApiKey_1 = require("./GatewayApiKey");
 const InvocationTokenCodec_1 = require("./InvocationTokenCodec");
-exports.LEGACY_GATEWAY_KEY_AUTHENTICATION = 'legacy-gateway-key-authentication';
 const INVALID_GATEWAY_API_KEY = 'Invalid gateway API key';
 exports.DEFAULT_GATEWAY_API_KEY_SCOPES = ['models:read', 'inference:write'];
+const INVOCATION_TOKEN_PREFIX = 'xpod_inv_v1.';
 class GatewayApiKeyAuthenticator {
     constructor(options) {
-        this.repository = options.repository;
         this.deployment = options.deployment;
         this.requiredScopes = options.requiredScopes ?? [...exports.DEFAULT_GATEWAY_API_KEY_SCOPES];
         this.invocationTokenCodec = options.invocationTokenCodec;
@@ -24,68 +22,16 @@ class GatewayApiKeyAuthenticator {
         if (!Number.isSafeInteger(this.maxClockSkewMs) || this.maxClockSkewMs < 0 || this.maxClockSkewMs > 30_000) {
             throw new Error('Gateway invocation token clock skew must be between 0 and 30000 milliseconds');
         }
-        this.dummyHash = (0, GatewayApiKey_1.hashGatewayApiKeySecret)('xpod-gateway-missing-key-dummy-secret');
     }
     canAuthenticate(request) {
-        const bearer = this.readBearer(request);
-        return Boolean(bearer
-            && (bearer.startsWith('xpod_inv_v1.') || (0, GatewayApiKey_1.parseGatewayApiKey)(bearer)));
+        return Boolean(this.readBearer(request)?.startsWith(INVOCATION_TOKEN_PREFIX));
     }
     async authenticate(request) {
         const bearer = this.readBearer(request);
-        if (bearer?.startsWith('xpod_inv_v1.')) {
-            return this.authenticateInvocationToken(bearer);
-        }
-        const parsed = bearer ? (0, GatewayApiKey_1.parseGatewayApiKey)(bearer) : undefined;
-        if (!parsed) {
-            return { success: false, error: INVALID_GATEWAY_API_KEY };
-        }
-        if (!this.repository) {
-            return infrastructureError(new Error('Gateway API key repository is not configured'));
-        }
-        const repositoryContext = {
-            gatewayKeyVerification: { reason: 'gateway-key-verifier' },
-        };
-        let record;
-        try {
-            record = await this.repository.findById(parsed.keyId, repositoryContext);
-        }
-        catch (cause) {
-            return infrastructureError(cause);
-        }
-        if (!record || record.kind === 'client-credentials') {
-            await (0, GatewayApiKey_1.verifyGatewayApiKeySecret)(parsed.secret, await this.dummyHash);
-            return invalidGatewayApiKey();
-        }
-        const secretMatches = await (0, GatewayApiKey_1.verifyGatewayApiKeySecret)(parsed.secret, record.secretHash);
-        if (!secretMatches
-            || parsed.deployment !== this.deployment
-            || record.deployment !== this.deployment
-            || record.revokedAt
-            || record.disabledAt
-            || isExpired(record, this.now())
-            || !hasRequiredScopes(record.scopes, this.requiredScopes)) {
+        if (!bearer?.startsWith(INVOCATION_TOKEN_PREFIX)) {
             return invalidGatewayApiKey();
         }
-        const lastUsedAt = this.now();
-        try {
-            await this.repository.touchLastUsed(record.id, lastUsedAt, repositoryContext);
-        }
-        catch (cause) {
-            return infrastructureError(cause);
-        }
-        const context = {
-            type: 'solid',
-            webId: record.owner,
-            accountId: record.owner,
-            viaGatewayApiKey: true,
-            gatewayRuntimeAccess: true,
-            gatewayKeyId: record.id,
-            gatewayKeyFingerprint: fingerprintGatewayBearer(bearer),
-            scopes: record.scopes,
-            tokenType: 'Bearer',
-        };
-        return { success: true, context };
+        return this.authenticateInvocationToken(bearer);
     }
     authenticateInvocationToken(token) {
         const claims = this.invocationTokenCodec?.decode(token);
@@ -95,6 +41,7 @@ class GatewayApiKeyAuthenticator {
         const context = {
             type: 'solid',
             webId: claims.webId,
+            ...(claims.podUrl ? { authorizedPodUrl: claims.podUrl } : {}),
             accountId: claims.webId,
             viaGatewayApiKey: true,
             internalInvocation: true,
@@ -134,18 +81,6 @@ function invalidGatewayApiKey() {
         statusCode: 401,
     };
 }
-function infrastructureError(cause) {
-    return {
-        success: false,
-        error: 'Gateway API key authentication unavailable',
-        category: 'service_unavailable',
-        statusCode: 503,
-        cause,
-    };
-}
-function isExpired(record, now) {
-    return Boolean(record.expiresAt && record.expiresAt.getTime() <= now.getTime());
-}
 function hasRequiredScopes(scopes, requiredScopes) {
     return requiredScopes.every((scope) => scopes.includes(scope));
 }

package/dist/api/ai-gateway/auth/InvocationTokenAuthenticator.js

@@ -34,6 +34,7 @@ class InvocationTokenAuthenticator {
         const context = {
             type: 'solid',
             webId: claims.webId,
+            ...(claims.podUrl ? { authorizedPodUrl: claims.podUrl } : {}),
             accountId: claims.webId,
             internalInvocation: true,
             scopes: claims.scopes,

package/dist/api/ai-gateway/auth/InvocationTokenCodec.d.ts

@@ -5,6 +5,8 @@ export interface InvocationTokenClaims {
     audience: string;
     issuer: string;
     webId: string;
+    /** Signed canonical storage binding; absent only on legacy unbound invocations. */
+    podUrl?: string;
     scopes: string[];
     issuedAt: Date;
     expiresAt: Date;
@@ -20,6 +22,8 @@ export interface InvocationTokenInput {
     audience: string;
     issuer: string;
     webId: string;
+    /** Signed canonical storage binding; absent only on legacy unbound invocations. */
+    podUrl?: string;
     scopes: string[];
     issuedAt: Date;
     expiresAt: Date;

package/dist/api/ai-gateway/auth/InvocationTokenCodec.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AesInvocationTokenCodec = void 0;
 exports.requireCanonicalOrigin = requireCanonicalOrigin;
 exports.requireCanonicalWebId = requireCanonicalWebId;
+const PodBaseUrlResolver_1 = require("../pod/PodBaseUrlResolver");
 const node_crypto_1 = require("node:crypto");
 const PREFIX = 'xpod_inv_v1';
 const AAD_CONTEXT = 'xpod:gateway:internal-invocation:v1';
@@ -42,6 +43,7 @@ class AesInvocationTokenCodec {
             aud: audience,
             iss: issuer,
             webId,
+            ...(input.podUrl !== undefined ? { podUrl: (0, PodBaseUrlResolver_1.normalizeVerifiedPodRoot)(input.podUrl) } : {}),
             scopes,
             iat: issuedAt,
             exp: expiresAt,
@@ -97,7 +99,9 @@ class AesInvocationTokenCodec {
             const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
             const parsed = JSON.parse(plaintext.toString('utf8'));
             const keys = Object.keys(parsed).sort();
-            if (keys.join(',') !== 'aud,deployment,exp,iat,iss,jti,kid,scopes,v,webId'
+            if (keys.join(',') !== (parsed.podUrl === undefined
+                ? 'aud,deployment,exp,iat,iss,jti,kid,scopes,v,webId'
+                : 'aud,deployment,exp,iat,iss,jti,kid,podUrl,scopes,v,webId')
                 ||
                     parsed.v !== 1
                 || parsed.kid !== kid
@@ -105,6 +109,7 @@ class AesInvocationTokenCodec {
                 || typeof parsed.aud !== 'string'
                 || typeof parsed.iss !== 'string'
                 || typeof parsed.webId !== 'string'
+                || (parsed.podUrl !== undefined && typeof parsed.podUrl !== 'string')
                 || !Array.isArray(parsed.scopes)
                 || typeof parsed.iat !== 'number'
                 || typeof parsed.exp !== 'number'
@@ -115,6 +120,7 @@ class AesInvocationTokenCodec {
             const audience = requireCanonicalOrigin(parsed.aud, 'audience');
             const issuer = requireCanonicalOrigin(parsed.iss, 'issuer');
             const webId = requireCanonicalWebId(parsed.webId);
+            const podUrl = parsed.podUrl === undefined ? undefined : (0, PodBaseUrlResolver_1.normalizeVerifiedPodRoot)(parsed.podUrl);
             const scopes = requireScopes(parsed.scopes);
             const issuedAt = requireEpoch(parsed.iat);
             const expiresAt = requireEpoch(parsed.exp);
@@ -128,6 +134,7 @@ class AesInvocationTokenCodec {
                 audience,
                 issuer,
                 webId,
+                ...(podUrl ? { podUrl } : {}),
                 scopes,
                 issuedAt: new Date(issuedAt),
                 expiresAt: new Date(expiresAt),

package/dist/api/ai-gateway/connect/FileSessionImportAdapter.d.ts

@@ -22,6 +22,8 @@ export interface LocalSessionImportAdapter {
 export interface FileSessionImportAdapterOptions {
     profile: SessionImportProfile;
     homeDir?: string;
+    /** Environment snapshot used to resolve declared overrides; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
     readFile?: (filePath: string, encoding: BufferEncoding) => Promise<string>;
     maxBytes?: number;
 }
@@ -30,6 +32,7 @@ export declare class FileSessionImportAdapter implements LocalSessionImportAdapt
     readonly offeringId: string;
     private readonly profile;
     private readonly homeDir;
+    private readonly env;
     private readonly readFile;
     private readonly maxBytes;
     constructor(options: FileSessionImportAdapterOptions);