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

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,34 @@
+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 { ClientError } 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 class SourceExhausted extends ClientError {
+    constructor();
+}
+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 { ClientError } 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 class SourceExhausted extends ClientError {
+    constructor() {
+        super('The source credential expires too soon for a Domain token exchange.');
+    }
+}
+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 new 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 SourceExhausted))
+            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;
+}

package/dist/session/execution.d.ts

@@ -0,0 +1,65 @@
+import type { NodeId } from '@astrale-os/kernel-core/graph/node';
+import type { Value } from '@astrale-os/kernel-dsl/value';
+import type { CallableReference } from './reference.js';
+declare const EXECUTION_OUTPUT: unique symbol;
+/**
+ * Immediate value of a durable call: the `K.Execution` it created or recovered. `Output` is the
+ * handler output of the called declaration, carried only by the type.
+ */
+export interface ExecutionRef<Output = unknown> {
+    readonly id: NodeId;
+    readonly [EXECUTION_OUTPUT]?: Output;
+}
+export type ExecutionOutcome<Output = unknown> = {
+    readonly kind: 'completed';
+    readonly value: Output;
+} | {
+    readonly kind: 'failed';
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly family?: string;
+        readonly details?: Value;
+    };
+} | {
+    readonly kind: 'cancelled';
+};
+export type ExecutionState = 'pending' | 'running' | 'waiting' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'expired';
+export interface ExecutionStatus<Output = unknown> {
+    readonly id: NodeId;
+    readonly function: NodeId;
+    readonly version: `sha256:${string}`;
+    readonly state: ExecutionState;
+    readonly createdAt: string;
+    readonly outcome?: ExecutionOutcome<Output>;
+}
+type Empty = Readonly<Record<string, never>>;
+type ExecutionLike<Output> = ExecutionRef<Output> | NodeId;
+/**
+ * Typed references to the methods of one Execution, for `session.invoke`:
+ *
+ * ```ts
+ * const run = await session.invoke(remind(invoice), { days: 3 })
+ * const outcome = await session.invoke(execution.result(run), { waitMs: 10_000 })
+ * ```
+ */
+export declare const execution: Readonly<{
+    status: <Output>(target: ExecutionLike<Output>) => CallableReference<Empty, ExecutionStatus<Output>>;
+    /** Outcome once terminal; fails `EXECUTION_PENDING` when `waitMs` elapses first. */
+    result: <Output>(target: ExecutionLike<Output>) => CallableReference<{
+        readonly waitMs?: number;
+    }, ExecutionOutcome<Output>>;
+    /** Cooperative cancellation; `force` kills without compensation (owner Domain only). */
+    cancel: <Output>(target: ExecutionLike<Output>) => CallableReference<{
+        readonly force?: boolean;
+    }, ExecutionStatus<Output>>;
+    /** Resolve a named durable promise once (owner Domain only). */
+    signal: (target: ExecutionLike<unknown>) => CallableReference<{
+        readonly name: string;
+        readonly value: Value;
+    }, Empty>;
+    resume: <Output>(target: ExecutionLike<Output>) => CallableReference<Empty, ExecutionStatus<Output>>;
+    /** Forget the Execution and stop its run (owner Domain only). */
+    delete: (target: ExecutionLike<unknown>) => CallableReference<Empty, Empty>;
+}>;
+export {};

package/dist/session/execution.js

