@adonis-agora/authkit-client 0.19.0 → 0.19.2

package/build/commands/configure.js

@@ -16,4 +16,10 @@ export async function configure(command) {
             AUTHKIT_REDIRECT_URI: `Env.schema.string({ format: 'url', tld: false })`,
         },
     });
+    // As rotas não são registradas pelo configure. O caminho é o `registerOidcClient`
+    // (startSession/endSession, RP-initiated logout, back-channel); o controller
+    // ejetado acima existe só para quem precisa customizar o fluxo.
+    command.logger.info('Registre as rotas de sessão em start/routes.ts com registerOidcClient(router) ' +
+        "(import { registerOidcClient } from '@adonis-agora/authkit-client'). " +
+        'O app/controllers/oidc_session_controller.ts publicado é só para customizar o fluxo.');
 }

package/build/providers/authkit_client_provider.js

@@ -6,7 +6,7 @@ import { configProvider } from '@adonisjs/core';
 import { RuntimeException } from '@adonisjs/core/exceptions';
 import { decodeJwt } from 'jose';
 import { Authenticator } from '../src/authenticator.js';
-import { completeAuthorization, createAuthorizationRequest, } from '../src/authorization.js';
+import { assertCallbackBelongs, completeAuthorization, createAuthorizationRequest, } from '../src/authorization.js';
 import { validateLogoutToken } from '../src/backchannel_logout.js';
 import { conventionEndpoints, discoverEndpoints, mergeEndpoints, } from '../src/discovery.js';
 import { validateIdToken, } from '../src/id_token.js';
