@adonis-agora/authkit-client 0.17.3 → 0.18.0

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/index.d.ts

@@ -19,6 +19,8 @@ export { getAuthkit } from './src/host/request_authenticator.js';
 export { isAuthkitAdmin, authkitDashboardAuthorize, authkitDashboardMiddleware, } from './src/host/dashboard_guard.js';
 export type { DashboardGuardOptions } from './src/host/dashboard_guard.js';
 export { default as AuthkitContextMiddleware } from './src/middleware/authkit_context_middleware.js';
+export { default as RequireOrgMiddleware } from './src/middleware/require_org_middleware.js';
+export type { RequireOrgMiddlewareOptions } from './src/middleware/require_org_middleware.js';
 export { lucidMirror } from './src/lucid_mirror.js';
 export type { LucidMirrorOptions } from './src/lucid_mirror.js';
 export { registerOidcClient } from './src/register_oidc_client.js';

package/build/index.js

@@ -11,6 +11,7 @@ export { authkitClientGuard, AuthkitClientGuard } from './src/host/authkit_clien
 export { getAuthkit } from './src/host/request_authenticator.js';
 export { isAuthkitAdmin, authkitDashboardAuthorize, authkitDashboardMiddleware, } from './src/host/dashboard_guard.js';
 export { default as AuthkitContextMiddleware } from './src/middleware/authkit_context_middleware.js';
+export { default as RequireOrgMiddleware } from './src/middleware/require_org_middleware.js';
 export { lucidMirror } from './src/lucid_mirror.js';
 export { registerOidcClient } from './src/register_oidc_client.js';
 export { validateLogoutToken, InvalidLogoutTokenError, InMemorySessionIndex, BACKCHANNEL_LOGOUT_EVENT, } from './src/backchannel_logout.js';

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/require_org_middleware.d.ts

@@ -0,0 +1,47 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { NextFn } from '@adonisjs/core/types/http';
+export interface RequireOrgMiddlewareOptions {
+    /**
+     * Para onde mandar quem não tem org ativa. Default: `/account/orgs` — a tela
+     * de seleção que o host-kit do authkit-server já serve.
+     */
+    redirectTo?: string;
+    /**
+     * `web` (default) redireciona para {@link redirectTo}; `api` responde 403 com
+     * um corpo JSON — rotas de API não têm para onde redirecionar.
+     */
+    mode?: 'web' | 'api';
+    /**
+     * Restringe às orgs listadas. Útil para rotas que só existem dentro de um
+     * conjunto conhecido de tenants. Ausente → qualquer org ativa serve.
+     */
+    oneOf?: string[];
+}
+/**
+ * Exige que a sessão tenha uma **organização ativa** (claim `org_id`, exposta
+ * como `identity.orgId`).
+ *
+ * Existe porque num app multi-tenant "estar autenticado" e "estar dentro de um
+ * tenant" são coisas diferentes: sem esta barreira, uma request de um usuário
+ * logado mas sem org ativa chega no controller com `tenantId` indefinido, e daí
+ * o escopo por tenant do `@adonis-agora/authz` cai no escopo GLOBAL — que é o
+ * pior lugar para se cair por acidente. Fail-closed: sem sessão ou sem org, não
+ * passa.
+ *
+ * Registre como named middleware e encadeie DEPOIS do de auth:
+ *
+ * ```ts title="start/kernel.ts"
+ * export const middleware = router.named({
+ *   auth: () => import('@adonis-agora/authkit-client/auth_middleware'),
+ *   requireOrg: () => import('@adonis-agora/authkit-client/require_org_middleware'),
+ * })
+ * ```
+ *
+ * ```ts title="start/routes.ts"
+ * router.group(() => { … }).use([middleware.auth(), middleware.requireOrg()])
+ * router.group(() => { … }).use([middleware.auth(), middleware.requireOrg({ mode: 'api' })])
+ * ```
+ */
+export default class RequireOrgMiddleware {
+    handle(ctx: HttpContext, next: NextFn, options?: RequireOrgMiddlewareOptions): Promise<any>;
+}