@@ -0,0 +1,35 @@
+import { Path } from '@astrale-os/kernel-core/path';
+import { K } from '@astrale-os/kernel-core/schema';
+import { reference } from './reference.js';
+const methods = K.classes.Execution.methods;
+const bound = {
+    status: reference(K, methods.status),
+    result: reference(K, methods.result),
+    cancel: reference(K, methods.cancel),
+    signal: reference(K, methods.signal),
+    resume: reference(K, methods.resume),
+    delete: reference(K, methods.delete),
+};
+function receiver(execution) {
+    return Path.id(typeof execution === 'string' ? execution : execution.id);
+}
+/**
+ * Typed references to the methods of one Execution, for `session.invoke`:
+ *
+ * ```ts
+ * const run = await session.invoke(remind(invoice), { days: 3 })
+ * const outcome = await session.invoke(execution.result(run), { waitMs: 10_000 })
+ * ```
+ */
+export const execution = Object.freeze({
+    status: (target) => bound.status(receiver(target)),
+    /** Outcome once terminal; fails `EXECUTION_PENDING` when `waitMs` elapses first. */
+    result: (target) => bound.result(receiver(target)),
+    /** Cooperative cancellation; `force` kills without compensation (owner Domain only). */
+    cancel: (target) => bound.cancel(receiver(target)),
+    /** Resolve a named durable promise once (owner Domain only). */
+    signal: (target) => bound.signal(receiver(target)),
+    resume: (target) => bound.resume(receiver(target)),
+    /** Forget the Execution and stop its run (owner Domain only). */
+    delete: (target) => bound.delete(receiver(target)),
+});

package/dist/session/index.d.ts

