docusaurus-roles-plugin 1.0.0-beta.1

package/README.md

@@ -0,0 +1,249 @@
+# Docusaurus Roles Plugin
+
+Role-based access control (RBAC) for **Docusaurus docs and blogs**, using front matter and a runtime role provider.
+
+This plugin allows you to **conditionally hide or forbid access** to content (docs, blog posts, nav items, and sidebars) based on user roles that *you* define and resolve.
+
+> [!CAUTION]
+> This plugin **does not provide true security**. It operates at the **UI and routing layer only**.
+>
+> **You are responsible for protecting your content at the hosting / network level** (for example, via authentication, authorization rules, or server-side enforcement).
+>
+> Treat this plugin as a **presentation and UX layer**, not a security boundary.
+
+---
+
+## Features
+
+- 🔒 Restrict access to **individual docs and blog posts**
+- 🧭 Hide or filter **navbar items**
+- 📚 Restrict **doc and blog sidebars**
+- 🧩 Works with async role resolution (e.g. auth providers, APIs)
+- 🏷️ Role requirements defined directly in **front matter**
+
+---
+
+## Installation
+
+```bash
+npm install docusaurus-roles-plugin
+```
+
+---
+
+## Configuration
+
+### 1. Add the plugin to `docusaurus.config.ts`
+
+```ts
+// docusaurus.config.ts
+import { protectBlogSidebar, protectDocSidebar } from "docusaurus-roles-plugin";
+import type { Config } from "@docusaurus/types";
+import type * as Preset from "@docusaurus/preset-classic";
+
+const config: Config = {
+  presets: [
+    [
+      "classic",
+      {
+        docs: {
+          sidebarItemsGenerator: protectDocSidebar,
+        },
+        blog: {
+          processBlogPosts: protectBlogSidebar,
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  plugins: [
+    [
+      "docusaurus-roles-plugin",
+      {
+        // Defaults
+        unauthorizedBehavior: "forbidden"
+      } satisfies RolesPluginOptions,
+    ],
+  ],
+};
+
+export default config;
+```
+
+---
+
+### 2. Provide user roles at runtime
+
+Create or modify `/src/theme/Root.tsx` and wrap your site with the `RolesProvider`.
+
+```tsx
+import React from "react";
+import { RolesProvider } from "docusaurus-roles-plugin/runtime";
+
+export default function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <RolesProvider
+      roles={async () => {
+        // Retrieve roles for current user.
+        return ["admin", "editor"];
+      }}
+    >
+      {children}
+    </RolesProvider>
+  );
+}
+```
+
+---
+
+## Restricting Docs or Blog Posts
+
+```md
+---
+required_roles:
+  - admin
+  - editor
+required_roles_mode: all
+---
+```
+
+### Fields
+
+| Field               | Description                                 |
+| ------------------- | ------------------------------------------- |
+| required_roles      | Array of roles required to view the content |
+| required_roles_mode | "all" (default) or "any"                    |
+
+**Examples**
+
+* **all**: User must have *every* listed role
+* **any**: User must have *at least one* listed role
+
+## Restricting Navbar items
+
+```ts
+// docusaurus.config.ts
+const config: Config = {
+  // ...
+  themeConfig: {
+    // ...
+    navbar: {
+      items: [
+        {
+          type: "docSidebar",
+          sidebarId: "tutorialSidebar",
+          position: "left",
+          label: "Tutorial",
+          // NOTE: This is camel case not snake_case like FrontMatter to match conventions
+          requiredRoles: ["...", /* ... */],
+          requiredRolesMode: "any"
+        },
+        { to: "/blog", label: "Blog", position: "left" },
+        {
+          href: "https://github.com/facebook/docusaurus",
+          label: "GitHub",
+          position: "right",
+        },
+      ],
+    },
+  }
+}
+```
+
+---
+
+## Unauthorized Behavior
+
+You can control what happens when a user lacks required roles:
+
+```ts
+unauthorizedBehavior: "forbidden" | "redirect";
+redirectTo: "/404" | "...";
+```
+
+* **forrbidden** → Renders swizzlable (customizable) forbidden component.
+* **redirect** → Redirects the user to a custom route.
+
+---
+
+## Azure Static Web Apps (Example Use Case)
+
+*This is the primary environment this plugin was designed for.*
+
+### Why Azure Static Web Apps?
+
+Azure Static Web Apps provides built-in:
+
+* Authentication (Entra ID / Azure AD)
+* Authorization via role claims
+* Role exposure to the frontend
+
+Relevant documentation:
+
+* [https://learn.microsoft.com/en-us/azure/static-web-apps/authentication-authorization](https://learn.microsoft.com/en-us/azure/static-web-apps/authentication-authorization)
+* [https://learn.microsoft.com/en-us/azure/static-web-apps/user-information](https://learn.microsoft.com/en-us/azure/static-web-apps/user-information)
+
+---
+
+### Example `staticwebapp.config.json`
+
+```json
+{
+  "routes": [
+    {
+      "route": "/",
+      "allowedRoles": ["anonymous", "authenticated"]
+    }
+  ],
+  "responseOverrides": {
+    "401": {
+      "redirect": "/login",
+      "statusCode": 302
+    },
+    "403": {
+      "rewrite": "/unauthorized.html"
+    }
+  },
+  "auth": {
+    "identityProviders": {
+      "azureActiveDirectory": {
+        "registration": {
+          "openIdIssuer": "https://login.microsoftonline.com/***/v2.0",
+          "clientIdSettingName": "***",
+          "clientSecretSettingName": "***"
+        },
+        "login": {
+          "loginParameters": [
+            "scope=openid profile email"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+Your `RolesProvider` can map Azure-provided role claims directly into the plugin.
+
+---
+
+## Philosophy & Scope
+
+* This plugin is intentionally **opinionated**
+* It solves **content gating**, not authentication
+* It is designed to integrate with **existing auth systems**
+* No assumptions are made about identity providers
+
+If your needs differ, feel free to open an issue or fork.
+
+---
+
+## Contributing
+
+This plugin primarily serves my own use cases, but suggestions and improvements are welcome.
+
+* 🐛 Bug reports
+* 💡 Feature ideas
+* 🧩 Integration examples
+
+Please open an issue with context about your setup.

package/dist/index.cjs

@@ -0,0 +1,119 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  addDocSidebarCustomProps: () => addDocSidebarCustomProps,
+  default: () => pluginRoles,
+  protectBlogSidebar: () => protectBlogSidebar,
+  protectDocSidebar: () => protectDocSidebar,
+  setRolesByPermaLink: () => setRolesByPermaLink
+});
+module.exports = __toCommonJS(index_exports);
+var import_path = __toESM(require("path"), 1);
+
+// src/options.ts
+function getRoleFrontMatter(frontMatter) {
+  if (!frontMatter || typeof frontMatter !== "object") return {};
+  return frontMatter;
+}
+function getRoleRequirements(frontMatter) {
+  const roleFrontMatter = getRoleFrontMatter(frontMatter);
+  return {
+    requiredRoles: roleFrontMatter.required_roles ?? [],
+    requiredRolesMode: roleFrontMatter.required_roles_mode ?? "all"
+  };
+}
+
+// src/index.ts
+var addDocSidebarCustomProps = (docs) => {
+  var _a;
+  for (const doc of docs) {
+    const roles = doc.frontMatter.required_roles;
+    if (!roles) continue;
+    const props = (_a = doc.frontMatter).sidebar_custom_props ?? (_a.sidebar_custom_props = {});
+    props.required_roles = roles;
+    props.required_roles_mode = doc.frontMatter.required_roles_mode;
+  }
+};
+var protectDocSidebar = async ({
+  defaultSidebarItemsGenerator,
+  ...args
+}) => {
+  addDocSidebarCustomProps(args.docs);
+  return defaultSidebarItemsGenerator(args);
+};
+var rolesByPermalink = [];
+function createDeferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+var blogRolesReady = createDeferred();
+var setRolesByPermaLink = (blogPosts) => {
+  blogRolesReady = createDeferred();
+  rolesByPermalink = blogPosts.map((bp) => ({
+    permalink: bp.metadata.permalink,
+    ...getRoleRequirements(bp.metadata.frontMatter)
+  }));
+  blogRolesReady.resolve();
+};
+var protectBlogSidebar = async ({ blogPosts }) => {
+  setRolesByPermaLink(blogPosts);
+  return blogPosts;
+};
+function pluginRoles(_context, options) {
+  return {
+    name: "docusaurus-roles-plugin",
+    getThemePath() {
+      return import_path.default.resolve(__dirname, "../src/theme");
+    },
+    async contentLoaded({ actions }) {
+      await blogRolesReady.promise;
+      actions.setGlobalData({
+        rolesByPermalink,
+        unauthorizedBehavior: options.unauthorizedBehavior ?? "notFound",
+        redirectTo: options.redirectTo ?? "/access-denied"
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  addDocSidebarCustomProps,
+  protectBlogSidebar,
+  protectDocSidebar,
+  setRolesByPermaLink
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/options.ts"],"sourcesContent":["import path from \"path\";\nimport type { LoadContext, Plugin } from \"@docusaurus/types\";\nimport {\n  getRoleRequirements,\n  type RolesPluginOptions,\n  type RoleEntry,\n} from \"./options\";\nimport { BlogPost, ProcessBlogPostsFn } from \"@docusaurus/plugin-content-blog\";\nimport {\n  SidebarItemsGeneratorDoc,\n  SidebarItemsGeneratorOption,\n} from \"@docusaurus/plugin-content-docs/src/sidebars/types.js\";\n\nexport { RolesPluginOptions } from \"./options\";\n\n/**\n * Used to apply FrontMatter required_roles and required_roles_mode to\n * sidebar_custom_props.required_roles and sidebar_custom_props.required_roles_mode.\n *\n * Should use protectDocSidebar for simple use cases.\n *\n * @param docs - The docs to transform.\n */\nexport const addDocSidebarCustomProps = (docs: SidebarItemsGeneratorDoc[]) => {\n  for (const doc of docs) {\n    const roles = doc.frontMatter.required_roles;\n    if (!roles) continue;\n\n    const props = (doc.frontMatter.sidebar_custom_props ??= {});\n    props.required_roles = roles;\n    props.required_roles_mode = doc.frontMatter.required_roles_mode;\n  }\n};\n\n/**\n * Used to protect docs sidebar is a plug and play for sidebarItemsGenerator\n */\nexport const protectDocSidebar: SidebarItemsGeneratorOption = async ({\n  defaultSidebarItemsGenerator,\n  ...args\n}) => {\n  addDocSidebarCustomProps(args.docs);\n\n  return defaultSidebarItemsGenerator(args);\n};\n\nlet rolesByPermalink: RoleEntry[] = [];\n\nfunction createDeferred<T>() {\n  let resolve!: (value: T) => void;\n  let reject!: (reason?: unknown) => void;\n  const promise = new Promise<T>((res, rej) => {\n    resolve = res;\n    reject = rej;\n  });\n  return { promise, resolve, reject };\n}\n\nlet blogRolesReady = createDeferred<void>();\n\n/**\n * Used to set rolesByPermalink which is used by overriden BlogSidebar\n * to protect blog sidebar.\n */\nexport const setRolesByPermaLink = (blogPosts: BlogPost[]) => {\n  blogRolesReady = createDeferred<void>();\n\n  rolesByPermalink = blogPosts.map((bp) => ({\n    permalink: bp.metadata.permalink,\n    ...getRoleRequirements(bp.metadata.frontMatter),\n  }));\n\n  blogRolesReady.resolve();\n};\n\n/**\n * Used to protect blog sidebar is a plug and play for processBlogPosts.\n */\nexport const protectBlogSidebar: ProcessBlogPostsFn = async ({ blogPosts }) => {\n  setRolesByPermaLink(blogPosts);\n  return blogPosts;\n};\n\nexport default function pluginRoles(\n  _context: LoadContext,\n  options: RolesPluginOptions,\n): Plugin {\n  return {\n    name: \"docusaurus-roles-plugin\",\n\n    getThemePath() {\n      return path.resolve(__dirname, \"../src/theme\");\n    },\n\n    async contentLoaded({ actions }) {\n      await blogRolesReady.promise;\n\n      actions.setGlobalData({\n        rolesByPermalink,\n        unauthorizedBehavior: options.unauthorizedBehavior ?? \"notFound\",\n        redirectTo: options.redirectTo ?? \"/access-denied\",\n      });\n    },\n  };\n}\n","export type UnauthorizedBehavior = \"forbidden\" | \"redirect\";\n\nexport type RolesPluginOptions = {\n  unauthorizedBehavior?: UnauthorizedBehavior;\n  redirectTo?: string; // default '/access-denied'\n};\n\nexport type InternalRolesPluginOptions = {\n  rolesByPermalink: RoleEntry[];\n} & RolesPluginOptions;\n\nexport type RolesMode = \"all\" | \"any\";\n\nexport type RoleRequirements = {\n  requiredRoles: string[];\n  requiredRolesMode: RolesMode;\n};\n\nexport type RoleFrontMatter = {\n  required_roles?: string[];\n  required_roles_mode?: RolesMode;\n};\n\nexport type RoleEntry = RoleRequirements & {\n  permalink: string;\n};\n\nexport function getRoleFrontMatter(frontMatter: unknown): RoleFrontMatter {\n  if (!frontMatter || typeof frontMatter !== \"object\") return {};\n  return frontMatter as RoleFrontMatter;\n}\n\nexport function getRoleRequirements(frontMatter: unknown): RoleRequirements {\n  const roleFrontMatter = getRoleFrontMatter(frontMatter);\n  return {\n    requiredRoles: roleFrontMatter.required_roles ?? [],\n    requiredRolesMode: roleFrontMatter.required_roles_mode ?? \"all\",\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAAiB;;;AC2BV,SAAS,mBAAmB,aAAuC;AACxE,MAAI,CAAC,eAAe,OAAO,gBAAgB,SAAU,QAAO,CAAC;AAC7D,SAAO;AACT;AAEO,SAAS,oBAAoB,aAAwC;AAC1E,QAAM,kBAAkB,mBAAmB,WAAW;AACtD,SAAO;AAAA,IACL,eAAe,gBAAgB,kBAAkB,CAAC;AAAA,IAClD,mBAAmB,gBAAgB,uBAAuB;AAAA,EAC5D;AACF;;;ADfO,IAAM,2BAA2B,CAAC,SAAqC;AAvB9E;AAwBE,aAAW,OAAO,MAAM;AACtB,UAAM,QAAQ,IAAI,YAAY;AAC9B,QAAI,CAAC,MAAO;AAEZ,UAAM,SAAS,SAAI,aAAY,yBAAhB,GAAgB,uBAAyB,CAAC;AACzD,UAAM,iBAAiB;AACvB,UAAM,sBAAsB,IAAI,YAAY;AAAA,EAC9C;AACF;AAKO,IAAM,oBAAiD,OAAO;AAAA,EACnE;AAAA,EACA,GAAG;AACL,MAAM;AACJ,2BAAyB,KAAK,IAAI;AAElC,SAAO,6BAA6B,IAAI;AAC1C;AAEA,IAAI,mBAAgC,CAAC;AAErC,SAAS,iBAAoB;AAC3B,MAAI;AACJ,MAAI;AACJ,QAAM,UAAU,IAAI,QAAW,CAAC,KAAK,QAAQ;AAC3C,cAAU;AACV,aAAS;AAAA,EACX,CAAC;AACD,SAAO,EAAE,SAAS,SAAS,OAAO;AACpC;AAEA,IAAI,iBAAiB,eAAqB;AAMnC,IAAM,sBAAsB,CAAC,cAA0B;AAC5D,mBAAiB,eAAqB;AAEtC,qBAAmB,UAAU,IAAI,CAAC,QAAQ;AAAA,IACxC,WAAW,GAAG,SAAS;AAAA,IACvB,GAAG,oBAAoB,GAAG,SAAS,WAAW;AAAA,EAChD,EAAE;AAEF,iBAAe,QAAQ;AACzB;AAKO,IAAM,qBAAyC,OAAO,EAAE,UAAU,MAAM;AAC7E,sBAAoB,SAAS;AAC7B,SAAO;AACT;AAEe,SAAR,YACL,UACA,SACQ;AACR,SAAO;AAAA,IACL,MAAM;AAAA,IAEN,eAAe;AACb,aAAO,YAAAA,QAAK,QAAQ,WAAW,cAAc;AAAA,IAC/C;AAAA,IAEA,MAAM,cAAc,EAAE,QAAQ,GAAG;AAC/B,YAAM,eAAe;AAErB,cAAQ,cAAc;AAAA,QACpB;AAAA,QACA,sBAAsB,QAAQ,wBAAwB;AAAA,QACtD,YAAY,QAAQ,cAAc;AAAA,MACpC,CAAC;AAAA,IACH;AAAA,EACF;AACF;","names":["path"]}

package/dist/index.d.cts

@@ -0,0 +1,35 @@
+import { LoadContext, Plugin } from '@docusaurus/types';
+import { BlogPost, ProcessBlogPostsFn } from '@docusaurus/plugin-content-blog';
+import { SidebarItemsGeneratorDoc, SidebarItemsGeneratorOption } from '@docusaurus/plugin-content-docs/src/sidebars/types.js';
+
+type UnauthorizedBehavior = "forbidden" | "redirect";
+type RolesPluginOptions = {
+    unauthorizedBehavior?: UnauthorizedBehavior;
+    redirectTo?: string;
+};
+
+/**
+ * Used to apply FrontMatter required_roles and required_roles_mode to
+ * sidebar_custom_props.required_roles and sidebar_custom_props.required_roles_mode.
+ *
+ * Should use protectDocSidebar for simple use cases.
+ *
+ * @param docs - The docs to transform.
+ */
+declare const addDocSidebarCustomProps: (docs: SidebarItemsGeneratorDoc[]) => void;
+/**
+ * Used to protect docs sidebar is a plug and play for sidebarItemsGenerator
+ */
+declare const protectDocSidebar: SidebarItemsGeneratorOption;
+/**
+ * Used to set rolesByPermalink which is used by overriden BlogSidebar
+ * to protect blog sidebar.
+ */
+declare const setRolesByPermaLink: (blogPosts: BlogPost[]) => void;
+/**
+ * Used to protect blog sidebar is a plug and play for processBlogPosts.
+ */
+declare const protectBlogSidebar: ProcessBlogPostsFn;
+declare function pluginRoles(_context: LoadContext, options: RolesPluginOptions): Plugin;
+
+export { type RolesPluginOptions, addDocSidebarCustomProps, pluginRoles as default, protectBlogSidebar, protectDocSidebar, setRolesByPermaLink };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { LoadContext, Plugin } from '@docusaurus/types';
+import { BlogPost, ProcessBlogPostsFn } from '@docusaurus/plugin-content-blog';
+import { SidebarItemsGeneratorDoc, SidebarItemsGeneratorOption } from '@docusaurus/plugin-content-docs/src/sidebars/types.js';
+
+type UnauthorizedBehavior = "forbidden" | "redirect";
+type RolesPluginOptions = {
+    unauthorizedBehavior?: UnauthorizedBehavior;
+    redirectTo?: string;
+};
+
+/**
+ * Used to apply FrontMatter required_roles and required_roles_mode to
+ * sidebar_custom_props.required_roles and sidebar_custom_props.required_roles_mode.
+ *
+ * Should use protectDocSidebar for simple use cases.
+ *
+ * @param docs - The docs to transform.
+ */
+declare const addDocSidebarCustomProps: (docs: SidebarItemsGeneratorDoc[]) => void;
+/**
+ * Used to protect docs sidebar is a plug and play for sidebarItemsGenerator
+ */
+declare const protectDocSidebar: SidebarItemsGeneratorOption;
+/**
+ * Used to set rolesByPermalink which is used by overriden BlogSidebar
+ * to protect blog sidebar.
+ */
+declare const setRolesByPermaLink: (blogPosts: BlogPost[]) => void;
+/**
+ * Used to protect blog sidebar is a plug and play for processBlogPosts.
+ */
+declare const protectBlogSidebar: ProcessBlogPostsFn;
+declare function pluginRoles(_context: LoadContext, options: RolesPluginOptions): Plugin;
+
+export { type RolesPluginOptions, addDocSidebarCustomProps, pluginRoles as default, protectBlogSidebar, protectDocSidebar, setRolesByPermaLink };

package/dist/index.js

@@ -0,0 +1,81 @@
+// src/index.ts
+import path from "path";
+
+// src/options.ts
+function getRoleFrontMatter(frontMatter) {
+  if (!frontMatter || typeof frontMatter !== "object") return {};
+  return frontMatter;
+}
+function getRoleRequirements(frontMatter) {
+  const roleFrontMatter = getRoleFrontMatter(frontMatter);
+  return {
+    requiredRoles: roleFrontMatter.required_roles ?? [],
+    requiredRolesMode: roleFrontMatter.required_roles_mode ?? "all"
+  };
+}
+
+// src/index.ts
+var addDocSidebarCustomProps = (docs) => {
+  var _a;
+  for (const doc of docs) {
+    const roles = doc.frontMatter.required_roles;
+    if (!roles) continue;
+    const props = (_a = doc.frontMatter).sidebar_custom_props ?? (_a.sidebar_custom_props = {});
+    props.required_roles = roles;
+    props.required_roles_mode = doc.frontMatter.required_roles_mode;
+  }
+};
+var protectDocSidebar = async ({
+  defaultSidebarItemsGenerator,
+  ...args
+}) => {
+  addDocSidebarCustomProps(args.docs);
+  return defaultSidebarItemsGenerator(args);
+};
+var rolesByPermalink = [];
+function createDeferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+var blogRolesReady = createDeferred();
+var setRolesByPermaLink = (blogPosts) => {
+  blogRolesReady = createDeferred();
+  rolesByPermalink = blogPosts.map((bp) => ({
+    permalink: bp.metadata.permalink,
+    ...getRoleRequirements(bp.metadata.frontMatter)
+  }));
+  blogRolesReady.resolve();
+};
+var protectBlogSidebar = async ({ blogPosts }) => {
+  setRolesByPermaLink(blogPosts);
+  return blogPosts;
+};
+function pluginRoles(_context, options) {
+  return {
+    name: "docusaurus-roles-plugin",
+    getThemePath() {
+      return path.resolve(__dirname, "../src/theme");
+    },
+    async contentLoaded({ actions }) {
+      await blogRolesReady.promise;
+      actions.setGlobalData({
+        rolesByPermalink,
+        unauthorizedBehavior: options.unauthorizedBehavior ?? "notFound",
+        redirectTo: options.redirectTo ?? "/access-denied"
+      });
+    }
+  };
+}
+export {
+  addDocSidebarCustomProps,
+  pluginRoles as default,
+  protectBlogSidebar,
+  protectDocSidebar,
+  setRolesByPermaLink
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/options.ts"],"sourcesContent":["import path from \"path\";\nimport type { LoadContext, Plugin } from \"@docusaurus/types\";\nimport {\n  getRoleRequirements,\n  type RolesPluginOptions,\n  type RoleEntry,\n} from \"./options\";\nimport { BlogPost, ProcessBlogPostsFn } from \"@docusaurus/plugin-content-blog\";\nimport {\n  SidebarItemsGeneratorDoc,\n  SidebarItemsGeneratorOption,\n} from \"@docusaurus/plugin-content-docs/src/sidebars/types.js\";\n\nexport { RolesPluginOptions } from \"./options\";\n\n/**\n * Used to apply FrontMatter required_roles and required_roles_mode to\n * sidebar_custom_props.required_roles and sidebar_custom_props.required_roles_mode.\n *\n * Should use protectDocSidebar for simple use cases.\n *\n * @param docs - The docs to transform.\n */\nexport const addDocSidebarCustomProps = (docs: SidebarItemsGeneratorDoc[]) => {\n  for (const doc of docs) {\n    const roles = doc.frontMatter.required_roles;\n    if (!roles) continue;\n\n    const props = (doc.frontMatter.sidebar_custom_props ??= {});\n    props.required_roles = roles;\n    props.required_roles_mode = doc.frontMatter.required_roles_mode;\n  }\n};\n\n/**\n * Used to protect docs sidebar is a plug and play for sidebarItemsGenerator\n */\nexport const protectDocSidebar: SidebarItemsGeneratorOption = async ({\n  defaultSidebarItemsGenerator,\n  ...args\n}) => {\n  addDocSidebarCustomProps(args.docs);\n\n  return defaultSidebarItemsGenerator(args);\n};\n\nlet rolesByPermalink: RoleEntry[] = [];\n\nfunction createDeferred<T>() {\n  let resolve!: (value: T) => void;\n  let reject!: (reason?: unknown) => void;\n  const promise = new Promise<T>((res, rej) => {\n    resolve = res;\n    reject = rej;\n  });\n  return { promise, resolve, reject };\n}\n\nlet blogRolesReady = createDeferred<void>();\n\n/**\n * Used to set rolesByPermalink which is used by overriden BlogSidebar\n * to protect blog sidebar.\n */\nexport const setRolesByPermaLink = (blogPosts: BlogPost[]) => {\n  blogRolesReady = createDeferred<void>();\n\n  rolesByPermalink = blogPosts.map((bp) => ({\n    permalink: bp.metadata.permalink,\n    ...getRoleRequirements(bp.metadata.frontMatter),\n  }));\n\n  blogRolesReady.resolve();\n};\n\n/**\n * Used to protect blog sidebar is a plug and play for processBlogPosts.\n */\nexport const protectBlogSidebar: ProcessBlogPostsFn = async ({ blogPosts }) => {\n  setRolesByPermaLink(blogPosts);\n  return blogPosts;\n};\n\nexport default function pluginRoles(\n  _context: LoadContext,\n  options: RolesPluginOptions,\n): Plugin {\n  return {\n    name: \"docusaurus-roles-plugin\",\n\n    getThemePath() {\n      return path.resolve(__dirname, \"../src/theme\");\n    },\n\n    async contentLoaded({ actions }) {\n      await blogRolesReady.promise;\n\n      actions.setGlobalData({\n        rolesByPermalink,\n        unauthorizedBehavior: options.unauthorizedBehavior ?? \"notFound\",\n        redirectTo: options.redirectTo ?? \"/access-denied\",\n      });\n    },\n  };\n}\n","export type UnauthorizedBehavior = \"forbidden\" | \"redirect\";\n\nexport type RolesPluginOptions = {\n  unauthorizedBehavior?: UnauthorizedBehavior;\n  redirectTo?: string; // default '/access-denied'\n};\n\nexport type InternalRolesPluginOptions = {\n  rolesByPermalink: RoleEntry[];\n} & RolesPluginOptions;\n\nexport type RolesMode = \"all\" | \"any\";\n\nexport type RoleRequirements = {\n  requiredRoles: string[];\n  requiredRolesMode: RolesMode;\n};\n\nexport type RoleFrontMatter = {\n  required_roles?: string[];\n  required_roles_mode?: RolesMode;\n};\n\nexport type RoleEntry = RoleRequirements & {\n  permalink: string;\n};\n\nexport function getRoleFrontMatter(frontMatter: unknown): RoleFrontMatter {\n  if (!frontMatter || typeof frontMatter !== \"object\") return {};\n  return frontMatter as RoleFrontMatter;\n}\n\nexport function getRoleRequirements(frontMatter: unknown): RoleRequirements {\n  const roleFrontMatter = getRoleFrontMatter(frontMatter);\n  return {\n    requiredRoles: roleFrontMatter.required_roles ?? [],\n    requiredRolesMode: roleFrontMatter.required_roles_mode ?? \"all\",\n  };\n}\n"],"mappings":";AAAA,OAAO,UAAU;;;AC2BV,SAAS,mBAAmB,aAAuC;AACxE,MAAI,CAAC,eAAe,OAAO,gBAAgB,SAAU,QAAO,CAAC;AAC7D,SAAO;AACT;AAEO,SAAS,oBAAoB,aAAwC;AAC1E,QAAM,kBAAkB,mBAAmB,WAAW;AACtD,SAAO;AAAA,IACL,eAAe,gBAAgB,kBAAkB,CAAC;AAAA,IAClD,mBAAmB,gBAAgB,uBAAuB;AAAA,EAC5D;AACF;;;ADfO,IAAM,2BAA2B,CAAC,SAAqC;AAvB9E;AAwBE,aAAW,OAAO,MAAM;AACtB,UAAM,QAAQ,IAAI,YAAY;AAC9B,QAAI,CAAC,MAAO;AAEZ,UAAM,SAAS,SAAI,aAAY,yBAAhB,GAAgB,uBAAyB,CAAC;AACzD,UAAM,iBAAiB;AACvB,UAAM,sBAAsB,IAAI,YAAY;AAAA,EAC9C;AACF;AAKO,IAAM,oBAAiD,OAAO;AAAA,EACnE;AAAA,EACA,GAAG;AACL,MAAM;AACJ,2BAAyB,KAAK,IAAI;AAElC,SAAO,6BAA6B,IAAI;AAC1C;AAEA,IAAI,mBAAgC,CAAC;AAErC,SAAS,iBAAoB;AAC3B,MAAI;AACJ,MAAI;AACJ,QAAM,UAAU,IAAI,QAAW,CAAC,KAAK,QAAQ;AAC3C,cAAU;AACV,aAAS;AAAA,EACX,CAAC;AACD,SAAO,EAAE,SAAS,SAAS,OAAO;AACpC;AAEA,IAAI,iBAAiB,eAAqB;AAMnC,IAAM,sBAAsB,CAAC,cAA0B;AAC5D,mBAAiB,eAAqB;AAEtC,qBAAmB,UAAU,IAAI,CAAC,QAAQ;AAAA,IACxC,WAAW,GAAG,SAAS;AAAA,IACvB,GAAG,oBAAoB,GAAG,SAAS,WAAW;AAAA,EAChD,EAAE;AAEF,iBAAe,QAAQ;AACzB;AAKO,IAAM,qBAAyC,OAAO,EAAE,UAAU,MAAM;AAC7E,sBAAoB,SAAS;AAC7B,SAAO;AACT;AAEe,SAAR,YACL,UACA,SACQ;AACR,SAAO;AAAA,IACL,MAAM;AAAA,IAEN,eAAe;AACb,aAAO,KAAK,QAAQ,WAAW,cAAc;AAAA,IAC/C;AAAA,IAEA,MAAM,cAAc,EAAE,QAAQ,GAAG;AAC/B,YAAM,eAAe;AAErB,cAAQ,cAAc;AAAA,QACpB;AAAA,QACA,sBAAsB,QAAQ,wBAAwB;AAAA,QACtD,YAAY,QAAQ,cAAc;AAAA,MACpC,CAAC;AAAA,IACH;AAAA,EACF;AACF;","names":[]}