docusaurus-plugin-password-gate 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Royal Bissell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# docusaurus-plugin-password-gate
+
+A client-side password gate for [Docusaurus](https://docusaurus.io/) v3 sites. Visitors must enter a password before seeing any content.
+
+## Install
+
+```bash
+npm install docusaurus-plugin-password-gate
+```
+
+## Setup
+
+### 1. Generate a password hash
+
+```bash
+echo -n "your-password" | shasum -a 256 | cut -d " " -f 1
+```
+
+Or use the bundled helper:
+
+```bash
+./node_modules/docusaurus-plugin-password-gate/scripts/hash-password.sh "your-password"
+```
+
+### 2. Add to `docusaurus.config.ts`
+
+```ts
+export default {
+  plugins: [
+    [
+      'docusaurus-plugin-password-gate',
+      {
+        passwordHash: '5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8',
+      },
+    ],
+  ],
+};
+```
+
+## Options
+
+| Option           | Type      | Default                          | Description                                      |
+| ---------------- | --------- | -------------------------------- | ------------------------------------------------ |
+| `passwordHash`   | `string`  | **required**                     | SHA-256 hex hash of the password                 |
+| `siteName`       | `string`  | `'Documentation'`                | Heading shown on the gate screen                 |
+| `placeholder`    | `string`  | `'Enter password'`               | Input placeholder text                           |
+| `buttonText`     | `string`  | `'Enter'`                        | Submit button label                              |
+| `errorMessage`   | `string`  | `'Incorrect password.'`          | Message shown after a failed attempt             |
+| `persistSession` | `boolean` | `false`                          | `true` = localStorage (survives restart), `false` = sessionStorage (clears on tab close) |
+| `storageKey`     | `string`  | `'docusaurus-password-gate'`     | Storage key used for the auth token              |
+
+## Security Model
+
+This plugin is **not a security boundary**. The password hash is shipped in the client-side JavaScript bundle and can be extracted by anyone who inspects it.
+
+It is suitable for:
+
+- Keeping casual visitors out of internal documentation
+- Preventing search engine indexing of gated content
+- Staging site access control where real auth is overkill
+
+It is **not** suitable for:
+
+- Protecting sensitive or regulated data
+- Multi-user access control
+- Compliance-regulated content
+
+For truly sensitive content, pair this with hosting-level authentication (Cloudflare Access, nginx basic auth, Vercel password protection, etc.).
+
+## License
+
+[MIT](LICENSE)

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from '@docusaurus/types';
+import type { PasswordGateOptions } from './options';
+export default function pluginPasswordGate(_context: unknown, options: PasswordGateOptions): Plugin;

package/lib/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = pluginPasswordGate;
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/i;
+function pluginPasswordGate(_context, options) {
+    if (!options.passwordHash || !SHA256_HEX_RE.test(options.passwordHash)) {
+        throw new Error('[docusaurus-plugin-password-gate] "passwordHash" must be a 64-character hex-encoded SHA-256 hash. ' +
+            'Generate one with: echo -n "your-password" | shasum -a 256 | cut -d " " -f 1');
+    }
+    return {
+        name: 'docusaurus-plugin-password-gate',
+        getThemePath() {
+            return '../lib/theme';
+        },
+        contentLoaded({ actions }) {
+            actions.setGlobalData({
+                passwordHash: options.passwordHash,
+                siteName: options.siteName ?? 'Documentation',
+                placeholder: options.placeholder ?? 'Enter password',
+                buttonText: options.buttonText ?? 'Enter',
+                errorMessage: options.errorMessage ?? 'Incorrect password.',
+                persistSession: options.persistSession ?? false,
+                storageKey: options.storageKey ?? 'docusaurus-password-gate',
+            });
+        },
+    };
+}

package/lib/options.d.ts

@@ -0,0 +1,9 @@
+export interface PasswordGateOptions {
+    passwordHash: string;
+    siteName?: string;
+    placeholder?: string;
+    buttonText?: string;
+    errorMessage?: string;
+    persistSession?: boolean;
+    storageKey?: string;
+}

package/lib/options.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/theme/Root.d.ts

@@ -0,0 +1,4 @@
+import { type ReactNode } from 'react';
+export default function Root({ children }: {
+    children: ReactNode;
+}): ReactNode;

package/lib/theme/Root.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = Root;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const useGlobalData_1 = require("@docusaurus/useGlobalData");
+function isGateData(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return (typeof obj.passwordHash === 'string' &&
+        typeof obj.siteName === 'string' &&
+        typeof obj.placeholder === 'string' &&
+        typeof obj.buttonText === 'string' &&
+        typeof obj.errorMessage === 'string' &&
+        typeof obj.persistSession === 'boolean' &&
+        typeof obj.storageKey === 'string');
+}
+const BASE_DELAY_MS = 1000;
+async function sha256(message) {
+    const msgBuffer = new TextEncoder().encode(message);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+}
+function getStorage(persist) {
+    if (typeof window === 'undefined')
+        return null;
+    return persist ? localStorage : sessionStorage;
+}
+function PasswordGate({ children, data }) {
+    const [authenticated, setAuthenticated] = (0, react_1.useState)(false);
+    const [ready, setReady] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(false);
+    const [input, setInput] = (0, react_1.useState)('');
+    const [locked, setLocked] = (0, react_1.useState)(false);
+    const failures = (0, react_1.useRef)(0);
+    (0, react_1.useEffect)(() => {
+        const storage = getStorage(data.persistSession);
+        if (storage?.getItem(data.storageKey) === 'authenticated') {
+            setAuthenticated(true);
+        }
+        setReady(true);
+    }, [data.persistSession, data.storageKey]);
+    const handleSubmit = (0, react_1.useCallback)(async (e) => {
+        e.preventDefault();
+        if (locked)
+            return;
+        const hash = await sha256(input);
+        if (hash === data.passwordHash) {
+            const storage = getStorage(data.persistSession);
+            storage?.setItem(data.storageKey, 'authenticated');
+            failures.current = 0;
+            setAuthenticated(true);
+            setError(false);
+            setInput('');
+        }
+        else {
+            failures.current += 1;
+            setError(true);
+            const delay = BASE_DELAY_MS * Math.pow(2, Math.min(failures.current - 1, 5));
+            setLocked(true);
+            setTimeout(() => setLocked(false), delay);
+        }
+    }, [input, data, locked]);
+    const handleInputChange = (0, react_1.useCallback)((e) => {
+        setInput(e.target.value);
+        if (error)
+            setError(false);
+    }, [error]);
+    if (authenticated) {
+        return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children });
+    }
+    if (!ready) {
+        return null;
+    }
+    return ((0, jsx_runtime_1.jsx)("div", { style: styles.overlay, children: (0, jsx_runtime_1.jsxs)("form", { onSubmit: handleSubmit, style: styles.card, children: [(0, jsx_runtime_1.jsx)("h2", { style: styles.title, children: data.siteName }), (0, jsx_runtime_1.jsx)("label", { htmlFor: "password-gate-input", style: styles.srOnly, children: "Password" }), (0, jsx_runtime_1.jsx)("input", { id: "password-gate-input", type: "password", value: input, onChange: handleInputChange, placeholder: data.placeholder, "aria-describedby": error ? 'password-gate-error' : undefined, style: styles.input, autoFocus: true }), (0, jsx_runtime_1.jsx)("button", { type: "submit", disabled: locked, style: locked ? { ...styles.button, ...styles.buttonDisabled } : styles.button, children: locked ? 'Wait\u2026' : data.buttonText }), error && ((0, jsx_runtime_1.jsx)("p", { id: "password-gate-error", role: "alert", style: styles.error, children: data.errorMessage }))] }) }));
+}
+function Root({ children }) {
+    const raw = (0, useGlobalData_1.usePluginData)('docusaurus-plugin-password-gate');
+    if (!isGateData(raw)) {
+        return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children });
+    }
+    return ((0, jsx_runtime_1.jsx)(PasswordGate, { data: raw, children: children }));
+}
+const styles = {
+    overlay: {
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        minHeight: '100vh',
+        backgroundColor: '#1b1b1d',
+        fontFamily: 'system-ui, -apple-system, sans-serif',
+    },
+    card: {
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '1rem',
+        padding: '2.5rem',
+        borderRadius: '8px',
+        backgroundColor: '#242526',
+        boxShadow: '0 4px 24px rgba(0,0,0,0.3)',
+        minWidth: '320px',
+    },
+    title: {
+        margin: 0,
+        color: '#e3e3e3',
+        fontSize: '1.25rem',
+        textAlign: 'center',
+    },
+    srOnly: {
+        position: 'absolute',
+        width: '1px',
+        height: '1px',
+        padding: 0,
+        margin: '-1px',
+        overflow: 'hidden',
+        clip: 'rect(0,0,0,0)',
+        whiteSpace: 'nowrap',
+        border: 0,
+    },
+    input: {
+        padding: '0.75rem 1rem',
+        borderRadius: '6px',
+        border: '1px solid #444',
+        backgroundColor: '#1b1b1d',
+        color: '#e3e3e3',
+        fontSize: '1rem',
+        outline: 'none',
+    },
+    button: {
+        padding: '0.75rem 1rem',
+        borderRadius: '6px',
+        border: 'none',
+        backgroundColor: '#3578e5',
+        color: '#fff',
+        fontSize: '1rem',
+        cursor: 'pointer',
+        fontWeight: 600,
+    },
+    buttonDisabled: {
+        opacity: 0.5,
+        cursor: 'not-allowed',
+    },
+    error: {
+        margin: 0,
+        color: '#fa383e',
+        fontSize: '0.875rem',
+        textAlign: 'center',
+    },
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "docusaurus-plugin-password-gate",
+  "version": "0.1.1",
+  "description": "Client-side password gate for Docusaurus sites",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@docusaurus/core": "^3.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "^3.0.0",
+    "@docusaurus/types": "^3.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.2"
+  },
+  "keywords": [
+    "docusaurus",
+    "plugin",
+    "password",
+    "authentication",
+    "gate"
+  ],
+  "license": "MIT",
+  "author": "Royal Bissell",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RoyalBis/docusaurus-plugin-password-gate.git"
+  },
+  "homepage": "https://github.com/RoyalBis/docusaurus-plugin-password-gate#readme",
+  "bugs": {
+    "url": "https://github.com/RoyalBis/docusaurus-plugin-password-gate/issues"
+  }
+}