@astrale-os/kernel-client 0.6.0-beta.65 → 0.6.0-beta.67

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

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

package/dist/session/credential/index.js

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

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

@@ -0,0 +1,12 @@
+/**
+ * Settlement allowance added to the declared delegation TTL to form the refresh threshold. It
+ * matches the destination-credential skew routing already applies to a warm entry, so a credential
+ * served here cannot expire between admission and delivery.
+ */
+export declare const SETTLEMENT_SKEW_MS = 5000;
+/** Total budget for one mint, matching the default Session operation budget. */
+export declare const MINT_TIMEOUT_MS = 30000;
+/** Bounded backoff between anticipation attempts after a failed mint. */
+export declare const BACKOFF_MS: readonly [1000, 2000, 4000];
+/** Steady retry interval once the bounded backoff is exhausted. */
+export declare const RETRY_INTERVAL_MS = 4000;

package/dist/session/credential/limits.js

@@ -0,0 +1,12 @@
+/**
+ * Settlement allowance added to the declared delegation TTL to form the refresh threshold. It
+ * matches the destination-credential skew routing already applies to a warm entry, so a credential
+ * served here cannot expire between admission and delivery.
+ */
+export const SETTLEMENT_SKEW_MS = 5_000;
+/** Total budget for one mint, matching the default Session operation budget. */
+export const MINT_TIMEOUT_MS = 30_000;
+/** Bounded backoff between anticipation attempts after a failed mint. */
+export const BACKOFF_MS = [1_000, 2_000, 4_000];
+/** Steady retry interval once the bounded backoff is exhausted. */
+export const RETRY_INTERVAL_MS = 4_000;

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

@@ -0,0 +1,51 @@
+import type { SessionAuth } from '../routing/index.js';
+/** One source credential and the exact instant it stops being accepted. */
+export interface SessionCredential {
+    readonly credential: string;
+    /** Absolute Unix time in milliseconds. */
+    readonly expiresAt: number;
+}
+/** Observable lifecycle of the single credential one provider owns. */
+export type SessionCredentialState = {
+    readonly status: 'empty';
+} | {
+    readonly status: 'valid';
+    readonly credential: SessionCredential;
+} | {
+    readonly status: 'refreshing';
+    readonly credential?: SessionCredential;
+} | {
+    readonly status: 'degraded';
+    readonly credential: SessionCredential;
+    readonly error: unknown;
+} | {
+    readonly status: 'expired';
+    readonly error: unknown;
+};
+export interface SessionCredentialProviderOptions {
+    /** Delegation TTL every served credential must still cover; also the SessionAuth TTL. */
+    readonly ttlSeconds: number;
+    /** Acquire one fresh credential; the supplied signal is owned by the provider. */
+    mint(signal: AbortSignal): Promise<SessionCredential>;
+    /** Caller-held credential admitted as the initial entry; it need only be unexpired. */
+    readonly initial?: SessionCredential;
+    readonly onChange?: (state: SessionCredentialState) => void;
+}
+/**
+ * Caller-owned source credential with a derived refresh threshold and shared minting.
+ *
+ * The provider is a SessionAuth, so a ClientSession consumes it directly. Anticipation is opt-in:
+ * an ephemeral process or a request-scoped worker never holds a pending timer it did not ask for.
+ */
+export interface SessionCredentialProvider extends SessionAuth {
+    state(): SessionCredentialState;
+    /** Serve a credential that still covers the delegation TTL; concurrent callers share one mint. */
+    acquire(signal?: AbortSignal): Promise<SessionCredential>;
+    /** Mint regardless of the current credential, joining a mint already in flight. */
+    refresh(signal?: AbortSignal): Promise<SessionCredential>;
+    /** Begin anticipating expiry: threshold timer, bounded backoff, and an expiry watchdog. */
+    start(): void;
+    /** Stop anticipating; a mint already in flight still settles. */
+    stop(): void;
+}
+export declare function createSessionCredentialProvider(options: SessionCredentialProviderOptions): SessionCredentialProvider;

package/dist/session/credential/provider.js

