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

package/src/lib/__tests__/idp-session.driver.ts

@@ -13,6 +13,9 @@ import { ensureFreshSession } from '../idp-session'
 
 const scenario = process.argv[2]
 const audience = process.env.DRIVER_AUDIENCE || undefined
+const minimumRemainingSeconds = process.env.DRIVER_MINIMUM_SECONDS
+  ? Number(process.env.DRIVER_MINIMUM_SECONDS)
+  : undefined
 let orgHintCalls = 0
 const resolveOrganizationId = async (): Promise<string | undefined> => {
   orgHintCalls += 1
@@ -25,12 +28,16 @@ function print(result: Record<string, unknown>): void {
 
 try {
   if (scenario === 'ensure') {
-    const session = await ensureFreshSession('alice', { audience, resolveOrganizationId })
+    const session = await ensureFreshSession('alice', {
+      audience,
+      minimumRemainingSeconds,
+      resolveOrganizationId,
+    })
     print({ ok: true, token: accessTokenForAudience(session, audience), orgHintCalls })
   } else if (scenario === 'ensure-concurrent') {
     const [a, b] = await Promise.all([
-      ensureFreshSession('alice', { audience, resolveOrganizationId }),
-      ensureFreshSession('alice', { audience, resolveOrganizationId }),
+      ensureFreshSession('alice', { audience, minimumRemainingSeconds, resolveOrganizationId }),
+      ensureFreshSession('alice', { audience, minimumRemainingSeconds, resolveOrganizationId }),
     ])
     print({
       ok: true,

package/src/lib/__tests__/idp-session.test.ts

@@ -80,6 +80,31 @@ describe('ensureFreshSession', () => {
     }
   })
 
+  test('refreshes at the conservative whole-second lifetime boundary', async () => {
+    const server = rotationServer()
+    try {
+      await writeIdpConfig(server.url)
+      const shortToken = unsignedJwt({ aud: AUD, exp: Math.ceil(Date.now() / 1_000) + 200 })
+      await writeSession({
+        access_token: shortToken,
+        // The loose millisecond timestamp appears sufficient. Delegation uses
+        // the JWT exp and its conservative second-boundary handoff instead.
+        expires_at: new Date(Date.now() + 201_000).toISOString(),
+      })
+
+      const result = await runDriver('ensure', {
+        DRIVER_AUDIENCE: AUD,
+        DRIVER_MINIMUM_SECONDS: '200',
+      })
+
+      expect(result.ok).toBe(true)
+      expect(server.refreshCount()).toBe(1)
+      expect(result.token).not.toBe(shortToken)
+    } finally {
+      await server.stop()
+    }
+  })
+
   test('refreshes with the client that issued the session instead of the IdP default', async () => {
     const server = rotationServer()
     try {

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/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