@adonis-agora/authkit-client 0.17.4 → 0.18.1

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-client",
-  "version": "0.17.4",
+  "version": "0.18.1",
   "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",
@@ -21,7 +21,8 @@
     "authentication",
     "authkit",
     "relying-party",
-    "jwt"
+    "jwt",
+    "tanstack-intent"
   ],
   "publishConfig": {
     "access": "public"
@@ -31,7 +32,8 @@
   "types": "./build/index.d.ts",
   "files": [
     "build",
-    "stubs"
+    "stubs",
+    "skills"
   ],
   "exports": {
     ".": "./build/index.js",
@@ -45,6 +47,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"
   },
@@ -77,7 +80,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",
@@ -89,10 +92,11 @@
     "@japa/assert": "4.2.0",
     "@japa/runner": "5.3.0",
     "@poppinss/ts-exec": "1.4.4",
+    "@tanstack/intent": "^0.3.2",
     "ioredis-mock": "8.13.1",
     "@types/node": "25.9.1",
     "typescript": "6.0.3",
-    "@adonis-agora/authkit-server": "0.58.2"
+    "@adonis-agora/authkit-server": "0.61.0"
   },
   "scripts": {
     "build": "tsc && node -e \"require('node:fs').cpSync('stubs','build/stubs',{recursive:true,filter:(s)=>!s.endsWith('.ts')})\"",

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

@@ -0,0 +1,242 @@
+---
+name: authkit-rp-client
+description: >-
+  Integrate an AdonisJS app as an OpenID Connect relying party with
+  @adonis-agora/authkit-client. Covers defineConfig({ issuer, clientId, redirectUri,
+  resolver }), resolvers.jwt({ tokenSource }) / resolvers.pat / resolvers.opaque,
+  resolveUser topologies (identityToUser, createUserinfoResolver, local Lucid model),
+  the authkit_middleware + @adonisjs/session ordering rule, ctx.auth
+  (getIdentity/getUser/hasGlobalRole), registerOidcClient(router, { prefix, redirects,
+  afterLogin, loginMiddleware }), backchannelLogout: { store } +
+  BackchannelRevocationMiddleware, AUTHKIT_REDIRECT_URI, and why app-role gating
+  belongs to @adonis-agora/authz instead. Use when wiring a client app to the IdP,
+  fixing null identity, choosing a user-resolution topology, or adding back-channel
+  logout.
+license: MIT
+metadata:
+  type: core
+  library: "@adonis-agora/authkit-client"
+  library_version: "0.18.0"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-authkit:packages/authkit-client/README.md"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-client/src/define_config.ts"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-client/src/resolvers/factory.ts"
+  - "DavideCarvalho/adonis-authkit:packages/authkit-client/src/register_oidc_client.ts"
+---
+
+# OIDC relying-party (client) integration
+
+`@adonis-agora/authkit-client` makes an AdonisJS app consume an OIDC provider (the
+AuthKit IdP or any other) with session-based auth: PKCE authorization-code login,
+locally-validated ID tokens (JWKS), typed `ctx.auth` per request. `configure`
+publishes `config/authkit_client.ts`, `OidcSessionController` (login/callback/logout)
+and registers the provider + middleware.
+
+## Setup
+
+```bash
+node ace add @adonis-agora/authkit-client
+```
+
+```ts
+// config/authkit_client.ts
+import env from '#start/env'
+import { defineConfig, resolvers } from '@adonis-agora/authkit-client'
+
+const authkitClientConfig = defineConfig({
+  issuer: env.get('AUTHKIT_ISSUER'),
+  clientId: env.get('AUTHKIT_CLIENT_ID'),
+  clientSecret: env.get('AUTHKIT_CLIENT_SECRET'),
+  redirectUri: env.get('AUTHKIT_REDIRECT_URI'), // must point at the callback route
+  resolver: resolvers.jwt({ tokenSource: 'session' }),
+})
+
+export default authkitClientConfig
+```
+
+```ts
+// start/routes.ts
+import router from '@adonisjs/core/services/router'
+import OidcSessionController from '#controllers/oidc_session_controller'
+
+router.get('/auth/login', [OidcSessionController, 'login'])
+router.get('/auth/callback', [OidcSessionController, 'callback'])
+router.post('/auth/logout', [OidcSessionController, 'logout'])
+```
+
+Source: `packages/authkit-client/README.md`, `stubs/config/authkit_client.stub`.
+
+## Core patterns
+
+### Pattern 1 — `ctx.auth` per request
+
+The `authkit_middleware` populates `ctx.auth`; identity comes from the validated
+token, the user from your `resolveUser`:
+
+```ts
+router.get('/me', async ({ auth }) => {
+  const identity = await auth.getIdentity() // validated OIDC claims, or null
+  const user = await auth.getUser()         // app model via resolveUser
+  const isAdmin = auth.hasGlobalRole('ADMIN') // sync — reads token claims
+  return { identity, user, isAdmin }
+})
+```
+
+`getIdentity()` resolves once per request and memoizes; `authenticate()` throws when
+anonymous; `check()` returns a boolean. `identity` (getter) is only populated after
+the first async call — prefer `getIdentity()`.
+
+Source: `packages/authkit-client/README.md` § Uso por request,
+`src/authenticator.ts` (`Authenticator`).
+
+### Pattern 2 — `resolveUser` per database topology
+
+Identity always comes from the token; what varies is how the app model is fetched:
+
+```ts
+// Same DB, cross-schema FK: map to a local Lucid model
+resolveUser: async (identity) => {
+  return AppUser.query().where('authUserId', identity.userId).firstOrFail()
+}
+
+// Separate DBs: the IdP emits a fat ID token — claims-only, zero lookups
+import { identityToUser } from '@adonis-agora/authkit-client'
+resolveUser: identityToUser // { id, email, name?, avatarUrl?, globalRoles }
+
+// Separate DBs + data beyond the claims: userinfo resolver against ${issuer}/me
+import { createUserinfoResolver } from '@adonis-agora/authkit-client'
+resolveUser: createUserinfoResolver({ issuer: env.get('AUTHKIT_ISSUER') })
+```
+
+Source: `packages/authkit-client/README.md` § Topologias de banco,
+`src/user_resolvers.ts`.
+
+### Pattern 3 — one-liner routes with `registerOidcClient`
+
+Instead of hand-writing the controller trio, register PKCE + state, code exchange,
+RP-initiated logout and role-based redirects in one call:
+
+```ts
+import router from '@adonisjs/core/services/router'
+import middleware from '#start/kernel'
+import { registerOidcClient } from '@adonis-agora/authkit-client'
+
+registerOidcClient(router, {
+  loginMiddleware: middleware.guest(),
+  redirects: { byGlobalRole: { ADMIN: '/admin' }, default: '/' },
+  // prefix defaults to /auth → /auth/login, /auth/callback, /auth/logout
+  // backchannelLogout defaults to true → also registers POST /auth/backchannel-logout
+})
+```
+
+Source: `src/register_oidc_client.ts` (`RegisterOidcClientOptions` + doc example).
+
+### Pattern 4 — back-channel logout for cookie sessions
+
+Pass a store and the kit derives the callback + enforcement middleware:
+
+```ts
+import { defineConfig, resolvers, lucidRevocationStore } from '@adonis-agora/authkit-client'
+
+defineConfig({
+  issuer: env.get('AUTHKIT_ISSUER'),
+  clientId: env.get('AUTHKIT_CLIENT_ID'),
+  redirectUri: env.get('AUTHKIT_REDIRECT_URI'),
+  resolver: resolvers.jwt(),
+  backchannelLogout: { store: lucidRevocationStore() },
+})
+```
+
+Then apply `BackchannelRevocationMiddleware` (from
+`@adonis-agora/authkit-client/backchannel_revocation_middleware`) so revoked
+sessions are rejected per request. Custom needs: `onBackchannelLogout` receives the
+validated `{ sid, sub }` (store runs first, then the hook).
+
+Source: `src/define_config.ts` (`BackchannelLogoutInput`), README.
+
+## Common mistakes
+
+### HIGH — Session middleware running after `authkit_middleware`
+
+```ts
+// Wrong — resolver reads an empty session; every request looks anonymous
+router.use([middleware.authkit(), middleware.session()])
+```
+
+```ts
+// Correct — @adonisjs/session MUST run BEFORE the authkit middleware
+router.use([middleware.session(), middleware.authkit()])
+```
+
+With `resolvers.jwt({ tokenSource: 'session' })` (the default) the resolver reads
+the token set from the `@adonisjs/session` store; if session middleware has not run
+yet the token is never found and `getIdentity()` silently returns `null` — no error,
+just a logged-out app.
+
+Source: `packages/authkit-client/README.md` § Ordem de middleware (importante).
+
+### HIGH — Putting app-role authorization in the client kit
+
+```ts
+// Wrong — expecting authkit to resolve app roles/permissions
+if (auth.hasGlobalRole('ADMIN')) { /* app-role check? */ }
+const can = await authkit.checkPermission(user, 'posts.edit') // does not exist
+```
+
+```ts
+// Correct — AuthKit authenticates + exposes token globalRoles; authz decides access
+if (auth.hasGlobalRole('ADMIN')) { /* global role from the token claims */ }
+// App roles/permissions: configure resolveRoles in @adonis-agora/authz
+// and enforce with authz/Bouncer route guards, not authkit_middleware.
+```
+
+AuthKit only authenticates and knows the `globalRoles` claim; app roles (domain
+tables) and permissions were deliberately moved out to `@adonis-agora/authz`.
+The `authkit_middleware` only enforces login.
+
+Source: `packages/authkit-client/README.md` callout ("Autorização por app-role saiu
+do AuthKit"), `stubs/config/authkit_client.stub` comment.
+
+### MEDIUM — `resolvers.opaque` without a confidential client
+
+```ts
+// Wrong — public client: throws at resolver creation
+resolver: resolvers.opaque({ introspectionUrl: '...' })
+```
+
+```ts
+// Correct — opaque introspection requires the client secret
+resolver: resolvers.opaque({
+  tokenSource: 'bearer',
+  cacheTtlMs: 30_000, // trade immediacy for fewer round-trips
+})
+```
+
+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.
+
+Source: `src/resolvers/factory.ts` (`resolvers.opaque` throw), README.
+
+### MEDIUM — Bearer resolver in a browser session app (or vice versa)
+
+```ts
+// Wrong — SPA/API app still using the default session source
+resolver: resolvers.jwt() // tokenSource defaults to 'session'
+```
+
+```ts
+// Correct — pick the source matching the transport
+resolver: resolvers.jwt({ tokenSource: 'bearer' }) // reads Authorization header
+```
+
+`tokenSource` decides where the ID token is read from: `'session'` (default, cookie
+apps) vs `'bearer'` (`Authorization` header for SPA/API callers). The mismatched
+source yields a silent `null` identity, not an error.
+
+Source: `packages/authkit-client/README.md` § Resolução de sessão,
+`src/resolvers/factory.ts` (`JwtResolverFactoryConfig`).
+
+See also: `authkit-idp-setup/SKILL.md` — the IdP side that issues these tokens, and
+`authkit-react-auth/SKILL.md` — how the identity reaches the frontend.