Agentics Shield

Zero-trust frontend content protection. Encrypt, authenticate, and deliver proprietary code via WebAssembly.

Shield prevents unauthorized access, scraping, and theft of your frontend source code by encrypting all protected assets server-side and decrypting them exclusively through a compiled WASM module in authenticated browser sessions.

How It Works

1. Initialize — Run npx agentics-shield init to generate cryptographic keys and a compiled WASM binary unique to your project via the Agentics Shield API.

2. Integrate — Mount the Shield middleware on your Express server. Protected files (JS, CSS, HTML) are AES-256-GCM encrypted at startup and served only to authenticated sessions.

3. Authenticate — When a visitor loads your page, the injected loader script initiates a cryptographic handshake (X25519 ECDH + AES-GCM) with your server through the WASM module. On success, a session is established and encrypted content is delivered and decrypted entirely in-browser.

4. Protect — All cryptographic operations run inside the WASM binary. Keys are baked in at compile time. No secrets are exposed in readable JavaScript. API requests from authenticated sessions are automatically signed and verified via HMAC proofs.

Architecture

Browser                         Your Server
  │                                  │
  │  ← page load (loader injected) → │
  │                                  │
  │  WASM loaded ──────────────────► │
  │  X25519 handshake ────────────► │  ← Shield middleware
  │  ◄──── encrypted session key ── │
  │                                  │
  │  fetch encrypted bundle ──────► │
  │  ◄──── AES-256-GCM content ─── │
  │                                  │
  │  WASM decrypts in-browser        │
  │  JS/CSS injected into DOM        │
  │                                  │
  │  API calls auto-signed ────────► │  ← proof verified
  │  ◄──── encrypted responses ──── │

All traffic stays between the browser and your server. The Agentics API is only contacted during init to compile the WASM binary.

Installation

npm install agentics-shield
# or
yarn add agentics-shield

Setup

1. Get Your API Key

Sign up at agentics.co.za/shield and retrieve your API key.

Set it as an environment variable:

export AGENTICS_API_KEY=your-api-key

Or create ~/.agentics/config.json:

{
  "apiKey": "your-api-key"
}

2. Initialize Shield

npx agentics-shield init --output ./shield

This contacts the Agentics Shield API, generates unique cryptographic keys, compiles a WASM binary with those keys embedded, and writes both to your output directory:

shield/
  shield.keys    # Server-side keys (keep secret, add to .gitignore)
  shield.wasm    # Compiled WASM binary with embedded keys

Add both files to .gitignore immediately.

3. Integrate With Express

const express = require('express');
const path = require('path');
const fs = require('fs');
const shield = require('agentics-shield');

const app = express();

const shieldInstance = shield.create({
  keys: path.resolve(__dirname, 'shield', 'shield.keys'),
  wasm: path.resolve(__dirname, 'shield', 'shield.wasm'),
  domains: ['yourdomain.com', '*.yourdomain.com'],
  prefix: '/shield',
  cors: ['*'],
  sessionTTL: 600,
  rateLimit: 120,
  protected: {
    'app.js': path.resolve(__dirname, 'public', 'app.js'),
    'style.css': path.resolve(__dirname, 'public', 'style.css')
  },
  onAuth: (event) => {
    if (event.success) {
      console.log(`Shield auth: ${event.domain} session ${event.sessionID}`);
    } else {
      console.log(`Shield auth failed: ${event.reason}`);
    }
  },
  onError: (event) => {
    console.error(`Shield error: ${event.error}`);
  }
});

app.use(shieldInstance.router());

app.get('/', (req, res) => {
  const html = fs.readFileSync(path.resolve(__dirname, 'public', 'index.html'), 'utf8');
  const injected = html.replace(
    '<script src="app.js"></script>',
    `<script data-cfasync="false">${shieldInstance.getLoaderJS()}</script>`
  );
  res.type('html').send(injected);
});

app.listen(3000);

The loader script replaces your original <script> tag. It handles WASM loading, authentication, content decryption, and DOM injection automatically.

Configuration

| Option | Type | Default | Description | |---|---|---|---| | keys | string or object | — | Path to shield.keys file, or keys object directly | | wasm | string or Buffer | — | Path to shield.wasm file, or WASM binary buffer | | domains | string[] | [] | Allowed domains (supports wildcards: *.example.com) | | prefix | string | '/shield' | URL prefix for Shield endpoints | | cors | string[] | [] | CORS allowed origins (['*'] for all) | | sessionTTL | number | 300 | Session time-to-live in seconds | | rateLimit | number | 60 | Max authentication requests per IP per minute | | protected | object | {} | Map of { filename: filepath } for files to encrypt | | onAuth | function | null | Callback on authentication events | | onError | function | null | Callback on error events |

API

shield.create(config)

Creates a Shield instance and returns an interface object.

Instance Methods

| Method | Description | |---|---| | .router() | Returns Express middleware that handles all Shield endpoints | | .protect() | Returns middleware that encrypts response bodies for authenticated sessions | | .requireSession() | Returns middleware that blocks unauthenticated requests | | .getLoaderJS() | Returns the client-side loader script string | | .getStatus() | Returns operational status (uptime, sessions, auth counts) | | .injectHTML(html, placeholder) | Replaces a placeholder in HTML with the loader script tag | | .verifyProof(req) | Manually verify a Shield proof from request headers | | .destroy() | Cleans up session stores and rate limiters |

Shield Endpoints

Mounted automatically via .router() under the configured prefix:

| Endpoint | Method | Description | |---|---|---| | {prefix}/authenticate | POST | X25519 ECDH authentication handshake | | {prefix}/content | GET | Serve encrypted content bundle | | {prefix}/auth.wasm | GET | Serve the WASM binary | | {prefix}/loader.js | GET | Serve the loader script | | {prefix}/challenge | POST | Issue session challenge | | {prefix}/status | GET | Shield operational status | | {prefix}/health | GET | Health check |

Protecting API Routes

Shield automatically intercepts fetch calls from authenticated sessions, attaching signed HMAC proofs to requests targeting /api/* paths. Use the .protect() or .requireSession() middleware on your API routes:

app.get('/api/data', shieldInstance.requireSession(), (req, res) => {
  res.json({ secret: 'only authenticated Shield sessions can access this' });
});

app.get('/api/sensitive', shieldInstance.protect(), (req, res) => {
  res.json({ data: 'this response will be encrypted in transit' });
});

Security Model

• X25519 ECDH key exchange for authentication handshakes
• AES-256-GCM encryption for all content bundles and session data
• HMAC-SHA256 signatures for request proof verification
• Compiled WASM — all cryptographic operations run inside a WebAssembly binary with keys baked in at compile time
• Nonce replay protection prevents reuse of authentication payloads
• Domain verification via cryptographic domain proofs
• Session-scoped content keys — each session receives a unique encryption key
• Constant-time comparisons for all signature verification
• No readable crypto in JavaScript — the published package contains only WASM wrapper functions

CLI

npx agentics-shield init [--output ./shield]
npx agentics-shield status <compile_id> [--output ./shield]

| Command | Description | |---|---| | init | Generate keys + compile WASM binary via Agentics Shield API | | status | Check status of a pending compilation |

Requirements

• Node.js >= 18.0.0
• Express (or compatible HTTP framework)

License

Proprietary — see LICENSE

© Agentics (Pty) Ltd