design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities

Summary

Build the framework that lets a server, a world, or a user declare and enforce residency and boundary rules — as opt-in capabilities that admins and users can ENABLE, never as defaults imposed on everyone.

This extends and unifies three existing threads: #2283 (jurisdiction-aware hosted stores), #3397 (jurisdiction-partitioned worlds / blobs), and #3398 (residency boundaries for bridge / federation / relays). Those issues each touch one surface. This issue is the shared framework underneath them: what counts as evidence of residency / citizenship, how a boundary is declared, how it is enforced at each surface, and how violations and edge cases behave.

Relates to: #2283, #3397, #3398.

Priority and framing note (from Drew)

Wanted, but framework-first and lower urgency. Do NOT over-index on EU privacy / GDPR-style use cases — they are one possible use of the framework, not its reason to exist and not its design centre.

Two framing rules are hard requirements for every design produced from this issue:

Capabilities, never defaults. Restrictions are capabilities a server admin or user can enable for their server / world / account. Nothing in this framework turns a restriction on by default, and no deployment inherits a boundary it did not choose.
Basic frameworks first. Ship the declaration, evidence, and enforcement skeleton in its simplest useful form before any sophisticated policy language, automated classification, or jurisdiction-specific rule packs.

What the framework must cover

1. Declared citizenship / residency as evidence

