@astrale-os/kernel-client 0.6.0-beta.8 → 0.6.0-beta.80

package/dist/session/exchange/exchange.d.ts

@@ -0,0 +1,54 @@
+import type { MintedCredential, UnresolvedIdentityExpr } from '@astrale-os/kernel-core/auth';
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import type { Client } from '../../client/index.js';
+import type { SchemaOptions } from '../../schema/schema.js';
+import type { Fetch } from '../../transport/http/index.js';
+import type { SessionOperation, SessionPolicy } from '../context/index.js';
+import type { SessionCredential } from '../credential/index.js';
+import type { EffectiveAuth, SessionAuth } from '../routing/index.js';
+import type { ExchangeRequest } from './options.js';
+/** Everything an exchange reaches: the Session's source Kernel and authority, and the Domain legs. */
+export interface ExchangeDependencies {
+    readonly kernel: IssuerId;
+    /** Unauthenticated Client for the source Kernel invocation endpoint. */
+    readonly source: () => Client;
+    /** The Session's source authority, when the Session has one. */
+    readonly auth?: SessionAuth;
+    readonly fetch: Fetch;
+    readonly policy: Readonly<SessionPolicy>;
+    readonly limits: SchemaOptions;
+    readonly maximumResponseBytes: number;
+    /** Open one operation for work shared by several Calls; it fails once the Session closes. */
+    readonly operation: (signal?: AbortSignal) => SessionOperation;
+}
+/** One Domain-issued Kernel credential and the delegation the Domain exchanged for it. */
+export interface DomainCredential extends SessionCredential {
+    readonly delegation: MintedCredential;
+}
+export interface DomainExchangeRequest {
+    readonly issuer: IssuerId;
+    /** Requested delegation lifetime; the source credential's remaining lifetime bounds it. */
+    readonly ttlSeconds: number;
+    readonly attenuation: UnresolvedIdentityExpr;
+    /**
+     * Lifetime the returned credential must exceed. A source that bounds the delegation within it is
+     * exhausted rather than exchanged.
+     */
+    readonly coverageMs?: number;
+}
+/** The attenuation that delegates the source caller's own identity. */
+export declare const SELF_ATTENUATION: Readonly<{
+    readonly kind: 'identity';
+    readonly self: true;
+}>;
+/**
+ * Delegate the source caller to one Domain issuer and redeem that delegation at the issuer's
+ * advertised endpoint for the Domain's credential to the source Kernel.
+ */
+export declare function exchangeDomainCredential(dependencies: ExchangeDependencies, source: EffectiveAuth, request: DomainExchangeRequest, operation: SessionOperation): Promise<DomainCredential>;
+/**
+ * One Domain credential for a named Domain issuer, as `session.exchange` returns it. When the
+ * request asks for more than the Session delegation, the credential covers that delegation, and the
+ * source is renewed once if the current one can no longer feed it.
+ */
+export declare function acquireDomainCredential(dependencies: ExchangeDependencies, request: ExchangeRequest, operation: SessionOperation): Promise<SessionCredential>;

package/dist/session/exchange/exchange.js

