capjs-core 0.1.5 → 0.1.7

package/src/index.js

@@ -1,3 +1,15 @@
+import {
+  agentFromCodes,
+  agentFromHeaders,
+  agentFromTrace,
+  summarizeAgent,
+  verifyWebBotAuth,
+} from "./agents.js";
+import {
+  analyzeBehavior,
+  DEFAULT_BEHAVIOR_THRESHOLD,
+  validateTrace,
+} from "./behavior.js";
 import {
   decryptGcm,
   encryptGcm,
@@ -15,7 +27,29 @@ import {
   verifyInstrumentationResult,
 } from "./instrumentation.js";
 
+export {
+  agentFromHeaders,
+  agentFromTrace,
+  parseSignatureAgent,
+  summarizeAgent,
+  verifyWebBotAuth,
+} from "./agents.js";
+export {
+  analyzeBehavior,
+  BEHAVIOR_WEIGHTS,
+  DEFAULT_BEHAVIOR_THRESHOLD,
+  WEAK_CAP,
+} from "./behavior.js";
+
 export { detectAutomation } from "./detect.js";
+export {
+  boundValues,
+  canonicalize,
+  generateInstrumentation,
+  MAX_BOUND_DATA,
+  serializeBound,
+  verifyInstrumentationResult,
+} from "./instrumentation.js";
 
 import { mintHashwxChallenges, verifyHashwxSolution } from "./hashwx.js";
 
@@ -106,6 +140,161 @@ function assertSecret(secret) {
   }
 }
 
