@volter/twin-webrisk

A local Google Cloud Web Risk twin for offline URL-safety checks. It models the Runhuman-critical SearchUris path used by @google-cloud/web-risk, plus local submissions, deterministic threat-list diffs, hash lookup, and operation status envelopes.

world-webrisk serve [--port N] [--root DIR] [--read-only]
world-webrisk conformance [--root DIR]

Coverage

The capability manifest (src/webrisk-capabilities.ts) is an honest partial denominator for Google Cloud Web Risk v1/v1beta1/v1eap1: SearchUris, SearchHashes, ComputeThreatListDiff, SubmitUri, long-running operations, threat-list data types, submission metadata, auth/error behavior, and the preview EvaluateUri surface are enumerated.

Modeled:

• Auth: OAuth 2.0 Authorization: Bearer <token> enforcement and the x-goog-user-project quota header on the network path. Missing/malformed credentials return Google-shaped UNAUTHENTICATED (401); sentinel tokens exercise PERMISSION_DENIED (403) and RESOURCE_EXHAUSTED (429).
• SearchUris: GET /v1/uris:search and Google SDK fallback transport with deterministic safe/unsafe verdicts, threat-type filtering, validation, RFC3339 cache-expiry, and faithful Google URL canonicalization (host lowercasing, dot stripping, /./ + /../ resolution, slash collapse, fragment removal, repeated percent-unescaping).
• SearchHashes: real full-hash (SHA-256) matches for any local full hash sharing the requested 4-byte prefix (base64url binary transport), with negativeExpireTime cache hints and explicit empty matches.
• ComputeThreatListDiff: faithful update-client protocol against a deterministic local threat list — RAW hash additions, RiceDeltaEncoding (Golomb-Rice encoder/decoder that round-trips), database checksum = SHA-256 of the delivered prefix set, maxDiffEntries / maxDatabaseEntries constraints, supportedCompressions (RAW/RICE by name or number), and incremental diffs (matching versionToken → no-op DIFF).
• Submissions and operations: local POST /v1/projects/:project/uris:submit with parent-project validation; submission threatTypes + ThreatInfo (faithful AbuseType, deterministic Confidence score/level, and ThreatJustification labels/comments), SubmitUriMetadata.State lifecycle (resolves to SUCCEEDED), submission get and per-project list; operations get, list (/v1/projects/:project/operations), :wait, :cancel (no-op on a finished op → {}), and DELETE (removes the record → {}).
• EvaluateUri (v1eap1 preview): POST /v1eap1/uris:evaluate returns scored per-threat-type matches (abuseType + deterministic confidence score/level) rather than a binary verdict; safe URLs yield an empty score list.
• Type enums: faithful proto enums (names + numbers) for ThreatType (incl. THREAT_TYPE_UNSPECIFIED=0, rejected as a request value), CompressionType, ThreatInfo.AbuseType, Confidence.ConfidenceLevel, ThreatJustification.JustificationLabel, SubmitUriMetadata.State, ThreatDiscovery.Platform, and the historical Safe Browsing v4 PlatformType / ThreatEntryType names (retained for parity).
• Errors: RESOURCE_EXHAUSTED (429) carries google.rpc.RetryInfo (retryDelay) and QuotaFailure error details, as Google attaches.
• Audit: a local audit log of URL checks (GET /v1/twin/audit) recording method, resource, uri, threatTypes, and matched — read-only checks are not logged.
• v1beta1: uris:search, hashes:search, and threatLists:computeDiff compatibility endpoints route to the v1 handlers.
• Connector: injected-client pulls for verdicts, threat-list diffs (pullWebRiskDiff → threatlist state), full-hash matches (pullWebRiskHashes), project config (pullWebRiskProject → project state), and submission history (pullWebRiskSubmissions), all idempotent; push confirms local submissions.

Not yet modeled (honest todos): SubmitUri ThreatDiscovery (platform + regionCodes) targeting metadata, a v1eap1 SearchHashes preview surface, and project IAM policy (getIamPolicy / setIamPolicy / testIamPermissions).

Out of scope:

• Real Google threat intelligence, ML scoring, privacy-preserving global update list freshness, and enforcement-grade false-positive/false-negative behavior are what the real root does. The twin reproduces the full update/transport protocol (canonicalization, Rice encoding, checksums, version tokens) against a deterministic local list, but the list contents are local, not Google's. The per-URI confidence scores returned by EvaluateUri are deterministic local stand-ins (no hosted ML), faithful to the response shape only.

No UI mirror

Google Web Risk is a vendor whose product is the API: it is a threat-list lookup service called from server code, with no operator-facing product UI at all (its Cloud Console presence is project and quota administration). Per ../../../docs/contributing/adding-a-twin.md ("Does this vendor get a mirror?") and ../../../docs/contributing/architecture.md C1b, this pack ships no React mirror and no UI capabilities — omit rather than fabricate a dashboard. Coverage is API + connector.

Architecture

State lives in the @volter/world-core event/action log. The serve path makes no real network calls. Connector functions accept injected executors for real Web Risk I/O and are not used by the local handler.