@@ -0,0 +1,58 @@
+import { credentialApi, IDENTITY_DELEGATE_PATH } from '../../auth/credential.js';
+import { identityApi } from '../../auth/identity.js';
+import { delegationCoverageMs } from '../credential/index.js';
+import { resolveAuth } from '../routing/index.js';
+import { redeem, tokenEndpoint } from './issuer.js';
+import { delegationTtl, isAuthority, renewing, sourceCaller, sourceExhausted } from './source.js';
+/** The attenuation that delegates the source caller's own identity. */
+export const SELF_ATTENUATION = Object.freeze({ kind: 'identity', self: true });
+/**
+ * Delegate the source caller to one Domain issuer and redeem that delegation at the issuer's
+ * advertised endpoint for the Domain's credential to the source Kernel.
+ */
+export async function exchangeDomainCredential(dependencies, source, request, operation) {
+    const caller = sourceCaller(dependencies, source, operation);
+    const [endpoint, principal] = await Promise.all([
+        tokenEndpoint(dependencies, request.issuer, operation),
+        identityApi(caller.call)
+            .whoami()
+            .then(({ id }) => id),
+    ]);
+    const ttlSeconds = delegationTtl(source.credential, request.ttlSeconds, request.coverageMs);
+    const delegation = await credentialApi(caller.call).delegate(principal, {
+        audience: request.issuer,
+        ttlSeconds,
+        attenuation: request.attenuation,
+    });
+    const credential = await redeem(dependencies, request.issuer, endpoint, delegation, operation);
+    // A Domain credential never outlives its source, so only a fresher source can lengthen it.
+    const bySource = ttlSeconds < request.ttlSeconds;
+    if (bySource && credential.expiresAt - Date.now() <= (request.coverageMs ?? 0)) {
+        throw sourceExhausted();
+    }
+    return Object.freeze({ ...credential, delegation });
+}
+/**
+ * One Domain credential for a named Domain issuer, as `session.exchange` returns it. When the
+ * request asks for more than the Session delegation, the credential covers that delegation, and the
+ * source is renewed once if the current one can no longer feed it.
+ */
+export async function acquireDomainCredential(dependencies, request, operation) {
+    const { auth } = dependencies;
+    const call = {
+        target: IDENTITY_DELEGATE_PATH,
+        input: { audience: request.issuer, ttlSeconds: request.ttlSeconds },
+    };
+    const coverageMs = auth === undefined ? 0 : delegationCoverageMs(auth.ttlSeconds);
+    const exchange = (source) => exchangeDomainCredential(dependencies, source, {
+        issuer: request.issuer,
+        ttlSeconds: request.ttlSeconds,
+        attenuation: source.delegate?.attenuation ?? SELF_ATTENUATION,
+        ...(request.ttlSeconds * 1_000 > coverageMs ? { coverageMs } : {}),
+    }, operation);
+    const source = await resolveAuth(auth, call, operation);
+    const exchanged = auth === undefined || !isAuthority(source)
+        ? await exchange(source)
+        : await renewing(auth, call, source, operation, exchange);
+    return Object.freeze({ credential: exchanged.credential, expiresAt: exchanged.expiresAt });
+}

package/dist/session/exchange/index.d.ts

@@ -0,0 +1,5 @@
+export { callableOrigin, installedIssuer } from './domain.js';
+export { acquireDomainCredential, exchangeDomainCredential, SELF_ATTENUATION, type DomainCredential, type DomainExchangeRequest, type ExchangeDependencies, } from './exchange.js';
+export { admitExchangeOptions, admitExchangeRequest, type ExchangeRequest, type SessionExchangeOptions, type SessionExchangeRequest, } from './options.js';
+export { createSessionExchange, type SessionExchange } from './presentation.js';
+export { isAuthority } from './source.js';

package/dist/session/exchange/index.js

@@ -0,0 +1,5 @@
+export { callableOrigin, installedIssuer } from './domain.js';
+export { acquireDomainCredential, exchangeDomainCredential, SELF_ATTENUATION, } from './exchange.js';
+export { admitExchangeOptions, admitExchangeRequest, } from './options.js';
+export { createSessionExchange } from './presentation.js';
+export { isAuthority } from './source.js';

package/dist/session/exchange/issuer.d.ts

@@ -0,0 +1,18 @@
+import type { MintedCredential } from '@astrale-os/kernel-core/auth';
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import type { SessionOperation } from '../context/index.js';
+import type { SessionCredential } from '../credential/index.js';
+import type { ExchangeDependencies } from './exchange.js';
+type IssuerDependencies = Pick<ExchangeDependencies, 'kernel' | 'fetch' | 'policy' | 'maximumResponseBytes'>;
+/**
+ * The token exchange endpoint a Domain issuer advertises. Endpoint policy applies here, so a denied
+ * endpoint is never returned and no delegation is minted for it.
+ */
+export declare function tokenEndpoint(dependencies: IssuerDependencies, domain: IssuerId, operation: SessionOperation): Promise<string>;
+/**
+ * Present a delegation at a Domain's token endpoint and admit the returned credential as provider
+ * evidence: it must be the exchange representation served with `Cache-Control: no-store`, its
+ * issuer that Domain, its audience the source Kernel, and its signed expiry the reported one.
+ */
+export declare function redeem(dependencies: IssuerDependencies, domain: IssuerId, endpoint: string, delegation: MintedCredential, operation: SessionOperation): Promise<SessionCredential>;
+export {};

package/dist/session/exchange/issuer.js

