@adonis-agora/authkit-server 1.0.0-rc.12 → 1.0.0-rc.13

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @adonis-agora/authkit-server
 
+## 1.0.0-rc.13
+
+### Patch Changes
+
+- [#475](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/475) [`2ebb953`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/2ebb953d1d96eb128febc7cc0c3e6f55a6000cc2) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `agora:doctor`'s `authkit.shield` check now reads the app's `config/shield.ts` and only warns when shield's CSRF check would really reject one of authkit's server-to-server POST endpoints (`{mountPath}/token`, `/token/introspection`, `/token/revocation`, `/authkit/pat/introspect`, and the personal-agent OAuth endpoints when enabled). It mirrors shield: CSRF off or a `methods` list without POST passes, an empty `methods` checks every method, and `exceptRoutes` may be a function (probed with a token-less POST) or a route-pattern array. `authkitCsrfExceptions` now matches the pathname anchored (`/oidc` or `/oidc/...`) instead of a substring, so `/admin/oidc/x`, `/oidc-clients` or `?next=/oidc` are no longer exempted.
+
 ## 1.0.0-rc.12
 
 ### Minor Changes

package/build/src/doctor/checks.d.ts

@@ -27,6 +27,11 @@ export interface DoctorInput {
      * Provided by the doctor command; undefined = not checked (doctor runs old version).
      */
     settingsTablePresent?: boolean;
+    /**
+     * The app's `config('shield')` (only its `csrf` block is read). `null` = no shield config;
+     * `undefined` = not collected (the CSRF check then cannot tell, and says so).
+     */
+    shieldConfig?: Record<string, any> | null;
     /**
      * Classes de adapter para detecção de volatilidade (injetadas pelo doctor command
      * em runtime). Quando ausente, o check de volatilidade usa heurística conservadora.
@@ -71,7 +76,32 @@ export declare function checkAccountStore(input: DoctorInput): Finding[];
 export declare function checkAccountStoreColumns(input: DoctorInput): Finding[];
 /** session provider configurado + warn se cookie store com tokenSets grandes. */
 export declare function checkSession(input: DoctorInput): Finding[];
-/** Hint de exceções de CSRF do shield para o mountPath. */
+/** A POST endpoint authkit mounts that is called without a browser CSRF token. */
+export interface CsrfExemptEndpoint {
+    /** A concrete request path (what `ctx.request.url()` returns). */
+    path: string;
+    /** The route pattern shield compares against an `exceptRoutes` array (`ctx.route.pattern`). */
+    pattern: string;
+}
+/**
+ * The server-to-server POST endpoints authkit mounts, which shield's CSRF check must not reject:
+ * the OIDC provider's token, introspection and revocation endpoints (under the `${mountPath}/*`
+ * wildcard route), PAT introspection, and — with `personalAgents` on — the agents' OAuth
+ * endpoints plus every extension's `csrfExemptPaths`.
+ */
+export declare function authkitCsrfExemptEndpoints(authkitConfig: Record<string, any> | null): CsrfExemptEndpoint[];
+/**
+ * Whether shield's CSRF check (as configured in `config/shield.ts`) would reject a token-less POST
+ * to `endpoint`, mirroring `@adonisjs/shield`: CSRF off → no; a non-empty `methods` without POST →
+ * no (an empty or missing `methods` checks every method); `exceptRoutes` as a function → rejected
+ * unless it returns a truthy value for that request; as an array → rejected unless it holds the route
+ * pattern. `'unknown'` when the function throws on the probe context.
+ */
+export declare function csrfRejects(shieldConfig: Record<string, any> | null | undefined, endpoint: CsrfExemptEndpoint): boolean | 'unknown';
+/**
+ * `authkit.shield`: evaluates the app's real `config/shield.ts` against the server-to-server POST
+ * endpoints authkit mounts, and warns only about the ones shield would actually reject.
+ */
 export declare function checkShield(input: DoctorInput): Finding;
 /** ally só é necessário quando social está configurado. */
 export declare function checkAlly(input: DoctorInput): Finding;

package/build/src/doctor/checks.js

@@ -238,7 +238,90 @@ export function checkSession(input) {
     }
     return findings;
 }
-/** Hint de exceções de CSRF do shield para o mountPath. */
+/**
+ * The server-to-server POST endpoints authkit mounts, which shield's CSRF check must not reject:
+ * the OIDC provider's token, introspection and revocation endpoints (under the `${mountPath}/*`
+ * wildcard route), PAT introspection, and — with `personalAgents` on — the agents' OAuth
+ * endpoints plus every extension's `csrfExemptPaths`.
+ */
+export function authkitCsrfExemptEndpoints(authkitConfig) {
+    const mount = String(authkitConfig?.mountPath ?? '/oidc').replace(/\/+$/, '') || '/oidc';
+    const endpoints = ['token', 'token/introspection', 'token/revocation'].map((rest) => ({ path: `${mount}/${rest}`, pattern: `${mount}/*` }));
+    endpoints.push({ path: '/authkit/pat/introspect', pattern: '/authkit/pat/introspect' });
+    const agents = authkitConfig?.personalAgents;
+    if (agents?.prefix) {
+        for (const rest of ['device_authorization', 'token']) {
+            const path = `${agents.prefix}/oauth/${rest}`;
+            endpoints.push({ path, pattern: path });
+        }
+        for (const extension of agents.extensions ?? []) {
+            for (const path of extension.csrfExemptPaths ?? [])
+                endpoints.push({ path, pattern: path });
+        }
+    }
+    return endpoints;
+}
+/** A minimal HttpContext for a token-less `POST path`, enough for an `exceptRoutes` function. */
+function csrfProbeContext(endpoint) {
+    const [pathname, query = ''] = endpoint.path.split('?');
+    const completeUrl = `http://localhost${endpoint.path}`;
+    const request = {
+        url: (includeQueryString) => includeQueryString && query ? `${pathname}?${query}` : pathname,
+        completeUrl: () => completeUrl,
+        method: () => 'POST',
+        intended: () => 'POST',
+        parsedUrl: { pathname, query, href: endpoint.path },
+        header: () => undefined,
+        headers: () => ({}),
+        hostname: () => 'localhost',
+        host: () => 'localhost',
+        protocol: () => 'http',
+        ip: () => '127.0.0.1',
+        input: () => undefined,
+        qs: () => ({}),
+        all: () => ({}),
+        matchesRoute: (identifier) => (Array.isArray(identifier) ? identifier : [identifier]).includes(endpoint.pattern),
+    };
+    return {
+        request,
+        route: { pattern: endpoint.pattern, methods: ['POST'] },
+        routeKey: `POST-${endpoint.pattern}`,
+    };
+}
+/**
+ * Whether shield's CSRF check (as configured in `config/shield.ts`) would reject a token-less POST
+ * to `endpoint`, mirroring `@adonisjs/shield`: CSRF off → no; a non-empty `methods` without POST →
+ * no (an empty or missing `methods` checks every method); `exceptRoutes` as a function → rejected
+ * unless it returns a truthy value for that request; as an array → rejected unless it holds the route
+ * pattern. `'unknown'` when the function throws on the probe context.
+ */
+export function csrfRejects(shieldConfig, endpoint) {
+    const csrf = shieldConfig?.csrf;
+    if (!csrf || csrf.enabled !== true)
+        return false;
+    const methods = Array.isArray(csrf.methods)
+        ? csrf.methods.map((m) => String(m).toLowerCase())
+        : [];
+    if (methods.length > 0 && !methods.includes('post'))
+        return false;
+    const except = csrf.exceptRoutes ?? [];
+    if (typeof except === 'function') {
+        try {
+            // Shield skips validation on any truthy return (`!this.#routesToIgnore(ctx)`).
+            return !except(csrfProbeContext(endpoint));
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    if (Array.isArray(except))
+        return !except.includes(endpoint.pattern);
+    return true;
+}
+/**
+ * `authkit.shield`: evaluates the app's real `config/shield.ts` against the server-to-server POST
+ * endpoints authkit mounts, and warns only about the ones shield would actually reject.
+ */
 export function checkShield(input) {
     if (!input.peers.shield) {
         return {
@@ -247,9 +330,41 @@ export function checkShield(input) {
         };
     }
     const mountPath = input.authkitConfig?.mountPath ?? '/oidc';
+    const helper = `authkitCsrfExceptions(ctx.request.url(), { mountPath: '${mountPath}' })`;
+    if (input.shieldConfig === undefined) {
+        return {
+            level: 'warn',
+            message: `config('shield') was not read, so the CSRF exemptions could not be checked. Make sure config/shield.ts's csrf.exceptRoutes exempts the IdP POST routes under "${mountPath}" (e.g. with ${helper}).`,
+        };
+    }
+    const endpoints = authkitCsrfExemptEndpoints(input.authkitConfig);
+    const rejected = [];
+    const unknown = [];
+    for (const endpoint of endpoints) {
+        const verdict = csrfRejects(input.shieldConfig, endpoint);
+        if (verdict === 'unknown')
+            unknown.push(endpoint.path);
+        else if (verdict)
+            rejected.push(endpoint.path);
+    }
+    if (rejected.length > 0) {
+        return {
+            level: 'warn',
+            message: `Shield's CSRF check rejects POST ${rejected.join(', ')} — server-to-server calls to these authkit endpoints fail. Exempt them in config/shield.ts's csrf.exceptRoutes, e.g. \`exceptRoutes: (ctx) => ${helper}\` (combine with your own exemptions using ||).`,
+        };
+    }
+    if (unknown.length > 0) {
+        return {
+            level: 'warn',
+            message: `csrf.exceptRoutes in config/shield.ts threw when probed with POST ${unknown.join(', ')}, so the doctor cannot tell whether they are exempt. Make sure it exempts them (e.g. with ${helper}).`,
+        };
+    }
+    const csrfOn = input.shieldConfig?.csrf?.enabled === true;
     return {
-        level: 'warn',
-        message: `Make sure the IdP POST routes under "${mountPath}" are in the shield CSRF exceptions (e.g. the /token endpoint), otherwise server-to-server calls fail. Use the exported authkitCsrfExceptions(url, { mountPath: '${mountPath}' }) helper in config/shield.ts's exceptRoutes instead of hand-writing the route-pattern check.`,
+        level: 'ok',
+        message: csrfOn
+            ? `shield's CSRF check exempts authkit's server-to-server POST endpoints (${endpoints.length} checked).`
+            : 'shield CSRF is off: authkit endpoints are not affected.',
     };
 }
 /** ally só é necessário quando social está configurado. */

package/build/src/doctor/doctor_input.js

@@ -47,9 +47,11 @@ export async function buildDoctorInput(app, logger) {
     // senão todo campo aparece como "ausente" (provider cru não tem issuer etc.).
     const authkitConfig = await resolveAuthkitConfig(app, config.get('authkit', null));
     const sessionConfig = config.get('session', null) ?? null;
+    const shieldConfig = config.get('shield', null) ?? null;
     return {
         authkitConfig,
         sessionConfig,
+        shieldConfig,
         peers: {
             session: await canImport('@adonisjs/session', logger),
             shield: await canImport('@adonisjs/shield', logger),

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

@@ -20,5 +20,8 @@ export interface AuthkitCsrfOptions {
  * Retorna `true` quando `url` é uma rota AuthKit que deve ser ISENTA de CSRF
  * (machine-to-machine). Cobre o mountPath do IdP, a introspecção de PAT e a
  * rota de back-channel logout do client e os endpoints OAuth de personal agents.
+ *
+ * O match é ANCORADO no pathname: `/oidc` e `/oidc/...` casam, mas `/foo/oidc/x`,
+ * `/oidc-admin` ou `/x?next=/oidc` não. A query string é ignorada.
  */
 export declare function authkitCsrfExceptions(url: string, options?: AuthkitCsrfOptions): boolean;

package/build/src/host/csrf.js

@@ -11,19 +11,39 @@
  * csrf: {
  *   enabled: true,
  *   exceptRoutes: (ctx) => authkitCsrfExceptions(ctx.request.url(), { mountPath: '/oidc' })
- *     || ctx.request.url().includes('/api'),
+ *     || ctx.request.url().startsWith('/api/'),
  * }
  * ```
  */
 import { normalizePersonalAgentsPrefix } from '../agents/config.js';
 import { getAuthHostConfig } from './auth_host_config.js';
+/** `path` é `prefix` ou fica debaixo dele (`prefix/...`) — nunca um substring solto. */
+function underPrefix(path, prefix) {
+    return path === prefix || path.startsWith(`${prefix}/`);
+}
+/** O pathname de `url`: sem query/hash, aceitando também uma URL absoluta. */
+function pathnameOf(url) {
+    let path = url;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path)) {
+        try {
+            path = new URL(path).pathname;
+        }
+        catch {
+            // Segue com a string crua: o match ancorado abaixo simplesmente não casa.
+        }
+    }
+    return path.split(/[?#]/, 1)[0] ?? '';
+}
 /**
  * Retorna `true` quando `url` é uma rota AuthKit que deve ser ISENTA de CSRF
  * (machine-to-machine). Cobre o mountPath do IdP, a introspecção de PAT e a
  * rota de back-channel logout do client e os endpoints OAuth de personal agents.
+ *
+ * O match é ANCORADO no pathname: `/oidc` e `/oidc/...` casam, mas `/foo/oidc/x`,
+ * `/oidc-admin` ou `/x?next=/oidc` não. A query string é ignorada.
  */
 export function authkitCsrfExceptions(url, options = {}) {
-    const mountPath = options.mountPath ?? '/oidc';
+    const mountPath = (options.mountPath ?? '/oidc').replace(/\/+$/, '');
     const backchannel = options.backchannelLogoutPath === false
         ? null
         : (options.backchannelLogoutPath ?? '/auth/backchannel-logout');
@@ -33,12 +53,12 @@ export function authkitCsrfExceptions(url, options = {}) {
             ? normalizePersonalAgentsPrefix(options.personalAgentsPrefix)
             : getAuthHostConfig()?.personalAgents?.prefix;
     const agentsOAuth = agentsPrefix ? `${agentsPrefix}/oauth/` : null;
-    const path = url.split('?')[0];
+    const path = pathnameOf(url);
     const extensionExempt = options.personalAgentExtensions !== false &&
         (getAuthHostConfig()?.personalAgents?.extensions ?? []).some((e) => e.csrfExemptPaths?.includes(path));
-    return (url.includes(mountPath) ||
-        url.includes('/authkit/pat') ||
-        (backchannel !== null && url === backchannel) ||
-        (agentsOAuth !== null && url.startsWith(agentsOAuth)) ||
+    return ((mountPath !== '' && underPrefix(path, mountPath)) ||
+        underPrefix(path, '/authkit/pat') ||
+        (backchannel !== null && path === backchannel) ||
+        (agentsOAuth !== null && path.startsWith(agentsOAuth)) ||
         extensionExempt);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-server",
-  "version": "1.0.0-rc.12",
+  "version": "1.0.0-rc.13",
   "description": "AdonisJS OIDC/OAuth2 provider (Identity Provider) toolkit: ejectable auth server with sessions, rate-limiting, MFA/TOTP, audit log, federated logout and OpenTelemetry metrics.",
   "license": "MIT",
   "author": "dudousxd",