@@ -0,0 +1,229 @@
+import { ClientError } from '../../errors/index.js';
+import { BACKOFF_MS, MINT_TIMEOUT_MS, RETRY_INTERVAL_MS, SETTLEMENT_SKEW_MS } from './limits.js';
+export function createSessionCredentialProvider(options) {
+    if (options === null || typeof options !== 'object') {
+        throw new TypeError('Session credential provider options are invalid.');
+    }
+    if (typeof options.mint !== 'function') {
+        throw new TypeError('Session credential mint capability is invalid.');
+    }
+    if (!Number.isSafeInteger(options.ttlSeconds) || options.ttlSeconds < 1) {
+        throw new TypeError('Session credential ttlSeconds must be a positive safe integer.');
+    }
+    if (options.onChange !== undefined && typeof options.onChange !== 'function') {
+        throw new TypeError('Session credential change observer is invalid.');
+    }
+    const { ttlSeconds } = 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;
+    let current = options.initial === undefined ? undefined : admitInitial(options.initial);
+    let state = Object.freeze(current === undefined
+        ? { status: 'empty' }
+        : { status: 'valid', credential: current });
+    let inflight;
+    let controller;
+    let waiting = 0;
+    let anticipating = false;
+    let refreshTimer;
+    let expiryTimer;
+    let attempt = 0;
+    return Object.freeze({
+        ttlSeconds,
+        state: () => state,
+        acquire,
+        refresh,
+        start,
+        stop,
+        resolve,
+    });
+    async function resolve(_call, signal) {
+        return { credential: (await acquire(signal)).credential };
+    }
+    function acquire(signal) {
+        if (current !== undefined && covers(current))
+            return Promise.resolve(current);
+        return share(signal);
+    }
+    function refresh(signal) {
+        return share(signal);
+    }
+    function start() {
+        anticipating = true;
+        attempt = 0;
+        schedule();
+    }
+    function stop() {
+        anticipating = false;
+        clearTimers();
+    }
+    /** Join the mint in flight, or begin one, while following only this caller's cancellation. */
+    function share(signal) {
+        if (signal?.aborted === true)
+            return Promise.reject(signal.reason);
+        const pending = inflight ?? begin();
+        if (signal === undefined)
+            return pending;
+        waiting += 1;
+        let settled = false;
+        return new Promise((complete, fail) => {
+            const leave = () => {
+                if (settled)
+                    return;
+                settled = true;
+                waiting -= 1;
+                signal.removeEventListener('abort', cancel);
+                // Nobody is waiting and nobody is anticipating: the mint has no beneficiary left.
+                if (waiting === 0 && !anticipating)
+                    controller?.abort(signal.reason);
+            };
+            const cancel = () => {
+                const reason = signal.reason;
+                leave();
+                fail(reason);
+            };
+            signal.addEventListener('abort', cancel, { once: true });
+            pending.then((credential) => {
+                if (settled)
+                    return;
+                settled = true;
+                waiting -= 1;
+                signal.removeEventListener('abort', cancel);
+                complete(credential);
+            }, (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                waiting -= 1;
+                signal.removeEventListener('abort', cancel);
+                fail(error);
+            });
+        });
+    }
+    function begin() {
+        publish({ status: 'refreshing', ...(current === undefined ? {} : { credential: current }) });
+        const owned = new AbortController();
+        controller = owned;
+        const signal = AbortSignal.any([owned.signal, AbortSignal.timeout(MINT_TIMEOUT_MS)]);
+        const pending = (async () => {
+            try {
+                const minted = admitMinted(await mint(signal));
+                current = minted;
+                attempt = 0;
+                publish({ status: 'valid', credential: minted });
+                if (anticipating)
+                    schedule();
+                return minted;
+            }
+            catch (error) {
+                settleFailure(error);
+                throw error;
+            }
+            finally {
+                inflight = undefined;
+                controller = undefined;
+            }
+        })();
+        inflight = pending;
+        // A rejection reaches every waiter; keep an unattached one from surfacing as unhandled.
+        pending.catch(() => undefined);
+        return pending;
+    }
+    function settleFailure(error) {
+        if (current !== undefined && current.expiresAt > Date.now()) {
+            publish({ status: 'degraded', credential: current, error });
+        }
+        else {
+            current = undefined;
+            publish({ status: 'expired', error });
+        }
+        if (anticipating)
+            retry();
+    }
+    /** Arm the threshold refresh and the expiry watchdog for the credential now held. */
+    function schedule() {
+        clearTimers();
+        if (!anticipating)
+            return;
+        if (current === undefined) {
+            void share().catch(() => undefined);
+            return;
+        }
+        // The threshold itself, with no extra lead: chained providers sharing this rule must not
+        // cascade into a mint loop, and the settlement skew already covers the round trip.
+        armRefresh(clamp(current.expiresAt - marginMs - Date.now()));
+        armExpiry(current);
+    }
+    function retry() {
+        if (refreshTimer !== undefined)
+            return;
+        const backoff = BACKOFF_MS[attempt];
+        attempt = Math.min(attempt + 1, BACKOFF_MS.length);
+        armRefresh(backoff ?? RETRY_INTERVAL_MS);
+        if (current !== undefined)
+            armExpiry(current);
+    }
+    function armRefresh(delay) {
+        refreshTimer = setTimeout(() => {
+            refreshTimer = undefined;
+            void share().catch(() => undefined);
+        }, delay);
+    }
+    function armExpiry(credential) {
+        if (expiryTimer !== undefined)
+            clearTimeout(expiryTimer);
+        expiryTimer = setTimeout(() => {
+            expiryTimer = undefined;
+            if (!anticipating || current !== credential)
+                return;
+            current = undefined;
+            publish({ status: 'expired', error: new ClientError('Session credential expired.') });
+        }, clamp(credential.expiresAt - Date.now()));
+    }
+    function clearTimers() {
+        if (refreshTimer !== undefined)
+            clearTimeout(refreshTimer);
+        if (expiryTimer !== undefined)
+            clearTimeout(expiryTimer);
+        refreshTimer = undefined;
+        expiryTimer = undefined;
+    }
+    function covers(credential) {
+        return credential.expiresAt - Date.now() > marginMs;
+    }
+    function publish(next) {
+        state = Object.freeze(next);
+        notify?.(state);
+    }
+    function admitMinted(input) {
+        const credential = admitShape(input);
+        if (credential === undefined)
+            throw new ClientError('Minted session credential is invalid.');
+        if (!covers(credential)) {
+            throw new ClientError('Minted session credential cannot cover the delegation TTL.');
+        }
+        return credential;
+    }
+}
+function admitInitial(input) {
+    const credential = admitShape(input);
+    if (credential === undefined || credential.expiresAt <= Date.now()) {
+        throw new TypeError('Initial session credential is invalid.');
+    }
+    return credential;
+}
+function admitShape(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        typeof input.credential !== 'string' ||
+        input.credential.length === 0 ||
+        !Number.isSafeInteger(input.expiresAt)) {
+        return undefined;
+    }
+    return Object.freeze({ credential: input.credential, expiresAt: input.expiresAt });
+}
+/** Keep every scheduled delay inside the platform timer range. */
+function clamp(delay) {
+    return Math.min(Math.max(delay, 0), 2_147_483_647);
+}