package/build/src/middleware/require_org_middleware.js

@@ -0,0 +1,39 @@
+import { ctxAuth } from '../host/ctx_auth.js';
+/**
+ * Exige que a sessão tenha uma **organização ativa** (claim `org_id`, exposta
+ * como `identity.orgId`).
+ *
+ * Existe porque num app multi-tenant "estar autenticado" e "estar dentro de um
+ * tenant" são coisas diferentes: sem esta barreira, uma request de um usuário
+ * logado mas sem org ativa chega no controller com `tenantId` indefinido, e daí
+ * o escopo por tenant do `@adonis-agora/authz` cai no escopo GLOBAL — que é o
+ * pior lugar para se cair por acidente. Fail-closed: sem sessão ou sem org, não
+ * passa.
+ *
+ * Registre como named middleware e encadeie DEPOIS do de auth:
+ *
+ * ```ts title="start/kernel.ts"
+ * export const middleware = router.named({
+ *   auth: () => import('@adonis-agora/authkit-client/auth_middleware'),
+ *   requireOrg: () => import('@adonis-agora/authkit-client/require_org_middleware'),
+ * })
+ * ```
+ *
+ * ```ts title="start/routes.ts"
+ * router.group(() => { … }).use([middleware.auth(), middleware.requireOrg()])
+ * router.group(() => { … }).use([middleware.auth(), middleware.requireOrg({ mode: 'api' })])
+ * ```
+ */
+export default class RequireOrgMiddleware {
+    async handle(ctx, next, options = {}) {
+        const identity = await ctxAuth(ctx).getIdentity();
+        const orgId = identity?.orgId ?? null;
+        const allowed = orgId !== null && (!options.oneOf || options.oneOf.includes(orgId));
+        if (allowed)
+            return next();
+        if (options.mode === 'api') {
+            return ctx.response.abort({ error: 'no_active_organization', message: 'This route requires an active organization.' }, 403);
+        }
+        return ctx.response.redirect(options.redirectTo ?? '/account/orgs');
+    }
+}

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/src/observability/context_bridge.js

@@ -1,3 +1,4 @@
+import { deriveOrgId } from '@adonis-agora/authkit-core';
 /**
  * Ponte estrutural (best-effort) entre a sessão resolvida do authkit e o
  * contexto do Agora. Lê o slot global `@agora/context:set` de forma ESTRUTURAL —
@@ -6,26 +7,14 @@
  */
 const SET_SLOT = Symbol.for('@agora/context:set');
 /**
- * Claims OIDC candidatas a "organização/tenant ativo". A primeira presente (e
- * string não vazia) vira o `tenantId`. Não falha se nenhuma existir.
+ * Deriva o tenant ativo da identidade. Prefere o `orgId` já resolvido (o caminho
+ * normal — `buildIdentityFromClaims` o preenche); cai para as claims cruas
+ * quando a `Identity` veio de um `SessionResolver` customizado que não o
+ * populou. A tabela de claims aceitas vive em `@adonis-agora/authkit-core`
+ * (`ORG_ID_CLAIMS`) para não divergir entre a identidade e esta ponte.
  */
