@astrale-os/sdk 0.1.5 → 0.1.7

package/src/auth/verify.ts

@@ -17,6 +17,8 @@ import type {
 import {
   CredentialMethodResolver,
   MethodRegistry,
+  SignatureVerificationError,
+  SigningKeyNotFoundError,
   verifyAudience,
   verifyCredential,
 } from '@astrale-os/kernel-core'
@@ -40,14 +42,72 @@ export type VerifiedInbound = {
 
 const methodResolver = new CredentialMethodResolver(new MethodRegistry())
 
+// JWKS resolvers cached per JWKS URL (module-level, like the pools/selfIds
+// Maps in kernel-client.ts). jose handles freshness WITHIN a resolver: 10min
+// max-age, 30s fetch cooldown, and auto-refetch on kid-miss when not cooling
+// down. The one gap — issuer restarts with new keys while the cooldown pins
+// the old set (the incident that got a prior indefinite cache removed) — is
+// covered by evict-and-retry-once in `verifyInboundCredential`, so indefinite
+// Map residency is safe and the per-call JWKS fetch is gone.
+const remoteResolvers = new Map<string, ReturnType<typeof createRemoteJWKSet>>()
+
+// Self-issued credentials verify against the worker's own in-memory key;
+// cache the local JWKS per canonical self-issuer (one key per worker) so the
+// public-JWK derivation isn't redone on every request.
+const localResolvers = new Map<string, ReturnType<typeof createLocalJWKSet>>()
+
+/** Clear cached JWKS resolvers. Used in tests when keys rotate between fixtures. */
+export function clearJwksCache(): void {
+  remoteResolvers.clear()
+  localResolvers.clear()
+}
+
+/**
+ * M-28 fix: a bare-slug iss (`mails.localhost`) makes
+ * `new URL('mails.localhost/.well-known/jwks.json')` throw "Invalid URL
+ * string". The dispatcher's identity map normalizes the iss it signs with,
+ * but inbound creds from older clients may still carry the slug form. Coerce
+ * to a URL with a default `https://` scheme (matches kernel.astrale.ai
+ * canonical form). If the actual receiver is on http://localhost the
+ * receiver-side resolver still works because both endpoints are on localhost
+ * — but for prod targets requiring TLS this is the right default.
+ */
+function jwksUrlFor(issuer: string): string {
+  const normalized = /^https?:\/\//.test(issuer) ? issuer : `https://${issuer}`
+  return `${normalized}/.well-known/jwks.json`
+}
+
+function getRemoteResolver(jwksUrl: string): ReturnType<typeof createRemoteJWKSet> {
+  let resolver = remoteResolvers.get(jwksUrl)
+  if (!resolver) {
+    resolver = createRemoteJWKSet(new URL(jwksUrl))
+    remoteResolvers.set(jwksUrl, resolver)
+  }
+  return resolver
+}
+
+function getLocalResolver(
+  selfIssuer: string,
+  privateKey: RemoteIdentityConfig['privateKey'],
+): ReturnType<typeof createLocalJWKSet> {
+  let resolver = localResolvers.get(selfIssuer)
+  if (!resolver) {
+    resolver = createLocalJWKSet({ keys: [derivePublicJwk(privateKey) as JWK] })
+    localResolvers.set(selfIssuer, resolver)
+  }
+  return resolver
+}
+
 /**
  * Build the key resolver for one verifying server. Captures `config` so it can
  * short-circuit the server's OWN issuer (`config.issuer`): a self-issued
  * credential is verified against the in-memory public key, never fetched — a
  * Worker can't fetch its own hostname, and it already holds the key. Every other
- * issuer is resolved live via JWKS (`createRemoteJWKSet`).
+ * issuer is resolved via the cached per-URL JWKS resolvers above; every JWKS
+ * URL touched is recorded in `resolvedJwksUrls` so the caller can evict
+ * exactly those resolvers if verification fails on an unknown signing key.
  */
-function makeResolveKeys(config: RemoteIdentityConfig) {
+function makeResolveKeys(config: RemoteIdentityConfig, resolvedJwksUrls: Set<string>) {
   // The worker's own canonical iss. STRICT: `config.issuer` is the serving URL
   // by contract (both producers — buildIdentityMap / buildAuxIdentityMap — feed
   // it `canonicalizeServingUrl(config.url)`), so a value that doesn't parse is
@@ -57,13 +117,6 @@ function makeResolveKeys(config: RemoteIdentityConfig) {
   // into an opaque per-call failure.
   const selfIssuer = canonicalizeServingUrl(config.issuer)
 
-  // TODO(cache): Re-add JWKS caching with a short TTL or kid-miss retry.
-  // A prior implementation cached `createRemoteJWKSet` per issuer URL
-  // indefinitely. jose's internal cache (30s cooldown, 10min max-age) caused
-  // stale keys when the issuer restarted — the resolver served old keys and
-  // jose refused to refetch within the cooldown window. On CF Workers the
-  // module-level Map persisted across requests, making it worse. For now we
-  // create a fresh resolver per call (jose deduplicates concurrent fetches).
   return async (issuer: IssuerId, _method: string, _kid?: string) => {
     const url = issuer as string
 
@@ -78,21 +131,13 @@ function makeResolveKeys(config: RemoteIdentityConfig) {
         canonical = undefined
       }
       if (canonical === selfIssuer) {
-        return createLocalJWKSet({ keys: [derivePublicJwk(config.privateKey) as JWK] })
+        return getLocalResolver(selfIssuer, config.privateKey)
       }
     }
 
-    // M-28 fix: a bare-slug iss (`mails.localhost`) makes
-    // `new URL('mails.localhost/.well-known/jwks.json')` throw "Invalid
-    // URL string". The dispatcher's identity map normalizes the iss it
-    // signs with, but inbound creds from older clients may still carry
-    // the slug form. Coerce to a URL with a default `https://` scheme
-    // (matches kernel.astrale.ai canonical form). If the actual receiver
-    // is on http://localhost the receiver-side resolver still works
-    // because both endpoints are on localhost — but for prod targets
-    // requiring TLS this is the right default.
-    const normalized = /^https?:\/\//.test(url) ? url : `https://${url}`
-    return createRemoteJWKSet(new URL(`${normalized}/.well-known/jwks.json`))
+    const jwksUrl = jwksUrlFor(url)
+    resolvedJwksUrls.add(jwksUrl)
+    return getRemoteResolver(jwksUrl)
   }
 }
 
@@ -106,13 +151,29 @@ export async function verifyInboundCredential(
   config: RemoteIdentityConfig,
 ): Promise<VerifiedInbound> {
   // Verify using kernel-core's credential verification pipeline
-  const verified = await verifyCredential(
-    {
-      methodResolver,
-      resolveKeys: makeResolveKeys(config),
-    },
-    credential,
-  )
+  const resolvedJwksUrls = new Set<string>()
+  const deps = { methodResolver, resolveKeys: makeResolveKeys(config, resolvedJwksUrls) }
+  let verified: VerifiedCredential
+  try {
+    verified = await verifyCredential(deps, credential)
+  } catch (error) {
+    // A cached resolver can hold a stale key set after the issuer rotates:
+    //  - new kid → jose kid-misses but its 30s fetch cooldown blocks the
+    //    refetch (SigningKeyNotFoundError) — the incident that got a prior
+    //    indefinite cache removed;
+    //  - SAME kid, new key material (kernel kids derive from the subject, so
+    //    a re-keyed issuer reuses its kid) → the signature check fails
+    //    (SignatureVerificationError).
+    // Both: evict the resolver(s) this verification touched and retry ONCE
+    // with fresh ones. Forged-token spam thus costs at most one JWKS fetch
+    // per bad credential — equal to the uncached per-call baseline, never
+    // worse. An empty set means self-issued — refetching can't help, rethrow.
+    const staleKeySuspect =
+      error instanceof SigningKeyNotFoundError || error instanceof SignatureVerificationError
+    if (!staleKeySuspect || resolvedJwksUrls.size === 0) throw error
+    for (const url of resolvedJwksUrls) remoteResolvers.delete(url)
+    verified = await verifyCredential(deps, credential)
+  }
 
   // Validate audience matches this function's issuer (its serving URL).
   // kernel-core's verifyAudience compares canonically.

package/src/cli/bin.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env bun
+/**
+ * `astrale-domain` bin entry. Runs under bun (native TS) so it can import the
+ * project's `astrale.config.ts` directly — matching the `astrale` CLI.
+ */
+
+import { run } from './run'
+
+run(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((err: unknown) => {
+    process.stderr.write(`\x1b[31m✗\x1b[0m ${(err as Error).message ?? String(err)}\n`)
+    if (process.env.DEBUG) process.stderr.write(`${(err as Error).stack ?? ''}\n`)
+    process.exit(1)
+  })

package/src/cli/dotenv.ts

@@ -0,0 +1,45 @@
+/**
+ * Minimal dotenv parser — the secrets-file boundary.
+ *
+ * `secrets: '.env.<env>'` in an adapter's params points a gitignored file whose
+ * entire contents are secrets. `loadDotenvFile` reads it into a flat
+ * `Record<string,string>` the CLI hands the adapter (injected into the local
+ * runtime in dev, pushed to a secret store in prod). No `process.env` mutation,
+ * no interpolation magic beyond `${VAR}` against earlier keys in the same file.
+ */
+
+import { readFileSync } from 'node:fs'
+
+export function parseDotenv(contents: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const raw of contents.split('\n')) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#')) continue
+    const match = /^(?:export\s+)?([A-Za-z_]\w*)\s*=\s*(.*)$/.exec(line)
+    if (!match) continue
+    const [, key, rawValue] = match
+    let value = rawValue.trim()
+    // Single quotes mean a LITERAL value (standard dotenv): no `${VAR}`
+    // interpolation, so a secret that legitimately contains a literal `${...}`
+    // (e.g. a password) survives intact instead of being silently blanked.
+    const singleQuoted = value.length >= 2 && value.startsWith("'") && value.endsWith("'")
+    if ((value.length >= 2 && value.startsWith('"') && value.endsWith('"')) || singleQuoted) {
+      value = value.slice(1, -1)
+    }
+    out[key] = singleQuoted
+      ? value
+      : value.replace(/\$\{(\w+)\}/g, (_, name: string) => out[name] ?? '')
+  }
+  return out
+}
+
+/** Read + parse a dotenv file. Returns `{}` if the file is absent (CI-safe). */
+export function loadDotenvFile(path: string): Record<string, string> {
+  let contents: string
+  try {
+    contents = readFileSync(path, 'utf-8')
+  } catch {
+    return {}
+  }
+  return parseDotenv(contents)
+}

package/src/cli/index.ts

@@ -0,0 +1,15 @@
+/**
+ * `@astrale-os/sdk/cli` — the `astrale-domain` CLI (dev | build | deploy) and
+ * the dotenv secrets-file boundary, folded in from the former
+ * `@astrale-os/devkit` package.
+ *
+ * Node-only: the CLI imports `node:fs`/`node:module`/`node:url` and runs under
+ * Bun (it imports the project's `astrale.config.ts` directly). This subpath is
+ * deliberately NOT re-exported from the package barrel — pulling it into the
+ * isomorphic `.` entry would poison browser/worker bundlers that traverse every
+ * re-export (the same rule that keeps `./server` and `./deploy` off the barrel).
+ * The bin lives at `./bin`.
+ */
+
+export { run, parseArgs } from './run'
+export { parseDotenv, loadDotenvFile } from './dotenv'