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

package/dist/errors/exchange-error.d.ts

@@ -0,0 +1,19 @@
+import { ClientError } from './client-error.js';
+/**
+ * Why a Domain token exchange failed.
+ *
+ * - `discovery`: the Domain issuer's configuration could not be read or admitted.
+ * - `unsupported`: the Domain issuer advertises no token exchange endpoint.
+ * - `unavailable`: a Domain issuer endpoint could not be reached.
+ * - `rejected`: the Domain refused the delegation; its public error is the `cause`.
+ * - `invalid-response`: the exchange response or its credential failed admission.
+ * - `source-exhausted`: the source credential can no longer grant the lifetime the exchange needs.
+ */
+export type ExchangeFailure = 'discovery' | 'unsupported' | 'unavailable' | 'rejected' | 'invalid-response' | 'source-exhausted';
+export interface ExchangeErrorOptions extends ErrorOptions {
+    readonly failure: ExchangeFailure;
+}
+export declare class ExchangeError extends ClientError {
+    readonly failure: ExchangeFailure;
+    constructor(message: string, options: ExchangeErrorOptions);
+}

package/dist/errors/exchange-error.js

@@ -0,0 +1,9 @@
+import { ClientError } from './client-error.js';
+export class ExchangeError extends ClientError {
+    failure;
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ExchangeError';
+        this.failure = options.failure;
+    }
+}

package/dist/errors/index.d.ts

@@ -1,4 +1,5 @@
 export * from './client-error.js';
+export * from './exchange-error.js';
 export * from './miss-error.js';
 export * from './protocol-error.js';
 export * from './response-error.js';

package/dist/errors/index.js

@@ -1,4 +1,5 @@
 export * from './client-error.js';
+export * from './exchange-error.js';
 export * from './miss-error.js';
 export * from './protocol-error.js';
 export * from './response-error.js';

package/dist/session/exchange/exchange.js