+function behaviorPolicy(opt) {
+  if (!opt) return null;
+  const o = typeof opt === "object" ? opt : {};
+  const th = Number(o.threshold);
+  return {
+    b: o.block === true ? 1 : 0,
+    s: o.strict === true ? 1 : 0,
+    r: o.requireInteraction === false ? 0 : 1,
+    th: th >= 0.1 && th <= 1 ? th : DEFAULT_BEHAVIOR_THRESHOLD,
+    ag: o.blockAgents === "all" ? 2 : o.blockAgents === "identified" ? 1 : 0,
+    va: o.allowVerifiedAgents === true ? 1 : 0,
+  };
+}
+
+async function requestAgentEvidence(evidence, opts) {
+  const req = opts.request;
+  if (!req?.headers) return null;
+  evidence.push(...agentFromHeaders(req.headers));
+  if (opts.verifyWebBotAuth !== true || !req.method || !req.url) return null;
+  if (!evidence.some((e) => e.evidence.startsWith("signature_agent:")))
+    return null;
+  return verifyWebBotAuth(req, {
+    authority:
+      opts.webBotAuthAuthority ??
+      (URL.canParse(req.url) ? new URL(req.url).host : null),
+    fetch: opts.fetch,
+    trustedOrigins: opts.trustedSignatureAgents,
+    nonceCheck: opts.webBotAuthNonceCheck,
+  });
+}
+
+const INSTR_ERROR_REASONS = {
+  csp_blocked: "instr_csp_blocked",
+  csp_script_blocked: "instr_csp_blocked",
+  natives_tampered: "instr_natives_tampered",
+  env_failed: "instr_env_failed",
+  script_failed: "instr_script_failed",
+};
+
+const instrErrorReason = (code) =>
+  Object.hasOwn(INSTR_ERROR_REASONS, code)
+    ? INSTR_ERROR_REASONS[code]
+    : "instr_failed";
+
+async function evaluateBehavior(policy, trace, payload, opts, bound) {
+  if (policy.ag > 0 && bound?.host === false) {
+    return {
+      fail: fail(
+        bound.isolated
+          ? "instr_isolated"
+          : bound.legacy
+            ? "instr_widget_outdated"
+            : "instr_host_unreachable",
+        { instr_error: true },
+      ),
+    };
+  }
+  const ctx = { strict: policy.s === 1, threshold: policy.th };
+  let pre = analyzeBehavior(trace, ctx);
+  if (pre.digest && typeof opts.behaviorReplayCheck === "function") {
+    const ttlMs = Math.max(60_000, (payload.exp ?? Date.now()) - Date.now());
+    let replayed = false;
+    try {
+      replayed = (await opts.behaviorReplayCheck(pre.digest, ttlMs)) === true;
+    } catch {}
+    if (replayed) pre = analyzeBehavior(trace, { ...ctx, replayed: true });
+  }
+  const evidence = (
+    trace && !validateTrace(trace) ? agentFromTrace(trace) : []
+  ).map((e) =>
+    e.agent === "gemini-in-chrome" && bound?.browser === "brave"
+      ? { ...e, agent: "brave-leo" }
+      : e,
+  );
+  if (bound) {
+    const seen = new Set(evidence.map((e) => e.evidence));
+    evidence.push(
+      ...agentFromCodes(bound.all).filter((e) => !seen.has(e.evidence)),
+    );
+  }
+  const verification = await requestAgentEvidence(evidence, opts);
+  const agent = summarizeAgent(evidence, verification);
+
+  let verdict = pre.verdict;
+  if (agent?.detected && verdict !== "automated") verdict = "agent";
+
+  const behavior = {
+    score: pre.score,
+    verdict,
+    flags: pre.flags,
+    signals: pre.signals,
+    ...(agent && { agent }),
+  };
+  const flags = pre.verdict === "missing" ? ["bh_missing"] : [...pre.flags];
+  if (agent?.detected) flags.push(`agent:${agent.name}`);
+
+  const blockAgent =
+    agent?.detected &&
+    !(policy.va === 1 && agent.verified) &&
+    (policy.ag === 2 || (policy.ag === 1 && agent.confidence === "high"));
+  if (blockAgent) {
+    return { fail: fail("behavior_agent", { behavior }) };
+  }
+  if (pre.verdict === "missing") {
+    if ((bound?.legacy || bound?.isolated) && policy.b !== 1) {
+      return { behavior, flags };
+    }
+    return { fail: fail("behavior_missing", { behavior }) };
+  }
+  if (policy.b === 1) {
+    if (pre.verdict === "automated") {
+      return { fail: fail("behavior_automated", { behavior }) };
+    }
+    if (policy.r === 1 && pre.verdict === "no_interaction") {
+      return { fail: fail("behavior_no_interaction", { behavior }) };
+    }
+  }
+  return { behavior, flags };
+}
+
+function sealedInstrMeta(instr, expires) {
+  if (!instr?.binding && !Array.isArray(instr?.expectedVals)) {
+    throw new Error(
+      "[capjs-core] instrumentationGenerator must return the binding from generateInstrumentation, or expectedVals",
+    );
+  }
+  return {
+    id: instr.id,
+    ...(Number.isFinite(instr.iat) && { iat: instr.iat }),
+    vars: instr.vars,
+    ...(instr.binding
+      ? { binding: instr.binding }
+      : { expectedVals: instr.expectedVals }),
+    blockAutomatedBrowsers: instr.blockAutomatedBrowsers === true,
+    blockAutomatedInteractions: instr.blockAutomatedInteractions === true,
+    detectAutomatedInteractions: instr.detectAutomatedInteractions === true,
+    behavior: instr.behavior === true,
+    behaviorEnforced: instr.behaviorEnforced === true,
+    expires,
+  };
+}
+
+function instrOptions(opts, ttlMs, bh) {
+  const base =
+    typeof opts.instrumentation === "object" && opts.instrumentation !== null
+      ? opts.instrumentation
+      : {};
+  return {
+    ...base,
+    ttlMs,
+    behavior: !!bh,
+    behaviorEnforced: !!bh && (bh.b === 1 || bh.ag > 0),
+  };
+}
+
 export async function generateChallenge(secret, opts = {}) {
   assertSecret(secret);
 
@@ -145,29 +334,21 @@ export async function generateChallenge(secret, opts = {}) {
   };
   if (opts.scope) payload.sk = String(opts.scope);
   if (opts.extra && typeof opts.extra === "object") payload.x = opts.extra;
+  const bh = behaviorPolicy(opts.behavior);
+  if (bh) payload.bh = bh;
 
   let instrumentation;
-  if (opts.instrumentation) {
-    const instrOpts =
-      typeof opts.instrumentation === "object" ? opts.instrumentation : {};
+  if (opts.instrumentation || bh) {
     const generator = opts.instrumentationGenerator || generateInstrumentation;
-    const instr = await generator({ ...instrOpts, ttlMs });
-    payload.ei = encryptGcm(
-      {
-        id: instr.id,
-        expectedVals: instr.expectedVals,
-        vars: instr.vars,
-        blockAutomatedBrowsers: instr.blockAutomatedBrowsers,
-        expires,
-      },
-      secret,
-    );
+    const instr = await generator(instrOptions(opts, ttlMs, bh));
+    payload.ei = encryptGcm(sealedInstrMeta(instr, expires), secret);
     instrumentation = instr.instrumentation;
   }
 
   const token = jwtSign(payload, secret);
   const result = { challenge: { c, s, d }, token, expires };
   if (instrumentation) result.instrumentation = instrumentation;
+  if (bh) result.behavior = true;
   return result;
 }
 
@@ -232,7 +413,22 @@ export async function validateChallenge(secret, body, opts = {}) {
     }
   }
 
