@adonis-agora/authkit-client 0.17.3 → 0.17.4

package/build/container_bindings.d.ts

@@ -0,0 +1,25 @@
+import type { AuthkitClientManager } from './providers/authkit_client_provider.js';
+/**
+ * SINGLE SOURCE of this package's container bindings.
+ *
+ * Deliberately separate from `types.ts`. `types.ts` augments
+ * `HttpContext.auth`, and that augmentation is the HOST'S to choose: an app that
+ * types its own `auth: Authenticator<AppUser>` cannot also receive the library's
+ * non-parameterised `auth: Authenticator` without the two merging into a
+ * conflict — one that `skipLibCheck` (on in every AdonisJS app) hides, leaving
+ * whichever declaration wins by include order.
+ *
+ * The container binding has no such problem: it names a key only this package
+ * owns. So it lives here, where the provider and the middleware can pull it in
+ * without dragging `HttpContext.auth` into the consumer's program.
+ *
+ * If you add an augmentation here, ask first whether a host could legitimately
+ * want to declare it differently. If yes, it belongs in `types.ts`, behind the
+ * host's explicit opt-in.
+ */
+declare module '@adonisjs/core/types' {
+    interface ContainerBindings {
+        'authkit.client': AuthkitClientManager;
+    }
+}
+export type { AuthkitClientManager };

package/build/container_bindings.js

@@ -0,0 +1 @@
+export {};

package/build/providers/authkit_client_provider.d.ts

@@ -1,3 +1,4 @@
+import '../container_bindings.js';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { ApplicationService } from '@adonisjs/core/types';
 import { Authenticator } from '../src/authenticator.js';
@@ -107,11 +108,6 @@ export declare class AuthkitClientManager {
     startSession(ctx: HttpContext, tokenSet: TokenSet): void;
     createAuthenticator(ctx: HttpContext): Promise<Authenticator>;
 }
