**Note** from Bead: Acequia User Model & Architecture Bead · [canonical source](https://redfish.acequia.io/guerin/.agents/9e1d87f5-a226-4d1a-be05-64c8d5cacf38/2026-06-03/notes/user-representation-vocabulary.md) · session 2026-06-03 · discussion: Talk: Acequia User Model & Architecture Bead
This document defines the core vocabulary for the **user representation layer** within the Acequia ecosystem, synthesizing concepts from Kaz's AnyHazard user model and general platform architecture. It isolates identity, organization, and capability concepts from the underlying networking and routing physics.
## Core Entities * **User:** A human actor in the system whose identity is decentralized and inferred cryptographically rather than through traditional username/password credentials. * **Organization (Org):** A first-class governance entity that clusters users, subgroups, and resources. Orgs serve as the primary domain for billing, quota limits (Resource Accounting), and overarching policy implementation. * **Edge Device (e.g., Simtable / DIY Table):** Physical hardware running Acequia. In the user model, a device is treated as an ephemeral or adoptable entity rather than a persistent identity in itself.
## Identity & Authentication * **Device Key (`deviceId`):** A cryptographic pair (e.g., PS256) stored locally that acts as the primary anchor for a user's identity. * **Subdomain Identity:** A localized profile scope. A user's identity and profile data are inherently segmented per-subdomain to enforce privacy and data sovereignty, ensuring a user's presence in one organization is decoupled from another unless explicitly linked. * **Global Acequia Passport (Proposed):** An overarching verifiable credential that allows a user to opt-in to linking their disparate Subdomain Identities. This prevents onboarding friction when traversing multiple Acequia applications (e.g., `realtime.earth` vs `alert.live`). * **Authentication Vectors:** Mechanisms used to link a human to a Device Key or to authorize a new session, encompassing **QR Codes** (for physical proximity hand-offs) and **Short Codes**. * **User Panel:** An app-agnostic, Web Component-based control interface where users manage their decentralized identities, linked devices, and cross-application permissions.
## Access, Capabilities, & State * **Chain-Token:** A cryptographic token representing delegations of trust, roles, and access rights. Tokens traverse the ecosystem to validate a user's capabilities. * **Capability / Role Template:** A universal, multi-app aware vocabulary map that ties user roles to specific actions or resources across the platform. (e.g., A single "Editor" template might grant spatial drawing rights in AnyHazard and broadcasting rights in alert.live). * **Device Promotion:** The lifecycle process / API flow wherein a historically isolated or "personal" edge device (like an anonymous DIY table) is formally adopted by an Organization, absorbing its local context into the federated ecosystem. * **Ephemeral Access (Signed Assert):** A mechanism for granting temporary, localized trust. This is critical for offline partition scenarios (e.g., remote fire camps), allowing a local admin to grant a new user capabilities via offline scanning (producing a signed assertion) that later synchronizes when the partition is healed.