@webdecoy/ai-protection 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,323 @@
+# WebDecoy AI Protection
+
+Bot and abuse protection for AI-powered applications. A small Node.js SDK that
+checks requests before your application invokes a model. Customer-defined rules run
+locally; proprietary bot detection runs in WebDecoy. See [architecture](ARCHITECTURE.md).
+
+**Alpha release: `0.1.0-alpha.1`.** Integration mechanics are tested;
+real-world detection accuracy and provider cost savings have not been established.
+Requires a WebDecoy property, a property-scoped API key, and a compatible WebDecoy
+service deployment. This repository contains the SDK, not the detection service.
+
+## Install
+
+```sh
+npm install @webdecoy/ai-protection@alpha
+```
+
+Node.js 22.22.3 or newer is required. The SDK has no runtime npm dependencies.
+Edge runtimes are not supported. Licensed under [Apache-2.0](LICENSE).
+
+Set `WEBDECOY_URL=https://ai-protection.webdecoy.com` on your server.
+Create a property-scoped API key with Write Detections permission in WebDecoy,
+then review results at [AI Protection](https://app.webdecoy.com/ai-protection).
+
+## Integrate
+
+Create the instance once in a **server-only module**, then call it inside your
+existing authenticated and validated AI endpoint:
+
+```ts
+import { createAIProtection } from '@webdecoy/ai-protection';
+
+const protect = createAIProtection({
+  webdecoyUrl: process.env.WEBDECOY_URL!,
+  webdecoyKey: process.env.WEBDECOY_KEY!,
+  propertyId: process.env.WEBDECOY_PROPERTY_ID!,
+  subjectSecret: process.env.WEBDECOY_SUBJECT_SECRET!, // random, >=32 characters
+  scopeId: 'support-chat',
+  route: '/api/chat', // fixed route template; never a user ID or raw URL
+  protectionMode: 'observe',
+  resolveClientIP: trustedClientIP, // implement for your ingress; see setup guide
+});
+
+// Inside your route, AFTER auth, origin checks, input validation and quotas:
+// return protect(request, () => callYourModelAndReturnResponse(request.signal));
+```
+
+`trustedClientIP` and `callYourModelAndReturnResponse` represent your application's
+existing infrastructure/model code; they are not SDK exports. The protected
+callback returns a standard `Response` or `Promise<Response>`.
+
+See the [Next.js / AI SDK guide](NEXTJS.md) and the [runnable local example](examples/nextjs).
+The guide documents trusted IP handling, cancellation and the complete integration flow.
+
+## What happens
+
+1. Your application validates and authenticates the request.
+2. Local rules evaluate server-supplied context. An enforced local denial stops
+   immediately, without waiting for cloud detection. Otherwise the SDK verifies its WebDecoy
+   property/account binding and sends request metadata.
+3. Cloud observation records bot verdicts without enforcing them. Each local
+   rule has its own observe/enforce mode; explicit customer policies still apply.
+4. With both local and account enforcement enabled on an entitled plan, block and
+   challenge verdicts return HTTP 403 before the callback.
+5. An allowed response streams through unchanged.
+
+WebDecoy outages **allow requests by default**. A missing or mismatched account
+binding falls back to observation and skips scoring. Missing trusted IPs also skip
+scoring and emit a degraded-coverage event. Successful chat alone does not prove
+protection is connected. Cancelled requests never start the protected callback. Enforced local rule errors
+return 503 by default; this is separate from remote detector failure behavior.
+A challenge verdict has no interactive verification UI in this alpha.
+
+## Data and scope
+
+The SDK sends IP address, method, URL pathname (not query), user agent, header
+names, accept-language and accept-encoding values for detection. Separate reporting
+sends decision/check metadata and handler outcomes; see [the full schema](ARCHITECTURE.md#reporting-and-hosting-lifecycle). It does **not** send request
+bodies, prompts, session cookies, authorization values or model responses.
+When browser evidence is explicitly enabled, only the WebDecoy receipt cookie is sent. Avoid sensitive
+identifiers in URL paths. Keys stay in your server environment.
+
+This SDK provides request admission, not prompt-injection filtering, verified
+agent identity, model/tool authorization or spending caps. Keep your existing
+authentication, origin checks, request limits and user quotas. A metadata verdict
+is not proof that a caller is human.
+
+## Explicit decisions and reporting
+
+The callable wrapper remains available. For custom enforcement use
+`protect.check(request, trustedContext)`, inspect `conclusion`, `reason`,
+`degraded` and `checks`, then call `protect.report(decision, outcome)` once.
+Reporting is best-effort and separate from the decision. Attach `waitUntil` to
+hosting lifecycle support; see [the contract and examples](ARCHITECTURE.md).
+Application outcomes, including local denials and unavailable checks, are sent
+asynchronously to WebDecoy and your observation sink. The dashboard identifies
+these as SDK reports, separately from detector evidence. Central delivery requires
+the compatible reporting endpoint; `reportToWebDecoy: false` disables it.
+
+## Configuration
+
+Required: `webdecoyUrl` (HTTPS AI Protection API origin; HTTP allowed only on loopback),
+`webdecoyKey`, `propertyId`, `scopeId`, `subjectSecret`, `resolveClientIP`.
+
+Optional: `protectionMode` (`enforce` by default; start pilots with `observe`),
+`detectorFailureMode` (`open` by default), `detectorTimeoutMs` (1000),
+`baselineLimit` (10), `baselineWindowMs` (60000), `rules` (none),
+`onObservation` (JSON stdout), `waitUntil` (hosting lifecycle hook),
+`reportingTimeoutMs` (1000), `maxPendingReports` (100), and `reportToWebDecoy` (true).
+The baseline is a process-local shadow comparison, not an enforced rate limit.
+
+Verified account bindings cache for 60 seconds; failures cache for 5 seconds.
+A cold binding lookup and detector call each have their own timeout (roughly two
+seconds total with defaults). Account changes are eventually consistent.
+Observation records describe admission and callback response creation, not stream
+completion, model usage, blocked spend or successful provider cancellation.
+
+## Develop
+
+```sh
+npm ci
+npm test
+npm run test:types
+npm run check:package
+cd examples/nextjs
+npm ci
+npm run build -- --webpack
+npm test
+```
+
+Tests use a local detector and local AI model; no live keys or paid inference.
+[Release instructions](RELEASING.md) cover publishing the public npm package.
+
+## Shared account quotas (opt-in)
+
+Configure `accountQuota` from trusted server code, after authenticating and
+validating the application's request:
+
+```js
+accountQuota: {
+  ruleId: 'chat_v1', limit: 20, windowSeconds: 60,
+  mode: 'enforce', failureMode: 'open',
+  subject: authenticated => ({accountId: authenticated.databaseId}),
+}
+```
+
+The subject callback is synchronous. Do not pass IDs or plan claims copied from
+browser headers/body. Optional `sessionLimit` and `sessionId` add a stricter session
+cap beneath the account cap; rotating sessions does not reset the account limit.
+The quota rule is independent of cloud/dashboard detection mode. It defaults to
+observation, with a one-second timeout and fail-open for state errors. Use
+`failureMode: 'closed'` explicitly to return 503 when a hard quota cannot be checked.
+Enforced exhaustion returns 429 and `Retry-After`; explicit `check` callers use
+`decision.retryAfterSeconds` and must enforce the decision themselves.
+
+This needs the shared quota backend (migration 78 and `/api/v1/sdk/ai-abuse/quota`).
+Observation and enforcement share counters. In default schema 1, each allowed
+admission consumes a unit, including retries and requests later cancelled/blocked
+by another check; there are no automatic retries or refunds. Opt-in schema 2
+adds bounded recovery of the same admission (see below). Counters
+use fixed UTC windows: up to twice the limit can pass across a window boundary.
+This does not bound concurrent inference or establish model-cost savings.
+
+The account ID is HMAC-SHA256 pseudonymized with the property and rule ID before
+transmission; no raw context or prompt is added to quota/report payloads. The
+secret defaults to `subjectSecret` and must be identical across replicas. An
+explicit `accountQuota.subjectSecret` can separate quota identity from other SDK
+observations. Rotating it resets quotas; coordinate rotation after the longest
+window. These identifiers are correlatable pseudonyms, not anonymous data.
+Backend retention removes expired buckets on access and in an hourly sweep;
+healthy maximum retention is the 24-hour maximum window plus one sweep, with
+possible extension during cleanup failure/backlog.
+
+One rule ID binds immutable limit/window/session-limit settings. Inconsistent
+replicas receive an unavailable check, governed by the configured failure policy;
+new policy versions deliberately create fresh counters. Bounds are 32 policies
+and 10,000 active account/session buckets per property. Quota-store errors and
+capacity limits do not change the detector's separate failure policy. State can
+commit just before a timeout, so a failed check does not prove no unit was used.
+
+
+## Distributed concurrency (unpublished, #1373)
+
+Optional concurrency policy shares per-account and property/feature capacity
+across app replicas. Defaults are observe/open; detector failure policy is
+independent. Authenticate first and derive the account ID from trusted server
+state. Keep rule IDs and subject secrets identical across replicas.
+
+Configure `concurrency: {ruleId: 'chat_v1', accountLimit: 2, featureLimit: 20,
+subject: user => ({accountId: user.databaseId})}` and call
+`protect.concurrent(request, async ({signal}) => ({response, finished}), user)`.
+Propagate signal to the provider. `finished` must be a Promise resolving only
+when all protected work has ended. The original Response is returned untouched.
+Use the host's waitUntil hook where required and validate host execution limits.
+The ordinary callable wrapper rejects concurrency configuration; `check` alone
+does not acquire a lease.
+
+Heartbeat TTL defaults to 30 seconds and maximum runtime to 300 seconds.
+Confirmed completion releases immediately. Errors, cancellation, crashes and
+lease loss retain capacity until maximum runtime, because cancellation is not
+proof a remote provider stopped. Upstream work must honor cancellation and have
+a real runtime bound. Fail-open outages cannot guarantee a concurrency cap.
+Released replay tombstones remain 24 hours: the pilot cap is 10,000 granted
+acquisitions/day/property and 32 policies/property. This is not a throughput SLA.
+The private app repository's `integrations/ai-abuse/CONCURRENCY.md` documents the
+wire contract, failure behavior, deployment order and validation evidence.
+
+
+## Upstream model budgets (unpublished, #1374)
+
+Opt-in token and integer micro-USD budgets reserve a conservative maximum before
+each provider attempt and reconcile only confirmed usage. Configure account,
+customer-organization and feature limits, a fixed UTC window, a trusted subject
+callback, and an explicit versioned model price catalog. Rates use micro-USD per
+million input/output tokens. Unknown prices are rejected before work; an explicit
+zero rate is permitted for intentionally free model usage, not unmeasured hosting.
+
+Use exported `createAIBudget(options)`, then
+`budget.run(user, {priceId, maxInputTokens, maxOutputTokens}, work, signal)`.
+The callback gets `{provider, model, maxInputTokens, maxOutputTokens, signal}`
+and returns `{value, finished: Promise<BudgetUsage|null>}`. The result contains
+the identical `value` and an `accounting` Promise; keep the latter alive using
+host waitUntil where needed. `BudgetDenied` carries 429/503 and Retry-After
+metadata before work. Missing/rejected usage retains the maximum charge.
+
+Defaults are observe/open, independently of detector availability. A hard budget
+requires explicit enforce/closed plus correctly enforced input/output bounds,
+accurate complete prices/usage and no hidden provider retries. Every retry,
+fallback and tool-loop model call needs a fresh reservation. Cancellation/crash/
+missing usage never automatically refunds charges. An actual overrun records debt
+and signals overrun but cannot undo an already-billed call. Fixed-window accounting
+is based on admission time, not the provider's invoice period.
+
+There is an Ollama final-usage normalizer for native generate/chat metadata;
+other provider clients need a reviewed application adapter. The SDK never parses
+or stores prompts/outputs to meter usage. This does not change WebDecoy plans or
+create a subscription meter. The private app's `integrations/ai-abuse/BUDGETS.md`
+contains examples, supported workloads, privacy, capacity and release gates.
+
+## Optional browser evidence
+
+Add `data-runtime-evidence="true"` to the existing WebDecoy scanner tag and set
+`browserEvidenceOrigin` to the exact HTTPS site origin (no trailing slash).
+Requires the compatible ingest/CDN deployment and a same-origin AI endpoint.
+The SDK forwards only the property-specific WebDecoy receipt, never the other
+cookies. The signed observation expires after 60 seconds and is bound to the
+property, origin, IP and user agent. Missing or invalid evidence fails open and
+adds an unavailable `browser_evidence` check; a clean receipt never overrides
+another denial. This is optional risk evidence, not proof of a human or identity.
+Start in observe mode; real-world accuracy has not been established.
+
+In browser code, optionally `await prepareBrowserEvidence()` from
+`@webdecoy/ai-protection/browser` before your existing chat fetch. The helper
+waits at most 1500ms by default and returns `{available: boolean}`. Continue the
+request regardless; server admission decides. Load the opted-in tag first.
+
+## Model-attempt reports
+
+Budget hooks now send separate start/finish events to WebDecoy automatically.
+Each attempt has a random call ID; pass the admission decision's request ID in
+`requestId` on the budget call (`decision.id`). The run returns `callId`.
+Keep `run.accounting` alive with host lifecycle support, then `budget.flush()`
+can drain queued reports. Budget reporting accepts `waitUntil`,
+`reportingTimeoutMs`, `maxPendingReports` and `reportToWebDecoy`.
+
+The dashboard labels callback starts and final usage as SDK-reported and joins
+retained reservations to confirm accounting. Neither is a provider invoice.
+Missing usage is unknown, and avoided cost is unavailable—not inferred from
+request denials. Usage events contain numeric tokens, configured rates and price/
+rule codes, but no prompts, responses, model names or raw user identities. Use
+non-sensitive price/rule codes. Reporting remains bounded and best effort;
+failures do not change provider results, trigger retries or refund charges.
+Requires the compatible usage endpoint; old backends may log reporting failures.
+
+## Release and runtime contract
+
+The SDK is published under Apache-2.0 on the `alpha` npm dist-tag. WebDecoy's
+hosted detection service is separate and is not included in this package.
+
+Control-plane JSON responses are capped at 64 KiB (2 KiB for stateful controls).
+Detector/config timeouts default to 1000ms each, maximum 10000ms. Trusted IP
+resolution has its own `clientIPTimeoutMs` (1000ms default, maximum 10000ms) and
+receives `{signal}` as its second argument. On timeout, cloud detection is skipped
+with degraded coverage. Resolver exceptions remain application errors; caller
+cancellation always prevents the callback. Resolvers must cooperate with abort.
+
+Set `route` to a stable template such as `/accounts/{id}/chat` when paths contain
+identifiers. Otherwise the pathname is used, with query/fragment omitted. The SDK
+does not trust forwarding headers automatically. Header names and the documented
+metadata values still leave the app; never place secrets in those values.
+
+Reporting timeouts and queue capacity each have a maximum of 10000 (ms/events).
+Application rules and hooks must not block the event loop. There is no unconditional
+wall-clock SLA for arbitrary customer code or uncooperative hosting runtimes.
+See RELEASE.md for supported versions, installation and release checks.
+
+### Recovering an uncertain quota admission (opt-in)
+
+After your runtime supports quota schema 2, set `accountQuota.idempotency: true`.
+The SDK generates one server-side operation ID and retries the quota RPC at most
+once after transport/5xx/malformed-response failures, keeping the same ID and
+payload. `timeoutMs` applies per attempt (at most twice that time overall).
+Cancellation stops retries; HTTP 4xx stops retries; there is no schema-1 fallback.
+Legacy configuration remains schema 1 with no automatic retry.
+
+To recover the same admission across requests/processes, generate and persist
+`createQuotaOperationId()` in trusted server state, and supply
+`accountQuota.operationId: context => context.persistedOperationId`. The local
+quota check exposes `operationId`; it is omitted from central reports. Never take
+this ID directly from an untrusted browser or reuse it for different operations.
+
+IDs expire ten minutes after creation (database clock, 30-second forward skew
+allowance). Expired IDs are rejected even after receipt cleanup. Capacity is
+10,000 retained operations/property, including denials. Identical replays return
+the original decision; changed payloads conflict. An unresolved response is
+`account_quota_outcome_unknown`, distinct from a known quota denial. Existing
+open/closed settings still apply. After expiry, do not mint a fresh ID to retry an
+unknown operation blindly. The stored quota count/retry hint is an original-window
+snapshot, not current quota state.
+
+Only admission is deduplicated. Repeated application/model calls still require
+application-level idempotency. Deploy migration 83, grants and runtime support
+before enabling this option; no package publication is required for local testing.

package/RELEASE.md

@@ -0,0 +1,75 @@
+# Supported installation and release candidate
+
+Private alpha candidate `@webdecoy/ai-protection@0.1.0-alpha.1`.
+Repository creation, public visibility, license approval and registry publication
+are separate owner decisions. The current manifest has `private: true` to prevent
+accidental publication. Do not advertise npm installation until it is released.
+
+## Supported surface
+
+- Node standard Request/Response on Node >=22.22.3; tests on 22.22.3 and 26.5.0.
+- Next.js Node Route Handler fixture: Next 16.3.6, React 19.3.0, AI SDK 7.0.117.
+  The tested provider is a deterministic local model, not an arbitrary SDK adapter.
+- Browser `./browser` entrypoint only for optional same-origin HTTPS receipt
+  preparation. It does not contain the server key or server SDK.
+- No server SDK claim for Cloudflare/Vercel Edge, Deno, Bun, generic WordPress or
+  Flowise. Other Node frameworks may call the Fetch API; adapters are not validated.
+
+## Install privately
+
+```sh
+npm ci --ignore-scripts
+npm test
+npm run test:types
+npm run check:package
+npm pack --ignore-scripts --pack-destination /your/private/artifact-directory
+```
+
+Install the exact tarball in the application (`npm install /path/to/file.tgz`) and
+commit its lockfile or retain the artifact in an approved private store. Do not
+make customer deployments depend on an absolute path to this development checkout.
+The Next.js example uses a local file link only for development and is not included
+in the package. A public npm command becomes valid only after owner-approved release.
+
+The package check builds the real tarball, verifies its exact file allowlist,
+checks zero runtime/optional dependencies and no install/postinstall hooks, prints
+integrity and installs it into a separate temporary consumer. It tests exports
+without access to the source checkout. No scripts execute during consumer install.
+
+## Availability and latency
+
+Default configured network waits before provider invocation:
+
+- IP resolver: <=1000ms waiting; callback must be cooperative, timeout degrades open.
+- Account/config: <=1000ms on cache miss (verified grant cached 60s, failures 5s).
+- Detection: <=1000ms; default failure policy open.
+- Optional quota: <=1000ms; default observe/open.
+- Optional concurrency acquire: <=1000ms; default observe/open.
+- Each optional budget reservation: <=1000ms; default observe/open.
+
+With a synchronous resolver, basic cold/warm admission has up to 2s/1s of configured
+remote waits. A resolver that stalls adds up to 1s then skips cloud calls. An async
+resolver that succeeds near its timeout can make cold admission approach 3s.
+All three optional controls can add another 3s before the first model attempt.
+Model runtime, auth/database work, CPU scheduling, event-loop stalls and customer
+rules are outside these configured waits. This is not a latency SLA. Each custom
+local rule must be synchronous and cheap. Never use remote I/O inside a local rule.
+
+Reports are asynchronous with bounded timeout/queue. `waitUntil` or Next `after`
+keeps delivery alive; response streaming is not modified. Budget accounting needs
+its own lifecycle wait until provider completion. On shutdown, stop accepting and
+drain requests/model work, then flush admission and budget reporters. Hard process
+termination can lose reports and leave conservative charges.
+
+## Release gate
+
+Before changing `private` or publishing: owner approves repository/license choices,
+verify npm identity and scope permission, pin the release commit and supported
+backend contracts, rerun checks, inspect the artifact/integrity and publish the
+exact reviewed candidate under `alpha`. Never commit tokens or bypass a failed
+registry authorization check. Backend scorer/keys remain private.
+
+The private application issue #1377 tracks the deployment/contract matrix and full
+evidence. Production capacity and arbitrary-provider behavior are not implied by
+passing local fixtures. The package contains no detector engine or executable
+remote policies.

package/account.mjs

@@ -0,0 +1,33 @@
+import {readJSON,abortable} from './transport.mjs';
+const uuid = /^[a-f\d]{8}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{12}$/i;
+export const validPropertyID = value => typeof value === 'string' && uuid.test(value) && value !== '00000000-0000-0000-0000-000000000000';
+
+// Short, bounded cache. Never reuse a paid grant after expiry on a failed refresh.
+export function createAccountBinding({webdecoyUrl, webdecoyKey, propertyId, detectorTimeoutMs, now = Date.now}) {
+  let cached, until = 0, pending;
+  return async signal => {
+    signal.throwIfAborted();
+    if (cached && now() < until) return cached;
+    if (pending) return abortable(pending,signal);
+    pending = (async () => {
+      let next = {status:'unavailable', enforce:false};
+      try {
+        const response = await fetch(new URL('/api/v1/sdk/ai-abuse/config', webdecoyUrl), {
+          headers:{Authorization:`Bearer ${webdecoyKey}`}, redirect:'error',
+          signal:AbortSignal.any([signal, AbortSignal.timeout(detectorTimeoutMs)])
+        });
+        if (!response.ok) { await response.body?.cancel(); throw new Error('account_unavailable'); }
+        const value = await readJSON(response);
+        if (value.schema !== 1 || !validPropertyID(value.property_id) || !validPropertyID(value.organization_id) ||
+            !['observe','enforce'].includes(value.mode) || value.observe !== true || typeof value.enforce !== 'boolean') throw new Error('invalid_account');
+        next = value.property_id.toLowerCase() === propertyId.toLowerCase()
+          ? {status:'verified', enforce:value.enforce, mode:value.mode, organization_id:value.organization_id, property_id:value.property_id}
+          : {status:'property_mismatch', enforce:false};
+      } catch { /* Unknown account state keeps chat available in observation. */ }
+      cached = next;
+      until = now() + (next.status === 'verified' ? 60000 : 5000);
+      return next;
+    })().finally(() => { pending = undefined; });
+    return abortable(pending,signal);
+  };
+}

package/admission.mjs

@@ -0,0 +1,87 @@
+import {readJSON} from './transport.mjs';
+import {prepareBrowserOrigin,browserEvidenceInput} from './browser-evidence.mjs';
+import { createAccountBinding, validPropertyID } from './account.mjs';
+import { randomUUID } from 'node:crypto';
+import { createBaseline, observationSubject } from './observation.mjs';
+
+// Adapters authenticate/validate their request and resolve a trustworthy client IP
+// before calling check. No model calls, sessions, routes or response rewriting here.
+export function createAdmission(options) {
+  const c = {protectionMode: 'enforce', detectorFailureMode: 'open', detectorTimeoutMs: 1000,
+    baselineLimit: 10, baselineWindowMs: 60000,
+    onObservation: event => console.log(JSON.stringify(event)), ...options};
+  if (!['observe', 'enforce'].includes(c.protectionMode) || !['open', 'closed'].includes(c.detectorFailureMode)) throw new Error('Invalid admission mode');
+  for (const key of ['detectorTimeoutMs', 'baselineLimit', 'baselineWindowMs']) {
+    if (!Number.isSafeInteger(c[key]) || c[key] <= 0) throw new Error(`Invalid ${key}`);
+  }
+  if(c.detectorTimeoutMs>10000)throw Error('detectorTimeoutMs must be <=10000');
+  const url = new URL(c.webdecoyUrl);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.pathname !== '/' || url.search || url.hash ||
+      (url.protocol !== 'https:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) throw new Error('Invalid detector origin');
+  if (!c.webdecoyKey || /[\r\n]/.test(c.webdecoyKey) || !c.scopeId || typeof c.subjectSecret !== 'string' || c.subjectSecret.length < 32 || typeof c.onObservation !== 'function') throw new Error('Invalid admission configuration');
+  if (!validPropertyID(c.propertyId)) throw new Error('An existing WebDecoy propertyId is required');
+  const browserOrigin=prepareBrowserOrigin(c.browserEvidenceOrigin);
+  const accountBinding = createAccountBinding(c);
+  const baseline = createBaseline({limit: c.baselineLimit, windowMs: c.baselineWindowMs});
+  return {
+    async check({ip, method, path, headers, signal = new AbortController().signal}) {
+      const requestId = randomUUID();
+      const accountStarted = performance.now();
+      const account = await accountBinding(signal);
+      const accountMs = Math.round((performance.now() - accountStarted) * 100) / 100;
+      const mode = account.status === 'verified' && account.enforce && account.mode === 'enforce' ? c.protectionMode : 'observe';
+      const observation = {event: 'webdecoy_admission', schema: 1, request_id: requestId,
+        timestamp: new Date().toISOString(), mode, requested_mode: c.protectionMode, property_id: c.propertyId,
+        account_status: account.status, account_ms: accountMs,
+        subject: observationSubject(c.subjectSecret, c.scopeId, ip),
+        baseline_limit: c.baselineLimit, baseline_window_ms: c.baselineWindowMs,
+        baseline_decision: baseline(ip), detector_decision: 'unavailable',
+        detector_ms: 0, action: 'unavailable', upstream_attempted: false};
+      if (account.status !== 'verified') {
+        observation.action = 'forwarded';
+        return {observation, allowed:true};
+      }
+      const checkStarted = performance.now();
+      let verdict;
+      try {
+        const response = await fetch(new URL('/api/v1/sdk/detect', c.webdecoyUrl), {
+          method: 'POST', redirect: 'error',
+          headers: {'Authorization': `Bearer ${c.webdecoyKey}`, 'Content-Type': 'application/json'},
+          signal: AbortSignal.any([signal, AbortSignal.timeout(c.detectorTimeoutMs)]),
+          body: JSON.stringify({
+            browser_evidence: browserEvidenceInput(browserOrigin,c.propertyId,headers),
+            decision_mode: 'unified_v1',
+            ai_admission: {request_id:requestId, mode},
+            request_metadata: {method, path, ip, user_agent: headers['user-agent'] ?? '', timestamp: Date.now()},
+            cs: {hn: Object.keys(headers), al: headers['accept-language'] ?? '', ae: headers['accept-encoding'] ?? ''},
+            local_analysis: {needs_verification: true}
+          })
+        });
+        if (!response.ok) { await response.body?.cancel(); throw new Error('detector_http'); }
+        verdict = await readJSON(response);
+        // Older servers ignore unknown request fields; require an explicit
+        // acknowledgement so a legacy metadata-only allow cannot look protected.
+        if (verdict?.decision_mode !== 'unified_v1') throw new Error('unsupported_decision_mode');
+        if (!['allow', 'block', 'challenge'].includes(verdict?.decision)) throw new Error('invalid_verdict');
+        observation.detector_decision = verdict.decision;
+        if(browserOrigin)observation.browser_evidence=['allow','block','challenge','missing','invalid'].includes(verdict.browser_evidence)?verdict.browser_evidence:'unsupported';
+      } catch {
+        if (mode === 'enforce' && c.detectorFailureMode === 'closed') {
+          observation.action = 'denied_unavailable';
+          return {observation, allowed: false, status: 503, error: 'protection_unavailable'};
+        }
+        // A failed check is not an abuse verdict. Preserve availability without
+        // relaxing origin, session, input, capacity or upstream authentication checks.
+        console.warn(JSON.stringify({event: 'webdecoy_check_unavailable', action: 'allowed_without_verdict'}));
+        verdict = {decision: 'allow'};
+      } finally { observation.detector_ms = Math.round((performance.now() - checkStarted) * 100) / 100; }
+      // A challenge is never silently accepted; interactive clearance is a later integration.
+      observation.action = mode === 'enforce' && verdict.decision !== 'allow' ? 'denied' : 'forwarded';
+      if (observation.action === 'denied') return {observation, allowed: false, status: 403, error: verdict.decision === 'challenge' ? 'verification_required' : 'request_denied'};
+      return {observation, allowed: true};
+    },
+    record(observation) {
+      try { c.onObservation(observation); } catch { console.warn('Observation sink failed'); }
+    }
+  };
+}

package/browser-evidence.mjs

@@ -0,0 +1,17 @@
+export function prepareBrowserOrigin(raw){
+ if(raw===undefined)return null;
+ const u=new URL(raw);
+ if(u.protocol!=='https:'||u.origin!==raw||u.username||u.password)throw Error('browserEvidenceOrigin must be an exact HTTPS origin');
+ return raw;
+}
+export function browserEvidenceInput(origin,property,headers){
+ if(!origin)return undefined;
+ const name='__Host-wd_runtime_'+property.toLowerCase();
+ const entries=(headers.cookie??'').split(';').map(p=>p.trim()).filter(p=>p.startsWith(name+'='));
+ const token=entries.length===1?entries[0].slice(name.length+1):'';
+ return {origin,token:token.length<=4096&&/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token)?token:''};
+}
+export function browserEvidenceCheck(status,mode){
+ const known=['allow','block','challenge'].includes(status);
+ return {id:'browser_evidence',source:'remote',mode,decision:known?(status==='block'?'deny':status):'unavailable',reason:'browser_evidence_'+(known||['missing','invalid'].includes(status)?status:'unsupported'),durationMs:0};
+}

package/browser.d.mts

@@ -0,0 +1,2 @@
+/** Refresh the installed browser tag's short-lived evidence; never blocks on failure. */
+export function prepareBrowserEvidence(options?:{timeoutMs?:number}):Promise<{available:boolean}>;

package/browser.mjs

@@ -0,0 +1,11 @@
+// Browser-only optional entrypoint; no server key, Node imports or scoring code.
+export function prepareBrowserEvidence({timeoutMs=1500}={}) {
+ if(!Number.isInteger(timeoutMs)||timeoutMs<1||timeoutMs>5000)throw Error('Invalid browser evidence timeout');
+ if(typeof window==='undefined'||typeof window.dispatchEvent!=='function')return Promise.resolve({available:false});
+ return new Promise(resolve=>{
+  let ended=false;
+  const finish=available=>{if(ended)return;ended=true;clearTimeout(timer);resolve({available:available===true})};
+  const timer=setTimeout(()=>finish(false),timeoutMs);
+  try{window.dispatchEvent(new CustomEvent('webdecoy:runtime-prepare',{detail:{done:finish}}))}catch{finish(false)}
+ });
+}