@astrale-os/kernel-client 0.6.0-beta.71 → 0.6.0-beta.74

package/dist/session/content.js

@@ -0,0 +1,160 @@
+import { NodeId } from '@astrale-os/kernel-core/graph/node';
+import { Path } from '@astrale-os/kernel-core/path';
+import { K } from '@astrale-os/kernel-core/schema';
+import { download } from '@astrale-os/kernel-core/schema/kernel/syscalls/references';
+import { PropertyKey } from '@astrale-os/kernel-dsl/v1/addressing';
+import * as artifact from '@astrale-os/kernel-protocol/artifact';
+import { CODES } from '@astrale-os/kernel-protocol/errors';
+import { ClientError, ProtocolError, ResponseError, TransportError } from '../errors/index.js';
+import { admitControlOptions, runSessionOperation } from './context/index.js';
+import { reference } from './reference.js';
+import { requireResultKind } from './routing/index.js';
+const UPLOAD = reference(K, K.functions.upload);
+const DOWNLOAD = Path.project(download);
+const CONTENT_TIMEOUT_MS = 30 * 60 * 1_000;
+const MAXIMUM_ATTEMPTS = 3;
+/** Transfer immutable content over the authenticated Session routing conversation. */
+export function createContentApi(dependencies) {
+    async function upload(source, options) {
+        const body = admitBody(source);
+        const mediaType = admitMediaType(options?.mediaType);
+        const operation = dependencies.operation(contentControls(options));
+        let last;
+        for (let attempt = 0; attempt < MAXIMUM_ATTEMPTS; attempt++) {
+            try {
+                const result = await dependencies.invoke(UPLOAD, { mediaType }, { body }, operation);
+                return uploadResult(result);
+            }
+            catch (cause) {
+                last = cause;
+                if (!retryable(cause) || attempt + 1 === MAXIMUM_ATTEMPTS || operation.signal.aborted) {
+                    throw cause;
+                }
+                await runSessionOperation(operation, (signal) => delay(200 * 2 ** attempt, signal));
+            }
+        }
+        throw last;
+    }
+    async function download(location, options) {
+        const operation = dependencies.operation(contentControls(options));
+        const result = await dependencies.dispatch(DOWNLOAD, admitLocation(location), operation);
+        return verifiedDownload(requireResultKind('binary', result).value);
+    }
+    return Object.freeze({ upload, download });
+}
+function admitLocation(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('Content location is invalid.');
+    }
+    return Object.freeze({ node: NodeId(input.node), property: PropertyKey(input.property) });
+}
+function admitBody(input) {
+    if (typeof Blob !== 'undefined' && input instanceof Blob)
+        return input;
+    if (input instanceof Uint8Array) {
+        // Blob snapshots an ArrayBuffer view; a SharedArrayBuffer view needs an owned copy.
+        const bytes = input.buffer instanceof ArrayBuffer
+            ? input
+            : new Uint8Array(input);
+        return new Blob([bytes]);
+    }
+    throw new TypeError('Content upload source must be a Blob, File, or Uint8Array.');
+}
+function admitMediaType(input) {
+    if (typeof input !== 'string')
+        throw new TypeError('Content upload mediaType is required.');
+    return artifact.identify(new Uint8Array(), input).mediaType;
+}
+function contentControls(input) {
+    const controls = admitControlOptions(input);
+    return Object.freeze({ ...controls, timeoutMs: controls.timeoutMs ?? CONTENT_TIMEOUT_MS });
+}
+function uploadResult(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new ClientError('Content upload returned an invalid receipt.');
+    }
+    const value = input;
+    if (typeof value.receipt !== 'string' ||
+        value.receipt.length === 0 ||
+        typeof value.expiresAt !== 'string' ||
+        !Number.isFinite(Date.parse(value.expiresAt))) {
+        throw new ClientError('Content upload returned an invalid receipt.');
+    }
+    let ref;
+    try {
+        ref = artifact.accept(value.ref);
+    }
+    catch (cause) {
+        throw new ClientError('Content upload returned an invalid Ref.', { cause });
+    }
+    return Object.freeze({
+        receipt: value.receipt,
+        ref,
+        expiresAt: value.expiresAt,
+    });
+}
+function retryable(cause) {
+    return ((cause instanceof TransportError && cause.context.kind === 'invocation') ||
+        (cause instanceof ResponseError &&
+            (cause.reason?.code === 'BLOB_UNAVAILABLE' ||
+                cause.code === CODES.CANCELLED ||
+                cause.code === CODES.DEADLINE_EXCEEDED ||
+                cause.code === CODES.OUTCOME_UNKNOWN)));
+}
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', abort);
+            resolve();
+        }, ms);
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', abort, { once: true });
+    });
+}
+async function verifiedDownload(input) {
+    const raw = input.headers?.['x-astrale-blob-size'];
+    if (raw === undefined || !/^(?:0|[1-9][0-9]*)$/u.test(raw)) {
+        await cancelBinary(input);
+        throw new ProtocolError('Content download omitted its exact content size.');
+    }
+    const expected = Number(raw);
+    if (!Number.isSafeInteger(expected)) {
+        await cancelBinary(input);
+        throw new ProtocolError('Content download content size is invalid.');
+    }
+    if (input.body instanceof Uint8Array) {
+        if (input.body.byteLength !== expected) {
+            throw new ProtocolError('Content download ended before its exact content size.');
+        }
+        return input;
+    }
+    return Object.freeze({ ...input, body: exactContentBytes(input.body, expected) });
+}
+async function cancelBinary(input) {
+    if (input.body instanceof Uint8Array)
+        return;
+    try {
+        await input.body[Symbol.asyncIterator]().return?.();
+    }
+    catch {
+        // Preserve the admission error after the response stream has been closed.
+    }
+}
+async function* exactContentBytes(body, expected) {
+    let received = 0;
+    for await (const bytes of body) {
+        received += bytes.byteLength;
+        if (received > expected) {
+            throw new ProtocolError('Content download exceeded its exact content size.');
+        }
+        yield bytes;
+    }
+    if (received !== expected) {
+        throw new ProtocolError('Content download ended before its exact content size.');
+    }
+}

