@astrale-os/sdk 0.5.0-beta.67 → 0.5.0-beta.68

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.0-beta.68](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.67...sdk-v0.5.0-beta.68) (2026-08-28)
+
+
+### Performance Improvements
+
+* **execution:** cache issuer verification basis ([#307](https://github.com/astrale-os/sdk/issues/307)) ([a88f227](https://github.com/astrale-os/sdk/commit/a88f22700e61f5c5926621f95fc66638b462fbf5))
+
 ## [0.5.0-beta.67](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.66...sdk-v0.5.0-beta.67) (2026-08-28)
 
 

package/dist/execution/identity/authentication.d.ts

@@ -2,7 +2,7 @@ import type { Fetch } from '@astrale-os/kernel-client';
 import type { CredentialInput, Grant, IssuerId } from '../../platform/auth/index.js';
 import type { AuthenticatedInvocation } from '../invocation/index.js';
 import type { InvocationAdmissionInput } from '../invocation/index.js';
-import type { IdentityNetworkPolicy, VerificationBasis } from './jwks.js';
+import type { IdentityNetworkPolicy, VerificationBasis, VerificationBasisResolver } from './jwks.js';
 import type { SigningMaterial } from './signing.js';
 export declare function admit(request: InvocationAdmissionInput, configuration: AuthenticationConfiguration): Promise<unknown>;
 export interface AuthenticationConfiguration {
@@ -11,6 +11,7 @@ export interface AuthenticationConfiguration {
     readonly signing: SigningMaterial;
     readonly fetch: Fetch;
     readonly policy: IdentityNetworkPolicy;
+    readonly verification: VerificationBasisResolver;
 }
 export declare function authenticate(credentialInput: CredentialInput, expectedKernel: IssuerId, execution: {
     readonly deadline: number;

package/dist/execution/identity/authentication.js

@@ -48,7 +48,7 @@ export async function admit(request, configuration) {
     }
 }
 export async function authenticate(credentialInput, expectedKernel, execution, configuration) {
-    const established = await establishCaller(credentialInput, configuration.issuer, configuration.fetch, execution, configuration.policy);
+    const established = await establishCaller(credentialInput, configuration.issuer, configuration.verification, execution, configuration.policy);
     if (established.verified.iss !== expectedKernel) {
         throw protocolError('AUTH_INVALID', 'Credential is invalid.');
     }
@@ -104,10 +104,10 @@ export async function authenticate(credentialInput, expectedKernel, execution, c
         });
     }
 }
-async function establishCaller(input, audience, fetch, execution, policy) {
+async function establishCaller(input, audience, verification, execution, policy) {
     requireLive(execution);
     try {
-        const context = await verifyCredential(input, audience, fetch, execution.signal, policy);
+        const context = await verifyCredential(input, audience, verification, execution.signal, policy);
         const carried = delegation.accept(context.verified.claims.delegation);
         if (typeof carried.credential !== 'string') {
             throw new CredentialRejected('Destination carrier has no Kernel authority proof.');

package/dist/execution/identity/exchange.d.ts

@@ -1,10 +1,9 @@
-import type { Fetch } from '@astrale-os/kernel-client';
 import type { exchange } from '@astrale-os/kernel-server';
 import type { IssuerId } from '../../platform/auth/index.js';
-import type { IdentityNetworkPolicy } from './jwks.js';
+import type { IdentityNetworkPolicy, VerificationBasisResolver } from './jwks.js';
 import type { SigningMaterial } from './signing.js';
 export interface ExchangeOptions {
     readonly maximumTtlSeconds?: number;
 }
 export declare function maximumExchangeTtl(input: ExchangeOptions | undefined): number;
-export declare function tokenExchange(issuer: IssuerId, subject: string, signing: SigningMaterial, fetch: Fetch, policy: IdentityNetworkPolicy, maximumTtlSeconds: number): exchange.Provider;
+export declare function tokenExchange(issuer: IssuerId, subject: string, signing: SigningMaterial, policy: IdentityNetworkPolicy, verification: VerificationBasisResolver, maximumTtlSeconds: number): exchange.Provider;

package/dist/execution/identity/exchange.js

@@ -22,19 +22,22 @@ export function maximumExchangeTtl(input) {
     }
     return value;
 }
-export function tokenExchange(issuer, subject, signing, fetch, policy, maximumTtlSeconds) {
+export function tokenExchange(issuer, subject, signing, policy, verification, maximumTtlSeconds) {
     return Object.freeze({
         async exchange(request, context) {
             try {
-                const outer = await verifyCredential(request.token, issuer, fetch, context.signal, policy);
+                context.signal.throwIfAborted();
+                const outer = await verifyCredential(request.token, issuer, verification, context.signal, policy);
                 requireProfile(outer.verified, 'outer');
                 const carried = delegation.accept(outer.verified.claims.delegation);
                 if (typeof carried.credential !== 'string')
                     invalid();
+                context.signal.throwIfAborted();
                 const inner = await verifyCredentialAgainst(carried.credential, outer.verified.iss, outer.basis);
                 requireProfile(inner.verified, 'inner');
                 requireCoherence(outer.verified, inner.verified);
                 acceptResolvedDelegation(inner.verified.claims.delegation);
+                context.signal.throwIfAborted();
                 const now = Math.floor(Date.now() / 1_000);
                 const expiresAt = Math.min(outer.verified.exp, inner.verified.exp, now + maximumTtlSeconds);
                 if (expiresAt <= now)
@@ -55,6 +58,7 @@ export function tokenExchange(issuer, subject, signing, fetch, policy, maximumTt
                     .setIssuedAt(now)
                     .setExpirationTime(expiresAt)
                     .sign(await signing.privateKey);
+                context.signal.throwIfAborted();
                 return issuerExchange.response(token, expiresAt);
             }
             catch (cause) {

package/dist/execution/identity/identity.js

@@ -2,6 +2,7 @@ import { admit, authenticate } from './authentication.js';
 import { publicationDelivery } from './delivery.js';
 import { httpIssuer } from './errors.js';
 import { maximumExchangeTtl, tokenExchange } from './exchange.js';
+import { createVerificationBasisResolver } from './jwks.js';
 import { signing } from './signing.js';
 /** Create one stateless execution identity backed by an asymmetric private JWK. */
 export function createIdentity(input) {
@@ -25,16 +26,18 @@ export function createIdentity(input) {
         ...(input.allowEndpoint === undefined ? {} : { allowEndpoint: input.allowEndpoint }),
         ...(input.allowInsecureHttp === true ? { allowInsecureHttp: true } : {}),
     });
+    const verification = createVerificationBasisResolver(fetch, policy);
     const configuration = Object.freeze({
         issuer,
         subject: input.subject,
         signing: material,
         fetch,
         policy,
+        verification,
     });
     const exchangeProvider = input.tokenExchange === false
         ? undefined
-        : tokenExchange(issuer, input.subject, material, fetch, policy, maximumExchangeTtl(input.tokenExchange));
+        : tokenExchange(issuer, input.subject, material, policy, verification, maximumExchangeTtl(input.tokenExchange));
     return identity({
         issuer,
         subject: input.subject,

package/dist/execution/identity/jwks.d.ts

@@ -10,7 +10,15 @@ export interface VerificationBasis {
     readonly algorithms: readonly [string, ...string[]];
     readonly keys: readonly JsonWebKey[];
 }
-export declare function verifyCredential(input: CredentialInput, audience: IssuerId, fetch: Fetch, signal: AbortSignal, policy: IdentityNetworkPolicy): Promise<{
+export interface VerificationBasisResolver {
+    resolve(issuer: IssuerId, keyId: string | undefined, signal: AbortSignal): Promise<VerificationBasis>;
+}
+/**
+ * Retain only recently admitted public issuer material for one execution Identity.
+ * An unseen key ID may refresh once per cooldown; failures never replace a usable basis.
+ */
+export declare function createVerificationBasisResolver(fetch: Fetch, policy: IdentityNetworkPolicy, now?: () => number): VerificationBasisResolver;
+export declare function verifyCredential(input: CredentialInput, audience: IssuerId, bases: VerificationBasisResolver, signal: AbortSignal, policy: IdentityNetworkPolicy): Promise<{
     readonly raw: CredentialInput;
     readonly verified: VerifiedCredential;
     readonly basis: VerificationBasis;

package/dist/execution/identity/jwks.js

@@ -5,7 +5,94 @@ import { errors as joseErrors, importJWK, jwtVerify } from 'jose';
 import { credential } from '../../platform/auth/index.js';
 import { CredentialRejected, IssuerUnavailable, admitEndpoint, httpIssuer } from './errors.js';
 const MAXIMUM_DISCOVERY_BYTES = 256 * 1024;
-export async function verifyCredential(input, audience, fetch, signal, policy) {
+const MAXIMUM_VERIFICATION_BASES = 64;
+const VERIFICATION_BASIS_TTL_MS = 60_000;
+const UNKNOWN_KEY_REFRESH_COOLDOWN_MS = 60_000;
+/**
+ * Retain only recently admitted public issuer material for one execution Identity.
+ * An unseen key ID may refresh once per cooldown; failures never replace a usable basis.
+ */
+export function createVerificationBasisResolver(fetch, policy, now = Date.now) {
+    const bases = new Map();
+    const pending = new Map();
+    return Object.freeze({
+        async resolve(issuer, keyId, signal) {
+            signal.throwIfAborted();
+            const cached = bases.get(issuer);
+            const observedAt = now();
+            const age = cached === undefined ? Number.POSITIVE_INFINITY : observedAt - cached.refreshedAt;
+            const fresh = cached !== undefined && age >= 0 && age < VERIFICATION_BASIS_TTL_MS;
+            const knownKey = keyId === undefined ||
+                cached?.basis.keys.some((candidate) => candidate.kid === keyId) === true;
+            const unknownKeyCooldown = cached?.unknownKeyRefreshedAt !== undefined &&
+                observedAt - cached.unknownKeyRefreshedAt >= 0 &&
+                observedAt - cached.unknownKeyRefreshedAt < UNKNOWN_KEY_REFRESH_COOLDOWN_MS;
+            if (fresh && knownKey) {
+                bases.delete(issuer);
+                bases.set(issuer, cached);
+                return cached.basis;
+            }
+            const unknownKeyRefresh = cached !== undefined && !knownKey;
+            let refresh = pending.get(issuer);
+            if (refresh === undefined && fresh && unknownKeyCooldown) {
+                bases.delete(issuer);
+                bases.set(issuer, cached);
+                return cached.basis;
+            }
+            if (refresh === undefined && unknownKeyRefresh && cached !== undefined) {
+                bases.set(issuer, Object.freeze({ ...cached, unknownKeyRefreshedAt: observedAt }));
+            }
+            if (refresh === undefined) {
+                const controller = new AbortController();
+                refresh = {
+                    controller,
+                    operation: undefined,
+                    subscribers: 0,
+                    settled: false,
+                    unknownKeyRefresh,
+                    requestedKeyIds: new Set(keyId === undefined ? [] : [keyId]),
+                };
+                const owned = refresh;
+                owned.operation = discover(issuer, fetch, controller.signal, policy)
+                    .then((basis) => {
+                    controller.signal.throwIfAborted();
+                    const refreshedAt = now();
+                    if (bases.size >= MAXIMUM_VERIFICATION_BASES && !bases.has(issuer)) {
+                        const oldest = bases.keys().next().value;
+                        if (oldest !== undefined)
+                            bases.delete(oldest);
+                    }
+                    bases.delete(issuer);
+                    bases.set(issuer, Object.freeze({
+                        basis,
+                        refreshedAt,
+                        ...(owned.unknownKeyRefresh ||
+                            [...owned.requestedKeyIds].some((requested) => !basis.keys.some((candidate) => candidate.kid === requested))
+                            ? { unknownKeyRefreshedAt: refreshedAt }
+                            : {}),
+                    }));
+                    return basis;
+                })
+                    .finally(() => {
+                    owned.settled = true;
+                    if (pending.get(issuer) === owned)
+                        pending.delete(issuer);
+                });
+                pending.set(issuer, owned);
+            }
+            else if (unknownKeyRefresh) {
+                refresh.unknownKeyRefresh = true;
+            }
+            if (keyId !== undefined)
+                refresh.requestedKeyIds.add(keyId);
+            const basis = await subscribe(refresh, issuer, pending, signal);
+            signal.throwIfAborted();
+            return basis;
+        },
+    });
+}
+export async function verifyCredential(input, audience, bases, signal, policy) {
+    signal.throwIfAborted();
     let inspected;
     try {
         inspected = credential.inspect(input);
@@ -22,11 +109,48 @@ export async function verifyCredential(input, audience, fetch, signal, policy) {
     catch (cause) {
         throw new CredentialRejected('Credential issuer is invalid.', cause);
     }
-    const basis = await discover(admittedIssuer, fetch, signal, policy);
+    const basis = await bases.resolve(admittedIssuer, inspected.kid, signal);
+    signal.throwIfAborted();
     const verified = await verifyCredentialAgainst(input, audience, basis, inspected);
+    signal.throwIfAborted();
     admitEndpoint(`${admittedIssuer.replace(/\/+$/u, '')}/invoke`, policy);
     return Object.freeze({ raw: input, verified: verified.verified, basis });
 }
+function subscribe(refresh, issuer, pending, signal) {
+    signal.throwIfAborted();
+    refresh.subscribers += 1;
+    return new Promise((resolve, reject) => {
+        let complete = false;
+        const finish = () => {
+            if (complete)
+                return false;
+            complete = true;
+            signal.removeEventListener('abort', cancel);
+            refresh.subscribers -= 1;
+            if (!refresh.settled && refresh.subscribers === 0) {
+                if (pending.get(issuer) === refresh)
+                    pending.delete(issuer);
+                refresh.controller.abort(new DOMException('Issuer discovery was cancelled.', 'AbortError'));
+            }
+            return true;
+        };
+        const cancel = () => {
+            if (!finish())
+                return;
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', cancel, { once: true });
+        refresh.operation.then((basis) => {
+            if (!finish())
+                return;
+            resolve(basis);
+        }, (cause) => {
+            if (!finish())
+                return;
+            reject(cause);
+        });
+    });
+}
 export async function verifyCredentialAgainst(input, audience, basis, preinspected) {
     let inspected;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.5.0-beta.67",
+  "version": "0.5.0-beta.68",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",