@adonis-agora/authkit-client 0.11.0 → 0.13.0

package/build/src/authenticator.d.ts

@@ -11,7 +11,13 @@ export interface AuthenticatorDeps {
     /** lê o access token do token set da sessão (opcional; usado por resolvers userinfo) */
     getAccessToken?: () => string | null | undefined;
 }
-export declare class Authenticator {
+/**
+ * Autenticador do request. O parâmetro `TUser` é o tipo do usuário do app que `resolveUser`
+ * devolve — o app o fixa via augmentation de `HttpContext.auth` (`auth: Authenticator<AppUser>`),
+ * e aí `getUser()` passa a devolver `AppUser | null` em todo call-site, sem cast. Default `unknown`
+ * mantém o comportamento anterior (nada a mudar em quem não augmenta).
+ */
+export declare class Authenticator<TUser = unknown> {
     #private;
     private ctx;
     private deps;
@@ -21,7 +27,15 @@ export declare class Authenticator {
     authenticate(): Promise<Identity>;
     check(): Promise<boolean>;
     hasGlobalRole(role: string): boolean;
-    getUser(): Promise<unknown>;
+    getUser(): Promise<TUser | null>;
+    /**
+     * O `TUser` autenticado, NÃO-nulo. Fail-closed: lança quando não há sessão (ou quando `resolveUser`
+     * não devolve usuário) — pensado para rotas atrás do middleware de auth, onde `null` seria uma
+     * rota mal-configurada, não um visitante. Espelha `authenticate()` (que devolve a `Identity`); este
+     * devolve o usuário do app. Substitui o wrapper `currentUser(auth)` que cada app reescrevia sobre
+     * `getUser()`. Para rotas que aceitam visitante, use `getUser()` (devolve `TUser | null`).
+     */
+    getUserOrFail(): Promise<TUser>;
     /**
      * Monta o objeto pronto para compartilhar com o frontend (ex.: Inertia share),
      * casando com o `AuthSharedProps` que o `@adonis-agora/authkit-react` consome.
@@ -29,7 +43,7 @@ export declare class Authenticator {
      * é responsabilidade do `@adonis-agora/authz` — o AuthKit só autentica.
      */
     toSharedProps(): Promise<{
-        user: unknown;
+        user: TUser | null;
         globalRoles: string[];
     } | null>;
 }

package/build/src/authenticator.js

@@ -1,11 +1,17 @@
-import { AUTHKIT_METRICS, NoopRecorder } from "@adonis-agora/authkit-core";
+import { AUTHKIT_METRICS, NoopRecorder, } from "@adonis-agora/authkit-core";
 import { populateContext } from "./observability/context_bridge.js";
+/**
+ * Autenticador do request. O parâmetro `TUser` é o tipo do usuário do app que `resolveUser`
+ * devolve — o app o fixa via augmentation de `HttpContext.auth` (`auth: Authenticator<AppUser>`),
+ * e aí `getUser()` passa a devolver `AppUser | null` em todo call-site, sem cast. Default `unknown`
+ * mantém o comportamento anterior (nada a mudar em quem não augmenta).
+ */
 export class Authenticator {
     ctx;
     deps;
     #identity = null;
     #resolved = false;
-    #user;
+    #user = null;
     #userResolved = false;
     #recorder;
     constructor(ctx, deps, recorder = new NoopRecorder()) {
@@ -56,7 +62,11 @@ export class Authenticator {
         const identity = await this.getIdentity();
         if (identity && this.deps.resolveUser) {
             const accessToken = this.deps.getAccessToken?.() ?? undefined;
-            this.#user = await this.deps.resolveUser(identity, { accessToken });
+            // `resolveUser` é tipado `Promise<unknown>` (a lib não conhece o model do app); o `TUser`
+            // é a asserção do consumidor, feita UMA vez aqui em vez de em cada call-site de `getUser()`.
+            this.#user = (await this.deps.resolveUser(identity, {
+                accessToken,
+            }));
         }
         else {
             this.#user = null;
@@ -64,6 +74,20 @@ export class Authenticator {
         this.#userResolved = true;
         return this.#user;
     }
+    /**
+     * O `TUser` autenticado, NÃO-nulo. Fail-closed: lança quando não há sessão (ou quando `resolveUser`
+     * não devolve usuário) — pensado para rotas atrás do middleware de auth, onde `null` seria uma
+     * rota mal-configurada, não um visitante. Espelha `authenticate()` (que devolve a `Identity`); este
+     * devolve o usuário do app. Substitui o wrapper `currentUser(auth)` que cada app reescrevia sobre
+     * `getUser()`. Para rotas que aceitam visitante, use `getUser()` (devolve `TUser | null`).
+     */
+    async getUserOrFail() {
+        const user = await this.getUser();
+        if (user === null) {
+            throw new Error("Not authenticated: no user for the current session");
+        }
+        return user;
+    }
     /**
      * Monta o objeto pronto para compartilhar com o frontend (ex.: Inertia share),
      * casando com o `AuthSharedProps` que o `@adonis-agora/authkit-react` consome.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-client",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "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,7 +82,7 @@
     "ioredis-mock": "^8.9.0",
     "@types/node": "25.9.1",
     "typescript": "6.0.3",
-    "@adonis-agora/authkit-server": "0.35.0"
+    "@adonis-agora/authkit-server": "0.36.0"
   },
   "scripts": {
     "build": "tsc && node -e \"require('node:fs').cpSync('stubs','build/stubs',{recursive:true,filter:(s)=>!s.endsWith('.ts')})\"",