@@ -0,0 +1,149 @@
+import { inspect } from '@astrale-os/kernel-core/auth/credential';
+import { codecs, issuer } from '@astrale-os/kernel-protocol';
+import { ProtocolError } from '@astrale-os/kernel-protocol/errors';
+import { ClientError, ExchangeError, SessionError } from '../../errors/index.js';
+import { allowEndpoint, runSessionOperation } from '../context/index.js';
+import { boundedResponse, requireExactResponse } from '../discovery/index.js';
+const DISCOVERY = Object.freeze({ name: 'discovery', invalid: 'discovery' });
+const TOKEN_EXCHANGE = Object.freeze({ name: 'token exchange', invalid: 'invalid-response' });
+/**
+ * The token exchange endpoint a Domain issuer advertises. Endpoint policy applies here, so a denied
+ * endpoint is never returned and no delegation is minted for it.
+ */
+export async function tokenEndpoint(dependencies, domain, operation) {
+    const configuration = await fetchAdmitted(dependencies, DISCOVERY, new URL(issuer.paths(domain).configuration, domain).href, operation, (body) => issuer.acceptConfiguration(body, domain));
+    const endpoint = configuration.token_exchange_endpoint;
+    if (endpoint === undefined) {
+        throw new ExchangeError('The installed Domain does not advertise token exchange.', {
+            failure: 'unsupported',
+        });
+    }
+    allowEndpoint(endpoint, dependencies.policy);
+    return endpoint;
+}
+/**
+ * Present a delegation at a Domain's token endpoint and admit the returned credential as provider
+ * evidence: it must be the exchange representation served with `Cache-Control: no-store`, its
+ * issuer that Domain, its audience the source Kernel, and its signed expiry the reported one.
+ */
+export async function redeem(dependencies, domain, endpoint, delegation, operation) {
+    const exchanged = await fetchAdmitted(dependencies, TOKEN_EXCHANGE, endpoint, operation, (body, headers) => {
+        requireCredentialHeaders(headers);
+        return issuer.exchange.acceptResponse(body);
+    }, delegation);
+    let claims;
+    try {
+        claims = inspect(exchanged.token);
+    }
+    catch (cause) {
+        throw invalidResponse('Domain token exchange returned an invalid credential.', cause);
+    }
+    if (claims.iss !== domain ||
+        claims.aud !== dependencies.kernel ||
+        claims.claims.exp !== exchanged.expiresAt) {
+        throw invalidResponse('Domain token exchange returned an inconsistent credential.');
+    }
+    const expiresAt = exchanged.expiresAt * 1_000;
+    if (expiresAt <= Date.now()) {
+        throw invalidResponse('Domain token exchange returned an expired credential.');
+    }
+    return Object.freeze({ credential: exchanged.token, expiresAt });
+}
+/** Fetch one issuer leg and admit its JSON body; every failure names the leg that caused it. */
+async function fetchAdmitted(dependencies, leg, url, operation, admit, credential) {
+    allowEndpoint(url, dependencies.policy);
+    return runSessionOperation(operation, async (signal) => {
+        const init = {
+            method: credential === undefined ? 'GET' : 'POST',
+            headers: {
+                accept: credential === undefined ? 'application/json' : issuer.exchange.MEDIA_TYPE,
+                ...(credential === undefined ? {} : { authorization: `Bearer ${credential}` }),
+            },
+            credentials: 'omit',
+            cache: 'no-store',
+            referrerPolicy: 'no-referrer',
+            redirect: 'manual',
+            signal,
+        };
+        let response;
+        try {
+            response = await dependencies.fetch(url, init);
+        }
+        catch (cause) {
+            if (signal.aborted)
+                throw cause;
+            throw new ExchangeError(`Domain ${leg.name} could not be reached.`, {
+                failure: 'unavailable',
+                cause,
+            });
+        }
+        try {
+            requireExactResponse(response, url, 'Domain token exchange');
+            if (!response.ok)
+                throw await refusal(response, leg, signal);
+            return admit(codecs.json.decode(await boundedResponse(response, dependencies.maximumResponseBytes, signal)), response.headers);
+        }
+        catch (cause) {
+            throw signal.aborted ? cause : unadmitted(cause, leg);
+        }
+        finally {
+            // Also release unread bodies rejected by URL, status, or declared-size validation.
+            void response.body?.cancel().catch(() => undefined);
+        }
+    });
+    async function refusal(response, leg, signal) {
+        const status = `Domain ${leg.name} returned HTTP ${response.status}.`;
+        const refused = leg === TOKEN_EXCHANGE ? await domainError(response, signal) : undefined;
+        return refused === undefined
+            ? new ExchangeError(status, { failure: leg.invalid })
+            : new ExchangeError(`${status} ${refused.payload.code}: ${refused.message}`, {
+                failure: 'rejected',
+                cause: refused,
+            });
+    }
+    async function domainError(response, signal) {
+        try {
+            const body = await boundedResponse(response, dependencies.maximumResponseBytes, signal);
+            return new ProtocolError(issuer.exchange.acceptErrorResponse(codecs.json.decode(body)).error);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/**
+ * Report evidence the leg could not admit under that leg's failure. Validation failures of the
+ * representation (type, syntax, response shape) become exchange failures; anything else, including
+ * Session interruption and unknown defects, keeps its own identity.
+ */
+function unadmitted(cause, leg) {
+    if (cause instanceof ExchangeError || cause instanceof SessionError)
+        return cause;
+    if (cause instanceof ClientError || cause instanceof TypeError || cause instanceof SyntaxError) {
+        return new ExchangeError(`Domain ${leg.name} returned an invalid response.`, {
+            failure: leg.invalid,
+            cause,
+        });
+    }
+    return cause;
+}
+/** A credential is served as the exchange representation and never stored by an HTTP cache. */
+function requireCredentialHeaders(headers) {
+    const mediaType = headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase();
+    if (mediaType !== issuer.exchange.MEDIA_TYPE) {
+        throw invalidResponse('Domain token exchange returned an unsupported Content-Type.');
+    }
+    const directives = headers
+        .get('cache-control')
+        ?.split(',')
+        .map((directive) => directive.trim().toLowerCase()) ?? [];
+    if (!directives.includes('no-store')) {
+        throw invalidResponse('Domain token exchange response is missing Cache-Control: no-store.');
+    }
+}
+function invalidResponse(message, cause) {
+    return new ExchangeError(message, {
+        failure: 'invalid-response',
+        ...(cause === undefined ? {} : { cause }),
+    });
+}

package/dist/session/exchange/limits.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Delegation lifetime requested for each Domain credential when the caller names none. Short enough
+ * that a leaked Domain credential is worth little, long enough that a script re-exchanges each
+ * Domain a few times an hour rather than once per call.
+ */
+export declare const DEFAULT_EXCHANGE_TTL_SECONDS: number;
+/** Lifetime kept below the source credential, which the Kernel refuses to let a delegation reach. */
+export declare const ISSUANCE_MARGIN_SECONDS = 5;
+/** Source credentials whose Domain credentials one Session retains at once. */
+export declare const MAXIMUM_EXCHANGE_SOURCES = 8;

package/dist/session/exchange/limits.js

@@ -0,0 +1,10 @@
+/**
+ * Delegation lifetime requested for each Domain credential when the caller names none. Short enough
+ * that a leaked Domain credential is worth little, long enough that a script re-exchanges each
+ * Domain a few times an hour rather than once per call.
+ */
+export const DEFAULT_EXCHANGE_TTL_SECONDS = 5 * 60;
+/** Lifetime kept below the source credential, which the Kernel refuses to let a delegation reach. */
+export const ISSUANCE_MARGIN_SECONDS = 5;
+/** Source credentials whose Domain credentials one Session retains at once. */
+export const MAXIMUM_EXCHANGE_SOURCES = 8;

package/dist/session/exchange/options.d.ts

@@ -0,0 +1,29 @@
+import { type IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import type { SessionControlOptions } from '../context/index.js';
+import type { SessionAuth } from '../routing/index.js';
+/** Present each Domain callable with its declaring Domain's credential instead of the source one. */
+export interface SessionExchangeOptions {
+    /**
+     * Delegation lifetime requested for each Domain credential. The source credential's remaining
+     * lifetime and the Domain's own ceiling may shorten it.
+     */
+    readonly ttlSeconds?: number;
+}
+/** One explicit exchange through a named Domain issuer. */
+export interface SessionExchangeRequest extends SessionControlOptions {
+    /** Requested delegation lifetime; the source credential and the Domain may shorten it. */
+    readonly ttlSeconds?: number;
+}
+/** An admitted explicit exchange. */
+export interface ExchangeRequest {
+    readonly issuer: IssuerId;
+    readonly ttlSeconds: number;
+    readonly control: Readonly<SessionControlOptions>;
+}
+/**
+ * Admit exchange options against the Session auth they extend. Every Domain credential must still
+ * cover the Session delegation, so a request that could never cover it is rejected.
+ */
+export declare function admitExchangeOptions(input: SessionExchangeOptions | undefined, auth: SessionAuth | undefined): Readonly<Required<SessionExchangeOptions>> | undefined;
+/** Admit an explicit exchange: the canonical absolute issuer URL of the named Domain and its lifetime. */
+export declare function admitExchangeRequest(domain: string, input: SessionExchangeRequest | undefined): ExchangeRequest;

package/dist/session/exchange/options.js

@@ -0,0 +1,57 @@
+import { accept as acceptIssuer } from '@astrale-os/kernel-core/auth/issuer';
+import { admitControlOptions } from '../context/index.js';
+import { delegationCoverageMs } from '../credential/index.js';
+import { DEFAULT_EXCHANGE_TTL_SECONDS } from './limits.js';
+/**
+ * Admit exchange options against the Session auth they extend. Every Domain credential must still
+ * cover the Session delegation, so a request that could never cover it is rejected.
+ */
+export function admitExchangeOptions(input, auth) {
+    if (input === undefined)
+        return undefined;
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('Session exchange options are invalid.');
+    }
+    if (Reflect.ownKeys(input).some((key) => key !== 'ttlSeconds')) {
+        throw new TypeError('Session exchange options contain unexpected fields.');
+    }
+    if (auth === undefined)
+        throw new TypeError('Session exchange requires Session auth.');
+    const ttlSeconds = admitTtlSeconds(input.ttlSeconds);
+    if (ttlSeconds * 1_000 <= delegationCoverageMs(auth.ttlSeconds)) {
+        throw new TypeError('Session exchange ttlSeconds must exceed the Session auth ttlSeconds.');
+    }
+    return Object.freeze({ ttlSeconds });
+}
+/** Admit an explicit exchange: the canonical absolute issuer URL of the named Domain and its lifetime. */
+export function admitExchangeRequest(domain, input) {
+    if (input !== undefined &&
+        (input === null || typeof input !== 'object' || Array.isArray(input))) {
+        throw new TypeError('Session exchange request is invalid.');
+    }
+    const ttlSeconds = admitTtlSeconds(input?.ttlSeconds);
+    const control = admitControlOptions(input === undefined
+        ? undefined
+        : {
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+        });
+    return Object.freeze({ issuer: admitDomainIssuer(domain), ttlSeconds, control });
+}
+function admitTtlSeconds(input) {
+    const ttlSeconds = input ?? DEFAULT_EXCHANGE_TTL_SECONDS;
+    if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 1) {
+        throw new TypeError('Session exchange ttlSeconds must be a positive safe integer.');
+    }
+    return ttlSeconds;
+}
+function admitDomainIssuer(input) {
+    try {
+        const issuer = acceptIssuer(input);
+        void new URL(issuer);
+        return issuer;
+    }
+    catch (cause) {
+        throw new TypeError('Domain issuer is invalid.', { cause });
+    }
+}

package/dist/session/exchange/presentation.d.ts

@@ -0,0 +1,18 @@
+import type { AuthExchange, SessionAuth } from '../routing/index.js';
+import type { ExchangeDependencies } from './exchange.js';
+import type { SessionExchangeOptions } from './options.js';
+/** The per-Call exchange a Session applies after resolving its source authority. */
+export interface SessionExchange extends AuthExchange {
+    clear(): void;
+}
+/**
+ * Present each Call whose callable a remote installed Domain declares with the credential that
+ * Domain exchanged for the Call's source caller.
+ *
+ * Kernel callables, locally executed Domains, targets that name no Domain, and anonymous Calls keep
+ * the source authority unchanged. Domain credentials are held per source credential and replaced at
+ * the Session delegation threshold.
+ */
+export declare function createSessionExchange(dependencies: ExchangeDependencies & {
+    readonly auth: SessionAuth;
+}, options: Readonly<Required<SessionExchangeOptions>>): SessionExchange;

package/dist/session/exchange/presentation.js

@@ -0,0 +1,73 @@
+import { ClientError } from '../../errors/index.js';
+import { runSessionOperation } from '../context/index.js';
+import { createSessionCredentialProvider, delegationCoverageMs } from '../credential/index.js';
+import { createInstallations, declaringOrigin, isKernelOrigin } from './domain.js';
+import { exchangeDomainCredential, SELF_ATTENUATION } from './exchange.js';
+import { MAXIMUM_EXCHANGE_SOURCES } from './limits.js';
+import { isAuthority, renewing } from './source.js';
+/**
+ * Present each Call whose callable a remote installed Domain declares with the credential that
+ * Domain exchanged for the Call's source caller.
+ *
+ * Kernel callables, locally executed Domains, targets that name no Domain, and anonymous Calls keep
+ * the source authority unchanged. Domain credentials are held per source credential and replaced at
+ * the Session delegation threshold.
+ */
+export function createSessionExchange(dependencies, options) {
+    const { auth } = dependencies;
+    const coverageMs = delegationCoverageMs(auth.ttlSeconds);
+    const installations = createInstallations(dependencies);
+    const sources = new Map();
+    return Object.freeze({ resolve, clear });
+    async function resolve(call, effective, operation) {
+        if (!isAuthority(effective))
+            return effective;
+        const origin = declaringOrigin(call.target);
+        if (origin === undefined || isKernelOrigin(origin))
+            return effective;
+        const domain = await installations.issuerOf(origin, effective, operation);
+        if (domain === undefined)
+            return effective;
+        return renewing(auth, call, effective, operation, async (source) => {
+            if (source.delegate.ttlSeconds > auth.ttlSeconds) {
+                throw new ClientError('Session delegation outlives the Domain credential it would carry.');
+            }
+            const provider = providerFor(source, domain);
+            const exchanged = await runSessionOperation(operation, (signal) => provider.acquire(signal));
+            return Object.freeze({ credential: exchanged.credential, delegate: source.delegate });
+        });
+    }
+    function clear() {
+        installations.clear();
+        sources.clear();
+    }
+    function providerFor(source, domain) {
+        const held = heldFor(source.credential);
+        const known = held.get(domain);
+        if (known !== undefined)
+            return known;
+        const provider = createSessionCredentialProvider({
+            ttlSeconds: auth.ttlSeconds,
+            mint: (signal) => exchangeDomainCredential(dependencies, source, {
+                issuer: domain,
+                ttlSeconds: options.ttlSeconds,
+                attenuation: SELF_ATTENUATION,
+                coverageMs,
+            }, dependencies.operation(signal)),
+        });
+        held.set(domain, provider);
+        return provider;
+    }
+    /** Domain credentials never cross source credentials; the oldest source is forgotten first. */
+    function heldFor(credential) {
+        const known = sources.get(credential);
+        if (known !== undefined)
+            return known;
+        const held = new Map();
+        sources.set(credential, held);
+        if (sources.size > MAXIMUM_EXCHANGE_SOURCES) {
+            sources.delete(sources.keys().next().value);
+        }
+        return held;
+    }
+}

package/dist/session/exchange/source.d.ts

@@ -0,0 +1,32 @@
+import type { invocation } from '@astrale-os/kernel-protocol';
+import type { AuthCall } from '../../auth/auth.js';
+import type { Call, Result } from '../../client/index.js';
+import type { SessionOperation } from '../context/index.js';
+import type { EffectiveAuth, SessionAuth } from '../routing/index.js';
+import type { ExchangeDependencies } from './exchange.js';
+import { ExchangeError } from '../../errors/index.js';
+/** A resolved source that carries both a credential and its delegation. */
+export type SourceAuthority = Required<EffectiveAuth>;
+/** Source Kernel syscalls issued as exactly one admitted source caller within one operation. */
+export interface SourceCaller {
+    dispatch(call: Call): Promise<Result>;
+    readonly call: AuthCall;
+}
+/** The source credential can no longer grant a delegation that covers what its exchange carries. */
+export declare function sourceExhausted(): ExchangeError;
+export declare function isAuthority(auth: EffectiveAuth): auth is SourceAuthority;
+/** The source Kernel conversation of one exchange, acting as exactly the admitted source caller. */
+export declare function sourceCaller(dependencies: Pick<ExchangeDependencies, 'source'>, auth: EffectiveAuth, operation: SessionOperation): SourceCaller;
+/**
+ * Bound a requested delegation by the source credential's expiry less the issuance margin: the
+ * Kernel rejects a delegation that outlives its source, judged by its own clock. An opaque or
+ * transport-held source leaves the bound to the Kernel. A source that cannot grant one second, or
+ * bounds the delegation within `coverageMs`, is exhausted.
+ */
+export declare function delegationTtl(credential: string | undefined, ttlSeconds: number, coverageMs?: number): number;
+/**
+ * Run `attempt` with the resolved source, and once more with a renewed source if that one proved
+ * exhausted. The Session auth is refreshed only while it still resolves the exhausted credential, so
+ * concurrent Calls share one renewal; an auth that cannot refresh keeps the failure.
+ */
+export declare function renewing<T>(auth: SessionAuth, call: invocation.Call, source: SourceAuthority, operation: SessionOperation, attempt: (source: SourceAuthority) => Promise<T>): Promise<T>;

package/dist/session/exchange/source.js

@@ -0,0 +1,78 @@
+import { inspect } from '@astrale-os/kernel-core/auth/credential';
+import { ExchangeError } from '../../errors/index.js';
+import { runSessionOperation, sessionTransportOptions } from '../context/index.js';
+import { requireResultKind, resolveAuth } from '../routing/index.js';
+import { ISSUANCE_MARGIN_SECONDS } from './limits.js';
+/** The source credential can no longer grant a delegation that covers what its exchange carries. */
+export function sourceExhausted() {
+    return new ExchangeError('The source credential expires too soon for a Domain token exchange.', {
+        failure: 'source-exhausted',
+    });
+}
+export function isAuthority(auth) {
+    return auth.credential !== undefined && auth.delegate !== undefined;
+}
+/** The source Kernel conversation of one exchange, acting as exactly the admitted source caller. */
+export function sourceCaller(dependencies, auth, operation) {
+    const client = dependencies.source();
+    const caller = auth.credential === undefined ? client : client.as(auth.credential);
+    const dispatch = (input) => runSessionOperation(operation, () => caller.dispatch(input, {
+        ...sessionTransportOptions(operation),
+        ...(auth.delegate === undefined ? {} : { delegate: auth.delegate }),
+    }));
+    const call = async (target, input) => requireResultKind('value', await dispatch({ target, input })).value;
+    return Object.freeze({ dispatch, call });
+}
+/**
+ * Bound a requested delegation by the source credential's expiry less the issuance margin: the
+ * Kernel rejects a delegation that outlives its source, judged by its own clock. An opaque or
+ * transport-held source leaves the bound to the Kernel. A source that cannot grant one second, or
+ * bounds the delegation within `coverageMs`, is exhausted.
+ */
+export function delegationTtl(credential, ttlSeconds, coverageMs = 0) {
+    const remaining = remainingSeconds(credential);
+    if (remaining === undefined || remaining >= ttlSeconds)
+        return ttlSeconds;
+    if (remaining < 1 || remaining * 1_000 <= coverageMs)
+        throw sourceExhausted();
+    return remaining;
+}
+/**
+ * Run `attempt` with the resolved source, and once more with a renewed source if that one proved
+ * exhausted. The Session auth is refreshed only while it still resolves the exhausted credential, so
+ * concurrent Calls share one renewal; an auth that cannot refresh keeps the failure.
+ */
+export async function renewing(auth, call, source, operation, attempt) {
+    try {
+        return await attempt(source);
+    }
+    catch (cause) {
+        if (!(cause instanceof ExchangeError) || cause.failure !== 'source-exhausted')
+            throw cause;
+        let renewed = await resolveAuth(auth, call, operation);
+        if (renewed.credential === source.credential && auth.refresh !== undefined) {
+            const refresh = auth.refresh;
+            await runSessionOperation(operation, async (signal) => {
+                await refresh(signal);
+            });
+            renewed = await resolveAuth(auth, call, operation);
+        }
+        if (!isAuthority(renewed) || renewed.credential === source.credential)
+            throw cause;
+        return attempt(renewed);
+    }
+}
+function remainingSeconds(credential) {
+    if (credential === undefined)
+        return undefined;
+    let expiresAt;
+    try {
+        expiresAt = inspect(credential).claims.exp;
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof expiresAt !== 'number' || !Number.isSafeInteger(expiresAt))
+        return undefined;
+    return expiresAt - Math.ceil(Date.now() / 1_000) - ISSUANCE_MARGIN_SECONDS;
+}