Web identity: counting visitors without a cookie, and what the door keeps
A web project chooses how its door recognises a returning visitor, and what it does with the address
and the User-Agent of every request. This page is the contract. Everything here sits behind the
product-analytics gate (PA-01): with ANALYTICS_DPA_VERSION null, or the project's setting off, every
read and write below refuses with analytics_not_enabled and stores nothing.
Three identity modes
| Mode | What recognises a visitor | Session | identify |
|---|---|---|---|
cookie (the default) |
an id the SDK persists in the browser, under the project's consent basis | the SDK's | as the consent basis allows |
cookieless_stateless |
a key computed at the door, new every UTC day | one per key per day, no row | never |
cookieless_stateful |
the same key | 30 minutes of inactivity, in web_cookieless_sessions, purged daily |
only with consent, flagged consentGated in the evidence |
The key, in both cookieless modes:
inner = HMAC-SHA256(salt[project, UTC day], registrableDomain ‖ UA ‖ IP)
key = keyedPseudonym(projectKey, 'visitor', day ‖ inner) 32 hex = 128 bits
The registrable domain makes www.example.com and shop.example.com one site (a short built-in
suffix list, not the full Public Suffix List: an unknown suffix groups one label too coarsely, which
merges two sites rather than splitting one). ::ffff:1.2.3.4 and 1.2.3.4 are one address. With no
User-Agent and no address there is no key; the door does not put everyone in one "visitor".
The daily salt, and why destroying it is the feature
web_daily_salts holds 128 random bits per project and UTC day, sealed with the at-rest envelope
(purpose bucker:web-daily-salt, the row's natural key as AAD, so a copied ciphertext does not open).
A salt is kept for its day plus 72 hours (late data from an offline SDK still joins the right
key) and is then destroyed by the retention pass: the ciphertext is overwritten, destroyedAt is set
and a signed deletion_sweep receipt (stream web_daily_salts, one per organization and day, naming
the day and the project) is appended to the organization's receipt log in the same transaction.
After that nothing can recompute a key of that day from a guess of its inputs; and a late event for a
destroyed day gets no key rather than a fresh salt, because a second key for one day would split one
visitor in two. The sweep runs whether or not the analytics gate is open.
The day is the UTC day: a project has no timezone setting.
Derive, then drop
Before the address and the User-Agent are discarded the door derives, and stores only:
- country (and a region only if the project set
regionResolution: regionand the database has one), - traffic type, category and operator, and the network class,
- browser, operating-system and device families (no versions).
No web table has a column for a raw address or User-Agent (the tenant-key test enforces the naming
rule), assertCoarseFacts re-checks the derived result and throws on a value that parses as an
address or looks like a User-Agent, and a test scans the stored rows after a real cookieless hit.
Country resolution (the ip_geo seam)
shared/src/providers/ip-geo.ts on ProviderRegistry. Providers: dbip_lite (default; reads the
DB-IP Lite country CSV named by IP_GEO_DATABASE_PATH, optionally gzipped) and none. The policy for
a provider that is selected and cannot be built is fail closed to a null country: a missing,
unreadable or empty file, or a misspelt provider name, makes every lookup answer "unknown". Never a
guess, never a fallback to another source. The log-drain mappers (Vercel; Cloudflare when the line has
no country of its own) take their country from the same seam.
The data is DB-IP Lite, CC BY 4.0. The attribution line is printed on the trust page and is the
constant DBIP_ATTRIBUTION; api/test/web/ip-geo.test.ts holds the two equal. Obtaining the file and
confirming its licence terms are a human item (H-61).
IP-prefix retention (off by default)
ipRetentionDays is 0. A project may turn on retention of the IPv4 /24 or IPv6 /48 prefix (never a
finer address) for 1 to 30 days. Turning it off purges the kept prefixes and writes a signed
receipt (stream web_ip_prefixes) in the same transaction. This build has no storage for a prefix
(no column exists, and a raw address column would fail the naming rule), so the purge is the
IpPrefixStore seam and the receipt honestly records the rows that seam reports (zero by default).
The settings, and who may change them
| Act | Registry action | Who |
|---|---|---|
| Set the identity mode | web_identity_mode.update |
a person's own session, org:admin (OWNER) |
| Set the IP-prefix retention | web_ip_retention.update |
a person's own session, org:admin (OWNER) |
Both are human-only: an agent, a service principal, an OAuth-client token and a derived session are
refused before anything is read, and there is no MCP tool. A change toward a longer-lived
identifier (stateless to stateful to cookie; retention turned on or lengthened) is a loosening and
needs a second owner, or the hold for an organization with one, through the human-requester path.
A tightening (or no change) is one owner's act, applied at once. The direct door never applies a
loosening on one person's say: it answers 409 LOOSENING_NEEDS_SECOND_OWNER. Every change is forward
only: sessions and keys already stored keep the mode they were written under.
REST
GET /orgs/:o/projects/:p/web/settings mode, regionResolution, ipRetentionDays, cookielessShare, tunnelledShare
PUT /orgs/:o/projects/:p/web/identity-mode { mode, reason }
PUT /orgs/:o/projects/:p/web/ip-retention { days, reason }
cookielessShare is the share of the last seven days' sessions counted without a cookie; the same
read feeds web_capture_get. tunnelledShare is null until a door records tunnelled arrivals.