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

package/src/lib/__tests__/skills.test.ts

@@ -145,6 +145,12 @@ async function installFixture(
 ) {
   const calls: string[][] = []
   await installer(sourceRoot, snapshot, home, lockPath, calls)('npx', [])
+  const lock = await readLock(lockPath)
+  for (const skill of snapshot.skills) {
+    lock.skills[skill.name].astraleSourceRevision = snapshot.revision
+    lock.skills[skill.name].astraleSourceTree = skill.tree
+  }
+  await writeFile(lockPath, `${JSON.stringify(lock, null, 2)}\n`)
 }
 
 describe('Astrale skill reconciliation', () => {
@@ -164,9 +170,17 @@ describe('Astrale skill reconciliation', () => {
     expect(calls).toHaveLength(1)
     expect(calls[0]).toContain(`astrale-os/cli#${source.snapshot.ref}`)
     expect(requestedSkills(calls[0])).toEqual(source.snapshot.skills.map((skill) => skill.name))
-    expect(Object.keys((await readLock(target.lockPath)).skills).sort()).toEqual(
+    const installedLock = await readLock(target.lockPath)
+    expect(Object.keys(installedLock.skills).sort()).toEqual(
       source.snapshot.skills.map((skill) => skill.name).sort(),
     )
+    for (const skill of source.snapshot.skills) {
+      expect(installedLock.skills[skill.name]).toMatchObject({
+        ref: 'main',
+        astraleSourceRevision: source.snapshot.revision,
+        astraleSourceTree: skill.tree,
+      })
+    }
   })
 
   test('a coherent older cohort updates every current source skill', async () => {
@@ -398,7 +412,18 @@ describe('Astrale skill reconciliation', () => {
         lockPath: target.lockPath,
         resolveSource: async () => source.snapshot,
       }),
-    ).toEqual({ status: 'current' })
+    ).toEqual({
+      status: 'current',
+      source: {
+        repository: 'astrale-os/cli',
+        revision: source.snapshot.revision,
+        skills: source.snapshot.skills.map(({ name, tree, path }) => ({
+          name,
+          tree,
+          entrypoint: path,
+        })),
+      },
+    })
     expect(await filesystemSnapshot(target.root)).toBe(beforeCurrentCheck)
 
     await rm(join(target.home, '.agents/skills/astrale-cli'), { recursive: true, force: true })

package/src/lib/credential-lifetime.ts

@@ -0,0 +1,24 @@
+/** Whole seconds safely available after second-boundary rounding and carrier handoff. */
+export function remainingCredentialLifetimeSeconds(
+  expiresAtEpochSeconds: number,
+  nowEpochSeconds = Math.ceil(Date.now() / 1_000),
+): number {
+  if (!Number.isSafeInteger(expiresAtEpochSeconds) || !Number.isSafeInteger(nowEpochSeconds)) {
+    throw new TypeError('Credential expiration and current time must be safe epoch seconds.')
+  }
+  return expiresAtEpochSeconds - nowEpochSeconds - 1
+}
+
+export function credentialLifetimeCovers(
+  expiresAtEpochSeconds: number,
+  minimumRemainingSeconds: number,
+  nowEpochSeconds?: number,
+): boolean {
+  if (!Number.isSafeInteger(minimumRemainingSeconds) || minimumRemainingSeconds < 1) {
+    throw new TypeError('Credential minimum lifetime must be a positive safe integer.')
+  }
+  return (
+    remainingCredentialLifetimeSeconds(expiresAtEpochSeconds, nowEpochSeconds) >=
+    minimumRemainingSeconds
+  )
+}

package/src/lib/idp-session.ts

@@ -36,6 +36,8 @@ export 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.
@@ -63,9 +65,10 @@ export async function ensureFreshSession(
   identityName: string,
   opts: EnsureFreshSessionOptions = {},
 ): Promise<IdpSession> {
+  const minimumRemainingMs = minimumLifetimeMs(opts.minimumRemainingSeconds)
   const session = await readIdpSession(identityName)
   if (!session) throw new IdpSessionMissingError(identityName)
-  if (accessTokenForAudience(session, opts.audience)) return session
+  if (accessTokenForAudience(session, opts.audience, minimumRemainingMs)) return session
   if (!session.refresh_token) throw new IdpSessionNoRefreshTokenError(identityName)
 
   return withFileLock(idpSessionLockPath(identityName), async () => {
@@ -73,7 +76,7 @@ export async function ensureFreshSession(
     // already rotated the session — using its result is the whole point.
     const current = await readIdpSession(identityName)
     if (!current) throw new IdpSessionMissingError(identityName)
-    if (accessTokenForAudience(current, opts.audience)) return current
+    if (accessTokenForAudience(current, opts.audience, minimumRemainingMs)) return current
 
     // Org resolution order: explicit > bookmarked-at-create > router lookup.
     const bookmarkOrg =
@@ -106,7 +109,13 @@ export async function ensureFreshSession(
           })
         }
       }
-      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
     }
@@ -124,11 +133,24 @@ async function rescueAfterInvalidGrant(
   identityName: string,
   seen: IdpSession,
   audience: string | undefined,
+  minimumRemainingMs: number,
   error: unknown,
 ): Promise<IdpSession | undefined> {
   if (!(error instanceof OAuthTokenError) || error.code !== 'invalid_grant') return undefined
   const latest = await readIdpSession(identityName).catch(() => null)
   if (!latest || latest.updatedAt === seen.updatedAt) return undefined
-  if (!accessTokenForAudience(latest, audience)) return undefined
+  if (!accessTokenForAudience(latest, audience, minimumRemainingMs)) return undefined
   return latest
 }
+
+function minimumLifetimeMs(input: number | undefined): number {
+  const seconds = input ?? 60
+  if (
+    !Number.isSafeInteger(seconds) ||
+    seconds < 1 ||
+    seconds > Math.floor(Number.MAX_SAFE_INTEGER / 1_000)
+  ) {
+    throw new TypeError('IdP session minimum lifetime must be a positive safe integer.')
+  }
+  return seconds * 1_000
+}

package/src/lib/idp.ts

@@ -4,6 +4,7 @@ import { dirname, join } from 'node:path'
 import { z } from 'zod'
 
 import { atomicWrite, IDPS_PATH, IDP_SESSIONS_DIR, paths } from '../state/index'
+import { credentialLifetimeCovers } from './credential-lifetime'
 import { log } from './log'
 import { validateName, validateUrl } from './validation'
 
@@ -620,18 +621,37 @@ export function isSessionExpired(
  * top-level token's own `aud` claim. Without an `audience`, freshness of the
  * top-level token is the only requirement.
  */
-export function accessTokenForAudience(session: IdpSession, audience?: string): string | undefined {
+export function accessTokenForAudience(
+  session: IdpSession,
+  audience?: string,
+  minimumRemainingMs = 60_000,
+): string | undefined {
   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)) return entry.access_token
-  if (!isSessionExpired(session) && tokenAudienceMatches(session.access_token, audience)) {
+  if (entry && tokenHasMinimumLifetime(entry, minimumRemainingMs)) return entry.access_token
+  if (
+    tokenHasMinimumLifetime(session, minimumRemainingMs) &&
+    tokenAudienceMatches(session.access_token, audience)
+  ) {
     return session.access_token
   }
   return undefined
 }
 
+/** Prefer the JWT expiration used by delegation; opaque IdP tokens retain their timestamp path. */
+function tokenHasMinimumLifetime(
+  value: Pick<IdpSession, 'expires_at'> & { access_token: string },
+  minimumRemainingMs: number,
+): boolean {
+  const expiration = decodeTokenClaims(value.access_token)?.exp
+  if (typeof expiration === 'number' && Number.isSafeInteger(expiration)) {
+    return credentialLifetimeCovers(expiration, Math.ceil(minimumRemainingMs / 1_000))
+  }
+  return !isSessionExpired(value, minimumRemainingMs)
+}
+
 /**
  * Fold a freshly minted access token into the per-audience map under every
  * `aud` it carries, dropping entries that have already expired.

package/src/lib/skills/sync.ts

@@ -52,6 +52,11 @@ export type SkillApplyStatus =
 export type SkillCheckResult = {
   status: SkillCheckStatus
   error?: string
+  source?: {
+    repository: typeof ASTRALE_CLI_SKILL_SOURCE
+    revision: string
+    skills: Array<{ name: string; tree: string; entrypoint: string }>
+  }
 }
 
 export type SkillApplyResult = {
@@ -70,6 +75,8 @@ type SkillLockEntry = {
   skillFolderHash?: string
   installedAt?: string
   updatedAt?: string
+  astraleSourceRevision?: string
+  astraleSourceTree?: string
 }
 
 type SkillLock = {
@@ -83,6 +90,7 @@ type SkillState = 'absent' | 'current' | 'outdated' | 'unhealthy'
 
 type SkillInspection = {
   state: SkillState
+  sourceCurrent: boolean
   managedNames: string[]
   managedFolders: string[]
 }
@@ -297,7 +305,7 @@ async function inspectAstraleSkills(
     }),
   )
   if (managed.length === 0 && expectedPresence.every((present) => !present)) {
-    return { state: 'absent', managedNames: [], managedFolders: [] }
+    return { state: 'absent', sourceCurrent: false, managedNames: [], managedFolders: [] }
   }
 
   const folders = managed.flatMap(([name, entry]) => {
@@ -348,7 +356,7 @@ async function inspectAstraleSkills(
     }
   }
 
-  const exactCurrent =
+  const sourceCurrent =
     coherent &&
     managed.length === snapshot.skills.length &&
     folders.every(({ key, folder, entry }) => {
@@ -360,9 +368,20 @@ async function inspectAstraleSkills(
         actualHashes.get(folder) === skill.tree
       )
     })
+  const exactCurrent =
+    sourceCurrent &&
+    folders.every(({ folder, entry }) => {
+      const skill = expected.get(folder)
+      return (
+        skill !== undefined &&
+        entry.astraleSourceRevision === snapshot.revision &&
+        entry.astraleSourceTree === skill.tree
+      )
+    })
 
   return {
     state: exactCurrent ? 'current' : coherent ? 'outdated' : 'unhealthy',
+    sourceCurrent,
     managedNames: managed.map(([name]) => name),
     managedFolders: [...uniqueFolders],
   }
@@ -405,6 +424,28 @@ async function installSnapshot(
   )
 }
 
+async function stampAstraleSource(
+  snapshot: AstraleSkillSourceSnapshot,
+  lockPath: string,
+): Promise<void> {
+  const { lock } = await readSkillLock(lockPath)
+  if (!lock) throw new Error('skill installer receipt is unavailable after installation')
+  for (const skill of snapshot.skills) {
+    const entry = lock.skills[skill.name]
+    if (
+      !entry ||
+      !sourceOwned(entry) ||
+      entry.ref !== snapshot.ref ||
+      entry.skillPath !== skill.path
+    ) {
+      throw new Error(`skill installer receipt is incomplete for ${skill.name}`)
+    }
+    entry.astraleSourceRevision = snapshot.revision
+    entry.astraleSourceTree = skill.tree
+  }
+  await writeSkillLock(lockPath, lock)
+}
+
 async function selectedAgents(home: string, lockPath: string): Promise<string[]> {
   const { lock } = await readSkillLock(lockPath)
   const agents = new Set(
@@ -693,13 +734,27 @@ export async function checkAstraleSkills(
       dependencies.home,
       dependencies.lockPath,
     )
+    const status =
+      inspection.state === 'current'
+        ? 'current'
+        : inspection.state === 'unhealthy'
+          ? 'repair-needed'
+          : 'update-available'
     return {
-      status:
-        inspection.state === 'current'
-          ? 'current'
-          : inspection.state === 'unhealthy'
-            ? 'repair-needed'
-            : 'update-available',
+      status,
+      ...(status === 'current'
+        ? {
+            source: {
+              repository: ASTRALE_CLI_SKILL_SOURCE,
+              revision: snapshot.revision,
+              skills: snapshot.skills.map(({ name, tree, path }) => ({
+                name,
+                tree,
+                entrypoint: path,
+              })),
+            },
+          }
+        : {}),
     }
   } catch (error) {
     return { status: 'unavailable', error: error instanceof Error ? error.message : String(error) }
@@ -768,6 +823,15 @@ export async function syncAstraleSkills(
               dependencies.run,
               knownRetired,
             )
+            const installedInspection = await inspectAstraleSkills(
+              snapshot,
+              dependencies.home,
+              dependencies.lockPath,
+            )
+            if (!installedInspection.sourceCurrent) {
+              throw new Error('installed Astrale skills do not match the resolved source')
+            }
+            await stampAstraleSource(snapshot, dependencies.lockPath)
             const verified = await inspectAstraleSkills(
               snapshot,
               dependencies.home,

package/src/program/__tests__/program.test.ts

@@ -195,7 +195,7 @@ describe('program composition', () => {
       'whoami',
     ])
     expect(createHash('sha256').update(JSON.stringify(surface)).digest('hex')).toBe(
-      '092b8f4f737740105c8baed9d01a81604711b5b2719dfcb834eeeac414732c61',
+      '91c35b18985ad8606b5f2429fd8860b020a93edccb30dfbaa74d501929a8513b',
     )
   })
 
@@ -464,13 +464,50 @@ describe('help contract — read command split', () => {
     expect(queryHelp).not.toContain('--children <json>')
     expect(queryHelp).not.toContain('--edges <json>')
     expect(queryHelp).toContain('--ast <json>')
-    expect(queryHelp).toContain('--definition <path>')
+    expect(queryHelp).toContain('--class <path>')
+    expect(queryHelp).not.toContain('--definition')
     expect(queryHelp).toContain('--edge <class>')
     expect(queryHelp).toContain('--direction <direction>')
     expect(queryHelp).toContain('--limit <n>')
     expect(queryHelp).toContain('--cursor <token>')
     expect(queryHelp).not.toContain('--cypher <query>')
   })
+
+  test('keeps the removed query --definition flag outside the parsed command surface', async () => {
+    const program = await buildProgram()
+    const query = allCommands(program).find((command) => command.name() === 'query')
+    const parsed = query?.parseOptions(['--definition', '/:notes.example.dev:class.Note'])
+
+    expect(parsed?.unknown).toContain('--definition')
+    expect(query?.options.some((option) => option.attributeName() === 'definition')).toBe(false)
+  })
+
+  test('routes query --class through Commander as the exact Class option', async () => {
+    const program = await buildProgram()
+    const query = allCommands(program).find((command) => command.name() === 'query')
+    let observed: unknown
+    query?.action((sources, options) => {
+      observed = { sources, class: options.class, limit: options.limit, json: options.json }
+    })
+
+    await program.parseAsync([
+      'node',
+      'astrale',
+      'query',
+      '--class',
+      '/:notes.example.dev:class.Note',
+      '--limit',
+      '1',
+      '--json',
+    ])
+
+    expect(observed).toEqual({
+      sources: [],
+      class: '/:notes.example.dev:class.Note',
+      limit: '1',
+      json: true,
+    })
+  })
 })
 
 describe('help contract — explicit anonymous authentication', () => {

package/src/state/__tests__/exchange-credentials.test.ts

@@ -40,6 +40,7 @@ describe('exchange credential cache', () => {
     const resolve = (candidate: typeof first) =>
       cache.getOrRefresh(
         candidate,
+        30,
         async () => {
           refreshes += 1
           return entry(candidate, 200)
@@ -69,9 +70,9 @@ describe('exchange credential cache', () => {
     }
 
     const values = await Promise.all([
-      left.getOrRefresh(candidate, refresh, () => 100),
-      left.getOrRefresh(candidate, refresh, () => 100),
-      right.getOrRefresh(candidate, refresh, () => 100),
+      left.getOrRefresh(candidate, 30, refresh, () => 100),
+      left.getOrRefresh(candidate, 30, refresh, () => 100),
+      right.getOrRefresh(candidate, 30, refresh, () => 100),
     ])
     expect(new Set(values).size).toBe(1)
     expect(refreshes).toBe(1)
@@ -83,12 +84,14 @@ describe('exchange credential cache', () => {
     const candidate = key('https://kernel.example', 'https://domain.example', 'user')
     await cache.getOrRefresh(
       candidate,
+      30,
       async () => entry(candidate, 120),
       () => 50,
     )
     let refreshes = 0
     await cache.getOrRefresh(
       candidate,
+      30,
       async () => {
         refreshes += 1
         return entry(candidate, 220)
@@ -100,6 +103,7 @@ describe('exchange credential cache', () => {
     await expect(
       cache.getOrRefresh(
         key('https://other-kernel.example', candidate.domainIssuer, candidate.sourceSubject),
+        30,
         async () => entry(candidate, 220),
         () => 100,
       ),
@@ -108,6 +112,7 @@ describe('exchange credential cache', () => {
     await expect(
       cache.getOrRefresh(
         key(candidate.kernelIssuer, candidate.domainIssuer, 'other-source'),
+        30,
         async () => entry(candidate, 220),
         () => 100,
       ),
@@ -122,6 +127,7 @@ describe('exchange credential cache', () => {
       await expect(
         cache.getOrRefresh(
           malformedCandidate,
+          30,
           async () => entry(malformedCandidate, 220, malformed),
           () => 100,
         ),
@@ -137,6 +143,7 @@ describe('exchange credential cache', () => {
     for (const candidate of [a, b]) {
       await cache.getOrRefresh(
         candidate,
+        30,
         async () => entry(candidate, 200),
         () => 100,
       )
@@ -162,6 +169,7 @@ describe('exchange credential cache', () => {
     let refreshes = 0
     await cache.getOrRefresh(
       candidate,
+      30,
       async () => {
         refreshes += 1
         return entry(candidate, 200)
@@ -173,6 +181,103 @@ describe('exchange credential cache', () => {
     expect(stored.version).toBe(2)
     expect(JSON.stringify(stored)).not.toContain('legacy')
   })
+
+  test('refreshes a valid cached credential that cannot cover the requested invocation', async () => {
+    const cache = new ExchangeCredentialCache(path)
+    const candidate = key('https://kernel.example', 'https://domain.example', 'user')
+    await cache.getOrRefresh(
+      candidate,
+      30,
+      async () => entry(candidate, 250),
+      () => 100,
+    )
+    let refreshes = 0
+
+    await expect(
+      cache.getOrRefresh(
+        candidate,
+        185,
+        async () => {
+          refreshes += 1
+          return entry(candidate, 300)
+        },
+        () => 100,
+      ),
+    ).resolves.toBe(token(candidate, 300))
+    expect(refreshes).toBe(1)
+
+    await expect(
+      cache.getOrRefresh(
+        candidate,
+        201,
+        async () => entry(candidate, 190),
+        () => 100,
+      ),
+    ).rejects.toThrow(/required lifetime/i)
+  })
+
+  test('rejects a long outer token whose carried proof cannot cover the requested invocation', async () => {
+    const cache = new ExchangeCredentialCache(path)
+    const candidate = key('https://kernel.example', 'https://domain.example', 'user')
+
+    await expect(
+      cache.getOrRefresh(
+        candidate,
+        185,
+        async () => entry(candidate, 300, undefined, 150),
+        () => 100,
+      ),
+    ).rejects.toThrow(/required lifetime/i)
+  })
+
+  test('serializes concurrent short and long callers without serving a short carrier to the long caller', async () => {
+    for (const firstKind of ['short', 'long'] as const) {
+      const concurrentPath = join(directory, firstKind, 'credentials.json')
+      const firstCache = new ExchangeCredentialCache(concurrentPath)
+      const secondCache = new ExchangeCredentialCache(concurrentPath)
+      const candidate = key('https://kernel.example', 'https://domain.example', firstKind)
+      let releaseFirst!: () => void
+      let markFirstStarted!: () => void
+      const firstStarted = new Promise<void>((resolve) => {
+        markFirstStarted = resolve
+      })
+      const release = new Promise<void>((resolve) => {
+        releaseFirst = resolve
+      })
+      let refreshes = 0
+      const firstMinimum = firstKind === 'short' ? 30 : 185
+      const firstExpiration = firstKind === 'short' ? 200 : 300
+      const first = firstCache.getOrRefresh(
+        candidate,
+        firstMinimum,
+        async () => {
+          refreshes += 1
+          markFirstStarted()
+          await release
+          return entry(candidate, firstExpiration)
+        },
+        () => 100,
+      )
+      await firstStarted
+      const secondMinimum = firstKind === 'short' ? 185 : 30
+      const secondExpiration = firstKind === 'short' ? 300 : 200
+      const second = secondCache.getOrRefresh(
+        candidate,
+        secondMinimum,
+        async () => {
+          refreshes += 1
+          return entry(candidate, secondExpiration)
+        },
+        () => 100,
+      )
+      releaseFirst()
+
+      const [firstValue, secondValue] = await Promise.all([first, second])
+      const longValue = firstKind === 'long' ? firstValue : secondValue
+      expect(longValue).toBe(token(candidate, 300))
+      expect(refreshes).toBe(firstKind === 'short' ? 2 : 1)
+    }
+  })
 })
 
 function key(
@@ -193,9 +298,10 @@ function entry(
   candidate: ReturnType<typeof key>,
   expiresAt: number,
   malformed?: 'outer-delegation' | 'proof-without-delegation',
+  proofExpiresAt = expiresAt,
 ) {
   return {
-    credential: token(candidate, expiresAt, malformed),
+    credential: token(candidate, expiresAt, malformed, proofExpiresAt),
     expiresAt,
     user: candidate.sourceSubject,
     sourceIssuer: candidate.sourceIssuer,
@@ -207,13 +313,14 @@ function token(
   candidate: ReturnType<typeof key>,
   exp: number,
   malformed?: 'outer-delegation' | 'proof-without-delegation',
+  proofExp = exp,
 ): string {
   const encode = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
   const proof = `${encode({ alg: 'EdDSA', typ: 'JWT' })}.${encode({
     iss: candidate.kernelIssuer,
     sub: candidate.sourceSubject,
     aud: candidate.kernelIssuer,
-    exp,
+    exp: proofExp,
     ...(malformed === 'proof-without-delegation'
       ? {}
       : {

package/src/state/exchange-credentials.ts

@@ -2,6 +2,7 @@ import { credential, grant } from '@astrale-os/sdk/auth'
 import { chmod, mkdir, readFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
 
+import { credentialLifetimeCovers } from '../lib/credential-lifetime'
 import { atomicWrite, withFileLock } from './files'
 import { EXCHANGE_CREDENTIALS_PATH } from './paths'
 
@@ -37,16 +38,27 @@ export class ExchangeCredentialCache {
 
   getOrRefresh(
     key: exchange.Key,
+    minimumRemainingSeconds: number,
     refresh: () => Promise<exchange.Entry>,
     now = () => Math.floor(Date.now() / 1_000),
   ): Promise<string> {
+    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}\0${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
   }
 
@@ -68,6 +80,7 @@ export class ExchangeCredentialCache {
   private async getOrRefreshOnce(
     key: exchange.Key,
     encoded: string,
+    minimumRemainingSeconds: number,
     refresh: () => Promise<exchange.Entry>,
     now: () => number,
   ): Promise<string> {
@@ -76,14 +89,16 @@ export class ExchangeCredentialCache {
       const store = await readStore(this.path)
       const changed = scrub(store, now())
       const cached = store.entries[encoded]
-      if (cached !== undefined && validEntry(key, cached, now())) {
+      if (cached !== undefined && validEntry(key, cached, now(), minimumRemainingSeconds)) {
         if (changed) await writeStore(this.path, store)
         return cached.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)
@@ -187,7 +202,10 @@ function validEntry(
       !Object.hasOwn(inspected.claims, 'delegation') &&
       proof.iss === key.kernelIssuer &&
       proof.sub === entry.user &&
-      proof.aud === key.kernelIssuer
+      proof.aud === key.kernelIssuer &&
+      typeof proof.claims.exp === 'number' &&
+      Number.isSafeInteger(proof.claims.exp) &&
+      credentialLifetimeCovers(proof.claims.exp, minimumRemaining, now)
     )
   } catch {
     return false