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

package/src/connection/.spec/architecture.md

@@ -31,8 +31,11 @@ current Grant for routing. Connection itself persists no credential or route; th
 owner persists exchanged source credentials and the separate Kernel Client route artifact. A valid exchanged credential is selected by the
 authenticated source issuer and subject before any live `whoami`; cache misses alone resolve the
 registered Kernel User and perform delegation plus Domain exchange.
-Exchange authority is bounded to five minutes and never outlives the current source credential,
-matching the CLI route-age ceiling without forcing an unrelated two-minute refresh cycle.
+Exchange and destination-carrier authority cover the selected command timeout plus one bounded
+receipt margin, never outlive the current source credential, and retain the existing one-minute
+floor for short commands. A cached or freshly exchanged credential that cannot cover that lifetime
+is refreshed or rejected before destination dispatch, so a long durable mutation does not first
+discover expired callback authority after its provider effect commits.
 
 Every ClientSession receives the CLI-owned `state/session-routes` representation capability. Kernel
 Client still owns route keying, admission, expiry, and one safe stale/miss recovery; Connection does

package/src/connection/.spec/flows/session.ts

@@ -24,8 +24,9 @@ declare const resolveSourceCredential: (
 ) => Promise<string>
 /** Bind source authority without learning or minting destination credentials. */
 function createConnectionAuth(target: ConnectionTarget, options: ConnectionOptions): SessionAuth {
+  const ttlSeconds = Math.max(60, Math.ceil(resolveTimeoutMs(options.timeout) / 1_000) + 5)
   return {
-    ttlSeconds: 3_600,
+    ttlSeconds,
     async resolve(_call: Call, signal: AbortSignal) {
       return {
         credential: await resolveSourceCredential(target, options, target.issuer, signal),

package/src/connection/.spec/laws/connection.ts

@@ -135,12 +135,20 @@ export const CLI_CONNECTION_TERMINAL_CLOSE = defineLaw({
 export const CLI_CONNECTION_TIMEOUT = defineLaw({
   id: 'CLI-CONNECTION-TIMEOUT',
   statement:
-    'The CLI accepts only a positive integer timeout before constructing a Client Session and applies it to both source-Auth and Session operations.',
+    'The CLI accepts only a positive integer timeout before constructing a Client Session, applies it to source-Auth and Session operations, and requires exchanged and destination-carrier authority to cover that timeout plus the bounded receipt margin before destination dispatch.',
   tests: [
     {
       file: '__tests__/session.test.ts',
       id: 'TEST-CLI-CONNECTION-REJECTS-INVALID-TIMEOUT-BEFORE-OPEN',
     },
+    {
+      file: '__tests__/credential.test.ts',
+      id: 'TEST-CLI-CONNECTION-CARRIER-COVERS-COMMAND-TIMEOUT',
+    },
+    {
+      file: '__tests__/exchange.test.ts',
+      id: 'TEST-CLI-EXCHANGE-REJECTS-INSUFFICIENT-LIFETIME',
+    },
   ],
 })
 

package/src/connection/.spec/layout.ts

@@ -11,6 +11,7 @@ export default defineLayout({
     'failure/',
     'exchange.ts',
     'index.ts',
+    'lifetime.ts',
     'reasons.ts',
     'self.ts',
     'session.ts',

package/src/connection/__tests__/credential.test.ts

@@ -3,9 +3,13 @@ import type { SessionAuth } from '@astrale-os/sdk/client/session'
 import { issuer, type IssuerId } from '@astrale-os/sdk/auth'
 import { Path } from '@astrale-os/sdk/graph/path'
 import { describe, expect, test } from 'bun:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 
 import type { AstraleConfig } from '../../lib/config'
 
+import { persistKeypair, signAs } from '../../keys/index'
 import { bindCredentialIdentity } from '../auth'
 import { createCliCredential, createConnectionCredential } from '../credential'
 
@@ -77,6 +81,117 @@ describe('connection credential', () => {
     expect(resolved.delegate?.ttlSeconds).toBeLessThan(120)
   })
 
+  /** @evidence TEST-CLI-CONNECTION-CARRIER-COVERS-COMMAND-TIMEOUT */
+  test('covers a long command deadline with one destination carrier', async () => {
+    const expiresAt = Math.ceil(Date.now() / 1_000) + 300
+    const auth = createConnectionCredential(SOURCE, { resolve: async () => token(expiresAt) }, 185)
+
+    await expect(auth.resolve(TARGET_CALL, new AbortController().signal)).resolves.toMatchObject({
+      credential: token(expiresAt),
+      delegate: { ttlSeconds: 185 },
+    })
+    expect(auth.ttlSeconds).toBe(185)
+  })
+
+  test('real local-key credentials cover the supported long-operation carrier', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'astrale-carrier-key-'))
+    try {
+      await persistKeypair('alice', { keysDir: directory })
+      const source = await signAs('alice', directory, {
+        issuer: SOURCE,
+        audience: SOURCE,
+      })
+      const auth = createConnectionCredential(SOURCE, { resolve: async () => source }, 185)
+
+      await expect(auth.resolve(TARGET_CALL, new AbortController().signal)).resolves.toMatchObject({
+        credential: source,
+        delegate: { ttlSeconds: 185 },
+      })
+    } finally {
+      await rm(directory, { recursive: true, force: true })
+    }
+  })
+
+  test('real five-minute local-key credentials reject a 600-second carrier before dispatch', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'astrale-carrier-ceiling-key-'))
+    try {
+      await persistKeypair('alice', { keysDir: directory })
+      const source = await signAs('alice', directory, {
+        issuer: SOURCE,
+        audience: SOURCE,
+      })
+      const auth = createConnectionCredential(SOURCE, { resolve: async () => source }, 605)
+
+      await expect(auth.resolve(TARGET_CALL, new AbortController().signal)).rejects.toMatchObject({
+        code: 'CREDENTIAL_LIFETIME_INSUFFICIENT',
+      })
+    } finally {
+      await rm(directory, { recursive: true, force: true })
+    }
+  })
+
+  test('derives every destination carrier lifetime from the selected CLI timeout', () => {
+    for (const target of [
+      { url: `${SOURCE}/invoke`, kernelIssuer: SOURCE },
+      {
+        url: `${SOURCE}/invoke`,
+        kernelIssuer: SOURCE,
+        domainIssuer: issuer.accept('https://admin.example'),
+      },
+    ]) {
+      const auth = createCliCredential(target, {}, config, globalThis.fetch, 180_000)
+      expect(auth?.ttlSeconds).toBe(185)
+    }
+  })
+
+  test('rejects a long command before dispatch when its source bearer is too short', async () => {
+    const expiresAt = Math.ceil(Date.now() / 1_000) + 120
+    const auth = createConnectionCredential(SOURCE, { resolve: async () => token(expiresAt) }, 185)
+
+    await expect(auth.resolve(TARGET_CALL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'CREDENTIAL_LIFETIME_INSUFFICIENT',
+    })
+  })
+
+  test('rejects an inspectable short or expired bearer before a default command dispatch', async () => {
+    for (const expiresAt of [
+      Math.ceil(Date.now() / 1_000) + 30,
+      Math.ceil(Date.now() / 1_000) - 30,
+    ]) {
+      const auth = createConnectionCredential(SOURCE, {
+        resolve: async () => token(expiresAt),
+      })
+      await expect(auth.resolve(TARGET_CALL, new AbortController().signal)).rejects.toMatchObject({
+        code: 'CREDENTIAL_LIFETIME_INSUFFICIENT',
+      })
+    }
+  })
+
+  test('rejects a too-short explicit Domain bearer before exchange or destination I/O', async () => {
+    let fetches = 0
+    const expiresAt = Math.ceil(Date.now() / 1_000) + 120
+    const auth = createCliCredential(
+      {
+        url: `${SOURCE}/invoke`,
+        kernelIssuer: SOURCE,
+        domainIssuer: issuer.accept('https://admin.example'),
+      },
+      { creds: token(expiresAt) },
+      config,
+      async () => {
+        fetches += 1
+        throw new Error('network must remain untouched')
+      },
+      180_000,
+    )
+    if (auth === undefined) throw new Error('expected authenticated credential')
+
+    await expect(auth.resolve(TARGET_CALL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'CREDENTIAL_LIFETIME_INSUFFICIENT',
+    })
+    expect(fetches).toBe(0)
+  })
+
   /** @evidence TEST-CLI-CONNECTION-USES-RAW-SOURCE-CREDENTIAL */
   test('binds explicit CLI credentials to source-Kernel auth only', async () => {
     const auth = createCliCredential(

package/src/connection/__tests__/exchange.test.ts

@@ -101,9 +101,7 @@ describe('Domain token exchange', () => {
       },
     })
     const delegatedTtl = kernelRequests[1]!.body!.call.input.ttlSeconds
-    expect(delegatedTtl).toBeGreaterThan(0)
-    expect(delegatedTtl).toBeGreaterThanOrEqual(295)
-    expect(delegatedTtl).toBeLessThanOrEqual(300)
+    expect(delegatedTtl).toBe(75)
     expect(sourceAudiences).toEqual([KERNEL, KERNEL])
     expect(
       observed.filter((entry) => entry.url.endsWith('/.well-known/astrale/token')),
@@ -173,6 +171,87 @@ describe('Domain token exchange', () => {
     })
   })
 
+  test('requests and retains a carrier that covers a supported long command deadline', async () => {
+    const expiresAt = Math.floor(Date.now() / 1_000) + 250
+    const exchanged = token(DOMAIN, KERNEL, 'user-1', expiresAt)
+    const observed: Record<string, any>[] = []
+    const base = exchangeFetch(exchanged, { expiresAt })
+    const fetch: Fetch = async (input, init) => {
+      if (String(input) === INVOCATION) {
+        observed.push(JSON.parse(await new Response(init?.body).text()))
+      }
+      return base(input, init)
+    }
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => sourceToken('user-1', expiresAt + 50) },
+      fetch,
+      180_000,
+      new ExchangeCredentialCache(join(directory, 'long-credential.json')),
+    )
+
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).resolves.toBe(exchanged)
+    expect(observed[1]!.call.input.ttlSeconds).toBe(200)
+  })
+
+  /** @evidence TEST-CLI-EXCHANGE-REJECTS-INSUFFICIENT-LIFETIME */
+  test('rejects a too-short Domain exchange credential before destination dispatch', async () => {
+    const expiresAt = Math.floor(Date.now() / 1_000) + 150
+    const exchanged = token(DOMAIN, KERNEL, 'user-1', expiresAt)
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => sourceToken('user-1', expiresAt + 150) },
+      exchangeFetch(exchanged, { expiresAt }),
+      180_000,
+      new ExchangeCredentialCache(join(directory, 'short-credential.json')),
+    )
+
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_LIFETIME_INSUFFICIENT',
+    })
+  })
+
+  test('rejects a long outer Domain token whose carried Kernel proof is too short', async () => {
+    const outerExpiresAt = Math.floor(Date.now() / 1_000) + 250
+    const proofExpiresAt = Math.floor(Date.now() / 1_000) + 150
+    const exchanged = token(DOMAIN, KERNEL, 'user-1', outerExpiresAt, proofExpiresAt)
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => sourceToken('user-1', outerExpiresAt + 50) },
+      exchangeFetch(exchanged, { expiresAt: outerExpiresAt }),
+      180_000,
+      new ExchangeCredentialCache(join(directory, 'short-proof.json')),
+    )
+
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_LIFETIME_INSUFFICIENT',
+    })
+  })
+
+  test('rejects the real 300-second Domain ceiling for a 600-second command before destination dispatch', async () => {
+    const expiresAt = Math.floor(Date.now() / 1_000) + 300
+    const exchanged = token(DOMAIN, KERNEL, 'user-1', expiresAt)
+    const observed: string[] = []
+    const base = exchangeFetch(exchanged, { expiresAt })
+    const fetch: Fetch = async (input, init) => {
+      observed.push(String(input))
+      return base(input, init)
+    }
+    const resolver = createExchangeCredentialResolver(
+      TARGET,
+      { resolve: async () => sourceToken('user-1', expiresAt + 700) },
+      fetch,
+      600_000,
+      new ExchangeCredentialCache(join(directory, 'domain-ceiling.json')),
+    )
+
+    await expect(resolver.resolve(KERNEL, new AbortController().signal)).rejects.toMatchObject({
+      code: 'TOKEN_EXCHANGE_LIFETIME_INSUFFICIENT',
+    })
+    expect(observed.filter((url) => url === INVOCATION)).toHaveLength(2)
+    expect(observed.filter((url) => url.endsWith('/.well-known/astrale/token'))).toHaveLength(1)
+  })
+
   test('rejects success responses without no-store or with malformed fields', async () => {
     const exchanged = token(DOMAIN, KERNEL, 'user-1', EXPIRES_AT)
     const cache = () => new ExchangeCredentialCache(join(directory, crypto.randomUUID()))
@@ -237,7 +316,11 @@ describe('Domain token exchange', () => {
 
 function exchangeFetch(
   exchanged: string,
-  options: { readonly body?: unknown; readonly cacheControl?: boolean } = {},
+  options: {
+    readonly body?: unknown
+    readonly cacheControl?: boolean
+    readonly expiresAt?: number
+  } = {},
 ): Fetch {
   return async (input, init) => {
     const url = String(input)
@@ -253,7 +336,9 @@ function exchangeFetch(
     }
     if (url.endsWith('/.well-known/openid-configuration')) return jsonResponse(configuration(true))
     const response = new Response(
-      JSON.stringify(options.body ?? { token: exchanged, expiresAt: EXPIRES_AT }),
+      JSON.stringify(
+        options.body ?? { token: exchanged, expiresAt: options.expiresAt ?? EXPIRES_AT },
+      ),
       {
         status: 200,
         headers: {
@@ -290,13 +375,13 @@ function jsonResponse(value: unknown, status = 200, contentType = 'application/j
   })
 }
 
-function token(iss: string, aud: string, user: string, exp: number): string {
+function token(iss: string, aud: string, user: string, exp: number, proofExp = exp): string {
   const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
   const proof = `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
     iss: aud,
     sub: user,
     aud,
-    exp,
+    exp: proofExp,
     delegation: { v: 1, expr: { kind: 'identity', id: user } },
   })}.signature`
   return `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
@@ -308,12 +393,12 @@ function token(iss: string, aud: string, user: string, exp: number): string {
   })}.signature`
 }
 
-function sourceToken(subject: string | undefined): string {
+function sourceToken(subject: string | undefined, expiresAt = SOURCE_EXPIRES_AT): string {
   const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
   return `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
     iss: 'https://workos.example',
     ...(subject === undefined ? {} : { sub: subject }),
     aud: KERNEL,
-    exp: SOURCE_EXPIRES_AT,
+    exp: expiresAt,
   })}.signature`
 }

package/src/connection/auth.ts

@@ -47,7 +47,12 @@ export async function bindCredentialIdentity<Options extends ConnectionOptions>(
  *      registration for the target instance, use that target-issued `(iss, sub)`.
  */
 export async function resolveCredential(
-  opts: { as?: string; creds?: string; defaultIdentity?: string },
+  opts: {
+    as?: string
+    creds?: string
+    defaultIdentity?: string
+    minimumRemainingSeconds?: number
+  },
   config: AstraleConfig,
   audience: string = config.issuer,
   registrationKey?: string,
@@ -69,7 +74,12 @@ export async function resolveCredential(
       resolvedIdentity = identity
       resolvedName = identityName
       if ((identity.source ?? 'key') === 'idp')
-        return await resolveIdpAccessToken(identityName, identity, audience)
+        return await resolveIdpAccessToken(
+          identityName,
+          identity,
+          audience,
+          opts.minimumRemainingSeconds,
+        )
       return await signAs(
         identity.subject,
         KEYS_DIR,
@@ -81,7 +91,12 @@ export async function resolveCredential(
     resolvedIdentity = identity
     resolvedName = identity.name
     if ((identity.source ?? 'key') === 'idp') {
-      return await resolveIdpAccessToken(identity.name, identity, audience)
+      return await resolveIdpAccessToken(
+        identity.name,
+        identity,
+        audience,
+        opts.minimumRemainingSeconds,
+      )
     }
 
     return await signAs(
@@ -164,10 +179,11 @@ async function resolveIdpAccessToken(
   identityName: string,
   identity: Identity,
   audience: string,
+  minimumRemainingSeconds?: number,
 ): Promise<string> {
   let resolved
   try {
-    resolved = await ensureFreshSession(identityName, { audience })
+    resolved = await ensureFreshSession(identityName, { audience, minimumRemainingSeconds })
   } catch (e) {
     if (e instanceof IdpSessionMissingError) {
       throw new Error(

package/src/connection/credential.ts

@@ -7,8 +7,10 @@ import type { AstraleConfig } from '../lib/config'
 import type { ConnectionOptions, ConnectionTarget } from './target'
 
 import { AstraleError } from '../errors'
+import { remainingCredentialLifetimeSeconds } from '../lib/credential-lifetime'
 import { resolveCredential } from './auth'
 import { createExchangeCredentialResolver } from './exchange'
+import { exchangeCredentialTtlSeconds, invocationCredentialTtlSeconds } from './lifetime'
 import { registrationKeyForTarget } from './target'
 
 const DELEGATION_TTL_SECONDS = 60
@@ -21,32 +23,46 @@ export interface SourceCredentialResolver {
 export function createConnectionCredential(
   expectedSourceIssuer: IssuerId,
   source: SourceCredentialResolver,
+  ttlSeconds = DELEGATION_TTL_SECONDS,
 ): SessionAuth {
+  if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 1) {
+    throw new TypeError('Connection credential ttlSeconds must be a positive safe integer.')
+  }
   const resolveSource = source.resolve.bind(source)
   return Object.freeze({
-    ttlSeconds: DELEGATION_TTL_SECONDS,
+    ttlSeconds,
     async resolve(
       _call: Parameters<SessionAuth['resolve']>[0],
       signal: Parameters<SessionAuth['resolve']>[1],
     ) {
       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 } }),
       })
     },
   })
 }
 
 /** Never request a destination carrier that could outlive its current source bearer. */
-function sourceBoundDelegationTtl(input: string): number | undefined {
+function sourceBoundDelegationTtl(input: string, requestedTtlSeconds: number): number | undefined {
   try {
     const expiresAt = credential.inspect(input).claims.exp
     if (typeof expiresAt !== 'number' || !Number.isSafeInteger(expiresAt)) return undefined
-    const remaining = expiresAt - Math.ceil(Date.now() / 1_000) - 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
     // Preserve opaque explicit credentials; the Kernel remains their authority.
     return undefined
   }
@@ -66,6 +82,10 @@ export function createCliCredential(
     ...(options.as === undefined ? {} : { as: options.as }),
     ...(options.creds === undefined ? {} : { creds: options.creds }),
     ...(target.defaultIdentity === undefined ? {} : { defaultIdentity: target.defaultIdentity }),
+    minimumRemainingSeconds:
+      target.domainIssuer === undefined
+        ? invocationCredentialTtlSeconds(timeoutMs)
+        : exchangeCredentialTtlSeconds(timeoutMs),
   })
   const source: SourceCredentialResolver = {
     async resolve(audience, signal) {
@@ -89,7 +109,8 @@ export function createCliCredential(
           fetch,
           timeoutMs,
         )
-  return createConnectionCredential(target.kernelIssuer, effective)
+  const ttlSeconds = invocationCredentialTtlSeconds(timeoutMs)
+  return createConnectionCredential(target.kernelIssuer, effective, ttlSeconds)
 }
 
 /** Reject contradictory explicit credential selections before identity or network access. */

package/src/connection/exchange.ts

@@ -2,16 +2,17 @@ import type { IssuerId } from '@astrale-os/sdk/auth'
 import type { Fetch } from '@astrale-os/sdk/client'
 
 import { createAuth } from '@astrale-os/sdk/auth'
-import { credential, exchange as exchangeProtocol } from '@astrale-os/sdk/auth'
+import { credential, exchange as exchangeProtocol, grant } from '@astrale-os/sdk/auth'
 import { call, Client } from '@astrale-os/sdk/client'
 
 import type { SourceCredentialResolver } from './credential'
 import type { ConnectionTarget } from './target'
 
 import { AstraleError } from '../errors'
+import { remainingCredentialLifetimeSeconds } from '../lib/credential-lifetime'
 import { ExchangeCredentialCache } from '../state/exchange-credentials'
+import { cachedCredentialTtlSeconds, exchangeCredentialTtlSeconds } from './lifetime'
 
-const EXCHANGE_TTL_SECONDS = 5 * 60
 const MAXIMUM_RESPONSE_BYTES = 256 * 1024
 
 /** Exchange exact authenticated User authority for a Domain bearer bound to this Kernel. */
@@ -23,6 +24,8 @@ export function createExchangeCredentialResolver(
   cache = new ExchangeCredentialCache(),
 ): SourceCredentialResolver {
   requireExchangeTransport(target)
+  const cacheTtlSeconds = cachedCredentialTtlSeconds(timeoutMs)
+  const exchangeTtlSeconds = exchangeCredentialTtlSeconds(timeoutMs)
   return Object.freeze({
     async resolve(kernelIssuer: IssuerId, signal: AbortSignal): Promise<string> {
       requireLive(signal)
@@ -37,8 +40,9 @@ export function createExchangeCredentialResolver(
           sourceIssuer: sourceIdentity.issuer,
           sourceSubject: sourceIdentity.subject,
         }),
+        cacheTtlSeconds,
         async () => {
-          const delegationTtlSeconds = delegationLifetime(sourceToken)
+          const delegationTtlSeconds = delegationLifetime(sourceToken, exchangeTtlSeconds)
           const client = new Client({ url: `${kernelIssuer}/invoke`, fetch, timeoutMs })
           try {
             const authenticated = client.as(sourceToken)
@@ -69,7 +73,14 @@ export function createExchangeCredentialResolver(
             }
             if (envelope === undefined) throw new Error('Token delegation returned no credential.')
             return {
-              ...(await exchange(target.domainIssuer, kernelIssuer, envelope, fetch, signal)),
+              ...(await exchange(
+                target.domainIssuer,
+                kernelIssuer,
+                envelope,
+                cacheTtlSeconds,
+                fetch,
+                signal,
+              )),
               user: user.id,
               sourceIssuer: sourceIdentity.issuer,
               sourceSubject: sourceIdentity.subject,
@@ -107,7 +118,7 @@ function unknownFunctionOutcome(cause: unknown): boolean {
   return (error.reason as { readonly code?: unknown }).code === 'FUNCTION_OUTCOME_UNKNOWN'
 }
 
-function delegationLifetime(sourceToken: string): number {
+function delegationLifetime(sourceToken: string, requiredTtlSeconds: number): number {
   const expiresAt = credential.inspect(sourceToken).claims.exp
   if (typeof expiresAt !== 'number' || !Number.isSafeInteger(expiresAt)) {
     throw new AstraleError(
@@ -115,20 +126,28 @@ function delegationLifetime(sourceToken: string): number {
       'The source identity credential has no valid expiration.',
     )
   }
-  const remaining = expiresAt - Math.ceil(Date.now() / 1_000) - 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: IssuerId,
   kernelIssuer: IssuerId,
   envelope: string,
+  requiredTtlSeconds: number,
   fetch: Fetch,
   signal: AbortSignal,
 ): Promise<{ readonly credential: string; readonly expiresAt: number }> {
@@ -225,9 +244,48 @@ async function exchange(
       '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 })
 }
 
+/** The outer Domain bearer and its carried Kernel proof must both survive the operation. */
+function effectiveExchangeLifetime(
+  inspected: ReturnType<typeof credential.inspect>,
+  outerExpiresAt: number,
+): number {
+  let proofExpiresAt: number
+  try {
+    const carried = 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 value = credential.inspect(carried.credential).claims.exp
+    if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+      throw new TypeError('Domain credential carries an identity proof without an expiration.')
+    }
+    proofExpiresAt = value
+  } 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(
   fetch: Fetch,
   input: string,

package/src/connection/lifetime.ts

@@ -0,0 +1,25 @@
+const MINIMUM_CREDENTIAL_TTL_SECONDS = 60
+const INVOCATION_RECEIPT_MARGIN_SECONDS = 5
+const CACHE_HANDOFF_MARGIN_SECONDS = 5
+const TOKEN_EXCHANGE_SETTLEMENT_MARGIN_SECONDS = 15
+
+/** Cover the complete command deadline while preserving the existing short-command floor. */
+export function invocationCredentialTtlSeconds(timeoutMs: number): number {
+  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 / 1_000) + INVOCATION_RECEIPT_MARGIN_SECONDS,
+  )
+}
+
+/** Leave the final carrier lifetime intact after source delegation and issuer exchange settle. */
+export function exchangeCredentialTtlSeconds(timeoutMs: number): number {
+  return invocationCredentialTtlSeconds(timeoutMs) + TOKEN_EXCHANGE_SETTLEMENT_MARGIN_SECONDS
+}
+
+/** Refresh a cached token before the final Session carrier can cross a second boundary. */
+export function cachedCredentialTtlSeconds(timeoutMs: number): number {
+  return invocationCredentialTtlSeconds(timeoutMs) + CACHE_HANDOFF_MARGIN_SECONDS
+}