+  if (typeof opts.consumeNonce === "function") {
+    const sig = jwtSigHex(body.token);
+    if (!sig) return fail("invalid_token");
+    const ttlMs = Math.max(1, payload.exp - Date.now());
+    let claimed;
+    try {
+      claimed = await opts.consumeNonce(sig, ttlMs);
+    } catch (err) {
+      return fail("nonce_store_error", { error: String(err?.message || err) });
+    }
+    if (!claimed) return fail("already_redeemed");
+  }
+
   let riskFlags = [];
+  let bound = null;
+  let trace = null;
   if (payload.ei) {
     const instrMeta = decryptGcm(payload.ei, secret);
     if (!instrMeta) return fail("instr_corrupted", { instr_error: true });
@@ -247,6 +443,8 @@ export async function validateChallenge(secret, body, opts = {}) {
           : "instr_failed",
         { instr_error: true },
       );
+    } else if (typeof body.instr_error === "string") {
+      return fail(instrErrorReason(body.instr_error), { instr_error: true });
     } else if (body.instr_timeout === true) {
       return fail("instr_timeout", { instr_error: true });
     } else if (body.instr) {
@@ -258,22 +456,25 @@ export async function validateChallenge(secret, body, opts = {}) {
         });
       }
       if (r.riskFlags?.length) riskFlags = [...riskFlags, ...r.riskFlags];
+      if (r.agent) bound = r.agent;
+      trace = r.trace ?? null;
     } else {
       return fail("instr_missing", { instr_error: true });
     }
   }
 
-  if (typeof opts.consumeNonce === "function") {
-    const sig = jwtSigHex(body.token);
-    if (!sig) return fail("invalid_token");
-    const ttlMs = Math.max(1, payload.exp - Date.now());
-    let claimed;
-    try {
-      claimed = await opts.consumeNonce(sig, ttlMs);
-    } catch (err) {
-      return fail("nonce_store_error", { error: String(err?.message || err) });
-    }
-    if (!claimed) return fail("already_redeemed");
+  let behavior;
+  let agent = null;
+  if (payload.bh && typeof payload.bh === "object") {
+    const r = await evaluateBehavior(payload.bh, trace, payload, opts, bound);
+    if (r.fail) return r.fail;
+    behavior = r.behavior;
+    if (r.flags.length) riskFlags = [...riskFlags, ...r.flags];
+  } else {
+    const evidence = bound ? agentFromCodes(bound.all) : [];
+    const verification = await requestAgentEvidence(evidence, opts);
+    agent = evidence.length ? summarizeAgent(evidence, verification) : null;
+    if (agent?.detected) riskFlags = [...riskFlags, `agent:${agent.name}`];
   }
 
   const tokenTtlMs = opts.tokenTtlMs ?? DEFAULT_TOKEN_TTL_MS;
@@ -292,6 +493,8 @@ export async function validateChallenge(secret, body, opts = {}) {
       scope: payload.sk ?? null,
       iat: payload.iat,
       riskFlags,
+      ...(behavior && { behavior }),
+      ...(agent && { agent }),
     };
   }
 
