User-generated content

Any endpoint that accepts user-authored public content - posts, status updates, comments, replies, reviews - is a target for LLM-powered content generation. The right integration runs at the content-submit handler, blocks bot sessions, and uses the visitor fingerprint to cap posting velocity across account rotations.

The threat

Public content surfaces have two automation shapes stacked on top of each other:

Scripted posting - headless browsers or direct API calls submitting content on a schedule. Headless browsers get the automation attribution (Playwright, Puppeteer, Selenium). Direct API calls skip your page, so they carry no Foil token and your handler rejects them.
LLM-written content - the script is still automated, but now the content itself is generated by a language model in the same pipeline. The browser looks real because a real (headless) Chromium is driving it; the text looks real because it came from a capable LLM. Foil classifies the session by how the browser is driven, not by who wrote the text, so a script that posts LLM-written text is automation. The ai-agent category applies to agents that operate a browser themselves.

The second one is where policy has to be deliberate. Automation is unambiguously bad on a posting surface - no real human posts through Puppeteer. AI-generated content is blurrier: a human writing a post with LLM assistance is probably fine, an LLM agent posting hundreds of posts under one account is not. Foil doesn’t read the text. It sees whether a script, an agent, or a human drove the submission, regardless of who wrote the words. Three tactics dominate abuse on these endpoints:

Spam - outbound links, crypto shilling, promotion of other accounts or products.
Astroturfing - coordinated posting to manufacture consensus or suppress criticism.
Engagement farming - AI-generated posts designed to get reactions, build account reputation, and later pivot to spam or resale.

All three share the same detection target: a submission that wasn’t driven by a human at a keyboard.

The flow

Start Foil on the composer surface

Wherever the user actually drafts content - the compose modal, the reply box, the review form.

Call getSession() at the submit click

This captures keystroke timing, paste patterns, and the full fingerprint in the sealed handoff.

Verify and inspect the actor label

Check decision.verdict and the actor label in attribution.bot.labels (the label whose kind is actor). You’ll treat automation and ai-agent differently from human, and you may want to allow verified agents and crawlers through read endpoints (see API abuse).

Apply a visitor-fingerprint velocity cap

Even a “human” verdict shouldn’t let one fingerprint publish 200 posts per hour. Rate-limit by visitor_fingerprint.id, not just account ID.

Consider shadow mode

For surfaces where silent rejection is unacceptable, score content but don’t block - feed the verdict into trust-and-safety tooling instead.

Client integration

<script type="module">
  const foilPromise = import("https://cdn.usefoil.com/t.js").then(
    (Foil) =>
      Foil.start({
        publishableKey: "pk_live_your_publishable_key",
      }),
  );

  async function getFoilHandoff() {
    try {
      const foil = await foilPromise;
      return await foil.getSession();
    } catch (err) {
      // Send the post without a handoff. The server decides how to treat it.
      return null;
    }
  }

  document.querySelector("#post-form").addEventListener("submit", async (e) => {
    e.preventDefault();
    const foil = await getFoilHandoff();

    await fetch("/api/posts", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        body: e.target.body.value,
        foil,
      }),
    });
  });
</script>

If the script fails to load or getSession() fails, the page sends the post without a handoff, so a blocked script doesn’t leave the composer unresponsive. The server rejects a post without a valid token, as the next section shows. Keystroke and paste events are part of Foil’s behavioral signal set, and they fire strongest when the user is actually composing in your page. Mount the client on the composer, not just the top-level app shell.

Server verification

const { safeVerifyFoilToken } = require("@abxy/foil-server");