package/dist/session/index.d.ts

@@ -1,5 +1,6 @@
 export type { SessionControlOptions, SessionPolicy } from './context/index.js';
 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 { Auth, PersistedRoute, SessionRouteArtifact, SessionRouteStore, SessionAuth, SessionEnvelopeTransport, SessionRequestOptions, } from './routing/index.js';
 export { ClientSession, connect, type ClientSessionOptions, type ConnectOptions, } from './session.js';

package/dist/session/index.js

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

package/dist/session/reference.d.ts

@@ -1,7 +1,7 @@
 import type { Path as PathValue, PathLike } from '@astrale-os/kernel-core/path';
 import type { CallableInputOf, CallableOutputOf, CallableResultOf, Domain, ResolvedFunction, ExecutableMethod } from '@astrale-os/kernel-dsl/v1';
 import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
-import { schema as dslSchema } from '@astrale-os/kernel-dsl/v1';
+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';
 declare const REFERENCE_INPUT: unique symbol;
@@ -11,7 +11,7 @@ export interface CallableReference<InputValue = Input, Output = unknown> {
     /** @deprecated Informational only; dispatch pins `fingerprint` and revision pinning will be removed. */
     readonly revision: Revision;
     /** Meaning fingerprint of the callable; a generated reference always carries one. */
-    readonly fingerprint?: dslSchema.MeaningFingerprint;
+    readonly fingerprint?: MeaningFingerprint;
     readonly callable: KeyType.Callable;
     readonly target: PathValue;
     readonly outputMode: 'value' | 'stream' | 'binary';
@@ -22,7 +22,7 @@ export interface InstanceCallableReference<InputValue = Input, Output = unknown>
     (receiver: PathLike): CallableReference<InputValue, Output>;
     readonly origin: KeyType.Origin;
     readonly revision: Revision;
-    readonly fingerprint: dslSchema.MeaningFingerprint;
+    readonly fingerprint: MeaningFingerprint;
     readonly callable: KeyType.Callable;
     readonly outputMode: 'value' | 'stream' | 'binary';
 }

