# DSN and the region model

## Format

```
https://<publicKey>@<region>.<ingestHost>/<projectId>
```

Example: `https://a1b2c3d4@us.ingest.example.com/clx0project0id`

| Part | Rules |
| --- | --- |
| scheme | `https` (`http` is tolerated for local development only) |
| `publicKey` | `[A-Za-z0-9_-]+`, unique across the install |
| password half | **must be empty** — a DSN carrying a secret is rejected as malformed |
| `region` | first hostname label; `[a-z][a-z0-9-]{0,15}` |
| `ingestHost` | everything after the region label, port included |
| path | exactly one segment, the project id |
| query / fragment | must be absent |

Parsing lives in `domain/src/lib/dsn.ts` (`parseDsn` / `buildDsn`) and, for SDKs, in
`shared/src/protocol/dsn.ts`. `create-bucker` re-implements the same rules locally
so that `npx` pulls down zero dependencies.

## The Sentry-SDK form: the project's number

Every Sentry SDK refuses a DSN whose project segment is not an integer. The JavaScript SDKs
disable themselves without saying so outside debug mode (`Invalid Sentry Dsn: Invalid
projectId`), and sentry-python raises at `init` (`invalid literal for int()`). A Bucker
project id is not an integer, so the DSN above cannot be given to an unmodified Sentry SDK.

Each project therefore also has a number (`Project.sentryProjectId`), and every key reports a
second, equivalent DSN with it, `sentryDsn`:

```
https://<publicKey>@<region>.<ingestHost>/<projectNumber>
```

Use `sentryDsn` in `Sentry.init({ dsn })`. Every DSN-authenticated route (the envelope,
OTLP, check-ins, feedback and the rest) accepts either form in its `<projectId>` path segment.
The number only identifies the project. It never authenticates: the public key must still
belong to the project the path names, so a key addressed at another project's number is
refused with a `403`, exactly as with another project's id. Bucker's own SDKs accept both
forms.

## The public key is not a credential for anything but ingest

`ProjectKey.publicKey` appears in client bundles by design. It authenticates **ingest
only** — it cannot read an issue, list a project, or call the control plane. There is
no secret half to protect, which is why listing keys back to project members is safe
and why the onboarding endpoint can return the DSN.

Legacy Sentry DSNs carried a secret in the password slot. Bucker DSNs never do, and
`parseDsn` rejects one that tries.

## Why the region prefix exists on day one

The first hostname label is the data region. Adding an EU region later is then purely
additive — a new hostname, the same identifier scheme — instead of a migration that
rewrites every customer's DSN and every config file that quotes it.

The DSN is **derived, never stored**: `key.service.ts` builds it from
`{ publicKey, projectId, region }` on every read. Changing `INGEST_HOST` or
`INGEST_REGION` propagates to every key immediately.

Today only `us` and `eu` are accepted values for the server's own `INGEST_REGION`, and
only one region actually runs. The parser accepts any well-formed region label, so
SDKs and the CLI are already forward-compatible.

## Ingest endpoint

```
POST https://<region>.<ingestHost>/api/<projectId>/envelope/
Content-Type: application/x-sentry-envelope   (or any type: the route reads the body raw)
```

The bare form without the trailing slash is registered too, so `curl` and hand-rolled
clients do not hit a surprise 404.

Authentication is the public key, sent either as the `sentry_key` query parameter or
inside the envelope header's `dsn` field. The browser SDK avoids a preflight on every
event, and that takes two things together. First, auth goes in the query string, because
an `X-Sentry-Auth` header is not CORS-safelisted. Second, the SDK sends
`Content-Type: text/plain;charset=UTF-8`, which the ingest route accepts because it
ignores the type. Query-string auth with `application/x-sentry-envelope` is still
preflighted. A `sendBeacon` built that way is credentialed, so it cannot pass the ingest
route's `*`/no-credentials preflight and is silently dropped.
`code/sdks/browser/src/transport.ts` (`SIMPLE_CONTENT_TYPE`) explains why. Do not relax
the server policy to fix this.

A `200` carries `{ "id": "<eventId>" }` and an `X-Bucker-Ingest-Disposition` header.
**It means the envelope was accepted and queued**, not that an issue exists yet —
that happens when a worker drains the queue.

## A process serves one region, and refuses the rest

`INGEST_REGION` is also the region this process SERVES. An organization lives in one region
(`Organization.region`), and a process in another refuses it with **409** and
`error.details.redirectTo`, the region's API URL. The check is on every path that reaches an
organization, not only the compliance routes:

| Path | Where | What it costs |
| --- | --- | --- |
| REST routes naming `:orgSlug`, and every authenticated route (a `:projectId` in the URL, an org-bound credential) | `plugins/residency.ts`, after authentication | one cached lookup per org per 30 s |
| Ingest, OTLP, the platform drains and the replay recorder config | `lib/ingest-door.ts` (and `replay/config-routes.ts`), right after the DSN key resolves | one cached lookup per project per 30 s |
| Explore | `explore/printer/guard.ts`, on the org row it already loads | nothing |
| MCP tools | `mcp-server/src/tools/common.ts` and the status resolvers | nothing for an issue, one cached lookup otherwise |
| Worker job claims | `db/src/queue/postgres-driver.ts` and the remediation claim | one semi-join in the claim statement |

Details a client can rely on:

- `GET /orgs/:orgSlug/compliance/residency` is exempt. It reports `servedByThisRegion: false`, which
  is the answer that explains the refusals everywhere else.
- On an authenticated route, a signed-in caller who is **not a member** of the org gets a **404**
  and never the 409: whether someone else's organization lives in `eu` is not theirs to learn, and
  404 is what the other region's own deployment would answer here. The route itself never runs,
  even one that authorizes non-members (the operator console). On a public or optional-auth route
  (status pages, SSO entry points) everyone gets the 409, as an anonymous caller does.
- `redirectServing: false` in the 409 means the named region is not operating. `eu` is listed in
  the registry and **not active**: it has no DNS name and no stores, so there is nowhere to
  redirect to yet.
- The ingest door takes the project from the **key**, never from the body.
- The region of an org is cached for 30 seconds per process. A region migration is the only
  thing that changes it, and for up to 30 seconds after a cutover a process may still serve the
  org from its old region (the cutover does not yet evict the cache).
- No token changes. The refusal is made by the resolver, so a token issued before this check
  verifies exactly as it did; the audience stays `bucker-mcp`.

`residency_get` (MCP, `project:read`) tells an agent which region serves the org, which provider
and region hold each store (a `?` is "not yet confirmed", never a guess), and any region move in
flight; `include: [manifest]` adds the published trust manifest from `https://bucker.io/trust.json`.

## Configuration

| Variable | Default | Meaning |
| --- | --- | --- |
| `INGEST_REGION` | `us` | Region label this install stamps into DSNs |
| `INGEST_HOST` | `localhost:4000` | Ingest host *without* the region prefix |
| `INGEST_INLINE_MAX_BYTES` | `65536` | Above this, the raw envelope goes to blob storage instead of the row |
| `INGEST_MAX_ENVELOPE_BYTES` | `20971520` | Hard reject above this, with an accounted `too_large` outcome |