package/dist/session/context/operation.d.ts

@@ -13,7 +13,11 @@ export declare function createSessionOperation(lifecycle: AbortSignal, input: {
     readonly idempotencyKey?: RequestOptions['idempotencyKey'];
 } | undefined, defaultTimeoutMs: number): SessionOperation;
 export declare function remainingSessionTime(operation: SessionOperation): number;
-export declare function sessionTransportOptions(operation: SessionOperation, idempotencyKey?: RequestOptions['idempotencyKey']): RequestOptions;
+export declare function sessionTransportOptions(operation: SessionOperation): {
+    readonly signal: AbortSignal;
+    readonly timeoutMs: number;
+};
+export declare function sessionTransportOptions(operation: SessionOperation, idempotencyKey: RequestOptions['idempotencyKey']): RequestOptions;
 /** Settle independently of a caller capability that ignores its supplied AbortSignal. */
 export declare function runSessionOperation<Result>(operation: SessionOperation, task: (signal: AbortSignal) => Result | PromiseLike<Result>): Promise<Result>;
 export declare function requireSessionOperation(operation: SessionOperation): void;

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

@@ -1 +1 @@
-export { createSessionCredentialProvider, type SessionCredential, type SessionCredentialProvider, type SessionCredentialProviderOptions, type SessionCredentialState, } from './provider.js';
+export { createSessionCredentialProvider, delegationCoverageMs, type SessionCredential, type SessionCredentialProvider, type SessionCredentialProviderOptions, type SessionCredentialState, } from './provider.js';

package/dist/session/credential/index.js

@@ -1 +1 @@
-export { createSessionCredentialProvider, } from './provider.js';
+export { createSessionCredentialProvider, delegationCoverageMs, } from './provider.js';

package/dist/session/credential/provider.d.ts

@@ -48,4 +48,9 @@ export interface SessionCredentialProvider extends SessionAuth {
     /** Stop anticipating; a mint already in flight still settles. */
     stop(): void;
 }
+/**
+ * Remaining lifetime a credential must exceed to carry a delegation of `ttlSeconds`: the TTL itself
+ * plus the settlement skew, so it cannot expire between admission and delivery.
+ */
+export declare function delegationCoverageMs(ttlSeconds: number): number;
 export declare function createSessionCredentialProvider(options: SessionCredentialProviderOptions): SessionCredentialProvider;

package/dist/session/credential/provider.js

