Regulator Mode

Regulator Mode lets you grant an external regulator (CNIL, BaFin, internal DPO, auditor) scoped, time-bounded, read-only access to your Kaplaix evidence. Every query they make is recorded as an Ed25519-signed witness statement that both of you can verify offline.

• Read-only — regulators cannot write or approve anything.
• Scoped — date range plus optional filters on agents, sessions, and event categories.
• Revocable — kill the token from the console at any time.
• Auditable — every view (including 404s on out-of-scope probes) is cryptographically witnessed.
• Portable proof — download any witness bundle and verify it offline with the verify-witness CLI, independently of Kaplaix’s runtime.

Granting access

Open Settings → Regulator Access in the console. Required fields:

Optional narrowing (leave empty for the widest scope within the tenant):

• Agent IDs — restrict to specific agents.
• Session IDs — the narrowest scope: only these sessions visible.
• Event categories — tool_call, llm_call, data_access, approval, policy_decision, error, custom.

On submit, Kaplaix returns a one-time rga_* token and a ready-to-share URL:

https://app.kaplaix.com/regulator/access/rga_live_<43 chars>

Copy the token or the URL. It never reappears — only a SHA-256 hash of the token is kept in the database.

What the regulator sees

Opening the URL shows:

• A scope banner summarising what’s accessible and when it expires.
• A Sessions tab — a paginated list filtered to the granted scope.
• A Session detail view — events filtered to the same scope.
• A Witness log — every query (including 404s) tied to this access.
• Per-entry download of the witness bundle as JSON for offline verification.

No tenant console surface — no policies, no team, no settings. The layout is completely independent of the tenant session cookie by construction.

Revoking access

From Settings → Regulator Access, click the × on an active row and confirm with a reason (optional). The token is immediately invalidated; past witness statements remain intact and verifiable.

Offline verification

Every response the regulator sees produces a witness statement. The statement is downloadable from the Witness log tab as JSON.

1. Fetch the public keys

Kaplaix publishes its witness-signing public keys as a JWKS:

GET https://api.kaplaix.com/.well-known/kaplaix/witness-keys.json
Content-Type: application/jwk-set+json

Cache it locally — keys rotate on a ~quarterly cadence and retired keys stay listed so historical statements remain verifiable.

2. Run the verifier

Install @kaplaix/cli-verify (or download the pinned release binary):

npm install -g @kaplaix/cli-verify

Verify a downloaded witness bundle:

verify-witness --witness witness.json --jwks witness-keys.json
# or fetch the JWKS over HTTPS in one call:
verify-witness --witness witness.json \
  --jwks-url https://api.kaplaix.com/.well-known/kaplaix/witness-keys.json

Exit codes:

What the signature protects

The signed payload includes:

• kid — signing key id, resolves to a public key in the JWKS.
• tenantId, regulatorAccessId — who, bound to which grant.
• requestPath, requestQuery — what was asked.
• resultHash — SHA-256 of the canonicalised response body.
• resultRecordCount — number of records returned.
• requestAt — server-stamped timestamp.

Any modification to the response body, the query that produced it, or the metadata around it will invalidate the signature. The resultHash lets a regulator prove what they received, not merely that they received something.

Security properties

• Disjoint auth path — rga_* tokens never pass through the tenant API-key verifier. A bug in one cannot escalate into the other.
• Constant-time verification — tokens are compared with a constant-time hash, with timing equalisation on the “prefix not found” path.
• Append-only witness ledger — the application layer has no UPDATE or DELETE path on witness statements.
• Key rotation without evidence loss — retired keys stay in the JWKS with a validUntil window, so statements signed before rotation remain verifiable forever.

Limits

• Maximum access lifetime: 90 days. Renewals are a deliberate action.
• Regulators cannot export bulk archives in V1. (ZIP-export for regulators is tracked for a future release.)
• The token appears in the URL in V1. A cookie-based flow that strips the token from the URL after first load is planned.