Hướng dẫn tích hợp Shield Cloud

<!-- Production: challenge.js (obfuscated). Dev: shield-sdk.js -->
<script src="https://shield-cloud.vercel.app/v1/challenge.js"
        data-site-key="pk_live_SITE_KEY_CUA_BAN"
        data-api="https://shield-cloud.vercel.app"
        data-mode="auto"></script>
<!-- data-mode: auto | manual | off
     data-difficulty: optional leading-zero bits (min = plan)
     Custom domain: data-api="https://token.yourdomain.com"
     Flow: PoW interstitial → cookie shield-token → gated APIs -->

// 1) Issue
const issue = await fetch("https://shield-cloud.vercel.app/v1/pow/issue", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Shield-Site-Key": "pk_live_SITE_KEY_CUA_BAN",
  },
  credentials: "include",
  body: JSON.stringify({ device_id: crypto.randomUUID() }),
});
// 2) Client solves SHA-256 or bandwidth (SDK handles this)
// 3) Verify → shield-token cookie
// Or simply:
const token = await window.ShieldSDK.getToken({ baseUrl: "https://shield-cloud.vercel.app" });
// 4) Call protected API
await window.ShieldSDK.fetch("https://shield-cloud.vercel.app/v1/login", { method: "POST", body: "..." });

// Trình duyệt — dùng Shield SDK (bắt buộc cho web)
// data-mode="auto" tự chạy interstitial PoW.
// Gated APIs: token one-time (jti) — luôn đọc lại getStoredToken() sau init.
async function shieldLogin(email, password) {
  const api = "https://shield-cloud.vercel.app";
  const siteKey = "pk_live_SITE_KEY_CUA_BAN";

  await window.ShieldSDK.getToken({ baseUrl: api });
  window.ShieldSDK.trackFormFocus();

  // initSession is gated → burns jti and rotates shield-token
  const init = await window.ShieldSDK.initSession(api);
  if (!init.ok) throw new Error("Shield init thất bại");

  // NEVER reuse token string from before init
  const shieldToken = window.ShieldSDK.getStoredToken();
  const extra = shieldToken ? { "X-Shield-Token": shieldToken } : {};

  if (init.needs_challenge) {
    const ch = await fetch(api + "/v1/challenge", {
      method: "POST",
      headers: {
        "Content-Type": "application/json; charset=utf-8",
        "X-Shield-Site-Key": siteKey,
      },
      credentials: "include",
      body: JSON.stringify({
        session_id: init.session_id,
        captcha_token: "human-verified",
      }),
    });
    const data = await ch.json();
    if (!ch.ok) throw new Error("Challenge thất bại");
    extra["X-Behavior-Token"] = data.behavior_token;
  }

  const res = await window.ShieldSDK.encryptedFetch(
    api,
    "/login",
    { username: email, password, time: Math.floor(Date.now() / 1000) },
    String(init.session_id),
    extra
  );
  return res.json();
}

// Prefer ShieldSDK.fetch for your own APIs (queue + rotate + retry)
// await window.ShieldSDK.fetch("/api/private", { credentials: "include" });

npm install @kimidevvn/shield-cloud-node

// npm install @kimidevvn/shield-cloud-node
import {
  ShieldClient,
  shieldMiddleware,
  assertShield,
  ShieldAuthError,
} from "@kimidevvn/shield-cloud-node";

// Env: SHIELD_SECRET_KEY=sk_live_...  SHIELD_API_BASE=https://shield-cloud.vercel.app
const opts = {
  secretKey: process.env.SHIELD_SECRET_KEY,
  apiBase: process.env.SHIELD_API_BASE || "https://shield-cloud.vercel.app",
};

// --- Express ---
// app.use(shieldMiddleware(opts));
// app.get("/api/me", (req, res) => res.json({ visitor: req.shield }));

// --- Next.js App Router ---
export async function GET(req) {
  try {
    const visitor = await assertShield(req, opts);
    return Response.json({
      site: visitor.site,
      sid: visitor.token.sid,
      score: visitor.token.score,
    });
  } catch (e) {
    if (e instanceof ShieldAuthError) return e.toResponse();
    throw e;
  }
}

// --- One-shot ---
const shield = new ShieldClient(opts);
const result = await shield.verify({ token: cookieOrHeader });
// result.token.score = risk (higher = more bot-like); optional: reject if > 40
if (!result.ok) throw new Error(result.error);

# DNS
token.yourdomain.com.  CNAME  shield-cloud.vercel.app.

# Portal → site → JS Challenge → Custom token domain = token.yourdomain.com

# Embed (portal auto-generates this)
<script src="https://token.yourdomain.com/v1/challenge.js"
        data-site-key="pk_live_SITE_KEY_CUA_BAN"
        data-api="https://token.yourdomain.com"
        data-mode="auto"></script>

# API resolves site by Host header on token.yourdomain.com
# GET/PATCH /saas/sites/:id → { challenge.tokenDomain, api_base, cname_target }

// shield-gate.js — Cloudflare Worker (Mode C)
// Secrets: wrangler secret put SHIELD_SECRET_KEY | SHIELD_SITE_KEY | SHIELD_API_BASE | ORIGIN
// SHIELD_API_BASE example: https://shield-cloud.vercel.app
// ORIGIN example: https://origin.yourdomain.com
// Deploy: npx wrangler deploy  →  attach route *yourdomain.com/*
// Flow: valid cookie shield-token → proxy ORIGIN; else interstitial → reload

