access-hood

Zero‑dependency, client‑side access hood for React. It provides a lightweight, visual gate that asks for a password once and stores an obfuscated flag in localStorage to reveal gated content on subsequent visits.

Important: This is not real authentication. Use it only for low‑stakes gating (e.g., previews, prototypes, internal demos). Do not rely on this for protecting sensitive data.

Install

npm install access-hood

Quick start (with remote verification)

import React from "react";
import { AccessHood, setConfig } from "access-hood";

// Configure once at app startup (e.g., in your root file)
setConfig({
  verifyUrl: "/api/ah-verify", // can be absolute or relative; required
  // requestTimeoutMs: 8000,        // optional, defaults to 8000
  passwordHint: "Ask the team lead",
  metadata: {
    title: "Protected Preview",
    description: "This is a protected preview",
  },
  theme: {
    // override any colors you want; all fields optional
    buttonBackground: "#2563eb",
    buttonBorder: "#1e3a8a",
    buttonText: "#ffffff",
    containerBorder: "#e2e8f0",
    hintText: "#475569",
    errorText: "#dc2626",
  },
});

export const Demo = () => {
  return (
    <AccessHood>
      <main>
        <h1>Private content</h1>
        <p>Visible after entering the password once.</p>
      </main>
    </AccessHood>
  );
};

On your backend, implement the ah-verify endpoint:

// POST /ah-verify
// Body: { password: string }
// Response: { valid: boolean }
app.post("/ah-verify", async (req, res) => {
  const { password } = req.body;

  // Replace with your own verification logic
  const isValid = password === process.env.ACCESS_HOOD_PASSWORD;

  res.json({ valid: isValid });
});

API

• AccessHood: React component that renders a minimal password form until access is granted.
  • props
    • children: React.ReactNode: Content to show after access is granted.
• setConfig(config): Configure remote verification and gate behavior.
  • verifyUrl?: string: URL of your backend verification endpoint (e.g., "/api/ah-verify" or "https://example.com/ah-verify"). Required.
  • requestTimeoutMs?: number: Optional request timeout in milliseconds (default: 8000).
  • passwordHint?: string: Optional hint displayed under the form.
  • metadata?: { title?: string; description?: string }: Optional metadata; title sets document.title on mount.
  • theme?: Partial<AccessHoodTheme>: Optional color theme overrides.
  • storageKey?: string: Optional identifier used to derive the obfuscated localStorage flag (default: "ah_authed_v1").
• getConfig(): Read the current configuration.

Theming

You can customize colors by passing a theme prop or by generating styles yourself via getStyles if you need full control.

import { AccessHood, getStyles, type AccessHoodTheme } from "access-hood";

const theme: Partial<AccessHoodTheme> = {
  buttonBackground: "#2563eb",
  buttonBorder: "#1e3a8a",
  buttonText: "#ffffff",
  containerBorder: "#e2e8f0",
  hintText: "#475569",
  errorText: "#dc2626",
};

// or compute styles if you want to reuse them elsewhere
const styles = getStyles(theme);

How it works

• On mount, the component derives a deterministic, obfuscated storage key/value from the configured storageKey and a salt, and checks localStorage for that pair to automatically re‑grant access.
• On submit, the component sends a POST request to verifyUrl with body { password } and expects a JSON response { valid: boolean }.
• If the backend returns { valid: true }, the derived key/value is stored in localStorage and access is granted.
• Uses Web Crypto (SHA‑256) when available with a tiny non‑crypto fallback to remain functional in restricted environments.

Notes and limitations

• Client‑side gate only; even with a remote check, you should not ship sensitive data to the client unless the user is authorized server‑side.
• SSR: The gate renders on the client; the component no‑ops on the server.
• Clearing site data (or changing storageKey) will reset the gate.

Styling

The form uses inline styles generated by getStyles from src/accessHoodStyles.ts. Override colors via the theme prop, or fork/wrap for deeper customization.

TypeScript

First‑class TypeScript types are included. The package ships types alongside the compiled output.

File overview

• src/AccessHood.tsx — Functional React component implementing the gate and UX.
• src/accessHoodStyles.ts — Centralized inline styles used by the component.
• src/authStorage.ts — Internal helpers that derive obfuscated localStorage key/value and read/write the auth flag.
• src/config.ts — Remote verification configuration helpers (getConfig, setConfig).
• src/remoteVerify.ts — Internal remote password verification helper.
• src/index.ts — Public exports.

License

MIT