@@ -3,7 +3,7 @@ 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';
+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 });
 /**
@@ -28,7 +28,7 @@ export async function exchangeDomainCredential(dependencies, source, request, op
     // 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();
+        throw sourceExhausted();
     }
     return Object.freeze({ ...credential, delegation });
 }

package/dist/session/exchange/issuer.js

@@ -1,18 +1,22 @@
 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 { ClientError, ExchangeError, SessionError } from '../../errors/index.js';
 import { allowEndpoint, runSessionOperation } from '../context/index.js';
 import { boundedResponse, requireExactResponse } from '../discovery/index.js';
+const DISCOVERY = Object.freeze({ name: 'discovery', invalid: 'discovery' });
+const TOKEN_EXCHANGE = Object.freeze({ name: 'token exchange', invalid: 'invalid-response' });
 /**
  * The token exchange endpoint a Domain issuer advertises. Endpoint policy applies here, so a denied
  * endpoint is never returned and no delegation is minted for it.
  */
 export async function tokenEndpoint(dependencies, domain, operation) {
-    const configuration = issuer.acceptConfiguration(await fetchJson(dependencies, new URL(issuer.paths(domain).configuration, domain).href, operation), domain);
+    const configuration = await fetchAdmitted(dependencies, DISCOVERY, new URL(issuer.paths(domain).configuration, domain).href, operation, (body) => issuer.acceptConfiguration(body, domain));
     const endpoint = configuration.token_exchange_endpoint;
     if (endpoint === undefined) {
-        throw new ClientError('The installed Domain does not advertise token exchange.');
+        throw new ExchangeError('The installed Domain does not advertise token exchange.', {
+            failure: 'unsupported',
+        });
     }
     allowEndpoint(endpoint, dependencies.policy);
     return endpoint;
@@ -23,28 +27,28 @@ export async function tokenEndpoint(dependencies, domain, operation) {
  * the reported one.
  */
 export async function redeem(dependencies, domain, endpoint, delegation, operation) {
-    const exchanged = issuer.exchange.acceptResponse(await fetchJson(dependencies, endpoint, operation, delegation));
+    const exchanged = await fetchAdmitted(dependencies, TOKEN_EXCHANGE, endpoint, operation, (body) => issuer.exchange.acceptResponse(body), delegation);
     let claims;
     try {
         claims = inspect(exchanged.token);
     }
     catch (cause) {
-        throw new ClientError('Domain token exchange returned an invalid credential.', { cause });
+        throw invalidResponse('Domain token exchange returned an invalid credential.', cause);
     }
     if (claims.iss !== domain ||
         claims.aud !== dependencies.kernel ||
         claims.claims.exp !== exchanged.expiresAt) {
-        throw new ClientError('Domain token exchange returned an inconsistent credential.');
+        throw invalidResponse('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.');
+        throw invalidResponse('Domain token exchange returned an expired credential.');
     }
     return Object.freeze({ credential: exchanged.token, expiresAt });
 }
-async function fetchJson(dependencies, url, operation, credential) {
+/** Fetch one issuer leg and admit its JSON body; every failure names the leg that caused it. */
+async function fetchAdmitted(dependencies, leg, url, operation, admit, credential) {
     allowEndpoint(url, dependencies.policy);
-    const stage = credential === undefined ? 'discovery' : 'token exchange';
     return runSessionOperation(operation, async (signal) => {
         const init = {
             method: credential === undefined ? 'GET' : 'POST',
@@ -58,26 +62,43 @@ async function fetchJson(dependencies, url, operation, credential) {
             redirect: 'manual',
             signal,
         };
-        const response = await dependencies.fetch(url, init);
+        let response;
+        try {
+            response = await dependencies.fetch(url, init);
+        }
+        catch (cause) {
+            if (signal.aborted)
+                throw cause;
+            throw new ExchangeError(`Domain ${leg.name} could not be reached.`, {
+                failure: 'unavailable',
+                cause,
+            });
+        }
         try {
             requireExactResponse(response, url, 'Domain token exchange');
-            if (!response.ok) {
-                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));
+            if (!response.ok)
+                throw await refusal(response, leg, signal);
+            return admit(codecs.json.decode(await boundedResponse(response, dependencies.maximumResponseBytes, signal)));
+        }
+        catch (cause) {
+            throw signal.aborted ? cause : unadmitted(cause, leg);
         }
         finally {
             // Also release unread bodies rejected by URL, status, or declared-size validation.
             void response.body?.cancel().catch(() => undefined);
         }
     });
-    async function errorOf(response, signal) {
+    async function refusal(response, leg, signal) {
+        const status = `Domain ${leg.name} returned HTTP ${response.status}.`;
+        const refused = leg === TOKEN_EXCHANGE ? await domainError(response, signal) : undefined;
+        return refused === undefined
+            ? new ExchangeError(status, { failure: leg.invalid })
+            : new ExchangeError(`${status} ${refused.payload.code}: ${refused.message}`, {
+                failure: 'rejected',
+                cause: refused,
+            });
+    }
+    async function domainError(response, signal) {
         try {
             const body = await boundedResponse(response, dependencies.maximumResponseBytes, signal);
             return new ProtocolError(issuer.exchange.acceptErrorResponse(codecs.json.decode(body)).error);
@@ -87,3 +108,25 @@ async function fetchJson(dependencies, url, operation, credential) {
         }
     }
 }
+/**
+ * Report evidence the leg could not admit under that leg's failure. Validation failures of the
+ * representation (type, syntax, response shape) become exchange failures; anything else, including
+ * Session interruption and unknown defects, keeps its own identity.
+ */
+function unadmitted(cause, leg) {
+    if (cause instanceof ExchangeError || cause instanceof SessionError)
+        return cause;
+    if (cause instanceof ClientError || cause instanceof TypeError || cause instanceof SyntaxError) {
+        return new ExchangeError(`Domain ${leg.name} returned an invalid response.`, {
+            failure: leg.invalid,
+            cause,
+        });
+    }
+    return cause;
+}
+function invalidResponse(message, cause) {
+    return new ExchangeError(message, {
+        failure: 'invalid-response',
+        ...(cause === undefined ? {} : { cause }),
+    });
+}

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

@@ -4,7 +4,7 @@ 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';
+import { ExchangeError } from '../../errors/index.js';
 /** A resolved source that carries both a credential and its delegation. */
 export type SourceAuthority = Required<EffectiveAuth>;
 /** Source Kernel syscalls issued as exactly one admitted source caller within one operation. */
@@ -13,9 +13,7 @@ export interface SourceCaller {
     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 sourceExhausted(): ExchangeError;
 export declare function isAuthority(auth: EffectiveAuth): auth is SourceAuthority;
 /** The source Kernel conversation of one exchange, acting as exactly the admitted source caller. */
 export declare function sourceCaller(dependencies: Pick<ExchangeDependencies, 'source'>, auth: EffectiveAuth, operation: SessionOperation): SourceCaller;

package/dist/session/exchange/source.js

@@ -1,13 +1,13 @@
 import { inspect } from '@astrale-os/kernel-core/auth/credential';
-import { ClientError } from '../../errors/index.js';
+import { ExchangeError } from '../../errors/index.js';
 import { runSessionOperation, sessionTransportOptions } from '../context/index.js';
 import { requireResultKind, resolveAuth } from '../routing/index.js';
 import { ISSUANCE_MARGIN_SECONDS } from './limits.js';
 /** The source credential can no longer grant a delegation that covers what its exchange carries. */
-export class SourceExhausted extends ClientError {
-    constructor() {
-        super('The source credential expires too soon for a Domain token exchange.');
-    }
+export function sourceExhausted() {
+    return new ExchangeError('The source credential expires too soon for a Domain token exchange.', {
+        failure: 'source-exhausted',
+    });
 }
 export function isAuthority(auth) {
     return auth.credential !== undefined && auth.delegate !== undefined;
@@ -34,7 +34,7 @@ export function delegationTtl(credential, ttlSeconds, coverageMs = 0) {
     if (remaining === undefined || remaining >= ttlSeconds)
         return ttlSeconds;
     if (remaining < 1 || remaining * 1_000 <= coverageMs)
-        throw new SourceExhausted();
+        throw sourceExhausted();
     return remaining;
 }
 /**
@@ -47,7 +47,7 @@ export async function renewing(auth, call, source, operation, attempt) {
         return await attempt(source);
     }
     catch (cause) {
-        if (!(cause instanceof SourceExhausted))
+        if (!(cause instanceof ExchangeError) || cause.failure !== 'source-exhausted')
             throw cause;
         let renewed = await resolveAuth(auth, call, operation);
         if (renewed.credential === source.credential && auth.refresh !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-client",
-  "version": "0.6.0-beta.74",
+  "version": "0.6.0-beta.75",
   "description": "Universal Client — protocol-first, transport-agnostic",
   "keywords": [
     "astrale",