@@ -1,5 +1,12 @@
 import { ClientError } from '../../errors/index.js';
 import { BACKOFF_MS, MINT_TIMEOUT_MS, RETRY_INTERVAL_MS, SETTLEMENT_SKEW_MS } from './limits.js';
+/**
+ * Remaining lifetime a credential must exceed to carry a delegation of `ttlSeconds`: the TTL itself
+ * plus the settlement skew, so it cannot expire between admission and delivery.
+ */
+export function delegationCoverageMs(ttlSeconds) {
+    return ttlSeconds * 1_000 + SETTLEMENT_SKEW_MS;
+}
 export function createSessionCredentialProvider(options) {
     if (options === null || typeof options !== 'object') {
         throw new TypeError('Session credential provider options are invalid.');
@@ -17,7 +24,7 @@ export function createSessionCredentialProvider(options) {
     const mint = options.mint.bind(options);
     const notify = options.onChange?.bind(options);
     // The threshold is the coverage the caller already declared, never a separate guessed constant.
-    const marginMs = ttlSeconds * 1_000 + SETTLEMENT_SKEW_MS;
+    const marginMs = delegationCoverageMs(ttlSeconds);
     let current = options.initial === undefined ? undefined : admitInitial(options.initial);
     let state = Object.freeze(current === undefined
         ? { status: 'empty' }

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

@@ -0,0 +1,27 @@
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import type { invocation } from '@astrale-os/kernel-protocol';
+import { Path } from '@astrale-os/kernel-core/path';
+import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { SessionOperation } from '../context/index.js';
+import type { EffectiveAuth } from '../routing/index.js';
+import type { ExchangeDependencies } from './exchange.js';
+/** Installed issuers of the Domains one Session reaches. */
+export interface Installations {
+    issuerOf(origin: Key.Origin, source: EffectiveAuth, operation: SessionOperation): Promise<IssuerId | undefined>;
+    clear(): void;
+}
+/**
+ * The origin of the Domain whose declaration a Call executes, or undefined when the target names no
+ * Domain. An instance Method belongs to its qualified Class, never to its receiver's Domain.
+ */
+export declare function declaringOrigin(target: invocation.Call['target']): Key.Origin | undefined;
+export declare function callableOrigin(path: Path): Key.Origin | undefined;
+export declare function isKernelOrigin(origin: Key.Origin): boolean;
+/** The installed remote issuer of one Domain, read as the source caller; undefined when local. */
+export declare function installedIssuer(dependencies: Pick<ExchangeDependencies, 'kernel' | 'source' | 'limits'>, origin: Key.Origin, source: EffectiveAuth, operation: SessionOperation): Promise<IssuerId | undefined>;
+/**
+ * Remember each origin's installed issuer for the Session route age. The issuer is installation
+ * state, not authority, so one inspection serves every source credential; concurrent readers share
+ * it while each keeps its own cancellation and deadline.
+ */
+export declare function createInstallations(dependencies: ExchangeDependencies): Installations;

package/dist/session/exchange/domain.js

@@ -0,0 +1,63 @@
+import { targetPath } from '@astrale-os/kernel-core/callable';
+import { Path } from '@astrale-os/kernel-core/path';
+import { identity } from '@astrale-os/kernel-core/schema/kernel/syscalls/references';
+import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import { createSchema } from '../../schema/index.js';
+import { runSessionOperation } from '../context/index.js';
+import { sourceCaller } from './source.js';
+const KERNEL_ORIGIN = identity.whoami.owner.origin;
+/**
+ * The origin of the Domain whose declaration a Call executes, or undefined when the target names no
+ * Domain. An instance Method belongs to its qualified Class, never to its receiver's Domain.
+ */
+export function declaringOrigin(target) {
+    return callableOrigin(Path.parse(targetPath(target)));
+}
+export function callableOrigin(path) {
+    const last = path.ast.steps.at(-1);
+    if (last?.kind === 'method' && last.dispatch === 'instance')
+        return Key.origin(last.class);
+    return path.ast.anchor.kind === 'domain' ? path.ast.anchor.origin : undefined;
+}
+export function isKernelOrigin(origin) {
+    return origin === KERNEL_ORIGIN;
+}
+/** The installed remote issuer of one Domain, read as the source caller; undefined when local. */
+export async function installedIssuer(dependencies, origin, source, operation) {
+    const caller = sourceCaller(dependencies, source, operation);
+    const domain = await createSchema(caller.dispatch, dependencies.limits).inspect(origin);
+    const remote = domain.publication;
+    return remote === null || remote.identity.issuer === dependencies.kernel
+        ? undefined
+        : remote.identity.issuer;
+}
+/**
+ * Remember each origin's installed issuer for the Session route age. The issuer is installation
+ * state, not authority, so one inspection serves every source credential; concurrent readers share
+ * it while each keeps its own cancellation and deadline.
+ */
+export function createInstallations(dependencies) {
+    /** An inspection in flight never expires; a settled one lives for the route age. */
+    const entries = new Map();
+    return Object.freeze({
+        issuerOf(origin, source, operation) {
+            const held = entries.get(origin);
+            const { issuer } = held === undefined || held.expiresAt <= Date.now() ? inspect(origin, source) : held;
+            return runSessionOperation(operation, () => issuer);
+        },
+        clear: () => entries.clear(),
+    });
+    function inspect(origin, source) {
+        const issuer = installedIssuer(dependencies, origin, source, dependencies.operation());
+        const entry = { issuer, expiresAt: Infinity };
+        entries.set(origin, entry);
+        // Both reactions are attached, so a rejection that reaches no waiter is never unhandled.
+        issuer.then(() => {
+            entry.expiresAt = Date.now() + dependencies.policy.maximumRouteAgeMs;
+        }, () => {
+            if (entries.get(origin) === entry)
+                entries.delete(origin);
+        });
+        return entry;
+    }
+}

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 new 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: its issuer must be 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,89 @@
+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 } from '../../errors/index.js';
+import { allowEndpoint, runSessionOperation } from '../context/index.js';
+import { boundedResponse, requireExactResponse } from '../discovery/index.js';
+/**
+ * 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 = issuer.acceptConfiguration(await fetchJson(dependencies, new URL(issuer.paths(domain).configuration, domain).href, operation), domain);
+    const endpoint = configuration.token_exchange_endpoint;
+    if (endpoint === undefined) {
+        throw new ClientError('The installed Domain does not advertise token exchange.');
+    }
+    allowEndpoint(endpoint, dependencies.policy);
+    return endpoint;
+}
+/**
+ * Present a delegation at a Domain's token endpoint and admit the returned credential as provider
+ * evidence: its issuer must be 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 = issuer.exchange.acceptResponse(await fetchJson(dependencies, endpoint, operation, delegation));
+    let claims;
+    try {
+        claims = inspect(exchanged.token);
+    }
+    catch (cause) {
+        throw new ClientError('Domain token exchange returned an invalid credential.', { cause });
+    }
+    if (claims.iss !== domain ||
+        claims.aud !== dependencies.kernel ||
+        claims.claims.exp !== exchanged.expiresAt) {
+        throw new ClientError('Domain token exchange returned an inconsistent credential.');
+    }
+    const expiresAt = exchanged.expiresAt * 1_000;
+    if (expiresAt <= Date.now()) {
+        throw new ClientError('Domain token exchange returned an expired credential.');
+    }
+    return Object.freeze({ credential: exchanged.token, expiresAt });
+}
+async function fetchJson(dependencies, url, operation, credential) {
+    allowEndpoint(url, dependencies.policy);
+    const stage = credential === undefined ? 'discovery' : 'token exchange';
+    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,
+        };
+        const response = await dependencies.fetch(url, init);
+        try {
+            requireExactResponse(response, url, 'Domain token exchange');
+            if (!response.ok) {
+                const failure = credential === undefined ? undefined : await errorOf(response, signal);
+                const status = `Domain ${stage} returned HTTP ${response.status}.`;
+                throw failure === undefined
+                    ? new ClientError(status)
+                    : new ClientError(`${status} ${failure.payload.code}: ${failure.message}`, {
+                        cause: failure,
+                    });
+            }
+            return codecs.json.decode(await boundedResponse(response, dependencies.maximumResponseBytes, signal));
+        }
+        finally {
+            // Also release unread bodies rejected by URL, status, or declared-size validation.
+            void response.body?.cancel().catch(() => undefined);
+        }
+    });
+    async function errorOf(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;
+        }
+    }
+}

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 });
+    }
+}