@adonis-agora/authkit-client 0.20.1 → 0.20.3

package/build/src/define_config.d.ts

@@ -64,6 +64,9 @@ export interface ClientConfigInput {
      * Discovery runs lazily, on first use, so the app boots while the IdP is down.
      * A failure throws `OidcDiscoveryError` and is retried on the next request; a
      * previously discovered document keeps being served while refetches fail.
+     * Concurrent callers share one fetch per issuer; once `cacheTtlMs` (default
+     * 15 min) runs out, the cached document is served while one background refetch
+     * replaces it. Each request attempt is aborted after 10 s.
      *
      * `false` skips the network and uses `endpoints` on top of the authkit-server
      * convention (`/auth`, `/token`, `/jwks`, `/session/end`).

package/build/src/discovery.d.ts

@@ -51,7 +51,7 @@ export declare class OidcDiscoveryError extends Error {
 export interface DiscoverOptions {
     /** Manual overrides — win over the discovery document, field by field. */
     overrides?: Partial<OidcEndpoints>;
-    /** Per-issuer cache TTL. Default: 15 min. */
+    /** Per-issuer cache TTL; past it the document is served stale while one background refetch runs. Default: 15 min. */
     cacheTtlMs?: number;
     fetchImpl?: typeof fetch;
     /**
@@ -77,6 +77,8 @@ export interface DiscoverOptions {
  * Resolves the IdP endpoints via `/.well-known/openid-configuration`.
  *
  * - Successful documents are cached per issuer (TTL 15 min) — safe to call per request.
+ *   Once the TTL runs out the cached document keeps being served while one
+ *   background refetch replaces it; concurrent first calls share one fetch.
  * - The document's `issuer` must match the configured one (OIDC Discovery §4.3;
  *   a trailing-slash difference is tolerated and the document's exact value is
  *   returned in `issuer`).

package/build/src/discovery.js

@@ -57,11 +57,17 @@ export class OidcDiscoveryError extends Error {
     }
 }
 const DEFAULT_TTL_MS = 15 * 60_000;
+/** Each discovery request is aborted after this long. */
+const FETCH_TIMEOUT_MS = 10_000;
 const cache = new Map();
+/** One fetch per issuer at a time; concurrent callers share it. */
+const inflight = new Map();
 /**
  * Resolves the IdP endpoints via `/.well-known/openid-configuration`.
  *
  * - Successful documents are cached per issuer (TTL 15 min) — safe to call per request.
+ *   Once the TTL runs out the cached document keeps being served while one
+ *   background refetch replaces it; concurrent first calls share one fetch.
  * - The document's `issuer` must match the configured one (OIDC Discovery §4.3;
  *   a trailing-slash difference is tolerated and the document's exact value is
  *   returned in `issuer`).
@@ -73,20 +79,20 @@ export async function discoverEndpoints(issuer, options = {}) {
     const onError = options.onError ?? 'fallback';
     const cached = cache.get(base);
     let doc;
-    if (cached && Date.now() - cached.fetchedAt < ttl) {
+    if (cached) {
         doc = cached.doc;
+        // Stale-while-revalidate (and stale-while-error): an IdP blip must not break a
+        // client that already knows the endpoints. A failed refetch writes nothing, so
+        // the next call retries.
+        if (Date.now() - cached.fetchedAt >= ttl)
+            refresh(base, options).catch(() => { });
     }
     else {
         try {
-            doc = await fetchDiscovery(base, options.fetchImpl ?? fetch, options.resilience);
-            cache.set(base, { doc, fetchedAt: Date.now() });
+            doc = await refresh(base, options);
         }
         catch (error) {
-            // Stale-while-error: an IdP blip must not break a client that already knows
-            // the endpoints. Nothing is written, so the next call retries.
-            if (cached)
-                doc = cached.doc;
-            else if (onError === 'throw')
+            if (onError === 'throw')
                 throw error;
         }
     }
@@ -99,6 +105,28 @@ export async function discoverEndpoints(issuer, options = {}) {
     assertRequired(base, endpoints);
     return endpoints;
 }
+function refresh(base, options) {
+    let pending = inflight.get(base);
+    if (!pending) {
+        pending = fetchDiscovery(base, withTimeout(options.fetchImpl ?? fetch), options.resilience)
+            .then((doc) => {
+            cache.set(base, { doc, fetchedAt: Date.now() });
+            return doc;
+        })
+            .finally(() => inflight.delete(base));
+        inflight.set(base, pending);
+    }
+    return pending;
+}
+/** A fresh timeout per attempt, so a retrying resilience policy is not cut short. */
+function withTimeout(fetchImpl) {
+    return ((input, init) => fetchImpl(input, {
+        ...init,
+        signal: init?.signal
+            ? AbortSignal.any([init.signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
+            : AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    }));
+}
 async function fetchDiscovery(base, fetchImpl, resilience) {
     const url = `${base}/.well-known/openid-configuration`;
     const fail = (message, cause) => {
@@ -149,4 +177,5 @@ function assertRequired(base, endpoints) {
 /** Clears the discovery cache (tests). */
 export function __clearDiscoveryCacheForTests() {
     cache.clear();
+    inflight.clear();
 }

package/build/src/lucid_mirror.d.ts

@@ -1,7 +1,9 @@
 import type { Identity } from '@adonis-agora/authkit-core';
-/** Model Lucid mínimo que o mirror precisa (só `updateOrCreate`). */
+/** Model Lucid mínimo que o mirror precisa. */
 interface LucidModelLike {
     updateOrCreate(search: Record<string, unknown>, payload: Record<string, unknown>): Promise<any>;
+    /** Leitura sem transação nem lock, usada quando o espelho já está em dia. */
+    findBy?(key: string, value: unknown): Promise<any>;
 }
 export interface LucidMirrorOptions {
     /**
@@ -22,7 +24,9 @@ export interface LucidMirrorOptions {
 /**
  * Factory do padrão "espelho local" de `resolveUser`: faz `updateOrCreate` do usuário
  * de domínio a partir das claims do id_token, opcionalmente pré-carrega relações e
- * injeta os papéis globais. Substitui o `resolveUser` que cada app reescrevia.
+ * injeta os papéis globais. Quando a linha já tem os valores das claims (o caso de
+ * todo request depois do login), lê com `findBy` em vez de abrir a transação com
+ * `SELECT ... FOR UPDATE` do `updateOrCreate`. Substitui o `resolveUser` que cada app reescrevia.
  *
  * ```ts
  * resolveUser: lucidMirror(AppUser, {

package/build/src/lucid_mirror.js

@@ -1,7 +1,17 @@
+/** O usuário já tem exatamente esses valores? Valores não primitivos contam como diferentes. */
+function alreadyMirrored(user, payload) {
+    return Object.entries(payload).every(([key, value]) => {
+        if (value !== null && typeof value === 'object')
+            return false;
+        return Object.is(user[key], value);
+    });
+}
 /**
  * Factory do padrão "espelho local" de `resolveUser`: faz `updateOrCreate` do usuário
  * de domínio a partir das claims do id_token, opcionalmente pré-carrega relações e
- * injeta os papéis globais. Substitui o `resolveUser` que cada app reescrevia.
+ * injeta os papéis globais. Quando a linha já tem os valores das claims (o caso de
+ * todo request depois do login), lê com `findBy` em vez de abrir a transação com
+ * `SELECT ... FOR UPDATE` do `updateOrCreate`. Substitui o `resolveUser` que cada app reescrevia.
  *
  * ```ts
  * resolveUser: lucidMirror(AppUser, {
@@ -17,7 +27,11 @@ export function lucidMirror(Model, options = {}) {
     const idColumn = options.idColumn ?? 'id';
     return async (identity) => {
         const synced = options.sync ? options.sync(identity) : { email: identity.email };
-        const user = await Model.updateOrCreate({ [idColumn]: identity.userId }, { [idColumn]: identity.userId, ...synced });
+        const payload = { [idColumn]: identity.userId, ...synced };
+        let user = Model.findBy ? await Model.findBy(idColumn, identity.userId) : null;
+        if (!user || !alreadyMirrored(user, payload)) {
+            user = await Model.updateOrCreate({ [idColumn]: identity.userId }, payload);
+        }
         if (options.preload) {
             for (const relation of options.preload) {
                 await user.load(relation);

package/build/src/resolvers/factory.d.ts

@@ -20,7 +20,8 @@ export interface OpaqueResolverFactoryConfig {
     introspectionUrl?: string;
     /**
      * TTL (ms) do cache de respostas `active:true`. Default 0 (revogação imediata).
-     * Suba para reduzir round-trips ao custo de imediatismo.
+     * Suba para reduzir round-trips ao custo de imediatismo. Nunca além do `exp` do
+     * token; no máximo 10.000 tokens por processo.
      */
     cacheTtlMs?: number;
 }

package/build/src/resolvers/opaque_resolver.d.ts

@@ -24,7 +24,9 @@ export interface OpaqueResolverConfig {
     /**
      * TTL (ms) do cache em memória de respostas `active:true`, para não introspectar
      * a cada request. Default 0 (sem cache → revogação propaga imediatamente). Suba
-     * para trocar imediatismo por menos round-trips.
+     * para trocar imediatismo por menos round-trips. Uma entrada vence no que vier
+     * primeiro entre o TTL e o `exp` do token; o cache guarda no máximo 10.000 tokens
+     * (expirados saem primeiro, depois o mais antigo).
      */
     cacheTtlMs?: number;
     fetchImpl?: FetchImpl;

package/build/src/resolvers/opaque_resolver.js

@@ -1,5 +1,7 @@
 import { getTokenFromSource } from '../token_source.js';
 import { buildIdentityFromClaims, introspectToken } from './identity.js';
+/** Teto de tokens no cache; o mais antigo sai primeiro. */
+const MAX_CACHE_ENTRIES = 10_000;
 /**
  * Resolver de access token OPACO via introspection padrão (RFC 7662) a cada request.
  *
@@ -29,9 +31,10 @@ export class OpaqueResolver {
         const ttl = this.config.cacheTtlMs ?? 0;
         if (ttl > 0) {
             const hit = this.#cache.get(token);
-            // `nowMs` vem do ctx (request) para não depender de Date.* — ver #now().
-            if (hit && this.#now() - hit.storedAt < ttl)
+            if (hit && this.#now() < hit.expiresAt)
                 return hit.identity;
+            if (hit)
+                this.#cache.delete(token);
         }
         const introspectionUrl = await this.config.introspectionUrl();
         if (!introspectionUrl)
@@ -44,9 +47,32 @@ export class OpaqueResolver {
         }
         const identity = buildIdentityFromClaims(data, this.config.globalRolesClaim);
         if (ttl > 0)
-            this.#cache.set(token, { identity, storedAt: this.#now() });
+            this.#store(token, identity, ttl, data.exp);
         return identity;
     }
+    /**
+     * Guarda a identidade por `ttl`, nunca além do `exp` do token: um token que
+     * expira antes do TTL deixa de resolver quando expira, não quando o cache vence.
+     */
+    #store(token, identity, ttl, exp) {
+        const lifetime = typeof exp === 'number' ? Math.min(ttl, exp * 1000 - Date.now()) : ttl;
+        if (lifetime <= 0)
+            return;
+        const now = this.#now();
+        if (this.#cache.size >= MAX_CACHE_ENTRIES) {
+            for (const [key, entry] of this.#cache) {
+                if (entry.expiresAt <= now)
+                    this.#cache.delete(key);
+            }
+            for (const key of this.#cache.keys()) {
+                if (this.#cache.size < MAX_CACHE_ENTRIES)
+                    break;
+                this.#cache.delete(key);
+            }
+        }
+        this.#cache.delete(token);
+        this.#cache.set(token, { identity, expiresAt: now + lifetime });
+    }
     /** Relógio monotônico de processo (evita Date.* direto; testável). */
     #now() {
         return Math.trunc(performance.now());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-client",
-  "version": "0.20.1",
+  "version": "0.20.3",
   "description": "AdonisJS OIDC/OAuth2 relying-party (client) toolkit: session-based authentication against an OpenID Connect identity provider, with JWT/PAT user resolvers and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",
@@ -82,22 +82,22 @@
     }
   },
   "dependencies": {
-    "@adonis-agora/authkit-core": "0.10.0",
+    "@adonis-agora/authkit-core": "0.10.1",
     "jose": "6.2.13"
   },
   "devDependencies": {
-    "@adonis-agora/authkit-server": "0.81.2",
+    "@adonis-agora/authkit-server": "0.82.1",
     "@adonis-agora/resilience": "0.4.0",
     "@adonisjs/auth": "10.1.0",
     "@adonisjs/core": "7.6.0",
     "@adonisjs/lucid": "22.4.2",
-    "@adonisjs/session": "8.1.0",
+    "@adonisjs/session": "8.3.0",
     "@adonisjs/tsconfig": "2.0.0",
     "@japa/assert": "4.2.0",
-    "@japa/runner": "5.3.0",
-    "@poppinss/ts-exec": "1.4.4",
-    "@tanstack/intent": "0.4.0",
-    "@types/node": "26.5.1",
+    "@japa/runner": "5.4.0",
+    "@poppinss/ts-exec": "1.5.1",
+    "@tanstack/intent": "0.5.6",
+    "@types/node": "26.6.5",
     "ioredis-mock": "8.13.1",
     "tempura": "0.4.1",
     "testcontainers": "12.2.1",

package/skills/authkit-rp-client/SKILL.md

@@ -222,6 +222,9 @@ The opaque resolver introspects with `clientId`/`clientSecret` and the factory
 throws `resolvers.opaque requer um client confidencial (clientSecret)` when the
 config lacks a secret — a public client cannot authenticate introspection.
 
+With `cacheTtlMs`, a cached identity expires at the earlier of the TTL and the
+token's `exp`, and the cache holds at most 10,000 tokens per resolver.
+
 Source: `src/resolvers/factory.ts` (`resolvers.opaque` throw), README.
 
 ### MEDIUM — Bearer resolver in a browser session app (or vice versa)