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

package/dist/auth/credential.d.ts

@@ -21,6 +21,7 @@ export interface DelegateOptions {
 }
 export declare const IDENTITY_IMPERSONATE_PATH: NodePath;
 export declare const IDENTITY_MINT_PATH: NodePath;
+export declare const IDENTITY_DELEGATE_PATH: NodePath;
 export declare function credentialApi(call: AuthCall): Readonly<{
     impersonate(input: ImpersonateOptions, options?: RequestOptions): Promise<MintedCredential>;
     mint(input: MintOptions, options?: RequestOptions): Promise<MintedCredential>;

package/dist/auth/credential.js

@@ -3,6 +3,7 @@ import { identity } from '@astrale-os/kernel-core/schema/kernel/syscalls/referen
 const identityOwner = Path.project(identity.whoami.owner);
 export const IDENTITY_IMPERSONATE_PATH = Path.staticMethod(identityOwner, identity.impersonate.name).raw;
 export const IDENTITY_MINT_PATH = Path.staticMethod(identityOwner, identity.mint.name).raw;
+export const IDENTITY_DELEGATE_PATH = Path.staticMethod(identityOwner, identity.delegate.name).raw;
 export function credentialApi(call) {
     return Object.freeze({
         async impersonate(input, options) {
@@ -12,8 +13,7 @@ export function credentialApi(call) {
             return credential(await call(IDENTITY_MINT_PATH, input, options));
         },
         async delegate(principal, input, options) {
-            const target = Path.staticMethod(identityOwner, identity.delegate.name).raw;
-            return credential(await call(target, { ...input, principal }, options));
+            return credential(await call(IDENTITY_DELEGATE_PATH, { ...input, principal }, options));
         },
     });
 }

package/dist/schema/introspection.js

@@ -1,9 +1,13 @@
 import { Path } from '@astrale-os/kernel-core/path';
 import { introspect as introspectRef } from '@astrale-os/kernel-core/schema/kernel/syscalls/references';
+import { loadMsgpack } from '@astrale-os/kernel-protocol/codecs';
 import * as schema from '@astrale-os/kernel-protocol/schema';
 import { call } from '../client/index.js';
 const INTROSPECT_PATH = Path.project(introspectRef).raw;
 export async function introspect(invoke, limits, request, options) {
+    // The evidence is MessagePack behind a lazy import: fetch it with the request, not after it.
+    // A failed preload is surfaced by decode, which imports the same modules again.
+    void loadMsgpack().catch(() => undefined);
     const result = await invoke(call(INTROSPECT_PATH, request), options);
     if (result.kind !== 'binary') {
         throw new TypeError('Schema introspection returned a non-binary result.');

package/dist/session/admission.d.ts

@@ -1,18 +1,6 @@
 import type { invocation } from '@astrale-os/kernel-protocol';
 import type { AdmissionOptions, FunctionAdmission } from '../auth/index.js';
-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 { SessionAuth } from './routing/index.js';
-export interface FunctionAdmissionDependencies {
-    readonly kernel: string;
-    readonly auth?: SessionAuth;
-    readonly source: () => Client;
-    readonly fetch: Fetch;
-    readonly policy: Readonly<SessionPolicy>;
-    readonly limits: SchemaOptions;
-    readonly maximumResponseBytes: number;
-}
+import type { SessionOperation } from './context/index.js';
+import type { ExchangeDependencies } from './exchange/index.js';
 /** Check a remote Call through the existing Domain exchange and Kernel admission protocols. */
-export declare function admitFunction(dependencies: FunctionAdmissionDependencies, call: invocation.Call, options: AdmissionOptions | undefined, operation: SessionOperation): Promise<FunctionAdmission>;
+export declare function admitFunction(dependencies: ExchangeDependencies, call: invocation.Call, options: AdmissionOptions | undefined, operation: SessionOperation): Promise<FunctionAdmission>;

package/dist/session/admission.js

@@ -4,13 +4,9 @@ import { Path } from '@astrale-os/kernel-core/path';
 import { admitOutput } from '@astrale-os/kernel-core/schema/kernel/syscalls/contracts';
 import { function as functions } from '@astrale-os/kernel-core/schema/kernel/syscalls/references';
 import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
-import { codecs, issuer } from '@astrale-os/kernel-protocol';
-import { credentialApi } from '../auth/credential.js';
-import { identityApi } from '../auth/identity.js';
 import { ClientError } from '../errors/index.js';
-import { createSchema } from '../schema/index.js';
-import { allowEndpoint, runSessionOperation, sessionTransportOptions } from './context/index.js';
-import { boundedResponse, requireExactResponse } from './discovery/index.js';
+import { runSessionOperation, sessionTransportOptions } from './context/index.js';
+import { callableOrigin, exchangeDomainCredential, installedIssuer, isAuthority, SELF_ATTENUATION, } from './exchange/index.js';
 import { matchesCallable } from './reference.js';
 import { requireResultKind, resolveAuth } from './routing/index.js';
 const ADMIT = Path.staticMethod(Path.project(functions.admit.owner), functions.admit.name);
@@ -18,47 +14,30 @@ const ADMIT = Path.staticMethod(Path.project(functions.admit.owner), functions.a
 export async function admitFunction(dependencies, call, options, operation) {
     const target = Path.parse(targetPath(call.target));
     const origin = callableOrigin(target);
+    if (origin === undefined) {
+        throw new ClientError('Function admission requires a Domain-qualified callable target.');
+    }
     const attenuation = options?.attenuation === undefined
         ? undefined
         : grant.acceptUnresolved({ v: 1, expr: options.attenuation }).expr;
     const effective = await resolveAuth(dependencies.auth, call, operation);
-    if (effective.credential === undefined || effective.delegate === undefined) {
+    if (!isAuthority(effective)) {
         throw new ClientError('Function admission requires an authenticated session.');
     }
     // Resolve once for the intended Call, then retain that exact caller across every helper syscall.
-    const client = dependencies.source();
-    const caller = client.as(effective.credential);
-    const dispatch = (input) => runSessionOperation(operation, () => caller.dispatch(input, {
-        ...sessionTransportOptions(operation),
-        delegate: effective.delegate,
-    }));
-    const callIdentity = async (target, input) => requireResultKind('value', await dispatch({ target, input })).value;
-    const identity = identityApi(callIdentity);
-    const credentials = credentialApi(callIdentity);
-    const schema = createSchema(dispatch, dependencies.limits);
-    const [domain, self] = await Promise.all([schema.inspect(origin), identity.whoami()]);
-    const remote = domain.publication;
-    if (remote === null || remote.identity.issuer === dependencies.kernel) {
+    const domain = await installedIssuer(dependencies, origin, effective, operation);
+    if (domain === undefined) {
         throw new ClientError('Function admission through token exchange requires a remote Domain.');
     }
-    const configuration = issuer.acceptConfiguration(await fetchJson(dependencies, new URL(issuer.paths(remote.identity.issuer).configuration, remote.identity.issuer).href, operation), remote.identity.issuer);
-    const endpoint = configuration.token_exchange_endpoint;
-    if (endpoint === undefined) {
-        throw new ClientError('The installed Domain does not advertise token exchange.');
-    }
-    allowEndpoint(endpoint, dependencies.policy);
-    const credential = await credentials.delegate(self.id, {
-        audience: remote.identity.issuer,
+    const exchanged = await exchangeDomainCredential(dependencies, effective, {
+        issuer: domain,
         ttlSeconds: effective.delegate.ttlSeconds,
-        attenuation: attenuation ?? effective.delegate.attenuation ?? { kind: 'identity', self: true },
-    });
-    const exchanged = issuer.exchange.acceptResponse(await fetchJson(dependencies, endpoint, operation, credential));
-    if (exchanged.expiresAt * 1_000 <= Date.now()) {
-        throw new ClientError('Domain token exchange returned an expired credential.');
-    }
-    const result = await runSessionOperation(operation, () => client
-        .as(exchanged.token)
-        .dispatch({ target: ADMIT, input: { call, credential } }, { ...sessionTransportOptions(operation), delegate: effective.delegate }));
+        attenuation: attenuation ?? effective.delegate.attenuation ?? SELF_ATTENUATION,
+    }, operation);
+    const result = await runSessionOperation(operation, () => dependencies
+        .source()
+        .as(exchanged.credential)
+        .dispatch({ target: ADMIT, input: { call, credential: exchanged.delegation } }, { ...sessionTransportOptions(operation), delegate: effective.delegate }));
     const output = admitOutput.parse(requireResultKind('value', result).value);
     const callable = Key(output.callable);
     if (!matchesCallable(target, callable)) {
@@ -78,40 +57,3 @@ export async function admitFunction(dependencies, call, options, operation) {
     }
     return Object.freeze({ callable, ...(receiver === undefined ? {} : { receiver: receiver.raw }) });
 }
-function callableOrigin(path) {
-    const last = path.ast.steps.at(-1);
-    if (last?.kind === 'method' && last.dispatch === 'instance')
-        return Key.origin(last.class);
-    if (path.ast.anchor.kind === 'domain')
-        return path.ast.anchor.origin;
-    throw new ClientError('Function admission requires a Domain-qualified callable target.');
-}
-async function fetchJson(dependencies, url, operation, credential) {
-    allowEndpoint(url, dependencies.policy);
-    return runSessionOperation(operation, async (signal) => {
-        const init = {
-            method: credential === undefined ? 'GET' : 'POST',
-            headers: {
-                accept: 'application/json',
-                ...(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) {
-                throw new ClientError(`Domain ${credential === undefined ? 'discovery' : 'token exchange'} returned HTTP ${response.status}.`);
-            }
-            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);
-        }
-    });
-}

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;