@strapi-community/plugin-better-auth-dashboard 1.0.0 → 1.1.1

package/dist/server/index.mjs

@@ -1,4 +1,4 @@
-import { errors } from "@strapi/utils";
+import { errors, z } from "@strapi/utils";
 const strapi$1 = { "name": "better-auth-dashboard" };
 const packageJson = {
   strapi: strapi$1
@@ -35,8 +35,14 @@ const bootstrap = async ({ strapi: strapi2 }) => {
   }
 };
 const config = {
-  default: {},
+  default: { mcp: { enabled: false }, dashApi: { enabled: false } },
   validator(config2) {
+    if (config2.mcp !== void 0 && config2.mcp.enabled !== void 0 && typeof config2.mcp.enabled !== "boolean") {
+      throw new Error("mcp.enabled must be a boolean");
+    }
+    if (config2.dashApi !== void 0 && config2.dashApi.enabled !== void 0 && typeof config2.dashApi.enabled !== "boolean") {
+      throw new Error("dashApi.enabled must be a boolean");
+    }
     if (config2.email_callback_url === void 0) return;
     if (typeof config2.email_callback_url !== "string" || config2.email_callback_url.length === 0) {
       throw new Error("email_callback_url must be a non-empty string");
@@ -50,60 +56,83 @@ const config = {
 };
 const DASHBOARD_API_KEY = process.env.BETTER_AUTH_DASHBOARD_SECRET || "strapi-internal-dashboard-key";
 const DASH_CONTEXT_HEADER = "x-dash-context";
+function decodeDashContextHeader(value) {
+  if (typeof value !== "string" || value.length === 0) return {};
+  try {
+    const parsed = JSON.parse(Buffer.from(value, "base64").toString("utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+  }
+  return {};
+}
 async function hashApiKey(value) {
   const data = new TextEncoder().encode(value);
   const buf = await crypto.subtle.digest("SHA-256", data);
   return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
-const proxyController = () => ({
-  async handleAuthRequest(ctx) {
-    const auth = strapi.service("plugin::better-auth.auth-service").getAuth();
-    if (!auth)
-      throw new errors.ApplicationError("No Better Auth config file found");
-    if (!auth.api.signJWT) {
-      throw new errors.ApplicationError(
-        "[@strapi-community/plugin-better-auth-dashboard] The better-auth JWT plugin is required. Add jwt() from 'better-auth/plugins' to your better-auth configuration."
-      );
+async function signDashToken(auth, extra = {}) {
+  const { token } = await auth.api.signJWT({
+    body: {
+      payload: {
+        iat: Math.floor(Date.now() / 1e3),
+        apiKeyHash: await hashApiKey(DASHBOARD_API_KEY),
+        ...extra
+      },
+      overrideOptions: { jwt: { expirationTime: "5m" } }
     }
-    const contextHeader = ctx.request.headers[DASH_CONTEXT_HEADER];
-    let extra = {};
-    if (typeof contextHeader === "string" && contextHeader.length > 0) {
-      try {
-        const decoded = Buffer.from(contextHeader, "base64").toString("utf8");
-        const parsed = JSON.parse(decoded);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-          extra = parsed;
-        }
-      } catch {
-      }
+  });
+  return token;
+}
+function getAuth(strapi2) {
+  const auth = strapi2.service("plugin::better-auth.auth-service").getAuth();
+  if (!auth) {
+    throw new Error("No Better Auth configuration was found.");
+  }
+  if (!auth.api?.signJWT) {
+    throw new Error(
+      "The Better Auth jwt() plugin is required for dashboard/MCP features. Add jwt() from 'better-auth/plugins' to your Better Auth configuration."
+    );
+  }
+  return auth;
+}
+async function getDashApi(strapi2, context = {}) {
+  const auth = getAuth(strapi2);
+  const token = await signDashToken(auth, context);
+  return { auth, headers: new Headers({ Authorization: `Bearer ${token}` }) };
+}
+const dashController = () => ({
+  async handleDashRequest(ctx) {
+    const path = ctx.params.path;
+    if (!path) {
+      throw new errors.ValidationError("Missing dash endpoint path.");
     }
-    const apiKeyHash = await hashApiKey(DASHBOARD_API_KEY);
-    const { token } = await auth.api.signJWT({
-      body: {
-        payload: { iat: Math.floor(Date.now() / 1e3), apiKeyHash, ...extra },
-        overrideOptions: { jwt: { expirationTime: "5m" } }
-      }
-    });
+    const auth = getAuth(strapi);
+    const token = await signDashToken(
+      auth,
+      decodeDashContextHeader(ctx.request.headers[DASH_CONTEXT_HEADER])
+    );
     const url = new URL(
       ctx.request.url,
       `${ctx.request.protocol}://${ctx.request.host}`
     );
-    const betterAuthPath = ctx.params.path || "";
-    url.pathname = `/api/auth/${betterAuthPath}`;
+    url.pathname = `/api/auth/dash/${path}`;
     const headers = new Headers();
-    Object.entries(ctx.request.headers).forEach(([key, value]) => {
+    for (const [key, value] of Object.entries(ctx.request.headers)) {
       if (value) {
         headers.set(key, Array.isArray(value) ? value[0] : String(value));
       }
-    });
+    }
     headers.set("Authorization", `Bearer ${token}`);
     const hasBody = ctx.request.method !== "GET" && ctx.request.method !== "HEAD";
-    const request = new Request(url.toString(), {
-      method: ctx.request.method,
-      headers,
-      body: hasBody ? JSON.stringify(ctx.request.body) : void 0
-    });
-    const response = await auth.handler(request);
+    const response = await auth.handler(
+      new Request(url.toString(), {
+        method: ctx.request.method,
+        headers,
+        body: hasBody ? JSON.stringify(ctx.request.body) : void 0
+      })
+    );
     ctx.status = response.status;
     response.headers.forEach((value, key) => {
       ctx.set(key, value);
@@ -204,7 +233,7 @@ const settingsController = () => ({
   }
 });
 const controllers = {
-  "auth-controller": proxyController,
+  "dash-controller": dashController,
   "db-controller": dbController,
   "settings-controller": settingsController
 };
@@ -342,6 +371,383 @@ const ACTIONS = {
     }
   ]
 };
+const USER_UID = "plugin::better-auth.user";
+const ACTION = {
+  OVERVIEW_READ: `plugin::${PLUGIN_ID}.overview.read`,
+  USER_READ: `plugin::${PLUGIN_ID}.user.read`,
+  USER_UPDATE: `plugin::${PLUGIN_ID}.user.update`
+};
+function getMcp(strapi2) {
+  return strapi2.ai?.mcp;
+}
+function userHasAttribute(strapi2, uid, attribute) {
+  const map = strapi2.contentTypes;
+  return Boolean(map[uid]?.attributes && attribute in map[uid].attributes);
+}
+function toolResult(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    structuredContent: payload
+  };
+}
+function toolError(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+function dashErrorMessage(e) {
+  if (e && typeof e === "object") {
+    const anyE = e;
+    if (anyE.body?.message) return String(anyE.body.message);
+    if (anyE.message) return String(anyE.message);
+  }
+  return String(e);
+}
+function isNotFoundError(e) {
+  const anyE = e;
+  return anyE?.statusCode === 404 || anyE?.status === "NOT_FOUND";
+}
+const dashUserOutput = z.object({
+  id: z.union([z.string(), z.number()]),
+  name: z.string().nullable().optional(),
+  email: z.string().nullable().optional(),
+  emailVerified: z.boolean().nullable().optional(),
+  image: z.string().nullable().optional(),
+  role: z.string().nullable().optional(),
+  banned: z.boolean().nullable().optional(),
+  banReason: z.string().nullable().optional(),
+  banExpires: z.union([z.string(), z.number()]).nullable().optional(),
+  createdAt: z.union([z.string(), z.number()]).nullable().optional(),
+  updatedAt: z.union([z.string(), z.number()]).nullable().optional()
+});
+function normalizeDashDate(value) {
+  if (value == null) return null;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" || typeof value === "number") return value;
+  const maybe = value;
+  if (typeof maybe.toISOString === "function") return maybe.toISOString();
+  return String(value);
+}
+function mapDashUser(u) {
+  return {
+    id: u.id,
+    name: u.name ?? null,
+    email: u.email ?? null,
+    emailVerified: u.emailVerified ?? null,
+    image: u.image ?? null,
+    role: u.role ?? null,
+    banned: u.banned ?? null,
+    banReason: u.banReason ?? null,
+    banExpires: normalizeDashDate(u.banExpires),
+    createdAt: normalizeDashDate(u.createdAt),
+    updatedAt: normalizeDashDate(u.updatedAt)
+  };
+}
+function registerBanTools(mcp) {
+  mcp.registerTool({
+    name: "better_auth_ban_user",
+    title: "Ban a Better Auth user",
+    description: "Ban (block) a Better Auth user by id, through the Better Auth dashboard API. Optionally set a reason and an expiry in days; Better Auth revokes the user's sessions.",
+    auth: { policies: [{ action: ACTION.USER_UPDATE }] },
+    resolveInputSchema: () => z.object({
+      userId: z.string().describe("The Better Auth user id"),
+      banReason: z.string().optional(),
+      banExpiresInDays: z.number().positive().optional().describe(
+        "Days from now until the ban expires; omit for a permanent ban"
+      )
+    }),
+    resolveOutputSchema: () => z.object({ banned: z.boolean() }),
+    createHandler: (strapi2) => async ({ args }) => {
+      const body = {};
+      if (args.banReason) body.banReason = args.banReason;
+      if (args.banExpiresInDays) {
+        body.banExpires = Date.now() + args.banExpiresInDays * 864e5;
+      }
+      try {
+        const { auth, headers } = await getDashApi(strapi2, {
+          userId: args.userId
+        });
+        await auth.api.dashBanUser({ body, headers });
+        return toolResult({ banned: true });
+      } catch (e) {
+        return toolError(`Failed to ban user: ${dashErrorMessage(e)}`);
+      }
+    }
+  });
+  mcp.registerTool({
+    name: "better_auth_unban_user",
+    title: "Unban a Better Auth user",
+    description: "Lift the ban on a Better Auth user by id, through the Better Auth dashboard API.",
+    auth: { policies: [{ action: ACTION.USER_UPDATE }] },
+    resolveInputSchema: () => z.object({ userId: z.string().describe("The Better Auth user id") }),
+    resolveOutputSchema: () => z.object({ unbanned: z.boolean() }),
+    createHandler: (strapi2) => async ({ args }) => {
+      try {
+        const { auth, headers } = await getDashApi(strapi2, {
+          userId: args.userId
+        });
+        await auth.api.dashUnbanUser({ headers });
+        return toolResult({ unbanned: true });
+      } catch (e) {
+        return toolError(`Failed to unban user: ${dashErrorMessage(e)}`);
+      }
+    }
+  });
+}
+function registerGetUser(mcp) {
+  mcp.registerTool({
+    name: "better_auth_get_user",
+    title: "Get a Better Auth user",
+    description: "Fetch a single Better Auth user by its Better Auth user id (use better_auth_list_users to find the id). Returns the user and its session/account counts.",
+    auth: { policies: [{ action: ACTION.USER_READ }] },
+    resolveInputSchema: () => z.object({
+      userId: z.string().describe("The Better Auth user id")
+    }),
+    resolveOutputSchema: () => z.object({
+      found: z.boolean(),
+      user: dashUserOutput.nullable(),
+      sessionsCount: z.number().optional(),
+      accountsCount: z.number().optional()
+    }),
+    createHandler: (strapi2) => async ({ args }) => {
+      try {
+        const { auth, headers } = await getDashApi(strapi2, {
+          userId: args.userId
+        });
+        const user = await auth.api.getDashUser({ query: {}, headers });
+        const raw = user;
+        return toolResult({
+          found: true,
+          user: mapDashUser(user),
+          sessionsCount: Array.isArray(raw.session) ? raw.session.length : void 0,
+          accountsCount: Array.isArray(raw.account) ? raw.account.length : void 0
+        });
+      } catch (e) {
+        if (isNotFoundError(e)) {
+          return toolResult({ found: false, user: null });
+        }
+        return toolError(`Failed to get user: ${dashErrorMessage(e)}`);
+      }
+    }
+  });
+}
+function registerListUsers(mcp) {
+  mcp.registerTool({
+    name: "better_auth_list_users",
+    title: "List Better Auth users",
+    description: "List and search Better Auth users (via the Better Auth dashboard API). `search` matches name or email, case-insensitively. Returns users plus the total count.",
+    auth: { policies: [{ action: ACTION.USER_READ }] },
+    resolveInputSchema: () => z.object({
+      search: z.string().optional().describe("Case-insensitive substring matched against name or email"),
+      limit: z.number().int().min(1).max(100).default(25),
+      offset: z.number().int().min(0).default(0)
+    }),
+    resolveOutputSchema: () => z.object({
+      total: z.number(),
+      count: z.number(),
+      onlineUsers: z.number().optional(),
+      users: z.array(dashUserOutput)
+    }),
+    createHandler: (strapi2) => async ({ args }) => {
+      const { search, limit, offset } = args;
+      const where = search ? JSON.stringify([
+        {
+          field: "email",
+          operator: "contains",
+          value: search,
+          connector: "OR"
+        },
+        {
+          field: "name",
+          operator: "contains",
+          value: search,
+          connector: "OR"
+        }
+      ]) : void 0;
+      try {
+        const { auth, headers } = await getDashApi(strapi2);
+        const result = await auth.api.getDashUsers({
+          query: {
+            limit,
+            offset,
+            sortBy: "createdAt",
+            sortOrder: "desc",
+            ...where ? { where } : {}
+          },
+          headers
+        });
+        const users = (result.users ?? []).map(
+          (u) => mapDashUser(u)
+        );
+        return toolResult({
+          total: result.total ?? users.length,
+          count: users.length,
+          onlineUsers: result.onlineUsers,
+          users
+        });
+      } catch (e) {
+        return toolError(`Failed to list users: ${dashErrorMessage(e)}`);
+      }
+    }
+  });
+}
+function registerSignupsGraph(mcp) {
+  mcp.registerTool({
+    name: "better_auth_signups_graph",
+    title: "Better Auth sign-ups over time",
+    description: "Return a time series of Better Auth user sign-ups (via the dashboard API), bucketed by day, week or month. Each point has newUsers, activeUsers and the running totalUsers.",
+    auth: { policies: [{ action: ACTION.OVERVIEW_READ }] },
+    resolveInputSchema: () => z.object({
+      period: z.enum(["daily", "weekly", "monthly"]).default("daily")
+    }),
+    resolveOutputSchema: () => z.object({
+      period: z.string(),
+      points: z.array(
+        z.object({
+          date: z.string(),
+          label: z.string(),
+          totalUsers: z.number(),
+          newUsers: z.number(),
+          activeUsers: z.number()
+        })
+      )
+    }),
+    createHandler: (strapi2) => async ({ args }) => {
+      try {
+        const { auth, headers } = await getDashApi(strapi2);
+        const graph = await auth.api.dashGetUserGraphData({
+          query: { period: args.period },
+          headers
+        });
+        return toolResult({
+          period: graph.period ?? args.period,
+          points: (graph.data ?? []).map((p) => ({
+            // dash() returns `date` as a JS Date; emit ISO (machine-readable)
+            // rather than the locale `String(Date)` form ("Tue Jun 16 2026 …").
+            date: String(normalizeDashDate(p.date) ?? ""),
+            label: String(p.label ?? ""),
+            totalUsers: Number(p.totalUsers ?? 0),
+            newUsers: Number(p.newUsers ?? 0),
+            activeUsers: Number(p.activeUsers ?? 0)
+          }))
+        });
+      } catch (e) {
+        return toolError(`Failed to load graph: ${dashErrorMessage(e)}`);
+      }
+    }
+  });
+}
+function registerUpdateUser(mcp) {
+  mcp.registerTool({
+    name: "better_auth_update_user",
+    title: "Update a Better Auth user",
+    description: "Update a Better Auth user's profile (name, email, image, emailVerified) by Better Auth user id, through the Better Auth dashboard API. Use the ban tools for ban state.",
+    auth: { policies: [{ action: ACTION.USER_UPDATE }] },
+    resolveInputSchema: () => z.object({
+      userId: z.string().describe("The Better Auth user id"),
+      name: z.string().optional(),
+      email: z.string().email().optional(),
+      image: z.string().optional(),
+      emailVerified: z.boolean().optional()
+    }),
+    resolveOutputSchema: () => z.object({
+      updated: z.boolean(),
+      user: dashUserOutput.nullable()
+    }),
+    createHandler: (strapi2) => async ({ args }) => {
+      const body = {};
+      if (args.name !== void 0) body.name = args.name;
+      if (args.email !== void 0) body.email = args.email;
+      if (args.image !== void 0) body.image = args.image;
+      if (args.emailVerified !== void 0)
+        body.emailVerified = args.emailVerified;
+      if (Object.keys(body).length === 0) {
+        return toolError("No fields to update were provided.");
+      }
+      try {
+        const { auth, headers } = await getDashApi(strapi2, {
+          userId: args.userId
+        });
+        const user = await auth.api.updateDashUser({ body, headers });
+        return toolResult({
+          updated: true,
+          user: mapDashUser(user)
+        });
+      } catch (e) {
+        return toolError(`Failed to update user: ${dashErrorMessage(e)}`);
+      }
+    }
+  });
+}
+const signupPeriod = z.object({
+  signUps: z.number().nullable(),
+  percentage: z.number().nullable()
+});
+const activePeriod = z.object({
+  active: z.number().nullable(),
+  percentage: z.number().nullable()
+});
+function registerUserStats(mcp) {
+  mcp.registerTool({
+    name: "better_auth_user_stats",
+    title: "Better Auth user statistics",
+    description: "Return Better Auth user statistics (via the dashboard API): total users, sign-ups in the last day/week/month with percentage change vs the previous period, and active users per period.",
+    auth: { policies: [{ action: ACTION.OVERVIEW_READ }] },
+    resolveOutputSchema: () => z.object({
+      total: z.number().nullable(),
+      daily: signupPeriod,
+      weekly: signupPeriod,
+      monthly: signupPeriod,
+      activeUsers: z.object({
+        daily: activePeriod,
+        weekly: activePeriod,
+        monthly: activePeriod
+      }),
+      degraded: z.boolean().optional()
+    }),
+    createHandler: (strapi2) => async () => {
+      try {
+        const { auth, headers } = await getDashApi(strapi2);
+        const stats = await auth.api.dashGetUserStats({ headers });
+        return toolResult(stats);
+      } catch (e) {
+        return toolError(`Failed to load stats: ${dashErrorMessage(e)}`);
+      }
+    }
+  });
+}
+function registerMcpTools(strapi2) {
+  const mcp = getMcp(strapi2);
+  if (!mcp) {
+    strapi2.log.warn(
+      "[@strapi-community/plugin-better-auth-dashboard] MCP integration is enabled but this Strapi version has no MCP server (requires >= 5.47). Skipping."
+    );
+    return;
+  }
+  registerListUsers(mcp);
+  registerGetUser(mcp);
+  registerUpdateUser(mcp);
+  registerUserStats(mcp);
+  registerSignupsGraph(mcp);
+  if (userHasAttribute(strapi2, USER_UID, "banned")) {
+    registerBanTools(mcp);
+  }
+  strapi2.log.info(
+    "[@strapi-community/plugin-better-auth-dashboard] Registered Better Auth MCP tools."
+  );
+}
+const HTTP_METHODS = ["GET", "POST"];
+const contentApiRoutes = {
+  type: "content-api",
+  routes: HTTP_METHODS.map((method) => ({
+    method,
+    path: "/better-auth-dashboard/dash/:path*",
+    handler: "dash-controller.handleDashRequest",
+    info: { pluginName: "better-auth-dashboard" },
+    config: {
+      policies: [],
+      prefix: ""
+    }
+  }))
+};
 const register = ({ strapi: strapi2 }) => {
   const actionsToRegister = [...ACTIONS.overview, ...ACTIONS.user];
   if (strapi2.plugin("better-auth").contentTypes?.organization)
@@ -349,14 +755,27 @@ const register = ({ strapi: strapi2 }) => {
   strapi2.admin.services.permission.actionProvider.registerMany(
     actionsToRegister
   );
+  const config2 = strapi2.config.get(`plugin::${PLUGIN_ID}`, {});
+  if (config2.dashApi?.enabled) {
+    strapi2.server.routes(contentApiRoutes);
+  }
+  if (config2.mcp?.enabled) {
+    try {
+      registerMcpTools(strapi2);
+    } catch (error) {
+      strapi2.log.warn(
+        `[@strapi-community/plugin-better-auth-dashboard] Failed to register MCP tools: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
 };
 const adminRoutes = () => ({
   type: "admin",
   routes: [
     {
       method: "GET",
-      path: "/auth/:path*",
-      handler: "auth-controller.handleAuthRequest",
+      path: "/auth/dash/:path*",
+      handler: "dash-controller.handleDashRequest",
       config: {
         policies: ["has-permission"],
         prefix: ""
@@ -364,8 +783,8 @@ const adminRoutes = () => ({
     },
     {
       method: "POST",
-      path: "/auth/:path*",
-      handler: "auth-controller.handleAuthRequest",
+      path: "/auth/dash/:path*",
+      handler: "dash-controller.handleDashRequest",
       config: {
         policies: ["has-permission"],
         prefix: ""
@@ -373,8 +792,8 @@ const adminRoutes = () => ({
     },
     {
       method: "PUT",
-      path: "/auth/:path*",
-      handler: "auth-controller.handleAuthRequest",
+      path: "/auth/dash/:path*",
+      handler: "dash-controller.handleDashRequest",
       config: {
         policies: ["has-permission"],
         prefix: ""
@@ -382,8 +801,8 @@ const adminRoutes = () => ({
     },
     {
       method: "PATCH",
-      path: "/auth/:path*",
-      handler: "auth-controller.handleAuthRequest",
+      path: "/auth/dash/:path*",
+      handler: "dash-controller.handleDashRequest",
       config: {
         policies: ["has-permission"],
         prefix: ""
@@ -391,8 +810,8 @@ const adminRoutes = () => ({
     },
     {
       method: "DELETE",
-      path: "/auth/:path*",
-      handler: "auth-controller.handleAuthRequest",
+      path: "/auth/dash/:path*",
+      handler: "dash-controller.handleDashRequest",
       config: {
         policies: ["has-permission"],
         prefix: ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strapi-community/plugin-better-auth-dashboard",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Better Auth dashboard for the Strapi admin panel",
   "keywords": [
     "strapi",
@@ -43,12 +43,17 @@
     "@playwright/test": "^1.49.0",
     "@strapi/sdk-plugin": "^6.0.0",
     "@strapi/strapi": "5.60.0",
+    "@strapi/types": "5.60.0",
     "@strapi/typescript-utils": "5.60.0",
+    "@strapi/utils": "5.60.0",
     "@types/koa": "^3.0.1",
     "@types/node": "^22",
     "@types/react": "^18.0.0",
     "@types/styled-components": "^5.1.36",
+    "@types/supertest": "^6.0.0",
+    "supertest": "^7.0.0",
     "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
     "@strapi-community/dev-utils": "0.0.1"
   },
   "peerDependencies": {
@@ -81,6 +86,7 @@
     "lint:ts:server": "cd server && tsc --noEmit",
     "lint:ts:admin": "cd admin && tsc --noEmit",
     "lint": "biome check --fix",
+    "test:integration": "vitest run",
     "test:e2e": "playwright test"
   }
 }