-declare module '@adonisjs/core/types' {
-    interface ContainerBindings {
-        'authkit.client': AuthkitClientManager;
-    }
-}
 export default class AuthkitClientProvider {
     protected app: ApplicationService;
     constructor(app: ApplicationService);

package/build/providers/authkit_client_provider.js

@@ -1,3 +1,6 @@
+// Single source of this package's container bindings (see container_bindings.ts).
+// A bare side-effect import so the declaration survives into the emitted `.d.ts`.
+import '../container_bindings.js';
 import { randomUUID } from 'node:crypto';
 import { configProvider } from '@adonisjs/core';
 import { RuntimeException } from '@adonisjs/core/exceptions';

package/build/src/host/ctx_auth.d.ts

@@ -0,0 +1,6 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { Authenticator } from '../authenticator.js';
+/** Read the authenticator the middleware placed on the context. */
+export declare function ctxAuth(ctx: HttpContext): Authenticator;
+/** Place the authenticator on the context. */
+export declare function setCtxAuth(ctx: HttpContext, authenticator: Authenticator): void;

package/build/src/host/ctx_auth.js

@@ -0,0 +1,8 @@
+/** Read the authenticator the middleware placed on the context. */
+export function ctxAuth(ctx) {
+    return ctx.auth;
+}
+/** Place the authenticator on the context. */
+export function setCtxAuth(ctx, authenticator) {
+    ctx.auth = authenticator;
+}

package/build/src/middleware/auth_middleware.js

@@ -1,10 +1,11 @@
+import { ctxAuth } from '../host/ctx_auth.js';
 /**
  * Middleware de autenticação do AuthKit: exige sessão válida. Autorização por role saiu daqui — use
  * `@adonis-agora/authz` (ou Bouncer) na rota. AuthKit só autentica.
  */
 export default class AuthkitAuthMiddleware {
     async handle(ctx, next, options = {}) {
-        const ok = await ctx.auth.check();
+        const ok = await ctxAuth(ctx).check();
         if (!ok)
             return ctx.response.redirect(options.redirectTo ?? '/auth/login');
         return next();

package/build/src/middleware/authkit_middleware.d.ts

@@ -1,4 +1,4 @@
-import '../../types.js';
+import '../../container_bindings.js';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { NextFn } from '@adonisjs/core/types/http';
 export default class AuthkitMiddleware {

package/build/src/middleware/authkit_middleware.js

@@ -1,22 +1,24 @@
-// Side-effect import: pulls the `HttpContext.auth` module augmentation (declared
-// in the package root `types.ts`) into this module's declaration graph, so an app
-// that registers this middleware gets `ctx.auth` typed as AuthKit's `Authenticator`.
-// It lives here — and not in `index.ts` — because this middleware is what actually
-// assigns `ctx.auth`. Apps that instead hand `ctx.auth` to `@adonisjs/auth` via
-// `authkitClientGuard` never register this middleware, so the two owners of
-// `ctx.auth` can never collide. Same pattern as `@adonisjs/auth`, which augments
-// `HttpContext` from its own `initialize_auth_middleware`.
-// It must be a bare side-effect import, not `import type {} from`: the type-only form
-// is erased from the emitted `.d.ts` as well, which would drop the augmentation again.
-// The runtime cost is nil — `build/types.js` is this package's own file and compiles
-// down to `export {}`.
-import '../../types.js';
+// Side-effect import: carries this package's `ContainerBindings` declaration into
+// the emitted `.d.ts`, so `containerResolver.make('authkit.client')` is typed in a
+// consumer's program. It must be a bare side-effect import — the
+// `import type {} from` form is erased from the declaration output.
+//
+// It points at `container_bindings.js`, NOT at the root `types.js`. `types.js`
+// also augments `HttpContext.auth`, and importing it here pushed that
+// augmentation into every app that registers this middleware, where it collided
+// with the app's own `auth: Authenticator<AppUser>`. `skipLibCheck` hid the
+// conflict and the library's non-parameterised declaration won, collapsing
+// `auth.getUser()` to `unknown` across the consumer's codebase. Typing `ctx.auth`
+// is the host's decision, taken by importing
+// `@adonis-agora/authkit-client/types`; it is not this middleware's to impose.
+import '../../container_bindings.js';
+import { setCtxAuth } from '../host/ctx_auth.js';
 export default class AuthkitMiddleware {
     async handle(ctx, next) {
         const manager = await ctx.containerResolver.make('authkit.client');
         // Renova proativamente o TokenSet (rotação de refresh token) antes de resolver.
         await manager.maybeRefresh(ctx);
-        ctx.auth = await manager.createAuthenticator(ctx);
+        setCtxAuth(ctx, await manager.createAuthenticator(ctx));
         return next();
     }
 }

package/build/src/middleware/silent_auth_middleware.js

@@ -1,3 +1,4 @@
+import { ctxAuth } from '../host/ctx_auth.js';
 /**
  * Resolve a identidade da sessão (popula `ctx.auth`) SEM exigir login — útil em
  * rotas públicas que mostram estado logado/deslogado. Nunca redireciona.
@@ -8,7 +9,7 @@
  */
 export default class AuthkitSilentAuthMiddleware {
     async handle(ctx, next) {
-        await ctx.auth.check();
+        await ctxAuth(ctx).check();
         return next();
     }
 }

package/build/types.d.ts

@@ -1,13 +1,43 @@
+import './container_bindings.js';
 import type { AuthkitClientManager } from './providers/authkit_client_provider.js';
 import type { Authenticator } from './src/authenticator.js';
+/**
+ * OPT-IN typing for `ctx.auth`.
+ *
+ * Reference this module from your app when you want `ctx.auth` typed as
+ * AuthKit's `Authenticator` and you are NOT declaring the property yourself:
+ *
+ * ```ts
+ * // any file in your app, e.g. app/types.ts
+ * import '@adonis-agora/authkit-client/types'
+ * ```
+ *
+ * NOTHING in this package imports this module on your behalf, and that is the
+ * point. `Authenticator` is generic (`Authenticator<TUser>`), and most apps
+ * declare their own augmentation so `auth.getUser()` returns their user model:
+ *
+ * ```ts
+ * declare module '@adonisjs/core/http' {
+ *   interface HttpContext {
+ *     auth: Authenticator<AppUser>
+ *   }
+ * }
+ * ```
+ *
+ * Two declarations of the same property with different types do not merge —
+ * they conflict, and because `skipLibCheck` is on in every AdonisJS app the
+ * conflict is never reported: one simply wins by include order. When the
+ * library's won, `auth.getUser()` collapsed to `unknown` across the whole app.
+ * So the library ships the declaration and lets you decide whether to load it,
+ * rather than forcing it through a middleware import.
+ *
+ * The container bindings come along with it (see `container_bindings.ts`); they
+ * are also available on their own, which is what the provider and the middleware
+ * use.
+ */
 declare module '@adonisjs/core/http' {
     interface HttpContext {
         auth: Authenticator;
     }
 }
-declare module '@adonisjs/core/types' {
-    interface ContainerBindings {
-        'authkit.client': AuthkitClientManager;
-    }
-}
 export type { Authenticator, AuthkitClientManager };

package/build/types.js

@@ -1 +1 @@
-export {};
+import './container_bindings.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-client",
-  "version": "0.17.3",
+  "version": "0.17.4",
   "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",
@@ -36,6 +36,7 @@
   "exports": {
     ".": "./build/index.js",
     "./types": "./build/types.js",
+    "./container_bindings": "./build/container_bindings.js",
     "./services/main": "./build/services/main.js",
     "./authkit_client_provider": "./build/providers/authkit_client_provider.js",
     "./auth": "./build/src/host/authkit_client_guard.js",
@@ -91,7 +92,7 @@
     "ioredis-mock": "8.13.1",
     "@types/node": "25.9.1",
     "typescript": "6.0.3",
-    "@adonis-agora/authkit-server": "0.58.1"
+    "@adonis-agora/authkit-server": "0.58.2"
   },
   "scripts": {
     "build": "tsc && node -e \"require('node:fs').cpSync('stubs','build/stubs',{recursive:true,filter:(s)=>!s.endsWith('.ts')})\"",