# 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: region` *and* 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.