@@ -111,6 +111,8 @@ export class AuthkitClientManager {
      * Throws `OidcCallbackError`; `error.restartable` means "send them back to login".
      */
     async completeAuthorization(params) {
+        // Before discovery: a stale or forged callback is restartable even while the IdP is down.
+        assertCallbackBelongs(params.pending, params.callbackParams);
         const { endpoints, keys } = await this.#idp();
         return completeAuthorization({
             ...params,
@@ -463,7 +465,7 @@ export default class AuthkitClientProvider {
     }
     register() {
         // Bound by class, like the first-party packages do, so `@inject()` works with
-        // `AuthkitClientManager` as a constructor type. The string key stays as an alias.
+        // `AuthkitClientManager` as a constructor type.
         this.app.container.singleton(AuthkitClientManager, async (resolver) => {
             const value = this.app.config.get('authkit_client');
             const config = (await configProvider.resolve(this.app, value));
@@ -473,7 +475,12 @@ export default class AuthkitClientProvider {
             const logger = await resolver.make('logger');
             return new AuthkitClientManager(config, { logger });
         });
-        this.app.container.alias('authkit.client', AuthkitClientManager);
+        // The string key resolves the class binding on every lookup — the same singleton — rather
+        // than being an `alias`: the container follows an alias before it checks bound values, so
+        // `bindValue('authkit.client', fake)`, how apps replaced the manager in tests before it was
+        // bound by class, would silently get the real one. Not cached here, so a `swap` of the class
+        // also reaches the string key, even after its first use.
+        this.app.container.bind('authkit.client', (resolver) => resolver.make(AuthkitClientManager));
     }
 }
 /** `sub` of a stored id_token, or undefined when there is none / it is unreadable. */

package/build/src/authorization.d.ts

@@ -115,6 +115,13 @@ export interface CompletedAuthorization {
     /** Validated id_token claims. */
     claims: IdTokenClaims;
 }
+/**
+ * The checks that say whether a callback belongs to this browser's pending authorization at all
+ * (`missing_pending`, `state_mismatch`). They need nothing from the IdP, so a caller that has to
+ * discover the IdP's endpoints first runs them before that: a stale or forged callback is
+ * restartable even while the IdP is unreachable, rather than surfacing as a discovery failure.
+ */
+export declare function assertCallbackBelongs(pending: PendingAuthorization | null | undefined, callbackParams: Record<string, unknown>): asserts pending is PendingAuthorization;
 /**
  * Finishes the authorization-code flow: checks `state` and `iss`, exchanges the
  * code (with the PKCE verifier) and validates the id_token, `nonce` included.

package/build/src/authorization.js

@@ -71,6 +71,21 @@ export class OidcCallbackError extends Error {
             this.code === 'missing_code');
     }
 }
+const str = (v) => (typeof v === 'string' && v ? v : undefined);
+/**
+ * The checks that say whether a callback belongs to this browser's pending authorization at all
+ * (`missing_pending`, `state_mismatch`). They need nothing from the IdP, so a caller that has to
+ * discover the IdP's endpoints first runs them before that: a stale or forged callback is
+ * restartable even while the IdP is unreachable, rather than surfacing as a discovery failure.
+ */
+export function assertCallbackBelongs(pending, callbackParams) {
+    if (!pending?.state || !pending.nonce || !pending.codeVerifier) {
+        throw new OidcCallbackError('missing_pending', 'No pending authorization for this callback');
+    }
+    if (str(callbackParams.state) !== pending.state) {
+        throw new OidcCallbackError('state_mismatch', 'Callback state does not match');
+    }
+}
 /**
  * Finishes the authorization-code flow: checks `state` and `iss`, exchanges the
  * code (with the PKCE verifier) and validates the id_token, `nonce` included.
@@ -80,15 +95,9 @@ export class OidcCallbackError extends Error {
  */
 export async function completeAuthorization(p) {
     const q = p.callbackParams;
-    const str = (v) => (typeof v === 'string' && v ? v : undefined);
-    const { issuer, tokenEndpoint, jwksUri } = p.endpoints ?? conventionEndpoints(p.issuer);
     const pending = p.pending;
-    if (!pending?.state || !pending.nonce || !pending.codeVerifier) {
-        throw new OidcCallbackError('missing_pending', 'No pending authorization for this callback');
-    }
-    if (str(q.state) !== pending.state) {
-        throw new OidcCallbackError('state_mismatch', 'Callback state does not match');
-    }
+    assertCallbackBelongs(pending, q);
+    const { issuer, tokenEndpoint, jwksUri } = p.endpoints ?? conventionEndpoints(p.issuer);
     const iss = str(q.iss);
     if (iss !== undefined && iss !== issuer) {
         throw new OidcCallbackError('issuer_mismatch', `Callback iss ${iss} is not ${issuer}`);

package/build/stubs/controllers/oidc_session_controller.stub

@@ -7,7 +7,7 @@ import { AuthkitClientManager, OidcCallbackError } from '@adonis-agora/authkit-c
 
 /**
  * Login, callback and logout written out by hand. If you do not need to customise
- * them, `registerOidcClient(router)` registers the same three routes for you.
+ * them, registerOidcClient(router) registers the same three routes for you.
  */
 @inject()
 export default class OidcSessionController {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-client",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "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",
@@ -83,7 +83,7 @@
     "jose": "6.2.12"
   },
   "devDependencies": {
-    "@adonis-agora/authkit-server": "0.80.1",
+    "@adonis-agora/authkit-server": "0.80.2",
     "@adonis-agora/resilience": "0.3.7",
     "@adonisjs/auth": "10.1.0",
     "@adonisjs/core": "7.5.0",

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

@@ -30,8 +30,9 @@ sources:
 `@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.
+publishes `config/authkit_client.ts` and registers the provider + middleware; the
+login/callback/logout routes come from `registerOidcClient(router)`. (`configure` also
+publishes an `OidcSessionController` stub, only for apps that must customise the flow.)
 
 ## Setup
 
@@ -58,13 +59,17 @@ export default authkitClientConfig
 ```ts
 // start/routes.ts
 import router from '@adonisjs/core/services/router'
-import OidcSessionController from '#controllers/oidc_session_controller'
+import { registerOidcClient } from '@adonis-agora/authkit-client'
 
-router.get('/auth/login', [OidcSessionController, 'login'])
-router.get('/auth/callback', [OidcSessionController, 'callback'])
-router.post('/auth/logout', [OidcSessionController, 'logout'])
+// /auth/login, /auth/callback, /auth/logout and /auth/backchannel-logout
+registerOidcClient(router)
 ```
 
+If you wire the scaffolded `OidcSessionController` instead, keep it on the manager:
+`startSession(ctx, tokenSet)` in the callback and `endSession(ctx)` in the logout —
+never a raw `session.put(sessionKey)` / `session.forget(sessionKey)`, which leaves a
+parked impersonation credential alive.
+
 Source: `packages/authkit-client/README.md`, `stubs/config/authkit_client.stub`.
 
 ## Core patterns

package/stubs/controllers/oidc_session_controller.stub

@@ -7,7 +7,7 @@ import { AuthkitClientManager, OidcCallbackError } from '@adonis-agora/authkit-c
 
 /**
  * Login, callback and logout written out by hand. If you do not need to customise
- * them, `registerOidcClient(router)` registers the same three routes for you.
+ * them, registerOidcClient(router) registers the same three routes for you.
  */
 @inject()
 export default class OidcSessionController {