@adonis-agora/authkit-client 1.0.0-rc.0 → 1.0.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @adonis-agora/authkit-client
 
+## 1.0.0-rc.1
+
+### Major Changes
+
+- [#451](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/451) [`1162aee`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/1162aeeee00d4706b8515d89e37f93d172cec44a) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `authkitDashboardMiddleware` is removed: every `@adonis-agora` console takes `authorize` now, so use `authkitDashboardAuthorize()` in its place. `authkitDashboardAuthorize` tells the two denials apart: a visitor without a session gets `401` (`{ allowed: false, reason: 'unauthenticated' }`) instead of `403`, and with the new `loginPath` option is sent to the app's login (`{ redirectTo }`). Signed in without the role is still `403`.
+
 ## 1.0.0-rc.0
 
 ### Major Changes

package/build/index.d.ts

@@ -15,8 +15,8 @@ export type { CreateDpopProofInput, DpopKeyPair } from './src/dpop.js';
 export { createDpopProof, dpopJwkThumbprint, generateDpopKeyPair, } from './src/dpop.js';
 export type { IdentityUserProviderContract } from './src/host/authkit_client_guard.js';
 export { AuthkitClientGuard, authkitClientGuard, authkitIdentityProvider, } from './src/host/authkit_client_guard.js';
-export type { DashboardGuardOptions } from './src/host/dashboard_guard.js';
-export { authkitDashboardAuthorize, authkitDashboardMiddleware, isAuthkitAdmin, } from './src/host/dashboard_guard.js';
+export type { DashboardGuardOptions, DashboardGuardResult } from './src/host/dashboard_guard.js';
+export { authkitDashboardAuthorize, isAuthkitAdmin, } from './src/host/dashboard_guard.js';
 export type { AuthkitUser, AuthkitUserType } from './src/host/request_authenticator.js';
 export { getAuthkit } from './src/host/request_authenticator.js';
 export type { ResiliencePolicy } from './src/http/resilient_fetch.js';

package/build/index.js

@@ -7,7 +7,7 @@ export { defineConfig, resolvers } from './src/define_config.js';
 export { conventionEndpoints, discoverEndpoints, OidcDiscoveryError } from './src/discovery.js';
 export { createDpopProof, dpopJwkThumbprint, generateDpopKeyPair, } from './src/dpop.js';
 export { AuthkitClientGuard, authkitClientGuard, authkitIdentityProvider, } from './src/host/authkit_client_guard.js';
-export { authkitDashboardAuthorize, authkitDashboardMiddleware, isAuthkitAdmin, } from './src/host/dashboard_guard.js';
+export { authkitDashboardAuthorize, isAuthkitAdmin, } from './src/host/dashboard_guard.js';
 export { getAuthkit } from './src/host/request_authenticator.js';
 export { resilientFetch } from './src/http/resilient_fetch.js';
 export { InvalidIdTokenError, validateIdToken } from './src/id_token.js';

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

@@ -2,22 +2,35 @@ import type { HttpContext } from '@adonisjs/core/http';
 export interface DashboardGuardOptions {
     /** Global role required to pass the gate. Default `'ADMIN'`. */
     role?: string;
+    /**
+     * The app's login page. When set, a visitor without a session is sent there (a page navigation
+     * gets a `302`, an API call a `401` carrying `redirectTo`) instead of a plain `401`.
+     */
+    loginPath?: string;
 }
+/** What {@link authkitDashboardAuthorize} answers: the shared console `authorize` result. */
+export type DashboardGuardResult = boolean | {
+    allowed: false;
+    reason: 'unauthenticated';
+} | {
+    redirectTo: string;
+};
 /**
- * Core predicate behind {@link authkitDashboardAuthorize} and
- * {@link authkitDashboardMiddleware}: authenticated (a resolvable authkit `Identity`) AND holding
- * the configured global role — `ctx.authkit.hasGlobalRole('ADMIN')`, the pattern hosts already
- * hand-roll per embedded admin dashboard (durable/media/agent/telescope).
+ * Core predicate behind {@link authkitDashboardAuthorize}: authenticated (a resolvable authkit
+ * `Identity`) AND holding the configured global role.
  *
- * Resolves the session via {@link getAuthkit}, which memoizes on `ctx.authkit`, so a second call
- * in the same request is free.
+ * Resolves the session via {@link getAuthkit} rather than reading `ctx.auth` directly: `ctx.auth`'s
+ * TYPE is host-owned, so this module can't assume its shape. `getAuthkit` works with both
+ * `authkit_middleware`'s `ctx.auth` and `authkitClientGuard`'s `ctx.authkit`, memoized per request.
  */
 export declare function isAuthkitAdmin(ctx: HttpContext, options?: DashboardGuardOptions): Promise<boolean>;
 /**
- * Adapter for the `authorize: (ctx) => boolean` shape that `@adonis-agora/durable`,
- * `@adonis-agora/agent` and `@adonis-agora/telescope` dashboard configs expect. A `false` return
- * makes the provider reply `403 { error: 'forbidden' }` — the provider's own behavior, unchanged
- * here.
+ * An `authorize` for any `@adonis-agora` console (durable, telescope, media, payments, agent):
+ * signed in to authkit AND holding the global role (`ADMIN` by default).
+ *
+ * - no session → `401` (or the `loginPath` redirect when set);
+ * - signed in without the role → `403`;
+ * - otherwise allowed.
  *
  * ```ts
  * // config/durable_dashboard.ts
@@ -25,24 +38,8 @@ export declare function isAuthkitAdmin(ctx: HttpContext, options?: DashboardGuar
  * import { authkitDashboardAuthorize } from '@adonis-agora/authkit-client'
  *
  * export default defineConfig({
- *   authorize: authkitDashboardAuthorize(),
- * })
- * ```
- */
-export declare function authkitDashboardAuthorize(options?: DashboardGuardOptions): (ctx: HttpContext) => Promise<boolean>;
-/**
- * Adapter for the `middleware: (ctx, next) => Promise<void>` shape that
- * `@adonis-agora/media`'s dashboard config expects. Mirrors the hand-rolled `requireAdmin` apps
- * wrote themselves: no session -> `401`; session without the role -> `403`; otherwise `next()`.
- *
- * ```ts
- * // config/media_dashboard.ts
- * import { defineConfig } from '@adonis-agora/media/dashboard'
- * import { authkitDashboardMiddleware } from '@adonis-agora/authkit-client'
- *
- * export default defineConfig({
- *   middleware: authkitDashboardMiddleware(),
+ *   authorize: authkitDashboardAuthorize({ loginPath: '/login' }),
  * })
  * ```
  */
-export declare function authkitDashboardMiddleware(options?: DashboardGuardOptions): (ctx: HttpContext, next: () => Promise<void>) => Promise<void>;
+export declare function authkitDashboardAuthorize(options?: DashboardGuardOptions): (ctx: HttpContext) => Promise<DashboardGuardResult>;

package/build/src/host/dashboard_guard.js

@@ -4,13 +4,12 @@ import { getAuthkit } from './request_authenticator.js';
  *  impersonation/token-exchange) — same convention, not a new one. */
 const DEFAULT_ADMIN_ROLE = 'ADMIN';
 /**
- * Core predicate behind {@link authkitDashboardAuthorize} and
- * {@link authkitDashboardMiddleware}: authenticated (a resolvable authkit `Identity`) AND holding
- * the configured global role — `ctx.authkit.hasGlobalRole('ADMIN')`, the pattern hosts already
- * hand-roll per embedded admin dashboard (durable/media/agent/telescope).
+ * Core predicate behind {@link authkitDashboardAuthorize}: authenticated (a resolvable authkit
+ * `Identity`) AND holding the configured global role.
  *
- * Resolves the session via {@link getAuthkit}, which memoizes on `ctx.authkit`, so a second call
- * in the same request is free.
+ * Resolves the session via {@link getAuthkit} rather than reading `ctx.auth` directly: `ctx.auth`'s
+ * TYPE is host-owned, so this module can't assume its shape. `getAuthkit` works with both
+ * `authkit_middleware`'s `ctx.auth` and `authkitClientGuard`'s `ctx.authkit`, memoized per request.
  */
 export async function isAuthkitAdmin(ctx, options = {}) {
     const authkit = await getAuthkit(ctx);
@@ -19,10 +18,12 @@ export async function isAuthkitAdmin(ctx, options = {}) {
     return authkit.hasGlobalRole(options.role ?? DEFAULT_ADMIN_ROLE);
 }
 /**
- * Adapter for the `authorize: (ctx) => boolean` shape that `@adonis-agora/durable`,
- * `@adonis-agora/agent` and `@adonis-agora/telescope` dashboard configs expect. A `false` return
- * makes the provider reply `403 { error: 'forbidden' }` — the provider's own behavior, unchanged
- * here.
+ * An `authorize` for any `@adonis-agora` console (durable, telescope, media, payments, agent):
+ * signed in to authkit AND holding the global role (`ADMIN` by default).
+ *
+ * - no session → `401` (or the `loginPath` redirect when set);
+ * - signed in without the role → `403`;
+ * - otherwise allowed.
  *
  * ```ts
  * // config/durable_dashboard.ts
@@ -30,39 +31,18 @@ export async function isAuthkitAdmin(ctx, options = {}) {
  * import { authkitDashboardAuthorize } from '@adonis-agora/authkit-client'
  *
  * export default defineConfig({
- *   authorize: authkitDashboardAuthorize(),
+ *   authorize: authkitDashboardAuthorize({ loginPath: '/login' }),
  * })
  * ```
  */
 export function authkitDashboardAuthorize(options = {}) {
-    return (ctx) => isAuthkitAdmin(ctx, options);
-}
-/**
- * Adapter for the `middleware: (ctx, next) => Promise<void>` shape that
- * `@adonis-agora/media`'s dashboard config expects. Mirrors the hand-rolled `requireAdmin` apps
- * wrote themselves: no session -> `401`; session without the role -> `403`; otherwise `next()`.
- *
- * ```ts
- * // config/media_dashboard.ts
- * import { defineConfig } from '@adonis-agora/media/dashboard'
- * import { authkitDashboardMiddleware } from '@adonis-agora/authkit-client'
- *
- * export default defineConfig({
- *   middleware: authkitDashboardMiddleware(),
- * })
- * ```
- */
-export function authkitDashboardMiddleware(options = {}) {
-    return async (ctx, next) => {
+    return async (ctx) => {
         const authkit = await getAuthkit(ctx);
         if (!(await authkit.check())) {
-            ctx.response.unauthorized({ message: 'Authentication required' });
-            return;
-        }
-        if (!authkit.hasGlobalRole(options.role ?? DEFAULT_ADMIN_ROLE)) {
-            ctx.response.forbidden({ message: 'Admin access required' });
-            return;
+            return options.loginPath
+                ? { redirectTo: options.loginPath }
+                : { allowed: false, reason: 'unauthenticated' };
         }
-        await next();
+        return authkit.hasGlobalRole(options.role ?? DEFAULT_ADMIN_ROLE);
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-client",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.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",
@@ -81,7 +81,7 @@
     "jose": "6.2.15"
   },
   "devDependencies": {
-    "@adonis-agora/authkit-server": "1.0.0-rc.0",
+    "@adonis-agora/authkit-server": "1.0.0-rc.1",
     "@adonis-agora/resilience": "0.4.3",
     "@adonisjs/auth": "10.1.0",
     "@adonisjs/core": "7.6.0",
@@ -92,7 +92,7 @@
     "@japa/runner": "5.4.0",
     "@poppinss/ts-exec": "1.5.2",
     "@tanstack/intent": "0.5.6",
-    "@types/node": "26.6.5",
+    "@types/node": "26.6.6",
     "ioredis-mock": "8.13.1",
     "tempura": "0.4.1",
     "testcontainers": "12.2.1",