app.post("/api/posts", async (req, res) => {
  const result = safeVerifyFoilToken(
    req.body.foil?.sealedToken,
    process.env.FOIL_SECRET_KEY,
  );

  if (!result.ok) {
    return res.status(403).json({ error: "Verification failed" });
  }

  const { decision, attribution, visitor_fingerprint } = result.data;
  const actor = attribution?.bot?.labels?.find((label) => label.kind === "actor")?.value ?? null;

  if (decision.verdict === "bot") {
    // Block every kind of bot on the posting surface: automation, ai-agent,
    // crawler, and unknown. You might still allow some of them on read APIs.
    return res.status(403).json({ error: "Posting blocked" });
  }

  // Even on a human verdict, apply a per-fingerprint velocity cap.
  if (visitor_fingerprint?.id) {
    const tooFast = await exceedsPostingRate(visitor_fingerprint.id);
    if (tooFast) return res.status(429).json({ error: "Slow down" });
  }

  const post = await createPost({
    authorId: req.session.userId,
    body: req.body.body,
    foilSessionId: result.data.session_id,
    foilVerdict: decision.verdict,
    foilActor: actor,
  });

  res.json({ post });
});

from foil_server import safe_verify_foil_token
import os

@app.post("/api/posts")
def create_post(request):
    result = safe_verify_foil_token(
        (request.json.get("foil") or {}).get("sealedToken", ""),
        os.environ["FOIL_SECRET_KEY"],
    )

    if not result.ok:
        return {"error": "Verification failed"}, 403

    decision = result.data.decision
    labels = (result.data.attribution.bot or {}).get("labels", [])
    actor = next((label["value"] for label in labels if label["kind"] == "actor"), None)
    visitor = result.data.visitor_fingerprint

    if decision.verdict == "bot":
        return {"error": "Posting blocked"}, 403

    if visitor and exceeds_posting_rate(visitor.id):
        return {"error": "Slow down"}, 429

    post = create_post_row(
        author_id=request.user.id,
        body=request.json["body"],
        foil_session_id=result.data.session_id,
        foil_verdict=decision.verdict,
        foil_actor=actor,
    )
    return {"post": post}

import foil "github.com/abxy-labs/foil-server-go"

func postsHandler(w http.ResponseWriter, r *http.Request) {
    var body PostBody
    json.NewDecoder(r.Body).Decode(&body)

    tr := foil.SafeVerifyFoilToken(
        body.Foil.SealedToken,
        os.Getenv("FOIL_SECRET_KEY"),
    )
    if !tr.OK {
        http.Error(w, "Verification failed", 403)
        return
    }

    if tr.Data.Decision.Verdict == "bot" {
        http.Error(w, "Posting blocked", 403)
        return
    }

    if visitor := tr.Data.VisitorFingerprint; visitor != nil {
        if exceedsPostingRate(visitor.ID) {
            http.Error(w, "Slow down", 429)
            return
        }
    }

    post := createPost(body, tr.Data)
    json.NewEncoder(w).Encode(map[string]any{"post": post})
}

require "foil/server"

post "/api/posts" do
  body = JSON.parse(request.body.read)
  tr = Foil::Server::SealedToken.safe_verify_foil_token(
    body.dig("foil", "sealedToken"),
  )
  halt 403, { error: "Verification failed" }.to_json unless tr[:ok]

  decision = tr[:data][:decision]
  visitor  = tr[:data][:visitor_fingerprint]

  halt 403, { error: "Posting blocked" }.to_json if decision[:verdict] == "bot"

  if visitor && exceeds_posting_rate?(visitor[:id])
    halt 429, { error: "Slow down" }.to_json
  end

  post = create_post(current_user, body["body"], tr[:data])
  { post: post }.to_json
end

use Foil\Server\SealedToken;

$body = json_decode(file_get_contents("php://input"), true);
$tr = SealedToken::safeVerify(
    $body["foil"]["sealedToken"] ?? "",
    getenv("FOIL_SECRET_KEY"),
);

if (!$tr->ok) {
    http_response_code(403);
    echo json_encode(["error" => "Verification failed"]);
    exit;
}

if ($tr->data->decision["verdict"] === "bot") {
    http_response_code(403);
    echo json_encode(["error" => "Posting blocked"]);
    exit;
}

$visitorId = $tr->data->visitor_fingerprint["id"] ?? null;
if ($visitorId && exceedsPostingRate($visitorId)) {
    http_response_code(429);
    echo json_encode(["error" => "Slow down"]);
    exit;
}

$post = createPost($body, $tr->data);
echo json_encode(["post" => $post]);