const COOKIE = "shield-token";

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const token = readCookie(request, COOKIE);
    if (token && (await verifyToken(env, token))) {
      return proxyOrigin(request, env);
    }
    const accept = request.headers.get("Accept") || "";
    if (request.method === "GET" && accept.includes("text/html")) {
      return challengePage(env, url);
    }
    return new Response(
      JSON.stringify({ ok: false, code: 1124, error: "shield_token_required" }),
      {
        status: 403,
        headers: { "Content-Type": "application/json", "x-shield-action": "challenge" },
      }
    );
  },
};

function readCookie(request, name) {
  const raw = request.headers.get("Cookie") || "";
  const parts = ("; " + raw).split("; " + name + "=");
  if (parts.length < 2) return null;
  return decodeURIComponent(parts.pop().split(";").shift() || "");
}

async function verifyToken(env, token) {
  const api = String(env.SHIELD_API_BASE || "").replace(/\/$/, "");
  const secret = env.SHIELD_SECRET_KEY || "";
  if (!api || !secret) return false;
  try {
    const res = await fetch(api + "/v1/verify", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ secret_key: secret, token }),
    });
    if (!res.ok) return false;
    const data = await res.json();
    return Boolean(data.ok && data.valid);
  } catch {
    return false;
  }
}

async function proxyOrigin(request, env) {
  const originBase = String(env.ORIGIN || "").replace(/\/$/, "");
  if (!originBase) return new Response('ORIGIN secret not set', { status: 500 });
  const url = new URL(request.url);
  const target = new URL(url.pathname + url.search, originBase);
  const headers = new Headers(request.headers);
  headers.set("X-Forwarded-Host", url.host);
  headers.set("X-Shield-Gate", "1");
  return fetch(new Request(target, {
    method: request.method,
    headers,
    body: request.method === "GET" || request.method === "HEAD" ? null : request.body,
    redirect: "manual",
  }));
}

function challengePage(env, url) {
  const api = String(env.SHIELD_API_BASE || "").replace(/\/$/, "");
  const siteKey = env.SHIELD_SITE_KEY || "";
  const next = url.pathname + url.search;
  const html = `<!DOCTYPE html><html><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Security Check</title>
<style>body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
background:#060a12;color:#e8eef7;font-family:system-ui,sans-serif}</style></head><body>
<p>Shield Security Check…</p>
<script src="${api}/v1/challenge.js" data-site-key="${siteKey}" data-api="${api}" data-mode="auto"></script>
<script>document.addEventListener("shield:ready",function(){location.replace(${JSON.stringify(next)});});</script>
</body></html>`;
  return new Response(html, {
    headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" },
  });
}

# wrangler.toml (tối giản)
name = "shield-gate"
main = "shield-gate.js"
compatibility_date = "2024-11-01"

# Sau đó:
# npx wrangler secret put SHIELD_SECRET_KEY
# npx wrangler secret put SHIELD_SITE_KEY
# npx wrangler secret put SHIELD_API_BASE
# npx wrangler secret put ORIGIN
# npx wrangler deploy

# === auth-sidecar.mjs (Node 18+) — chạy cạnh Nginx ===
# env:
#   SHIELD_SECRET_KEY=sk_live_...
#   SHIELD_API_BASE=https://shield-cloud.vercel.app
#   PORT=9090

import http from "node:http";

const PORT = Number(process.env.PORT || 9090);
const API = String(process.env.SHIELD_API_BASE || "").replace(/\/$/, "");
const SECRET = process.env.SHIELD_SECRET_KEY || "";

function readCookie(header, name) {
  if (!header) return null;
  const parts = ("; " + header).split("; " + name + "=");
  if (parts.length < 2) return null;
  return decodeURIComponent(parts.pop().split(";").shift() || "");
}

async function verify(token) {
  if (!token || !API || !SECRET) return false;
  const res = await fetch(API + "/v1/verify", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ secret_key: SECRET, token }),
  });
  if (!res.ok) return false;
  const data = await res.json();
  return Boolean(data.ok && data.valid);
}

http.createServer(async (req, res) => {
  if (!req.url || !req.url.startsWith("/auth")) {
    res.writeHead(404);
    return res.end("not found");
  }
  const token = req.headers["x-shield-token"] || readCookie(req.headers.cookie, "shield-token");
  const ok = await verify(String(token || ""));
  res.writeHead(ok ? 200 : 401, {
    "x-shield-action": ok ? "allow" : "challenge",
  });
  res.end(ok ? "ok" : "challenge");
}).listen(PORT);

# Chạy: node auth-sidecar.mjs

# === nginx (fragment) ===
# location = /__shield_auth {
#   internal;
#   proxy_pass_request_body off;
#   proxy_set_header Content-Length "";
#   proxy_set_header Cookie $http_cookie;
#   proxy_pass http://127.0.0.1:9090/auth;
# }
# location / {
#   auth_request /__shield_auth;
#   error_page 401 403 = @shield_challenge;
#   proxy_pass http://origin_upstream;
# }
# location @shield_challenge {
#   default_type text/html;
#   # interstitial: script src=https://shield-cloud.vercel.app/v1/challenge.js data-site-key=pk_live_XXX data-api=https://shield-cloud.vercel.app data-mode=auto
#   # on shield:ready → location.reload()
# }

curl -X POST "https://shield-cloud.vercel.app/v1/challenge" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "X-Shield-Site-Key: pk_live_SITE_KEY_CUA_BAN" \
  -d '{"session_id":"SESSION_ID","captcha_token":"human-verified"}'