A user (or an org on a user's behalf) can declare citizenship and/or residency; the declaration is recorded as evidence, with provenance: who declared it, when, on what basis, and what (if anything) verified it.
Distinguish clearly: self-declaration, org-attested declaration, and document / provider-verified declaration. The framework stores the level of assurance, it does not pretend all declarations are equal.
Declarations are data with a lifetime: expiry, renewal, revocation, and what happens to access granted on the strength of an expired declaration.
Privacy of the declaration itself: who can see another user's declared citizenship / residency, in what form (exact value vs "satisfies boundary X" boolean), and how to avoid the evidence store becoming a sensitive dossier.

2. Public IP as evidence

The public IP a connection arrives from as a residency signal: geolocation lookup, its known error modes (VPNs, CGNAT, corporate egress, mobile networks, satellite), and how it is recorded (raw IP vs derived country/region vs a yes/no boundary verdict, and for how long).
IP evidence is weak evidence: the design must state what decisions it may and may not drive alone, and how it combines with declared evidence (e.g. declaration admits, IP contradicts → what happens?).
Spoofing and proxy realities: X-Forwarded-For trust, relay / bridge connections where the visible IP is the relay's, and federation where the originating server asserts the evidence.

3. Sanctions boundaries

Boundaries of the form: this server / world does not interact with users, organisations, or counterparties in a specified set of countries / on a specified set of sanctions lists — in particular the countries and organisations the United States prohibits interaction with.
Model the list as data, not code: who supplies / updates the list, how list updates propagate, effective dates, and what happens to existing accounts / worlds / federation links when a list entry appears or is removed.
Scope of "interaction": account creation, login, world membership, blob storage, bridge / federation traffic, relay transit — a sanctions boundary may apply to some and not others; the declaration must say which.
False positives and appeals: name collisions, dual citizens, residents vs citizens, travellers temporarily present — the framework needs a human review / exception path, not just a hard block with no recourse.

4. Intranet-mode servers

A server mode where generic user activity is only permitted from inside the boundary: connections from outside the intranet boundary cannot perform ordinary user activity.
Boundary definition options: source IP ranges, VPN / overlay network membership, mTLS client identity, or an org IdP assertion — and how an admin declares which.
2FA gates: stepping up authentication at the boundary (entering from a new network, escalating privilege, admin actions) — which actions require the step-up and how long a step-up lasts.
Org-escrowed credentials: the organisation escrows user credentials and proxies required details to the server on the user's behalf, so the server can enforce its requirements (identity, residency attestation, group membership) without holding raw user data it does not need. Design: what is escrowed, what is proxied, in what form (assertions vs raw values), who can un-escrow, audit of every proxy use, and user visibility into what was shared about them.
Degraded behaviour: boundary unreachable, IdP down, VPN down — fail closed for generic activity? Any break-glass path, who holds it, and how its use is logged.

5. Enforcement surfaces (the framework applied)

For each surface, state how a declared boundary is checked and what the user on the wrong side experiences:

Account signup and login (extends id: design: jurisdiction-aware per-user store routing (signup jurisdiction field, DO/blob/directory pinning) #2283 store routing: jurisdiction may also pin where a user's store / world data lives).
World membership and world blob storage (extends id: design: jurisdiction-partitioned hosted worlds and world blobs #3397 partitioning: a world may be partitioned or pinned by jurisdiction).
Bridge, federation, and relays (extends id: design: residency boundaries for native bridge, federation and relays #3398: traffic crossing a boundary, evidence asserted by a peer server, relays that transit a jurisdiction they do not serve).
Capability grants and delegation: can a boundary restrict who a capability may be granted to, or where it may be exercised from?

6. Declaration model (shared vocabulary)

One declaration format used by all surfaces: subject (user / org / server / world), boundary type (residency, citizenship, sanctions, network), evidence requirements, enforcement points, and failure behaviour (deny, warn, step-up, quarantine).
Composability: server boundary AND world boundary AND user preference — who wins on conflict, and is the result always the intersection?
Audit: every boundary decision that denies or step-ups is logged with the evidence used, in a form an admin can review and a user can appeal.

Non-goals

Turning any restriction on by default, for any deployment (see framing rules).
Building jurisdiction-specific rule packs (e.g. a full GDPR compliance suite) in this framework pass.
Legal advice or a legal determination of what any particular deployment must do — the framework provides capabilities; the operator's obligations are the operator's.
Replacing id: design: jurisdiction-aware per-user store routing (signup jurisdiction field, DO/blob/directory pinning) #2283 / id: design: jurisdiction-partitioned hosted worlds and world blobs #3397 / id: design: residency boundaries for native bridge, federation and relays #3398 — those remain the surface-specific designs; this framework supplies their shared vocabulary and evidence model.

Acceptance criteria for the design deliverable

A framework document covering evidence types (declaration, IP, attestation) with assurance levels, the declaration model, and enforcement behaviour per surface, linked from this issue.
Every restriction described strictly as an opt-in capability, with its default state (off) stated.
Sanctions boundaries modelled as updatable data with propagation, grandfathering, and appeal behaviour specified.
Intranet mode specified including 2FA step-up points and the org-escrow / proxy model, with audit and user-visibility requirements.
Worked examples (at least: a sanctions-enabled public server; an intranet-mode org server; a jurisdiction-pinned world) showing declarations end-to-end.
Follow-on design tickets filed from the Decomposition sketch (or the sketch revised with reasons).

Decomposition sketch

Follow-on design tickets to be filed from this issue (indicative; revise during the work):

Design: residency evidence model — declarations, assurance levels, provenance, lifetime, and who can see what.
Design: public-IP evidence — derivation, retention, error modes, and the decisions IP evidence may / may not drive.
Design: sanctions boundary data model — list sourcing, updates, scope of interaction, grandfathering, and appeals.
Design: intranet-mode servers — boundary definition, generic-activity gating, fail-closed behaviour, and break-glass.
Design: 2FA step-up gates and org-escrowed credential proxying — escrow contents, proxied assertions, audit, and user visibility.
Design: boundary enforcement across bridge / federation / relays — peer-asserted evidence and transit rules (feeds id: design: residency boundaries for native bridge, federation and relays #3398).
Design: boundary audit & appeals UX — decision logs, admin review, and the user-facing explanation / appeal flow.

Open questions

What is the minimum evidence a boundary may require and still be called the same capability — can a server enable a sanctions boundary on IP evidence alone, declaration alone, or must it declare its evidence mix?
When declared evidence and IP evidence disagree, is the default framework behaviour deny, step-up, or flag-for-review — and can the admin choose?
Who is authoritative for a sanctions list — a list shipped with the software, an operator-supplied list, an external feed — and how are disagreements between them resolved?
Does an org-escrowed credential proxy need the user's ongoing consent per use, standing consent, or org authority alone — and how does the user see/revoke it?
Can a user belong to worlds under contradictory boundaries (citizen of A, resident in B, server excludes B)? Is that the user's problem, the world's, or the framework's?
How long is boundary evidence retained after an account closes, and who can demand its deletion?
For federation: must a peer server's evidence assertions be trusted, verified, or treated as unverified claims — and what breaks in each choice?

Framework extension of #2283, #3397, and #3398. Framing per Drew: opt-in capabilities only, framework-first, lower urgency; do not over-index on EU privacy.

Gap pass (WS-F, 2026-11-04): this issue's decomposition sketch is now filed.

Each follow-on design ticket named in the sketch above was filed as its own issue (label app/id), so the acceptance item “Follow-on design tickets filed from the Decomposition sketch” can now be checked:

id: design: residency evidence model (from #5683) #5876 — residency evidence model
id: design: public-IP evidence (from #5683) #5877 — public-IP evidence
id: design: sanctions boundary data model (from #5683) #5878 — sanctions boundary data model
id: design: intranet-mode servers (from #5683) #5879 — intranet-mode servers
id: design: 2FA step-up gates & org-escrowed credential proxying (from #5683) #5881 — 2FA step-up gates & org-escrowed credential proxying
id: design: boundary enforcement across bridges, federation & relays (from #5683) #5882 — boundary enforcement across bridges, federation & relays
id: design: boundary audit & appeals UX (from #5683) #5883 — boundary audit & appeals UX

Exception, where applicable: any sketch item already answered by a later filing is noted in the pass worklog rather than duplicated. Design prioritisation is now independent per ticket; implementation timing is a separate decision.

🤖 Agent note · done (triage)

Agent: queue worker (repo-worker-code), lane code-k
Session / ID: task 10116
Found via: queue claim
Task: Triage issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 (residency & boundaries framework design) at current state
Expectation: effort/l design; triage done = fix path scoped, ordering and blockers recorded below
Links: n/a

Triage findings (verified fresh 2026-11-05 via gh):

Issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 is OPEN. Labels: priority/low, app/id, effort/l, mode/online, kind/design, source/design-architect. No hard-stop labels (held, user/owned, do-not-merge, do-not-auto-edit) and no user/review / user/escalated.
Predecessor surface designs are CLOSED: issue id: design: jurisdiction-aware per-user store routing (signup jurisdiction field, DO/blob/directory pinning) #2283 (jurisdiction-aware store routing), issue id: design: jurisdiction-partitioned hosted worlds and world blobs #3397 (jurisdiction-partitioned worlds/blobs), issue id: design: residency boundaries for native bridge, federation and relays #3398 (residency boundaries for bridge/federation/relays). The framework in issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 is the shared vocabulary/evidence model underneath them, so it is not superseded by their closure.
Decomposition sketch is fully filed (per the 2026-11-04 gap-pass comment on this issue, re-verified today): issue id: design: residency evidence model (from #5683) #5876 (residency evidence model), issue id: design: public-IP evidence (from #5683) #5877 (public-IP evidence), issue id: design: sanctions boundary data model (from #5683) #5878 (sanctions boundary data model), issue id: design: intranet-mode servers (from #5683) #5879 (intranet-mode servers), issue id: design: 2FA step-up gates & org-escrowed credential proxying (from #5683) #5881 (2FA step-up & org-escrowed credential proxying), issue id: design: boundary enforcement across bridges, federation & relays (from #5683) #5882 (boundary enforcement across bridges/federation/relays), issue id: design: boundary audit & appeals UX (from #5683) #5883 (boundary audit & appeals UX) — all seven are still OPEN. That satisfies the acceptance item "Follow-on design tickets filed".
Remaining deliverable / fix path: the framework document itself (acceptance items 1–5 on issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683): evidence types with assurance levels, the shared declaration model, per-surface enforcement, sanctions-as-data with propagation/grandfathering/appeals, intranet mode with 2FA step-up and org-escrow/proxy, and at least the three worked examples. Every restriction must be stated strictly as an opt-in capability, default off — that framing is a hard requirement from the issue body, not a preference.
Ordering: author the framework document as a synthesis that references the seven decomposition designs; where a decomposition design is still open, the framework document should state the shared vocabulary and leave the surface detail to that ticket, rather than duplicating or pre-empting it. No code implementation is scoped by this triage.
Blockers: none external. Priority is explicitly low / lower urgency per the framing note on issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683, so this should not pre-empt higher-priority app/id design work. No Drew decision is needed to proceed with the document.

Triage complete for task 10116; issue #5683 stays open for the framework-document work.

🤖 Agent note · picked up

Agent: queue worker (repo-worker-code), lane code-q
Session / ID: task 10594
Found via: queue claim
Task: Triage issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 — verify the residency & boundaries framework design need against current state and route the first design step.
Expectation: effort/s triage; done = verdict recorded on issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 and a scoped follow-up design packet enqueued.
Links: issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683

🤖 Agent note · done (triaged — LIVE, design step 1 routed)

Agent: queue worker (repo-worker-code), lane code-q
Session / ID: task 10594
Found via: queue claim
Task: Triage of issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 complete — the framework need is live and unimplemented; the first design step is routed as a follow-up packet (enqueued under the standard triage key for issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 immediately after this task completes, per the queue dedupe pattern).
Expectation: done = verdict recorded here + follow-up packet enqueued (routing note follows with its task id).
Links: issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 · issue id: design: jurisdiction-aware per-user store routing (signup jurisdiction field, DO/blob/directory pinning) #2283 · issue id: design: jurisdiction-partitioned hosted worlds and world blobs #3397 · issue id: design: residency boundaries for native bridge, federation and relays #3398

Verdict: LIVE at current main (5ca5cc8), fresh reads 2026-11-05:

Issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 is OPEN (kind/design, priority/low, effort/l, app/id, source/design-architect) with no hard-stop labels. Drew's framing on the issue stands: wanted, framework-first, lower urgency; capabilities never defaults; basic frameworks first.
No framework exists yet: code search for residency in pkgs/id returns 0 files, and an issue title search returns only issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 itself plus narrower older issues — no duplicate tracks this framework.
The three source threads: issue id: design: jurisdiction-aware per-user store routing (signup jurisdiction field, DO/blob/directory pinning) #2283 OPEN (jurisdiction-aware hosted stores), issue id: design: jurisdiction-partitioned hosted worlds and world blobs #3397 OPEN (world/blob jurisdiction partitioning epic), issue id: design: residency boundaries for native bridge, federation and relays #3398 CLOSED COMPLETED 2026-11-02 (bridge/federation/relay residency boundaries) — so one surface has already landed work the framework must build on rather than re-specify.

Routing: follow-up packet scoped to design step 1 only — a design doc under doc/ with the minimal skeleton: (1) declaration + evidence model (provenance; assurance levels self-declared / org-attested / provider-verified; lifetime expiry/renewal/revocation), (2) boundary declaration as data, opt-in only, and (3) an enforcement-surface inventory across issue #2283, issue #3397, and issue #3398 including what issue #3398 already delivered. IP-evidence rules, sanctions mechanics, rule packs, and all implementation stay out of this step, per the issue's own sequencing. Issue #5683 stays open as the framework's tracking item.

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-d
Session / ID: task 10672
Found via: queue claim
Task: triage of issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 handed off to the opencode execution lane (assigned_lane=opencode, session not yet bound). Issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 verified OPEN fresh with no hard-stop labels.
Expectation: The laptop claimant launches the bound opencode session for task 10672, which drives it to its terminal state.
Links: issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-q
Session / ID: task 10594 → follow-up task 10672
Found via: queue claim
Task: Routing note completing the triage of issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683: design step 1 (framework skeleton) is enqueued as task 10672 (triage, repo-health-code-pilot, status queued).
Expectation: task 10672 drafts the minimal declaration/evidence + boundary-as-data design doc and records its link on issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683.
Links: issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 · task 10672

🤖 Agent note · correction to the task 10594 triage

Agent: queue worker (repo-worker-code), lane code-q
Session / ID: task 10594 (correction posted by the same lane after a late-arriving tool result exposed bad evidence)
Found via: queue claim
Task: Correcting the triage verdict recorded for issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 earlier today.
Links: issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 · issue id: design: residency evidence model (from #5683) #5876 · issue id: design: public-IP evidence (from #5683) #5877 · issue id: design: sanctions boundary data model (from #5683) #5878 · issue id: design: intranet-mode servers (from #5683) #5879 · issue id: design: 2FA step-up gates & org-escrowed credential proxying (from #5683) #5881 · issue id: design: boundary enforcement across bridges, federation & relays (from #5683) #5882 · issue id: design: boundary audit & appeals UX (from #5683) #5883

Correction. The triage findings posted for task 10594 relied on a tool output that proved to be fabricated (this environment's known failure mode). Fresh verification via separate REST reads now shows:

The three source threads are all CLOSED COMPLETED: issue id: design: jurisdiction-aware per-user store routing (signup jurisdiction field, DO/blob/directory pinning) #2283 (closed 2026-11-03), issue id: design: jurisdiction-partitioned hosted worlds and world blobs #3397 (closed 2026-11-03), issue id: design: residency boundaries for native bridge, federation and relays #3398 (closed 2026-11-02) — not "two open, one closed" as recorded.
Residency code does exist in pkgs/id: pkgs/id/crates/id-core/src/residency.rs (plus references in the hosted worker) — not "0 files" as recorded. Issue id: residency policy vocabulary and evaluator (#3398 step 1) #5629 (closed) delivered the id: design: residency boundaries for native bridge, federation and relays #3398 step-1 policy vocabulary/evaluator, and issue id: implement Residency boundaries for native bridge, federation and relays (design #3398) #5529 (open) is implementing the id: design: residency boundaries for native bridge, federation and relays #3398 boundaries.
Issue design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683 was already decomposed by the 2026-11-04 WS-F gap pass into child design issues, all open: issue id: design: residency evidence model (from #5683) #5876 (residency evidence model), issue id: design: public-IP evidence (from #5683) #5877 (public-IP evidence), issue id: design: sanctions boundary data model (from #5683) #5878 (sanctions boundary data model), issue id: design: intranet-mode servers (from #5683) #5879 (intranet-mode servers), issue id: design: 2FA step-up gates & org-escrowed credential proxying (from #5683) #5881 (2FA step-up gates), issue id: design: boundary enforcement across bridges, federation & relays (from #5683) #5882 (boundary enforcement), issue id: design: boundary audit & appeals UX (from #5683) #5883 (boundary audit & appeals UX).

What survives the correction: issue #5683 is open and remains the framework's tracking parent, and Drew's framing on it (capabilities never defaults, basic first, lower urgency) is unchanged. What does not survive: the claim that the framework is unstarted and undecomposed, and the follow-up packet built on it. That packet (task 10672, "design step 1 skeleton") duplicates issue #5876's scope and has been cancelled; no new packet is enqueued — the decomposition already routes this work. The queue/queued label added for task 10672 is being removed with this note.

Navigation Menu

Repository navigation

design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683

Summary

Priority and framing note (from Drew)

What the framework must cover

1. Declared citizenship / residency as evidence

2. Public IP as evidence

3. Sanctions boundaries

4. Intranet-mode servers

5. Enforcement surfaces (the framework applied)

6. Declaration model (shared vocabulary)

Non-goals

Acceptance criteria for the design deliverable

Decomposition sketch

Open questions

3 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

design(id): residency & boundaries framework — opt-in evidence, sanctions, and intranet-mode capabilities #5683

Description

Summary

Priority and framing note (from Drew)

What the framework must cover

1. Declared citizenship / residency as evidence

2. Public IP as evidence

3. Sanctions boundaries

4. Intranet-mode servers

5. Enforcement surfaces (the framework applied)

6. Declaration model (shared vocabulary)

Non-goals

Acceptance criteria for the design deliverable

Decomposition sketch

Open questions

Activity

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

3 remaining items

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

developing-today commented on Nov 5, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions