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

package/dist/server/index.js

@@ -37,8 +37,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");
@@ -52,60 +58,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 utils.errors.ApplicationError("No Better Auth config file found");
-    if (!auth.api.signJWT) {
-      throw new utils.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 utils.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);
@@ -206,7 +235,7 @@ const settingsController = () => ({
   }
 });
 const controllers = {
-  "auth-controller": proxyController,
+  "dash-controller": dashController,
   "db-controller": dbController,
   "settings-controller": settingsController
 };
@@ -344,6 +373,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 = utils.z.object({
+  id: utils.z.union([utils.z.string(), utils.z.number()]),
+  name: utils.z.string().nullable().optional(),
+  email: utils.z.string().nullable().optional(),
+  emailVerified: utils.z.boolean().nullable().optional(),
+  image: utils.z.string().nullable().optional(),
+  role: utils.z.string().nullable().optional(),
+  banned: utils.z.boolean().nullable().optional(),
+  banReason: utils.z.string().nullable().optional(),
+  banExpires: utils.z.union([utils.z.string(), utils.z.number()]).nullable().optional(),
+  createdAt: utils.z.union([utils.z.string(), utils.z.number()]).nullable().optional(),
+  updatedAt: utils.z.union([utils.z.string(), utils.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: () => utils.z.object({
+      userId: utils.z.string().describe("The Better Auth user id"),
+      banReason: utils.z.string().optional(),
+      banExpiresInDays: utils.z.number().positive().optional().describe(
+        "Days from now until the ban expires; omit for a permanent ban"
+      )
+    }),
+    resolveOutputSchema: () => utils.z.object({ banned: utils.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: () => utils.z.object({ userId: utils.z.string().describe("The Better Auth user id") }),
+    resolveOutputSchema: () => utils.z.object({ unbanned: utils.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: () => utils.z.object({
+      userId: utils.z.string().describe("The Better Auth user id")
+    }),
+    resolveOutputSchema: () => utils.z.object({
+      found: utils.z.boolean(),
+      user: dashUserOutput.nullable(),
+      sessionsCount: utils.z.number().optional(),
+      accountsCount: utils.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: () => utils.z.object({
+      search: utils.z.string().optional().describe("Case-insensitive substring matched against name or email"),
+      limit: utils.z.number().int().min(1).max(100).default(25),
+      offset: utils.z.number().int().min(0).default(0)
+    }),
+    resolveOutputSchema: () => utils.z.object({
+      total: utils.z.number(),
+      count: utils.z.number(),
+      onlineUsers: utils.z.number().optional(),
+      users: utils.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: () => utils.z.object({
+      period: utils.z.enum(["daily", "weekly", "monthly"]).default("daily")
+    }),
+    resolveOutputSchema: () => utils.z.object({
+      period: utils.z.string(),
+      points: utils.z.array(
+        utils.z.object({
+          date: utils.z.string(),
+          label: utils.z.string(),
+          totalUsers: utils.z.number(),
+          newUsers: utils.z.number(),
+          activeUsers: utils.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: () => utils.z.object({
+      userId: utils.z.string().describe("The Better Auth user id"),
+      name: utils.z.string().optional(),
+      email: utils.z.string().email().optional(),
+      image: utils.z.string().optional(),
+      emailVerified: utils.z.boolean().optional()
+    }),
+    resolveOutputSchema: () => utils.z.object({
+      updated: utils.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 = utils.z.object({
+  signUps: utils.z.number().nullable(),
+  percentage: utils.z.number().nullable()
+});
+const activePeriod = utils.z.object({
+  active: utils.z.number().nullable(),
+  percentage: utils.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: () => utils.z.object({
+      total: utils.z.number().nullable(),
+      daily: signupPeriod,
+      weekly: signupPeriod,
+      monthly: signupPeriod,
+      activeUsers: utils.z.object({
+        daily: activePeriod,
+        weekly: activePeriod,
+        monthly: activePeriod
+      }),
+      degraded: utils.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)
@@ -351,14 +757,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: ""
@@ -366,8 +785,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: ""
@@ -375,8 +794,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: ""
@@ -384,8 +803,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: ""
@@ -393,8 +812,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: ""