# Session readback for moderation review - pull full attribution and signals
curl https://api.usefoil.com/v1/sessions/sid_... \
  -H "Authorization: Bearer sk_live_..."

Decisioning policy by actor label

The top-level verdict tells you whether to block; the actor label in attribution.bot.labels tells you why and helps you build useful signal for trust and safety teams. A session can have no actor label, so treat a missing label as unknown.

Actor label	Recommended action
`automation`	Block. No legitimate use of Puppeteer/Playwright posting through a real user account.
`ai-agent`	Block on posting; allow on read APIs. LLM agents reading your content is a product question; LLM agents posting under user accounts is abuse.
`crawler`	Block on posting. Crawlers don’t compose.
`unknown` or no label, with a `bot` verdict	Block. Log for investigation - new automation patterns show up here first.
No label, with a `human` verdict	Allow, subject to the velocity cap below.

Persist the actor label alongside the content row (the examples store it as foilActor or foil_actor). A post that was created with a human verdict but whose decision.manipulation.verdict is high is a useful thing to surface to moderators without blocking the user outright. decision.manipulation is null when Foil has no manipulation assessment for the session, so check for that before you read verdict. The server SDKs don’t check a token’s age. Reject a token whose decision.evaluated_at is more than a few minutes old, so that an attacker can’t replay a token captured from one session. See Verify the token on your server for the check in each language.

Velocity caps that survive account rotation

Attackers rotate accounts - making a hundred accounts and posting from each one is cheaper than making one account and posting a hundred times. A per-account rate limit catches the second pattern and misses the first. Per-fingerprint caps catch both: the visitor_fingerprint.id persists across account creation on the same device, so a fingerprint that signed up three times in six hours is already suspicious by the time it tries to post.

Node.js

const redis = require("redis");
const client = redis.createClient();
const connected = client.connect(); // node-redis v4 requires an explicit connect.

async function exceedsPostingRate(visitorId) {
  await connected;
  const key = `posts:${visitorId}`;
  const count = await client.incr(key);
  if (count === 1) await client.expire(key, 3600);
  return count > 30; // tune per your surface
}

Pair with a per-account cap. The two limits solve different problems: per-account stops one user flooding your feed; per-fingerprint stops one attacker flooding it from many accounts.

The server SDKs type visitor_fingerprint as nullable, so the examples check for a missing ID. Foil resolves the visitor fingerprint before it issues a token, so a token from the browser SDK carries one. If your code does see a missing ID, fall back to IP-based limiting.

Shadow mode

Not every surface can silently reject content. A comments section on a news site where users expect their comment to appear might reasonably want to ship the post even on a bot verdict - but route it to a moderation queue, not to the public feed. Or score against a shadow threshold for 30 days before flipping to enforcement. Two patterns worth keeping separate:

Shadow scoring - verify the token, persist the verdict alongside the post, publish the post anyway. Used to baseline verdict distribution before you turn enforcement on. See Going to production.
Shadow ban - accept the post, publish it to the author only, suppress it from other feeds. Useful against low-grade spam where you want to waste the spammer’s time rather than tip them off that detection fired.

Whichever you pick, don’t mix them accidentally. A post that’s “shadow scored” should still appear publicly; a post that’s “shadow banned” should not.

What’s next

API abuse & scraping

The read-side counterpart: allow crawlers, block LLM scrapers.

Signup protection

Stop the account factory before the posts start.

Verdicts & scoring

How verdict, risk_score, and attribution fit together.

Going to production

Report-only and shadow-mode rollout plans.

Overview

Get started

Integrate

Use cases

Learn

Resources

User-generated content

The threat

The flow

Client integration

Server verification

Decisioning policy by actor label

Velocity caps that survive account rotation

Shadow mode

What’s next

API abuse & scraping

Signup protection

Verdicts & scoring

Going to production

​The threat

​The flow

​Client integration

​Server verification

​Decisioning policy by actor label

​Velocity caps that survive account rotation

​Shadow mode

​What’s next

API abuse & scraping

Signup protection

Verdicts & scoring

Going to production

The threat

The flow

Client integration

Server verification

Decisioning policy by actor label

Velocity caps that survive account rotation

Shadow mode

What’s next