@@ -3,9 +3,11 @@ export type { ContentApi, ContentLocation, ContentUploadOptions, ContentUploadRe
 export { bindSession, type BoundClientSession, type BoundSessionControls, type BoundSessionSource, } from './bound.js';
 export { createSessionCredentialProvider, type SessionCredential, type SessionCredentialProvider, type SessionCredentialProviderOptions, type SessionCredentialState, } from './credential/index.js';
 export type { SessionSnapshot } from './discovery/index.js';
+export type { SessionExchangeOptions, SessionExchangeRequest } from './exchange/index.js';
 export type { Auth, PersistedRoute, SessionRouteArtifact, SessionRouteStore, SessionAuth, SessionEnvelopeTransport, SessionRequestOptions, SessionRequestOptionsWithBody, } from './routing/index.js';
 export { ClientSession, connect, type ClientSessionOptions, type ConnectOptions, } from './session.js';
 export type { CallableReference, InputOfReference, InputModeOfReference, InstanceCallableReference, OutputOfReference, } from './reference.js';
 export { reference } from './reference.js';
+export { execution, type ExecutionOutcome, type ExecutionRef, type ExecutionState, type ExecutionStatus, } from './execution.js';
 export type { ResolvedView, ViewCatalog } from './views/index.js';
 export type { DomainBinding } from '../graph/domain/index.js';

package/dist/session/index.js

@@ -2,3 +2,4 @@ export { bindSession, } from './bound.js';
 export { createSessionCredentialProvider, } from './credential/index.js';
 export { ClientSession, connect, } from './session.js';
 export { reference } from './reference.js';
+export { execution, } from './execution.js';

package/dist/session/reference.d.ts

@@ -4,6 +4,7 @@ import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
 import type { MeaningFingerprint } from '@astrale-os/kernel-dsl/v1/schema/fingerprint';
 import { type Key as KeyType } from '@astrale-os/kernel-dsl/v1/addressing';
 import type { Binary, Input } from '../client/index.js';
+import type { ExecutionRef } from './execution.js';
 declare const REFERENCE_INPUT: unique symbol;
 declare const REFERENCE_INPUT_MODE: unique symbol;
 declare const REFERENCE_OUTPUT: unique symbol;
@@ -32,7 +33,12 @@ export type InputOfReference<Reference extends CallableReference<unknown>> = Ref
 export type OutputOfReference<Reference extends CallableReference<unknown>> = Reference extends CallableReference<infer _Input, infer Output> ? Output : never;
 export type InputModeOfReference<Reference extends CallableReference<unknown>> = Reference extends CallableReference<infer _Input, infer _Output, infer Mode> ? Mode : never;
 type ReferenceInput<Callable> = unknown extends CallableInputOf<Callable> ? Input : CallableInputOf<Callable>;
-type ReferenceOutput<Callable> = unknown extends CallableOutputOf<Callable> ? unknown : CallableResultOf<Callable, Binary>;
+type HandlerOutput<Callable> = unknown extends CallableOutputOf<Callable> ? unknown : CallableResultOf<Callable, Binary>;
+type ReferenceOutput<Callable> = Callable extends {
+    readonly execution: {
+        readonly durable: true;
+    };
+} ? ExecutionRef<HandlerOutput<Callable>> : HandlerOutput<Callable>;
 type ExecutableStaticMethod = ExecutableMethod<unknown, unknown, true>;
 type ExecutableInstanceMethod = ExecutableMethod<unknown, unknown, false>;
 /** Project one exact resolved Function or static Method into a typed Client reference. */

package/dist/session/routing/auth.d.ts

@@ -9,10 +9,20 @@ export interface SessionAuth {
     /** Default TTL for authenticated Calls whose Auth omits a delegation override. */
     readonly ttlSeconds: number;
     resolve(call: invocation.Call, signal: AbortSignal): Auth | Promise<Auth>;
+    /**
+     * Replace the source credential now, before `resolve` would. A Session asks for it only when a
+     * credential it derives from the current source, such as a Domain exchange, could not cover
+     * `ttlSeconds`: a derived credential never outlives its source.
+     */
+    refresh?(signal: AbortSignal): PromiseLike<unknown> | void;
 }
 export interface EffectiveAuth {
     readonly credential?: string;
     readonly delegate?: invocation.Delegate;
 }
+/** Replace the resolved source authority of one Call before routing partitions and presents it. */
+export interface AuthExchange {
+    resolve(call: invocation.Call, auth: EffectiveAuth, operation: SessionOperation): Promise<EffectiveAuth>;
+}
 export declare function admitSessionAuth(input: SessionAuth | undefined): SessionAuth | undefined;
 export declare function resolveAuth(resolver: SessionAuth | undefined, call: invocation.Call, operation: SessionOperation): Promise<EffectiveAuth>;

package/dist/session/routing/auth.js

@@ -10,7 +10,14 @@ export function admitSessionAuth(input) {
     if (!Number.isSafeInteger(input.ttlSeconds) || input.ttlSeconds < 1) {
         throw new TypeError('Session auth ttlSeconds must be a positive safe integer.');
     }
-    return Object.freeze({ ttlSeconds: input.ttlSeconds, resolve: input.resolve.bind(input) });
+    if (input.refresh !== undefined && typeof input.refresh !== 'function') {
+        throw new TypeError('Session auth refresh capability is invalid.');
+    }
+    return Object.freeze({
+        ttlSeconds: input.ttlSeconds,
+        resolve: input.resolve.bind(input),
+        ...(input.refresh === undefined ? {} : { refresh: input.refresh.bind(input) }),
+    });
 }
 export async function resolveAuth(resolver, call, operation) {
     if (resolver === undefined)

package/dist/session/routing/dispatch.d.ts

@@ -2,7 +2,7 @@ import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
 import type { Result } from '../../client/index.js';
 import type { Fetch } from '../../transport/http/index.js';
 import type { SessionOperation, SessionPolicy } from '../context/index.js';
-import type { SessionAuth } from './auth.js';
+import type { AuthExchange, SessionAuth } from './auth.js';
 import type { RouteCache } from './cache.js';
 import type { ClientPoolCapability } from './envelope.js';
 import type { SessionEnvelopeTransport, SessionRequestOptions } from './request.js';
@@ -13,6 +13,7 @@ export interface SessionDispatcherOptions {
     readonly pool: ClientPoolCapability;
     readonly websocketAvailable: boolean;
     readonly auth?: SessionAuth;
+    readonly exchange?: AuthExchange;
     readonly cache: RouteCache;
     readonly policy: Readonly<SessionPolicy>;
     readonly envelopeTransport: SessionEnvelopeTransport;

package/dist/session/routing/dispatch.js

@@ -21,8 +21,11 @@ export class SessionDispatcher {
         this.state.requireOpen();
         const call = acceptCall(input);
         // Authority is resolved before warm lookup so changed credentials or delegation cannot reuse a
-        // carrier minted for a different caller partition.
-        const auth = await resolveAuth(this.state.auth, call, operation);
+        // carrier minted for a different caller partition. An exchanged credential is its own partition.
+        const resolved = await resolveAuth(this.state.auth, call, operation);
+        const auth = this.state.exchange === undefined
+            ? resolved
+            : await this.state.exchange.resolve(call, resolved, operation);
         const source = this.state.kernel;
         const cacheKey = await this.state.cache.key(source, call, auth);
         const dispatch = Object.freeze({

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

@@ -1,4 +1,4 @@
-export { admitSessionAuth, resolveAuth, type Auth, type EffectiveAuth, type SessionAuth, } from './auth.js';
+export { admitSessionAuth, resolveAuth, type Auth, type AuthExchange, type EffectiveAuth, type SessionAuth, } from './auth.js';
 export { RouteCache, type LearnedRoute, type PersistedRoute, type SessionRouteArtifact, type SessionRouteStore, } from './cache.js';
 export { requireResultKind, SessionDispatcher, type SessionDispatcherOptions } from './dispatch.js';
 export { type ClientPoolCapability, type EnvelopeSelection } from './envelope.js';

package/dist/session/session.d.ts

@@ -12,7 +12,9 @@ import type { Fetch } from '../transport/http/index.js';
 import type { WebSocketConstructor } from '../transport/websocket/index.js';
 import type { ContentApi } from './content.js';
 import type { SessionControlOptions, SessionPolicy } from './context/index.js';
+import type { SessionCredential } from './credential/index.js';
 import type { SessionSnapshot } from './discovery/index.js';
+import type { SessionExchangeOptions, SessionExchangeRequest } from './exchange/index.js';
 import type { CallableReference, InputModeOfReference, InputOfReference, OutputOfReference } from './reference.js';
 import type { SessionRouteStore, SessionAuth, SessionEnvelopeTransport, SessionRequestOptions, SessionRequestOptionsWithBody } from './routing/index.js';
 import type { ViewCatalog } from './views/index.js';
@@ -24,6 +26,12 @@ export interface ClientSessionOptions {
     readonly pool?: Pick<ClientPoolType, 'clientFor'>;
     readonly websocket?: WebSocketConstructor;
     readonly auth?: SessionAuth;
+    /**
+     * Present each Domain callable with a credential its declaring Domain exchanges for the `auth`
+     * caller, so the Domain is the principal and the caller is `auth`. Kernel and local callables keep
+     * the `auth` credential.
+     */
+    readonly exchange?: SessionExchangeOptions;
     /** Optional caller-owned persistence for bounded confidential route artifacts. */
     readonly routeStore?: SessionRouteStore;
     readonly policy: SessionPolicy;
@@ -52,11 +60,19 @@ export declare class ClientSession {
     private readonly lifecycle;
     private readonly timeoutMs;
     private readonly routes;
+    private readonly exchangeDependencies;
+    private readonly callExchange?;
     private readonly admitTargetViews;
     private closed;
     constructor(options: ClientSessionOptions);
     /** Bind one admitted DSL Domain to authenticated graph projection and Method dispatch. */
     bind<const DomainValue extends Domain>(domain: DomainValue): DomainBinding<DomainValue>;
+    /**
+     * Delegate this Session's caller to one Domain issuer and exchange that delegation for the
+     * Domain's credential to this Kernel. Nothing is cached: hold the result, for example through
+     * `createSessionCredentialProvider`, for as long as it covers the calls it carries.
+     */
+    exchange(domain: string, options?: SessionExchangeRequest): Promise<SessionCredential>;
     /** Revalidate the intrinsic Publication without acquiring its bundle or Views. */
     publication(options?: SessionControlOptions): Promise<publication.Publication>;
     snapshot(options?: SessionControlOptions): Promise<SessionSnapshot>;

package/dist/session/session.js

@@ -14,6 +14,7 @@ import { admitFunction } from './admission.js';
 import { createContentApi } from './content.js';
 import { admitControlOptions, admitPolicy, createSessionOperation, DEFAULT_MAXIMUM_BUNDLE_BYTES, DEFAULT_MAXIMUM_PUBLICATION_BYTES, DEFAULT_MAXIMUM_RESPONSE_BYTES, DEFAULT_TIMEOUT_MS, admitKernel, allowEndpoint, kernelInvocationEndpoint, platformDuration, positive, } from './context/index.js';
 import { createSessionDiscovery } from './discovery/index.js';
+import { acquireDomainCredential, admitExchangeOptions, admitExchangeRequest, createSessionExchange, } from './exchange/index.js';
 import { admitReference } from './reference.js';
 import { admitEnvelopeTransport, admitInvocationOptions, admitSessionAuth, requireResultKind, RouteCache, SessionDispatcher, } from './routing/index.js';
 import { resolveViewsFor, targetViewCatalog } from './views/index.js';
@@ -31,6 +32,8 @@ export class ClientSession {
     lifecycle = new AbortController();
     timeoutMs;
     routes;
+    exchangeDependencies;
+    callExchange;
     admitTargetViews;
     closed = false;
     constructor(options) {
@@ -86,24 +89,31 @@ export class ClientSession {
         });
         this.routes = new RouteCache(policy.maximumRouteAgeMs, undefined, options.routeStore);
         const auth = admitSessionAuth(options.auth);
-        const admission = {
+        const exchange = admitExchangeOptions(options.exchange, auth);
+        this.exchangeDependencies = Object.freeze({
             kernel: this.kernel,
-            auth,
             source: () => {
                 allowEndpoint(sourceEndpoint, policy);
                 return pool.clientFor({ transport: 'http', url: sourceEndpoint });
             },
+            ...(auth === undefined ? {} : { auth }),
             fetch: fetchImpl,
             policy,
             limits: { maximumPublicationBytes, maximumBundleBytes },
             maximumResponseBytes,
-        };
+            operation: (signal) => this.operation(signal === undefined ? undefined : { signal }),
+        });
+        this.callExchange =
+            exchange === undefined || auth === undefined
+                ? undefined
+                : createSessionExchange({ ...this.exchangeDependencies, auth }, exchange);
         this.dispatcher = new SessionDispatcher({
             kernel: this.kernel,
             sourceEndpoint,
             pool,
             websocketAvailable,
             auth,
+            ...(this.callExchange === undefined ? {} : { exchange: this.callExchange }),
             cache: this.routes,
             policy,
             envelopeTransport: admitEnvelopeTransport(options.envelopeTransport ?? 'http'),
@@ -127,13 +137,22 @@ export class ClientSession {
         this.graph = createGraph((call, options) => this.call(call, options));
         this.auth = createAuth((target, input, options) => this.call({ target, input }, options), (call, options) => {
             const operation = this.operation(admitControlOptions(options));
-            return admitFunction(admission, acceptCall(call), options, operation);
+            return admitFunction(this.exchangeDependencies, acceptCall(call), options, operation);
         });
     }
     /** Bind one admitted DSL Domain to authenticated graph projection and Method dispatch. */
     bind(domain) {
         return createDomainBinding(domain, this.graph, (node, method, input) => this.invokeDomainMethod(domain, node, method, input));
     }
+    /**
+     * Delegate this Session's caller to one Domain issuer and exchange that delegation for the
+     * Domain's credential to this Kernel. Nothing is cached: hold the result, for example through
+     * `createSessionCredentialProvider`, for as long as it covers the calls it carries.
+     */
+    async exchange(domain, options) {
+        const request = admitExchangeRequest(domain, options);
+        return acquireDomainCredential(this.exchangeDependencies, request, this.operation(request.control));
+    }
     /** Revalidate the intrinsic Publication without acquiring its bundle or Views. */
     publication(options) {
         return this.discovery.publication(this.operation(admitControlOptions(options)));
@@ -208,6 +227,7 @@ export class ClientSession {
         this.ownedPool?.close();
         this.routes.clear();
         this.discovery.clear();
+        this.callExchange?.clear();
     }
     requireOpen() {
         if (this.closed)