@@ -306,14 +509,21 @@ export async function validateChallenge(secret, body, opts = {}) {
     scope: payload.sk ?? null,
     iat: payload.iat,
     riskFlags,
+    ...(behavior && { behavior }),
+    ...(agent && { agent }),
   };
 }
 
 async function generateChallengeV2(secret, opts) {
-  const protocols =
+  const bh = behaviorPolicy(opts.behavior);
+  const requested =
     Array.isArray(opts.protocols) && opts.protocols.length
       ? opts.protocols
       : ["rsw"];
+  const protocols =
+    bh && !requested.includes("instrumentation")
+      ? [...requested, "instrumentation"]
+      : requested;
   const ttlMs = opts.expiresMs ?? DEFAULT_CHALLENGE_TTL_MS;
   const now = Date.now();
   const exp = now + ttlMs;
@@ -361,27 +571,16 @@ async function generateChallengeV2(secret, opts) {
         expected.push({ protocol: "hashwx", ...minted.expected });
       }
     } else if (proto === "instrumentation") {
-      const instrOpts =
-        typeof opts.instrumentation === "object" &&
-        opts.instrumentation !== null
-          ? opts.instrumentation
-          : {};
       const generator =
         opts.instrumentationGenerator || generateInstrumentation;
-      const instr = await generator({ ...instrOpts, ttlMs });
+      const instr = await generator(instrOptions(opts, ttlMs, bh));
       challenges.push({
         protocol: "instrumentation",
         payload: { blob: instr.instrumentation },
       });
       expected.push({
         protocol: "instrumentation",
-        instrMeta: {
-          id: instr.id,
-          expectedVals: instr.expectedVals,
-          vars: instr.vars,
-          blockAutomatedBrowsers: instr.blockAutomatedBrowsers,
-          expires: exp,
-        },
+        instrMeta: sealedInstrMeta(instr, exp),
       });
     } else {
       throw new Error(`[capjs-core] unknown protocol '${proto}'`);
@@ -397,9 +596,12 @@ async function generateChallengeV2(secret, opts) {
   };
   if (opts.scope) tokenPayload.sk = String(opts.scope);
   if (opts.extra && typeof opts.extra === "object") tokenPayload.x = opts.extra;
+  if (bh) tokenPayload.bh = bh;
 
   const token = jwtSign(tokenPayload, secret);
-  return { token, format: 2, challenges, expires: exp };
+  const result = { token, format: 2, challenges, expires: exp };
+  if (bh) result.behavior = true;
+  return result;
 }
 
 async function validateChallengeV2(secret, body, payload, opts = {}) {
@@ -412,9 +614,13 @@ async function validateChallengeV2(secret, body, payload, opts = {}) {
   const expected = decrypted.expected;
   const solutions = body.solutions;
   let riskFlags = [];
+  let bound = null;
+  let trace = null;
 
-  if (solutions.length !== expected.length) return fail("invalid_solutions");
+  if (!Array.isArray(solutions) || solutions.length !== expected.length)
+    return fail("invalid_solutions");
 
+  const instrSteps = [];
   for (let i = 0; i < expected.length; i++) {
     const e = expected[i];
     const s = solutions[i];
@@ -432,32 +638,7 @@ async function validateChallengeV2(secret, body, payload, opts = {}) {
     } else if (e.protocol === "hashwx") {
       if (!(await verifyHashwxSolution(e, s))) return fail("invalid_solution");
     } else if (e.protocol === "instrumentation") {
-      const meta = e.instrMeta;
-      if (!meta) return fail("instr_corrupted", { instr_error: true });
-      if (meta.expires && Date.now() > meta.expires) {
-        return fail("instr_expired", { instr_error: true });
-      }
-      if (s.blocked === true) {
-        return fail(
-          meta.blockAutomatedBrowsers
-            ? "instr_automated_browser"
-            : "instr_failed",
-          { instr_error: true },
-        );
-      } else if (s.timeout === true) {
-        return fail("instr_timeout", { instr_error: true });
-      } else if (s.instr) {
-        const r = verifyInstrumentationResult(meta, s.instr);
-        if (!r.valid) {
-          return fail(r.reason || "instr_failed", {
-            instr_error: true,
-            ...(r.blockedBy && { blockedBy: r.blockedBy }),
-          });
-        }
-        if (r.riskFlags?.length) riskFlags = [...riskFlags, ...r.riskFlags];
-      } else {
-        return fail("instr_missing", { instr_error: true });
-      }
+      instrSteps.push([e.instrMeta, s]);
     } else {
       return fail("invalid_solution");
     }
@@ -476,6 +657,52 @@ async function validateChallengeV2(secret, body, payload, opts = {}) {
     if (!claimed) return fail("already_redeemed");
   }
 
+  for (const [meta, s] of instrSteps) {
+    if (!meta) return fail("instr_corrupted", { instr_error: true });
+    if (meta.expires && Date.now() > meta.expires) {
+      return fail("instr_expired", { instr_error: true });
+    }
+    if (s.blocked === true) {
+      return fail(
+        meta.blockAutomatedBrowsers
+          ? "instr_automated_browser"
+          : "instr_failed",
+        { instr_error: true },
+      );
+    }
+    if (typeof s.error === "string") {
+      return fail(instrErrorReason(s.error), { instr_error: true });
+    }
+    if (s.timeout === true) {
+      return fail("instr_timeout", { instr_error: true });
+    }
+    if (!s.instr) return fail("instr_missing", { instr_error: true });
+    const r = verifyInstrumentationResult(meta, s.instr);
+    if (!r.valid) {
+      return fail(r.reason || "instr_failed", {
+        instr_error: true,
+        ...(r.blockedBy && { blockedBy: r.blockedBy }),
+      });
+    }
+    if (r.riskFlags?.length) riskFlags = [...riskFlags, ...r.riskFlags];
+    if (r.agent) bound = r.agent;
+    trace = r.trace ?? null;
+  }
+
+  let behavior;
+  let agent = null;
+  if (payload.bh && typeof payload.bh === "object") {
+    const r = await evaluateBehavior(payload.bh, trace, payload, opts, bound);
+    if (r.fail) return r.fail;
+    behavior = r.behavior;
+    if (r.flags.length) riskFlags = [...riskFlags, ...r.flags];
+  } else {
+    const evidence = bound ? agentFromCodes(bound.all) : [];
+    const verification = await requestAgentEvidence(evidence, opts);
+    agent = evidence.length ? summarizeAgent(evidence, verification) : null;
+    if (agent?.detected) riskFlags = [...riskFlags, `agent:${agent.name}`];
+  }
+
   const tokenTtlMs = opts.tokenTtlMs ?? DEFAULT_TOKEN_TTL_MS;
   const tokenExpires = Date.now() + tokenTtlMs;
 
@@ -492,6 +719,8 @@ async function validateChallengeV2(secret, body, payload, opts = {}) {
       scope: payload.sk ?? null,
       iat: payload.iat,
       riskFlags,
+      ...(behavior && { behavior }),
+      ...(agent && { agent }),
     };
   }
 
@@ -506,5 +735,7 @@ async function validateChallengeV2(secret, body, payload, opts = {}) {
     scope: payload.sk ?? null,
     iat: payload.iat,
     riskFlags,
+    ...(behavior && { behavior }),
+    ...(agent && { agent }),
   };
 }