staticguard

v1.0.3

Published

a month ago

Client-side password protection for static websites with customizable UI

0High
0Medium
0Low

mvellandi

password-protection static-site client-side-auth authentication static-website password guard protection

StaticGuard

Client-side password protection for static websites with a beautiful, customizable UI.

Features

✅ Zero dependencies (vanilla JavaScript)
✅ Client-side SHA-256 password hashing
✅ Session-based authentication
✅ Rate limiting (5 attempts, 5-minute lockout)
✅ Fully customizable themes via CSS variables
✅ Automatic FOUC prevention
✅ Mobile-first responsive design
✅ Accessibility compliant (ARIA, keyboard navigation)

Installation

npm install staticguard

Quick Start

1. Generate Password Hash

npx staticguard-hash mypassword mysalt
# Output: abc123def456...

2. Copy CSS to Public Directory

Copy the StaticGuard CSS to your public/static directory:

cp node_modules/staticguard/dist/staticguard.css public/

3. Create Config File

Create a config file (e.g., staticguard-config.js):

import StaticGuard from 'staticguard';

StaticGuard.init({
  passwordHash: 'abc123def456...',
  salt: 'mysalt',
  headerText: 'Protected Content',
  subheaderText: 'Please enter the password.',
  guardImage: '/guard-image.png', // Optional
  theme: {
    primaryColor: '#8b4513',
    backgroundColor: '#faf8f6',
    pageBackgroundColor: '#3e2723',
    imageBackgroundColor: '#000000',
    borderColor: '#d4af37',
    textColor: '#342e29',
    errorColor: '#991b1b'
  }
});

4. Add to Your HTML

Add the CSS and config script to your HTML:

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="/staticguard.css" />
  <script type="module" src="./staticguard-config.js"></script>
</head>
<body>
  <!-- Your protected content -->
</body>
</html>

Note: The CSS file includes automatic FOUC prevention. No additional inline styles needed!

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | passwordHash | string | required | SHA-256 hash of password + salt | | salt | string | 'staticguard-default' | Salt for password hashing | | headerText | string | 'Protected Content' | Main heading text | | subheaderText | string | 'Please enter the password to continue.' | Subheading text | | guardImage | string | null | Optional image URL for left side | | theme | object | See below | Theme customization | | maxAttempts | number | 5 | Max failed attempts before lockout | | lockoutDuration | number | 300000 | Lockout duration in ms (5 minutes) | | sessionKey | string | 'staticguard_authenticated' | sessionStorage key |

Theme Options

All theme properties are optional:

theme: {
  primaryColor: '#8b4513',           // Border accents, button background
  backgroundColor: '#faf8f6',        // Form section background
  pageBackgroundColor: '#3e2723',    // Page overlay background
  imageBackgroundColor: '#000000',   // Image section background
  borderColor: '#d4af37',            // Modal border
  textColor: '#342e29',              // Text color
  errorColor: '#991b1b',             // Error message color
  inputBorderColor: '#d4d4d4',       // Input border
  buttonHoverColor: '#704010'        // Button hover color
}

Security Considerations

Important: StaticGuard provides client-side only password protection. This is:

✅ Good for:

Preventing casual browsing
Keeping content out of search engines
Simple "password gate" for static sites

❌ Not suitable for:

Protecting sensitive data
Enterprise security requirements
Defense against determined attackers

The password hash is accessible to anyone who views the page source. Use this as a lightweight access control mechanism, not true security.

License

MIT