@sbwcws/musa

Privacy-first, invisible captcha widget for bot protection. MUSA protects your websites from bots using browser fingerprinting and behavioral analysis, showing challenges only when necessary.

Installation

npm install @sbwcws/musa

Or include via CDN:

<script src="https://unpkg.com/@wcws/musa/dist/musa.min.js"></script>

Quick Start

JavaScript/TypeScript

import { Musa } from '@sbwcws/musa';

// Initialize the widget
const musa = new Musa({
  siteKey: 'your-site-key',
  onSuccess: (token) => {
    console.log('Verification successful:', token);
    // Send token to your server for validation
  },
  onError: (error) => {
    console.error('Verification failed:', error);
  },
});

// Render the widget in a container
musa.render('#captcha-container');

Script Tag

<div id="captcha-container"></div>

<script src="https://unpkg.com/@wcws/musa/dist/musa.min.js"></script>
<script>
  const musa = new window.musa.Musa({
    siteKey: 'your-site-key',
    onSuccess: function(token) {
      document.getElementById('musa-token').value = token;
    }
  });
  musa.render('#captcha-container');
</script>

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | siteKey | string | Yes | Your MUSA site key from the dashboard | | onSuccess | (token: string) => void | Yes | Callback when verification succeeds | | onError | (error: Error) => void | No | Callback when verification fails | | onExpire | () => void | No | Callback when token expires | | theme | 'light' \| 'dark' \| 'auto' | No | Widget theme (default: 'auto') | | size | 'normal' \| 'compact' | No | Widget size (default: 'normal') | | language | string | No | Language code (default: browser language) |

Methods

render(container: string | HTMLElement)

Renders the widget in the specified container.

musa.render('#my-container');
// or
musa.render(document.getElementById('my-container'));

reset()

Resets the widget to its initial state.

musa.reset();

remove()

Removes the widget from the DOM.

musa.remove();

getResponse()

Returns the current verification token, or null if not verified.

const token = musa.getResponse();

Server-Side Verification

After receiving the token on your server, verify it using the @wcws/musa-server package:

import { verifyToken } from '@wcws/musa-server';

const result = await verifyToken({
  secretKey: 'your-secret-key',
  token: tokenFromClient,
  remoteip: clientIpAddress, // optional
});

if (result.success) {
  // Token is valid
} else {
  // Token is invalid
}

React Integration

For React applications, use the @wcws/musa-react package:

npm install @wcws/musa-react

import { MusaWidget } from '@wcws/musa-react';

function MyForm() {
  return (
    <form>
      <MusaWidget
        siteKey="your-site-key"
        onSuccess={(token) => console.log(token)}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

How It Works

MUSA uses a multi-layered approach to bot detection:

1. Invisible Mode (85% of traffic) - Pure fingerprint + behavioral analysis. Legitimate users pass automatically.
2. Checkbox Mode (10% of traffic) - Simple click verification for medium-risk requests.
3. Interactive Challenge (5% of traffic) - Slide puzzle for high-risk requests.

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

License

MIT

Links

• Dashboard
• Documentation