@forge12interactive/silentshield-sdk-js

One zero-dependency package for SilentShield in Node.js:

• Verify — confirm a form submission came from a human.
• Observe — passively report AI-agent / bot traffic as it hits your app.
• Enforce — actually block disallowed AI bots per your dashboard policy.

Uses the global fetch built into Node, so there are no runtime dependencies.

Install

npm install @forge12interactive/silentshield-sdk-js

Requires Node.js >= 18.

Usage

Both capabilities come from the same client:

import express from "express";
import { createClient } from "@forge12interactive/silentshield-sdk-js";

const shield = createClient({ apiKey: process.env.SILENTSHIELD_API_KEY });
const app = express();
app.use(express.json());

// OBSERVE — mount once, near the top. Fire-and-forget, never blocks a request.
app.use(shield.observe);

// VERIFY — on your form submit route.
app.post("/signup", async (req, res) => {
  const { human } = await shield.verify(req.body.nonce);
  if (!human) return res.status(403).send("Verification failed");
  // ...proceed with a trusted human submission
  res.send("ok");
});

app.listen(3000);

Without a client

Top-level convenience helpers are also exported:

import { verify, observe } from "@forge12interactive/silentshield-sdk-js";

const { human } = await verify(nonce, { apiKey });
app.use(observe({ apiKey }));

verify(nonce) result

{
  human: boolean,      // true iff ok && verdict === "human" && confidence >= threshold
  verdict: string,     // e.g. "human" | "bot"
  confidence: number,  // 0..1
  requestId: string,   // server request id for support/debugging
}

A submission is treated as human only when ok === true, verdict === "human", and confidence >= humanThreshold (default 0.7).

Configuration

createClient, verify, and observe all accept the same options:

| Option | Env suggestion | Default | | ---------------- | ------------------------- | ---------------------------------------------------------- | | apiKey | SILENTSHIELD_API_KEY | — (required) | | verifyUrl | — | https://api.silentshield.io/v1/verify | | observeUrl | — | https://api.silentshield.io/api/v1/agent/telemetry | | directoryUrl | — | https://api.silentshield.io/api/v1/agent/bot-directory | | humanThreshold | — | 0.7 |

The known-agent token list (used to decide which requests are bot candidates) ships embedded and is refreshed from the bot directory at most once every ~24h, lazily and off the request path.

Fail-open behaviour

Everything is fail-open — if SilentShield is unreachable, your app keeps working:

• verify() never throws. On any network or parse error it resolves with { human: false, verdict: undefined, confidence: 0, requestId: undefined }. Decide your own policy for that case (block, allow, or soft-challenge).
• observe never throws and always calls next(). Telemetry is fire-and-forget; failures are silently ignored.

What gets sent (and when)

Telemetry is only sent for bot candidates — requests whose User-Agent matches a known agent token, or that carry an HTTP Message signature header. Human traffic is never reported. Each sighting contains: user-agent, IP, path (query stripped), method, and, when present, the HTTP Message Signature fields (signature, signature_input, signature_agent, authority, scheme).

GDPR / privacy note

• Server-side only. No cookies, no client-side JavaScript, no browser fingerprinting — nothing is stored on the visitor's device.
• IP handling. The raw IP is transmitted over TLS and hashed server-side; SilentShield does not retain raw IP addresses for telemetry.
• Scope. Only bot-candidate requests are observed. Ordinary human traffic is neither inspected beyond a UA/header check nor transmitted.
• Legal basis. Processing for bot/abuse detection rests on legitimate interest (Art. 6(1)(f) GDPR) in securing the service. Document it in your privacy policy and record of processing activities.

Enforcement — actually block AI bots (enforce)

observe only records visits. To block disallowed bots per the policy you set in the SilentShield dashboard, add the enforcer. It fetches the signed policy bundle, verifies its Ed25519 signature against the pinned keys, caches it, refreshes in the background, and decides per request — returning 403 for a denied bot and 429 for a throttled one. Fail-open: any error, an unverifiable bundle, or monitor mode lets the request through.

import express from "express";
import { enforce } from "@forge12interactive/silentshield-sdk-js";

const app = express();

// Put it first so blocked bots are turned away before your routes run.
app.use(enforce({ apiKey: process.env.SILENTSHIELD_SITE_KEY }));

app.get("/", (req, res) => res.send("hello"));
app.listen(3000);

Prerequisites for a real block: agent_gateway_enforce enabled and a Block rule set on the key in the dashboard (otherwise the bundle is monitor → nothing blocks). Bots are identified by User-Agent and treated as verified only when their source IP is in the operator's published range; behind a proxy, restore the real client IP into req.socket.remoteAddress.

createEnforcer(opts) returns { middleware, ready() } if you need the raw middleware or to await the first policy fetch (e.g. in tests).

License

MIT