package/dist/session/reference.js

@@ -1,6 +1,6 @@
 import { Path } from '@astrale-os/kernel-core/path';
-import { schema as dslSchema } from '@astrale-os/kernel-dsl/v1';
 import { callableAddress, Key, patterns, } from '@astrale-os/kernel-dsl/v1/addressing';
+import { callableFingerprint } from '@astrale-os/kernel-dsl/v1/schema/fingerprint';
 const FINGERPRINT_PATTERN = /^sha256:[0-9a-f]{64}$/u;
 export function reference(domain, callable) {
     if (Key.origin(callable.key) !== domain.origin)
@@ -10,7 +10,7 @@ export function reference(domain, callable) {
     const common = Object.freeze({
         origin: domain.origin,
         revision: domain.revision,
-        fingerprint: dslSchema.callableFingerprint(callable),
+        fingerprint: callableFingerprint(callable),
         callable: callable.key,
         outputMode: callable.output.mode,
     });

package/dist/session/session.js

@@ -1,5 +1,5 @@
 import { Path } from '@astrale-os/kernel-core/path';
-import { schema as dslSchema } from '@astrale-os/kernel-dsl/v1';
+import { callableFingerprint } from '@astrale-os/kernel-dsl/v1/schema/fingerprint';
 import { Client } from '../client/index.js';
 import { SessionError } from '../errors/index.js';
 import { createDomainBinding } from '../graph/domain/binding.js';
@@ -178,7 +178,7 @@ export class ClientSession {
         return this.invoke({
             origin: owner.origin,
             revision: owner.revision,
-            fingerprint: dslSchema.callableFingerprint(method),
+            fingerprint: callableFingerprint(method),
             callable: method.key,
             target: Path.instanceMethod(Path.id(node.id), method.key),
             outputMode: method.output.mode,

package/dist/session/session.typecheck.js

@@ -2,7 +2,7 @@ import { NodeId } from '@astrale-os/kernel-core/graph/node';
 import { Path } from '@astrale-os/kernel-core/path';
 import { K, KernelSchema } from '@astrale-os/kernel-core/schema';
 import { defineSchema, func, method, nodeClass, schema, valueSchema, } from '@astrale-os/kernel-dsl/v1';
-import { ClientSession, reference } from './index.js';
+import { ClientSession, createSessionCredentialProvider, reference } from './index.js';
 void new ClientSession(options);
 void auth;
 void control;
@@ -12,6 +12,15 @@ void request;
 void snapshot;
 const observedPublication = session.publication(control);
 void observedPublication;
+const credentials = createSessionCredentialProvider({
+    ttlSeconds: 60,
+    mint: async () => minted,
+});
+// A credential provider is a Session authentication resolver; no adapter stands between them.
+const credentialAuth = credentials;
+void new ClientSession({ ...options, auth: credentialAuth });
+// @ts-expect-error A minted credential must carry its own absolute expiry.
+void createSessionCredentialProvider({ ttlSeconds: 60, mint: async () => minted.credential });
 const dynamicReference = reference(dynamicDomain, dynamicMethod)(Path.id(NodeId('dynamic-node')));
 void session.invoke(dynamicReference, dynamicInput);
 const dynamicInputIsClientInput = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-client",
-  "version": "0.6.0-beta.65",
+  "version": "0.6.0-beta.67",
   "description": "Universal Client — protocol-first, transport-agnostic",
   "keywords": [
     "astrale",
@@ -65,14 +65,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@astrale-os/kernel-core": "0.9.0-beta.50",
-    "@astrale-os/kernel-dsl": "0.2.0-beta.35",
-    "@astrale-os/kernel-protocol": "0.5.0-beta.56",
+    "@astrale-os/kernel-core": "0.9.0-beta.51",
+    "@astrale-os/kernel-dsl": "0.2.0-beta.36",
+    "@astrale-os/kernel-protocol": "0.5.0-beta.57",
     "@tanstack/pacer": "0.20.1",
     "msgpackr": "^2.0.5"
   },
   "devDependencies": {
-    "@astrale-os/kernel-server": "0.5.0-beta.58",
+    "@astrale-os/kernel-server": "0.5.0-beta.59",
     "@astrale/typescript-config": "npm:@jsr/astrale__typescript-config@~1.1.0",
     "@types/node": "^22.0.0",
     "typescript": "7.0.2",