Skip to content
bucker

Data access and the personal-data read ledger

Who may read which data, and the record that they did. Two things live here: data access (who is allowed to read a restricted slice of a dataset) and the read ledger (one audit row for every read of personal data). Both are enforced by the server; the dashboard only shows them.

Data classes

Class What it is Default Needs pii:read
person_level Who did what: subjects, their events, the identity ledger restricted yes
replay Recorded sessions of a person restricted yes
survey_response An answer someone gave, with the identity they gave restricted yes
aggregate Counts and rates over a cohort at or above the project's floor unrestricted no
telemetry Spans, logs, metrics and error events: about the software unrestricted no

The defaults are the decision taken in code (OD-DP-07): person-level product data is restricted until an organization says who may read it. An organization changes the mode of a class; it cannot add a class or change what a class is.

Who may read a person

Reading a person is a person's act. A call is refused before the organization's policy is read when the caller is an agent, a service, an OAuth client (even for the person who authorized it), a delegated call, or an organization CI token. A person whose token lacks the human-only pii:read scope is refused with that scope named. After that, in order: the caller must be able to read the project, the project's product analytics must be enabled (the PA-01 gate, answered 422 analytics_not_enabled otherwise), and the organization's policy must admit them.

There is no MCP tool for person-level data. An agent that needs it asks the person to read it in the dashboard.

Modes and scopes

A scope names a slice of one class, by one attribute, and the people who may read it:

Attribute Example
project project = * (every project)
environment environment = production
service.name service.name = payments (telemetry only)
event_property:<name> event_property:plan = enterprise
host_tag:<name> host_tag:tier = db (telemetry only)

* as a value means every value of that attribute. A scope's people are users, teams of this organization or organization roles. Rows inside a scope's slice are readable only by its people, in whatever mode the class is. Rows outside every scope follow the class's mode: unrestricted lets anyone who holds the right permission read them; restricted lets nobody until a scope admits them. Two scopes that contain the same row are an OR.

An agent is judged as the person it acts for, so it can never read a slice that person cannot. An agent with no person behind it is on nobody's list, even though it holds an organization role of its own: a scope naming role: MEMBER admits the members who are people, and a scope's user entries can name only people.

A restricted dataset that is not about a person (telemetry by service.name, aggregates by an event property) is checked with assertScopeAdmits. For aggregates, which are product analytics, it also takes the project, which must belong to the organization, and refuses with analytics_not_enabled until that project's analytics gate is open.

A scope is versioned. Every change adds a version holding the state it produced, and restoreVersion writes an exact earlier state back as a new version; history is never rewritten. expectedVersion makes a write a compare-and-set (409 stale_version).

Changing it

Creating or changing a scope, and setting a class's mode, are human-only acts (org:admin, so an organization owner): a person's own signed-in session, not a token, an agent or an OAuth client. Each writes an audit row with before and after, in the same transaction as the change, and tells the owners afterwards.

Route Does Who
GET /orgs/:o/data-access?project= What you may read of each class, in which tier, and the cohort floor any member
GET /orgs/:o/data-scopes Every scope owner
POST /orgs/:o/data-scopes Create a scope (data_scope.create) owner, in a session
GET /orgs/:o/data-scopes/:id One scope and its versions owner
PATCH /orgs/:o/data-scopes/:id Change principals, archive, or restoreVersion (data_scope.update) owner, in a session
GET /orgs/:o/data-access-defaults The mode of each class owner
PUT /orgs/:o/data-access-defaults Set one or more modes (data_access_default.update) owner, in a session

data_access_get (MCP, read, project:read) answers the same question as the first route for an agent: the mode of each class, the tier it will be served (stored, sampled_agent, aggregate or refused), the scopes that bind it, and the project's cohort floor. Scopes that carve a slice out for other people are counted, never described. A scope's attribute text is untrusted data.

The read ledger

Every read that returns personal data writes one audit row, data.read, after the read, and the read fails if the row cannot be written: data that was taken but not recorded is not handed over.

A row holds the surface (dashboard, api, mcp, worker, cli), the tool or route, the data class, the tier the data was held in, the categories of personal data that came back with their counts (email, phone, ip_address, name, user_id, device_id, location, payment_card, government_id, credential, free_text, other), how many rows, the approval it ran under when one applied, where it went next (client or model_provider), and the digest of the query. It never holds a value, an identifier or the query text. The actor fields are the same as every other audit row: who, in which mode, through which transport and credential, for which client.

Volume. A read of the stored tier, or one that returned any category, is one row per call. A read that returned only aggregates and no category is one row per principal, session and hour, flushed every 60 seconds and on shutdown. It is never sampled.

audit_read_counts (how much each MCP principal read, by hour) also carries the categories.

For a developer adding a person-level read

const { orgId, admission } = await assertPersonLevelRead(principal, 'person_level', { projectId })
return ledgeredRead(ctx, { orgId, projectId, dataClass: 'person_level', surface: 'api',
  route: 'GET /…', tier: 'stored', egress: 'client', query }, async () => {
    const rows = await read(admission)           // filter by admission.admitsRow / slices
    const { value, manifest } = scrubValue(rows, { tier: 'agent' })
    return { value, manifest, rowCount: rows.length }
  })

api/test/data-access/ledger-coverage.test.ts fails for a file that calls these and has no driver there, so a reader cannot land without its row being checked.