-const TENANT_CLAIMS = [
-    'active_organization_id',
-    'org_id',
-    'organization_id',
-    'tenant_id',
-    'tid',
-];
-/** Deriva o tenant ativo das claims cruas, ou `undefined` quando ausente. */
-function deriveTenant(raw) {
-    if (!raw)
-        return undefined;
-    for (const claim of TENANT_CLAIMS) {
-        const value = raw[claim];
-        if (typeof value === 'string' && value.length > 0)
-            return value;
-    }
-    return undefined;
+function deriveTenant(identity) {
+    return identity.orgId ?? deriveOrgId(identity.raw) ?? undefined;
 }
 /**
  * Popula o contexto do Agora a partir de uma identidade recém-resolvida:
@@ -38,7 +27,7 @@ export function populateContext(identity) {
         const set = globalThis[SET_SLOT];
         if (!set)
             return;
-        const tenant = deriveTenant(identity.raw);
+        const tenant = deriveTenant(identity);
         set({
             userRef: { type: 'user', id: identity.userId },
             globalRoles: identity.globalRoles,

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

@@ -8,7 +8,9 @@ type FetchImpl = (url: string, init: any) => Promise<{
  * resolvers `jwt`, `pat` e `opaque`. Espelha exatamente o que o `JwtResolver`
  * produzia (a referência canônica): `sub`→userId, `email`, papéis na
  * `globalRolesClaim`, `name`/`picture`→profile, `sid`→sessionId, `iat`/`exp`
- * (segundos→ms, fallback 0) e as claims cruas em `raw`.
+ * (segundos→ms, fallback 0), a org/tenant ativo (`orgId`/`orgSlug`/`orgRole`,
+ * ver `deriveOrgId` — vale para o authkit E para IdPs de terceiros) e as claims
+ * cruas em `raw`.
  */
 export declare function buildIdentityFromClaims(claims: Record<string, unknown>, globalRolesClaim: string): Identity;
 export interface IntrospectAuth {

package/build/src/resolvers/identity.js

@@ -1,9 +1,12 @@
+import { deriveOrgId, deriveOrgRole, deriveOrgSlug } from '@adonis-agora/authkit-core';
 /**
  * Mapeamento canônico de claims OIDC validadas → Identity, compartilhado pelos
  * resolvers `jwt`, `pat` e `opaque`. Espelha exatamente o que o `JwtResolver`
  * produzia (a referência canônica): `sub`→userId, `email`, papéis na
  * `globalRolesClaim`, `name`/`picture`→profile, `sid`→sessionId, `iat`/`exp`
- * (segundos→ms, fallback 0) e as claims cruas em `raw`.
+ * (segundos→ms, fallback 0), a org/tenant ativo (`orgId`/`orgSlug`/`orgRole`,
+ * ver `deriveOrgId` — vale para o authkit E para IdPs de terceiros) e as claims
+ * cruas em `raw`.
  */
 export function buildIdentityFromClaims(claims, globalRolesClaim) {
     const roles = claims[globalRolesClaim];
@@ -16,6 +19,9 @@ export function buildIdentityFromClaims(claims, globalRolesClaim) {
             avatarUrl: typeof claims.picture === 'string' ? claims.picture : undefined,
         },
         sessionId: typeof claims.sid === 'string' ? claims.sid : undefined,
+        orgId: deriveOrgId(claims),
+        orgSlug: deriveOrgSlug(claims),
+        orgRole: deriveOrgRole(claims),
         issuedAt: typeof claims.iat === 'number' ? claims.iat * 1000 : 0,
         expiresAt: typeof claims.exp === 'number' ? claims.exp * 1000 : 0,
         raw: claims,

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.18.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",
@@ -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",
@@ -44,6 +45,7 @@
     "./authkit_context_middleware": "./build/src/middleware/authkit_context_middleware.js",
     "./backchannel_revocation_middleware": "./build/src/middleware/backchannel_revocation_middleware.js",
     "./auth_middleware": "./build/src/middleware/auth_middleware.js",
+    "./require_org_middleware": "./build/src/middleware/require_org_middleware.js",
     "./silent_auth_middleware": "./build/src/middleware/silent_auth_middleware.js",
     "./commands": "./build/commands/configure.js"
   },
@@ -76,7 +78,7 @@
   },
   "dependencies": {
     "jose": "5.10.0",
-    "@adonis-agora/authkit-core": "0.7.1"
+    "@adonis-agora/authkit-core": "0.8.0"
   },
   "devDependencies": {
     "@adonisjs/auth": "10.1.0",
@@ -91,7 +93,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.59.0"
   },
   "scripts": {
     "build": "tsc && node -e \"require('node:fs').cpSync('stubs','build/stubs',{recursive:true,filter:(s)=>!s.endsWith('.ts')})\"",