@astrale-os/cli 1.0.0-beta.31 → 1.0.0-beta.32

package/dist/astrale.js

@@ -2578,7 +2578,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@astrale-os/cli",
-    version: "1.0.0-beta.31",
+    version: "1.0.0-beta.32",
     description: "Astrale CLI — connect to existing Astrale kernels",
     keywords: [
       "astrale",
@@ -34087,6 +34087,20 @@ var init_auth4 = __esm(() => {
   init_auth();
 });
 
+// src/lib/credential-lifetime.ts
+function remainingCredentialLifetimeSeconds(expiresAtEpochSeconds, nowEpochSeconds = Math.ceil(Date.now() / 1000)) {
+  if (!Number.isSafeInteger(expiresAtEpochSeconds) || !Number.isSafeInteger(nowEpochSeconds)) {
+    throw new TypeError("Credential expiration and current time must be safe epoch seconds.");
+  }
+  return expiresAtEpochSeconds - nowEpochSeconds - 1;
+}
+function credentialLifetimeCovers(expiresAtEpochSeconds, minimumRemainingSeconds, nowEpochSeconds) {
+  if (!Number.isSafeInteger(minimumRemainingSeconds) || minimumRemainingSeconds < 1) {
+    throw new TypeError("Credential minimum lifetime must be a positive safe integer.");
+  }
+  return remainingCredentialLifetimeSeconds(expiresAtEpochSeconds, nowEpochSeconds) >= minimumRemainingSeconds;
+}
+
 // src/state/paths.ts
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -34141,15 +34155,19 @@ class ExchangeCredentialCache {
   constructor(path = EXCHANGE_CREDENTIALS_PATH) {
     this.path = path;
   }
-  getOrRefresh(key, refresh, now = () => Math.floor(Date.now() / 1000)) {
+  getOrRefresh(key, minimumRemainingSeconds, refresh, now = () => Math.floor(Date.now() / 1000)) {
+    if (!Number.isSafeInteger(minimumRemainingSeconds) || minimumRemainingSeconds < 1) {
+      throw new TypeError("Exchange credential minimum lifetime must be a positive safe integer.");
+    }
     const encoded = encodeKey(key);
-    const current = this.refreshing.get(encoded);
+    const pendingKey = `${encoded}\x00${minimumRemainingSeconds}`;
+    const current = this.refreshing.get(pendingKey);
     if (current !== undefined)
       return current;
-    const pending = this.getOrRefreshOnce(key, encoded, refresh, now).finally(() => {
-      this.refreshing.delete(encoded);
+    const pending = this.getOrRefreshOnce(key, encoded, minimumRemainingSeconds, refresh, now).finally(() => {
+      this.refreshing.delete(pendingKey);
     });
-    this.refreshing.set(encoded, pending);
+    this.refreshing.set(pendingKey, pending);
     return pending;
   }
   async deleteKernel(kernelIssuer) {
@@ -34167,20 +34185,20 @@ class ExchangeCredentialCache {
         delete store.entries[encoded];
     });
   }
-  async getOrRefreshOnce(key, encoded, refresh, now) {
+  async getOrRefreshOnce(key, encoded, minimumRemainingSeconds, refresh, now) {
     return withFileLock(`${this.path}.lock`, async () => {
       await ensurePrivateDirectory(this.path);
       const store = await readStore(this.path);
       const changed = scrub(store, now());
       const cached3 = store.entries[encoded];
-      if (cached3 !== undefined && validEntry(key, cached3, now())) {
+      if (cached3 !== undefined && validEntry(key, cached3, now(), minimumRemainingSeconds)) {
         if (changed)
           await writeStore(this.path, store);
         return cached3.credential;
       }
       const next = await refresh();
-      if (!validEntry(key, next, now(), 1)) {
-        throw new Error("Token exchange returned a credential inconsistent with its cache key.");
+      if (!validEntry(key, next, now(), minimumRemainingSeconds)) {
+        throw new Error("Token exchange returned a credential inconsistent with its cache key or required lifetime.");
       }
       store.entries[encoded] = Object.freeze({ ...next });
       await writeStore(this.path, store);
@@ -34239,7 +34257,7 @@ function validEntry(key, entry, now, minimumRemaining = MINIMUM_REMAINING_SECOND
       return false;
     }
     exports_grant.accept({ expr: Reflect.get(issued, "expr") });
-    return inspected.iss === key.domainIssuer && inspected.aud === key.kernelIssuer && inspected.claims.exp === entry.expiresAt && !Object.hasOwn(inspected.claims, "delegation") && proof.iss === key.kernelIssuer && proof.sub === entry.user && proof.aud === key.kernelIssuer;
+    return inspected.iss === key.domainIssuer && inspected.aud === key.kernelIssuer && inspected.claims.exp === entry.expiresAt && !Object.hasOwn(inspected.claims, "delegation") && proof.iss === key.kernelIssuer && proof.sub === entry.user && proof.aud === key.kernelIssuer && typeof proof.claims.exp === "number" && Number.isSafeInteger(proof.claims.exp) && credentialLifetimeCovers(proof.claims.exp, minimumRemaining, now);
   } catch {
     return false;
   }
@@ -38190,18 +38208,25 @@ function isSessionExpired(session, skewMs = 60000) {
     return false;
   return new Date(expiresAt).getTime() <= Date.now() + skewMs;
 }
-function accessTokenForAudience(session, audience) {
+function accessTokenForAudience(session, audience, minimumRemainingMs = 60000) {
   if (audience === undefined) {
-    return isSessionExpired(session) ? undefined : session.access_token;
+    return tokenHasMinimumLifetime(session, minimumRemainingMs) ? session.access_token : undefined;
   }
   const entry = session.tokens?.[audience];
-  if (entry && !isSessionExpired(entry))
+  if (entry && tokenHasMinimumLifetime(entry, minimumRemainingMs))
     return entry.access_token;
-  if (!isSessionExpired(session) && tokenAudienceMatches(session.access_token, audience)) {
+  if (tokenHasMinimumLifetime(session, minimumRemainingMs) && tokenAudienceMatches(session.access_token, audience)) {
     return session.access_token;
   }
   return;
 }
+function tokenHasMinimumLifetime(value2, minimumRemainingMs) {
+  const expiration = decodeTokenClaims(value2.access_token)?.exp;
+  if (typeof expiration === "number" && Number.isSafeInteger(expiration)) {
+    return credentialLifetimeCovers(expiration, Math.ceil(minimumRemainingMs / 1000));
+  }
+  return !isSessionExpired(value2, minimumRemainingMs);
+}
 function withCachedToken(tokens, accessToken, expiresAt) {
   const next = {};
   for (const [aud2, entry] of Object.entries(tokens ?? {})) {
@@ -80780,10 +80805,11 @@ function idpSessionLockPath(identityName) {
   return `${idpSessionPath(identityName)}.lock`;
 }
 async function ensureFreshSession(identityName, opts = {}) {
+  const minimumRemainingMs = minimumLifetimeMs(opts.minimumRemainingSeconds);
   const session3 = await readIdpSession(identityName);
   if (!session3)
     throw new IdpSessionMissingError(identityName);
-  if (accessTokenForAudience(session3, opts.audience))
+  if (accessTokenForAudience(session3, opts.audience, minimumRemainingMs))
     return session3;
   if (!session3.refresh_token)
     throw new IdpSessionNoRefreshTokenError(identityName);
@@ -80791,7 +80817,7 @@ async function ensureFreshSession(identityName, opts = {}) {
     const current = await readIdpSession(identityName);
     if (!current)
       throw new IdpSessionMissingError(identityName);
-    if (accessTokenForAudience(current, opts.audience))
+    if (accessTokenForAudience(current, opts.audience, minimumRemainingMs))
       return current;
     const bookmarkOrg = opts.organizationId ?? (opts.audience ? await orgIdForAudience(opts.audience) : undefined);
     const organizationId = bookmarkOrg ?? (opts.audience ? await (opts.resolveOrganizationId ?? fetchOrgHint)(opts.audience) : undefined);
@@ -80810,23 +80836,30 @@ async function ensureFreshSession(identityName, opts = {}) {
           });
         }
       }
-      const rescued = await rescueAfterInvalidGrant(identityName, current, opts.audience, e);
+      const rescued = await rescueAfterInvalidGrant(identityName, current, opts.audience, minimumRemainingMs, e);
       if (rescued)
         return rescued;
       throw e;
     }
   });
 }
-async function rescueAfterInvalidGrant(identityName, seen, audience, error52) {
+async function rescueAfterInvalidGrant(identityName, seen, audience, minimumRemainingMs, error52) {
   if (!(error52 instanceof OAuthTokenError) || error52.code !== "invalid_grant")
     return;
   const latest = await readIdpSession(identityName).catch(() => null);
   if (!latest || latest.updatedAt === seen.updatedAt)
     return;
-  if (!accessTokenForAudience(latest, audience))
+  if (!accessTokenForAudience(latest, audience, minimumRemainingMs))
     return;
   return latest;
 }
+function minimumLifetimeMs(input) {
+  const seconds = input ?? 60;
+  if (!Number.isSafeInteger(seconds) || seconds < 1 || seconds > Math.floor(Number.MAX_SAFE_INTEGER / 1000)) {
+    throw new TypeError("IdP session minimum lifetime must be a positive safe integer.");
+  }
+  return seconds * 1000;
+}
 var IdpSessionMissingError, IdpSessionNoRefreshTokenError;
 var init_idp_session = __esm(() => {
   init_state();
@@ -80871,14 +80904,14 @@ async function resolveCredential2(opts, config2, audience = config2.issuer, regi
       resolvedIdentity = identity4;
       resolvedName = identityName;
       if ((identity4.source ?? "key") === "idp")
-        return await resolveIdpAccessToken(identityName, identity4, audience);
+        return await resolveIdpAccessToken(identityName, identity4, audience, opts.minimumRemainingSeconds);
       return await signAs(identity4.subject, KEYS_DIR, resolveKeyIdentityAuthOptions(identity4, config2, audience, registrationKey));
     }
     const identity3 = await getDefault();
     resolvedIdentity = identity3;
     resolvedName = identity3.name;
     if ((identity3.source ?? "key") === "idp") {
-      return await resolveIdpAccessToken(identity3.name, identity3, audience);
+      return await resolveIdpAccessToken(identity3.name, identity3, audience, opts.minimumRemainingSeconds);
     }
     return await signAs(identity3.subject, KEYS_DIR, resolveKeyIdentityAuthOptions(identity3, config2, audience, registrationKey));
   } catch (e) {
@@ -80920,10 +80953,10 @@ function resolveKeyIdentityAuthOptions(identity3, config2, audience = config2.is
 function systemIdentityIssuer(identity3, audience, config2) {
   return identity3.subject === "system" ? audience : config2.issuer;
 }
-async function resolveIdpAccessToken(identityName, identity3, audience) {
+async function resolveIdpAccessToken(identityName, identity3, audience, minimumRemainingSeconds) {
   let resolved;
   try {
-    resolved = await ensureFreshSession(identityName, { audience });
+    resolved = await ensureFreshSession(identityName, { audience, minimumRemainingSeconds });
   } catch (e) {
     if (e instanceof IdpSessionMissingError) {
       throw new Error(`No cached IdP session for "${identityName}". Run: astrale auth login --idp ${identity3.idp ?? "<idp>"}`);
@@ -80978,9 +81011,26 @@ var init_auth7 = __esm(() => {
   };
 });
 
+// src/connection/lifetime.ts
+function invocationCredentialTtlSeconds(timeoutMs) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+    throw new TypeError("Invocation credential timeout must be a positive safe integer.");
+  }
+  return Math.max(MINIMUM_CREDENTIAL_TTL_SECONDS, Math.ceil(timeoutMs / 1000) + INVOCATION_RECEIPT_MARGIN_SECONDS);
+}
+function exchangeCredentialTtlSeconds(timeoutMs) {
+  return invocationCredentialTtlSeconds(timeoutMs) + TOKEN_EXCHANGE_SETTLEMENT_MARGIN_SECONDS;
+}
+function cachedCredentialTtlSeconds(timeoutMs) {
+  return invocationCredentialTtlSeconds(timeoutMs) + CACHE_HANDOFF_MARGIN_SECONDS;
+}
+var MINIMUM_CREDENTIAL_TTL_SECONDS = 60, INVOCATION_RECEIPT_MARGIN_SECONDS = 5, CACHE_HANDOFF_MARGIN_SECONDS = 5, TOKEN_EXCHANGE_SETTLEMENT_MARGIN_SECONDS = 15;
+
 // src/connection/exchange.ts
 function createExchangeCredentialResolver(target2, source2, fetch2, timeoutMs, cache2 = new ExchangeCredentialCache) {
   requireExchangeTransport(target2);
+  const cacheTtlSeconds = cachedCredentialTtlSeconds(timeoutMs);
+  const exchangeTtlSeconds = exchangeCredentialTtlSeconds(timeoutMs);
   return Object.freeze({
     async resolve(kernelIssuer, signal) {
       requireLive3(signal);
@@ -80992,8 +81042,8 @@ function createExchangeCredentialResolver(target2, source2, fetch2, timeoutMs, c
         domainIssuer: target2.domainIssuer,
         sourceIssuer: sourceIdentity.issuer,
         sourceSubject: sourceIdentity.subject
-      }), async () => {
-        const delegationTtlSeconds = delegationLifetime(sourceToken);
+      }), cacheTtlSeconds, async () => {
+        const delegationTtlSeconds = delegationLifetime(sourceToken, exchangeTtlSeconds);
         const client = new Client({ url: `${kernelIssuer}/invoke`, fetch: fetch2, timeoutMs });
         try {
           const authenticated3 = client.as(sourceToken);
@@ -81022,7 +81072,7 @@ function createExchangeCredentialResolver(target2, source2, fetch2, timeoutMs, c
           if (envelope === undefined)
             throw new Error("Token delegation returned no credential.");
           return {
-            ...await exchange(target2.domainIssuer, kernelIssuer, envelope, fetch2, signal),
+            ...await exchange(target2.domainIssuer, kernelIssuer, envelope, cacheTtlSeconds, fetch2, signal),
             user: user.id,
             sourceIssuer: sourceIdentity.issuer,
             sourceSubject: sourceIdentity.subject
@@ -81051,18 +81101,21 @@ function unknownFunctionOutcome(cause) {
     return false;
   return error52.reason.code === "FUNCTION_OUTCOME_UNKNOWN";
 }
-function delegationLifetime(sourceToken) {
+function delegationLifetime(sourceToken, requiredTtlSeconds) {
   const expiresAt = exports_credential.inspect(sourceToken).claims.exp;
   if (typeof expiresAt !== "number" || !Number.isSafeInteger(expiresAt)) {
     throw new AstraleError("TOKEN_EXCHANGE_SOURCE_INVALID", "The source identity credential has no valid expiration.");
   }
-  const remaining = expiresAt - Math.ceil(Date.now() / 1000) - 1;
+  const remaining = remainingCredentialLifetimeSeconds(expiresAt);
   if (!Number.isSafeInteger(remaining) || remaining < 1) {
     throw new AstraleError("TOKEN_EXCHANGE_SOURCE_EXPIRED", "The source identity credential has no lifetime available for token exchange.");
   }
-  return Math.min(EXCHANGE_TTL_SECONDS, remaining);
+  if (remaining < requiredTtlSeconds) {
+    throw new AstraleError("TOKEN_EXCHANGE_SOURCE_LIFETIME_INSUFFICIENT", "The source credential cannot cover the requested command timeout.", `Refresh the identity session or use a shorter --timeout; ${remaining} seconds remain but ${requiredTtlSeconds} are required.`);
+  }
+  return requiredTtlSeconds;
 }
-async function exchange(domainIssuer, kernelIssuer, envelope, fetch2, signal) {
+async function exchange(domainIssuer, kernelIssuer, envelope, requiredTtlSeconds, fetch2, signal) {
   const configurationUrl = new URL(exports_exchange.paths(domainIssuer).configuration, domainIssuer).toString();
   const configurationResponse = await fetchExchange(fetch2, configurationUrl, {
     method: "GET",
@@ -81119,8 +81172,31 @@ async function exchange(domainIssuer, kernelIssuer, envelope, fetch2, signal) {
   if (inspected.iss !== domainIssuer || inspected.aud !== kernelIssuer || inspected.claims.exp !== exchanged.expiresAt) {
     throw new AstraleError("TOKEN_EXCHANGE_PROTOCOL_ERROR", "Token exchange returned a credential inconsistent with the requested Domain and Kernel.");
   }
+  const remaining = effectiveExchangeLifetime(inspected, exchanged.expiresAt);
+  if (remaining < requiredTtlSeconds) {
+    throw new AstraleError("TOKEN_EXCHANGE_LIFETIME_INSUFFICIENT", "The Domain exchange credential cannot cover the requested command timeout.", `The Domain issuer returned ${Math.max(0, remaining)} seconds but ${requiredTtlSeconds} are required. Use a shorter --timeout or update the Domain execution service.`);
+  }
   return Object.freeze({ credential: exchanged.token, expiresAt: exchanged.expiresAt });
 }
+function effectiveExchangeLifetime(inspected, outerExpiresAt) {
+  let proofExpiresAt;
+  try {
+    const carried = exports_grant.acceptUnresolved(inspected.claims.grant).expr;
+    if (carried.kind !== "identity" || !("credential" in carried) || typeof carried.credential !== "string") {
+      throw new TypeError("Domain credential does not carry an identity proof.");
+    }
+    const value3 = exports_credential.inspect(carried.credential).claims.exp;
+    if (typeof value3 !== "number" || !Number.isSafeInteger(value3)) {
+      throw new TypeError("Domain credential carries an identity proof without an expiration.");
+    }
+    proofExpiresAt = value3;
+  } catch (cause) {
+    if (!(cause instanceof TypeError))
+      throw cause;
+    throw new AstraleError("TOKEN_EXCHANGE_PROTOCOL_ERROR", "Token exchange returned an invalid carried identity proof.", cause.message);
+  }
+  return remainingCredentialLifetimeSeconds(Math.min(outerExpiresAt, proofExpiresAt));
+}
 async function fetchExchange(fetch2, input, init, message2) {
   try {
     return await fetch2(input, init);
@@ -81191,14 +81267,13 @@ function requireLive3(signal) {
     return;
   throw signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted.", "AbortError");
 }
-var EXCHANGE_TTL_SECONDS, MAXIMUM_RESPONSE_BYTES;
+var MAXIMUM_RESPONSE_BYTES;
 var init_exchange4 = __esm(() => {
   init_auth4();
   init_auth4();
   init_client3();
   init_errors2();
   init_exchange_credentials();
-  EXCHANGE_TTL_SECONDS = 5 * 60;
   MAXIMUM_RESPONSE_BYTES = 256 * 1024;
 });
 
@@ -81388,28 +81463,36 @@ var init_target2 = __esm(() => {
 });
 
 // src/connection/credential.ts
-function createConnectionCredential(expectedSourceIssuer, source2) {
+function createConnectionCredential(expectedSourceIssuer, source2, ttlSeconds = DELEGATION_TTL_SECONDS) {
+  if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 1) {
+    throw new TypeError("Connection credential ttlSeconds must be a positive safe integer.");
+  }
   const resolveSource = source2.resolve.bind(source2);
   return Object.freeze({
-    ttlSeconds: DELEGATION_TTL_SECONDS,
+    ttlSeconds,
     async resolve(_call, signal) {
       const resolved = await resolveSource(expectedSourceIssuer, signal);
-      const ttlSeconds = sourceBoundDelegationTtl(resolved);
+      const delegatedTtlSeconds = sourceBoundDelegationTtl(resolved, ttlSeconds);
       return Object.freeze({
         credential: resolved,
-        ...ttlSeconds === undefined ? {} : { delegate: { ttlSeconds } }
+        ...delegatedTtlSeconds === undefined ? {} : { delegate: { ttlSeconds: delegatedTtlSeconds } }
       });
     }
   });
 }
-function sourceBoundDelegationTtl(input) {
+function sourceBoundDelegationTtl(input, requestedTtlSeconds) {
   try {
     const expiresAt = exports_credential.inspect(input).claims.exp;
     if (typeof expiresAt !== "number" || !Number.isSafeInteger(expiresAt))
       return;
-    const remaining = expiresAt - Math.ceil(Date.now() / 1000) - 1;
-    return Math.max(1, Math.min(DELEGATION_TTL_SECONDS, remaining));
-  } catch {
+    const remaining = remainingCredentialLifetimeSeconds(expiresAt);
+    if (remaining < requestedTtlSeconds) {
+      throw new AstraleError("CREDENTIAL_LIFETIME_INSUFFICIENT", "The selected credential cannot cover the requested command timeout.", `Use a fresh identity session or a shorter --timeout; ${Math.max(0, remaining)} seconds remain but ${requestedTtlSeconds} are required.`);
+    }
+    return Math.max(1, Math.min(requestedTtlSeconds, remaining));
+  } catch (cause) {
+    if (cause instanceof AstraleError)
+      throw cause;
     return;
   }
 }
@@ -81420,7 +81503,8 @@ function createCliCredential(target2, options, config2, fetch2 = globalThis.fetc
   const authOptions = Object.freeze({
     ...options.as === undefined ? {} : { as: options.as },
     ...options.creds === undefined ? {} : { creds: options.creds },
-    ...target2.defaultIdentity === undefined ? {} : { defaultIdentity: target2.defaultIdentity }
+    ...target2.defaultIdentity === undefined ? {} : { defaultIdentity: target2.defaultIdentity },
+    minimumRemainingSeconds: target2.domainIssuer === undefined ? invocationCredentialTtlSeconds(timeoutMs) : exchangeCredentialTtlSeconds(timeoutMs)
   });
   const source2 = {
     async resolve(audience, signal) {
@@ -81431,7 +81515,8 @@ function createCliCredential(target2, options, config2, fetch2 = globalThis.fetc
     }
   };
   const effective = target2.domainIssuer === undefined || options.creds !== undefined ? source2 : createExchangeCredentialResolver({ ...target2, domainIssuer: target2.domainIssuer }, source2, fetch2, timeoutMs);
-  return createConnectionCredential(target2.kernelIssuer, effective);
+  const ttlSeconds = invocationCredentialTtlSeconds(timeoutMs);
+  return createConnectionCredential(target2.kernelIssuer, effective, ttlSeconds);
 }
 function validateCredentialSelection(options) {
   if (options.as !== undefined && options.creds !== undefined) {

package/dist/public/connect-core.js

@@ -22743,6 +22743,20 @@ function date4(params) {
 
 // node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 config(en_default());
+// src/lib/credential-lifetime.ts
+function remainingCredentialLifetimeSeconds(expiresAtEpochSeconds, nowEpochSeconds = Math.ceil(Date.now() / 1000)) {
+  if (!Number.isSafeInteger(expiresAtEpochSeconds) || !Number.isSafeInteger(nowEpochSeconds)) {
+    throw new TypeError("Credential expiration and current time must be safe epoch seconds.");
+  }
+  return expiresAtEpochSeconds - nowEpochSeconds - 1;
+}
+function credentialLifetimeCovers(expiresAtEpochSeconds, minimumRemainingSeconds, nowEpochSeconds) {
+  if (!Number.isSafeInteger(minimumRemainingSeconds) || minimumRemainingSeconds < 1) {
+    throw new TypeError("Credential minimum lifetime must be a positive safe integer.");
+  }
+  return remainingCredentialLifetimeSeconds(expiresAtEpochSeconds, nowEpochSeconds) >= minimumRemainingSeconds;
+}
+
 // src/state/paths.ts
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -24130,18 +24144,25 @@ function isSessionExpired(session, skewMs = 60000) {
     return false;
   return new Date(expiresAt).getTime() <= Date.now() + skewMs;
 }
-function accessTokenForAudience(session, audience) {
+function accessTokenForAudience(session, audience, minimumRemainingMs = 60000) {
   if (audience === undefined) {
-    return isSessionExpired(session) ? undefined : session.access_token;
+    return tokenHasMinimumLifetime(session, minimumRemainingMs) ? session.access_token : undefined;
   }
   const entry = session.tokens?.[audience];
-  if (entry && !isSessionExpired(entry))
+  if (entry && tokenHasMinimumLifetime(entry, minimumRemainingMs))
     return entry.access_token;
-  if (!isSessionExpired(session) && tokenAudienceMatches(session.access_token, audience)) {
+  if (tokenHasMinimumLifetime(session, minimumRemainingMs) && tokenAudienceMatches(session.access_token, audience)) {
     return session.access_token;
   }
   return;
 }
+function tokenHasMinimumLifetime(value2, minimumRemainingMs) {
+  const expiration = decodeTokenClaims(value2.access_token)?.exp;
+  if (typeof expiration === "number" && Number.isSafeInteger(expiration)) {
+    return credentialLifetimeCovers(expiration, Math.ceil(minimumRemainingMs / 1000));
+  }
+  return !isSessionExpired(value2, minimumRemainingMs);
+}
 function withCachedToken(tokens, accessToken, expiresAt) {
   const next = {};
   for (const [aud2, entry] of Object.entries(tokens ?? {})) {
@@ -25047,10 +25068,11 @@ function idpSessionLockPath(identityName) {
   return `${idpSessionPath(identityName)}.lock`;
 }
 async function ensureFreshSession(identityName, opts = {}) {
+  const minimumRemainingMs = minimumLifetimeMs(opts.minimumRemainingSeconds);
   const session = await readIdpSession(identityName);
   if (!session)
     throw new IdpSessionMissingError(identityName);
-  if (accessTokenForAudience(session, opts.audience))
+  if (accessTokenForAudience(session, opts.audience, minimumRemainingMs))
     return session;
   if (!session.refresh_token)
     throw new IdpSessionNoRefreshTokenError(identityName);
@@ -25058,7 +25080,7 @@ async function ensureFreshSession(identityName, opts = {}) {
     const current = await readIdpSession(identityName);
     if (!current)
       throw new IdpSessionMissingError(identityName);
-    if (accessTokenForAudience(current, opts.audience))
+    if (accessTokenForAudience(current, opts.audience, minimumRemainingMs))
       return current;
     const bookmarkOrg = opts.organizationId ?? (opts.audience ? await orgIdForAudience(opts.audience) : undefined);
     const organizationId = bookmarkOrg ?? (opts.audience ? await (opts.resolveOrganizationId ?? fetchOrgHint)(opts.audience) : undefined);
@@ -25077,23 +25099,30 @@ async function ensureFreshSession(identityName, opts = {}) {
           });
         }
       }
-      const rescued = await rescueAfterInvalidGrant(identityName, current, opts.audience, e);
+      const rescued = await rescueAfterInvalidGrant(identityName, current, opts.audience, minimumRemainingMs, e);
       if (rescued)
         return rescued;
       throw e;
     }
   });
 }
-async function rescueAfterInvalidGrant(identityName, seen, audience, error51) {
+async function rescueAfterInvalidGrant(identityName, seen, audience, minimumRemainingMs, error51) {
   if (!(error51 instanceof OAuthTokenError) || error51.code !== "invalid_grant")
     return;
   const latest = await readIdpSession(identityName).catch(() => null);
   if (!latest || latest.updatedAt === seen.updatedAt)
     return;
-  if (!accessTokenForAudience(latest, audience))
+  if (!accessTokenForAudience(latest, audience, minimumRemainingMs))
     return;
   return latest;
 }
+function minimumLifetimeMs(input) {
+  const seconds = input ?? 60;
+  if (!Number.isSafeInteger(seconds) || seconds < 1 || seconds > Math.floor(Number.MAX_SAFE_INTEGER / 1000)) {
+    throw new TypeError("IdP session minimum lifetime must be a positive safe integer.");
+  }
+  return seconds * 1000;
+}
 
 // src/connection/auth.ts
 async function resolveCredential(opts, config2, audience = config2.issuer, registrationKey) {
@@ -25108,14 +25137,14 @@ async function resolveCredential(opts, config2, audience = config2.issuer, regis
       resolvedIdentity = identity3;
       resolvedName = identityName;
       if ((identity3.source ?? "key") === "idp")
-        return await resolveIdpAccessToken(identityName, identity3, audience);
+        return await resolveIdpAccessToken(identityName, identity3, audience, opts.minimumRemainingSeconds);
       return await signAs(identity3.subject, KEYS_DIR, resolveKeyIdentityAuthOptions(identity3, config2, audience, registrationKey));
     }
     const identity2 = await getDefault();
     resolvedIdentity = identity2;
     resolvedName = identity2.name;
     if ((identity2.source ?? "key") === "idp") {
-      return await resolveIdpAccessToken(identity2.name, identity2, audience);
+      return await resolveIdpAccessToken(identity2.name, identity2, audience, opts.minimumRemainingSeconds);
     }
     return await signAs(identity2.subject, KEYS_DIR, resolveKeyIdentityAuthOptions(identity2, config2, audience, registrationKey));
   } catch (e) {
@@ -25157,10 +25186,10 @@ function resolveKeyIdentityAuthOptions(identity2, config2, audience = config2.is
 function systemIdentityIssuer(identity2, audience, config2) {
   return identity2.subject === "system" ? audience : config2.issuer;
 }
-async function resolveIdpAccessToken(identityName, identity2, audience) {
+async function resolveIdpAccessToken(identityName, identity2, audience, minimumRemainingSeconds) {
   let resolved;
   try {
-    resolved = await ensureFreshSession(identityName, { audience });
+    resolved = await ensureFreshSession(identityName, { audience, minimumRemainingSeconds });
   } catch (e) {
     if (e instanceof IdpSessionMissingError) {
       throw new Error(`No cached IdP session for "${identityName}". Run: astrale auth login --idp ${identity2.idp ?? "<idp>"}`);

package/dist/public/keys/index.js

@@ -15613,6 +15613,20 @@ function date4(params) {
 
 // node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 config(en_default());
+// src/lib/credential-lifetime.ts
+function remainingCredentialLifetimeSeconds(expiresAtEpochSeconds, nowEpochSeconds = Math.ceil(Date.now() / 1000)) {
+  if (!Number.isSafeInteger(expiresAtEpochSeconds) || !Number.isSafeInteger(nowEpochSeconds)) {
+    throw new TypeError("Credential expiration and current time must be safe epoch seconds.");
+  }
+  return expiresAtEpochSeconds - nowEpochSeconds - 1;
+}
+function credentialLifetimeCovers(expiresAtEpochSeconds, minimumRemainingSeconds, nowEpochSeconds) {
+  if (!Number.isSafeInteger(minimumRemainingSeconds) || minimumRemainingSeconds < 1) {
+    throw new TypeError("Credential minimum lifetime must be a positive safe integer.");
+  }
+  return remainingCredentialLifetimeSeconds(expiresAtEpochSeconds, nowEpochSeconds) >= minimumRemainingSeconds;
+}
+
 // src/state/paths.ts
 import { homedir } from "node:os";
 import { join } from "node:path";

package/dist/public/paths/index.js

@@ -14446,6 +14446,20 @@ function date4(params) {
 
 // node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 config(en_default());
+// src/lib/credential-lifetime.ts
+function remainingCredentialLifetimeSeconds(expiresAtEpochSeconds, nowEpochSeconds = Math.ceil(Date.now() / 1000)) {
+  if (!Number.isSafeInteger(expiresAtEpochSeconds) || !Number.isSafeInteger(nowEpochSeconds)) {
+    throw new TypeError("Credential expiration and current time must be safe epoch seconds.");
+  }
+  return expiresAtEpochSeconds - nowEpochSeconds - 1;
+}
+function credentialLifetimeCovers(expiresAtEpochSeconds, minimumRemainingSeconds, nowEpochSeconds) {
+  if (!Number.isSafeInteger(minimumRemainingSeconds) || minimumRemainingSeconds < 1) {
+    throw new TypeError("Credential minimum lifetime must be a positive safe integer.");
+  }
+  return remainingCredentialLifetimeSeconds(expiresAtEpochSeconds, nowEpochSeconds) >= minimumRemainingSeconds;
+}
+
 // src/state/paths.ts
 import { homedir } from "node:os";
 import { join } from "node:path";

package/dist/types/connection/auth.d.ts

@@ -26,6 +26,7 @@ export declare function resolveCredential(opts: {
     as?: string;
     creds?: string;
     defaultIdentity?: string;
+    minimumRemainingSeconds?: number;
 }, config: AstraleConfig, audience?: string, registrationKey?: string): Promise<string>;
 export declare function resolveKeyIdentityAuthOptions(identity: Identity, config: AstraleConfig, audience?: string, registrationKey?: string): KeyIdentityAuthOptions;
 export declare function classifyNoRefreshTokenError(requestedAudience: string, sourceAudience: string | undefined, error: IdpSessionNoRefreshTokenError): IdpSessionNoRefreshTokenError | IdpAudienceMismatchError;

package/dist/types/connection/credential.d.ts

@@ -7,7 +7,7 @@ export interface SourceCredentialResolver {
     resolve(audience: IssuerId, signal: AbortSignal): Promise<string>;
 }
 /** Resolve source authority; an omitted Session delegation preserves exact current authority. */
-export declare function createConnectionCredential(expectedSourceIssuer: IssuerId, source: SourceCredentialResolver): SessionAuth;
+export declare function createConnectionCredential(expectedSourceIssuer: IssuerId, source: SourceCredentialResolver, ttlSeconds?: number): SessionAuth;
 /** Bind CLI identity state and Core Auth delegation to one Session auth capability. */
 export declare function createCliCredential(target: ConnectionTarget, options: ConnectionOptions, config: AstraleConfig, fetch?: Fetch, timeoutMs?: number): SessionAuth | undefined;
 /** Reject contradictory explicit credential selections before identity or network access. */

package/dist/types/connection/lifetime.d.ts

@@ -0,0 +1,6 @@
+/** Cover the complete command deadline while preserving the existing short-command floor. */
+export declare function invocationCredentialTtlSeconds(timeoutMs: number): number;
+/** Leave the final carrier lifetime intact after source delegation and issuer exchange settle. */
+export declare function exchangeCredentialTtlSeconds(timeoutMs: number): number;
+/** Refresh a cached token before the final Session carrier can cross a second boundary. */
+export declare function cachedCredentialTtlSeconds(timeoutMs: number): number;

package/dist/types/lib/credential-lifetime.d.ts

@@ -0,0 +1,3 @@
+/** Whole seconds safely available after second-boundary rounding and carrier handoff. */
+export declare function remainingCredentialLifetimeSeconds(expiresAtEpochSeconds: number, nowEpochSeconds?: number): number;
+export declare function credentialLifetimeCovers(expiresAtEpochSeconds: number, minimumRemainingSeconds: number, nowEpochSeconds?: number): boolean;

package/dist/types/lib/idp-session.d.ts

@@ -12,6 +12,8 @@ export declare class IdpSessionNoRefreshTokenError extends Error {
 export type EnsureFreshSessionOptions = {
     audience?: string;
     organizationId?: string;
+    /** Minimum source-token lifetime required before the caller starts its operation. */
+    minimumRemainingSeconds?: number;
     /**
      * Org-hint resolver, consulted only when a refresh actually happens.
      * Defaults to `fetchOrgHint`; injectable for tests.

package/dist/types/lib/idp.d.ts

@@ -196,7 +196,7 @@ export declare function isSessionExpired(session: Pick<IdpSession, 'expires_at'>
  * top-level token's own `aud` claim. Without an `audience`, freshness of the
  * top-level token is the only requirement.
  */
-export declare function accessTokenForAudience(session: IdpSession, audience?: string): string | undefined;
+export declare function accessTokenForAudience(session: IdpSession, audience?: string, minimumRemainingMs?: number): string | undefined;
 /**
  * Fold a freshly minted access token into the per-audience map under every
  * `aud` it carries, dropping entries that have already expired.

package/dist/types/state/exchange-credentials.d.ts

@@ -21,7 +21,7 @@ export declare class ExchangeCredentialCache {
     private readonly path;
     private readonly refreshing;
     constructor(path?: string);
-    getOrRefresh(key: exchange.Key, refresh: () => Promise<exchange.Entry>, now?: () => number): Promise<string>;
+    getOrRefresh(key: exchange.Key, minimumRemainingSeconds: number, refresh: () => Promise<exchange.Entry>, now?: () => number): Promise<string>;
     deleteKernel(kernelIssuer: string): Promise<void>;
     clear(): Promise<void>;
     private getOrRefreshOnce;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/cli",
-  "version": "1.0.0-beta.31",
+  "version": "1.0.0-beta.32",
   "description": "Astrale CLI — connect to existing Astrale kernels",
   "keywords": [
     "astrale",