Identity Contract¶
Every actor and every addressable entity in the Bluefly platform resolves to exactly one canonical identity record. This contract defines what an identity IS — the fields every identity must carry — independent of which registry or directory happens to store it today.
1. Identity Classes¶
| Class | What it identifies | Example |
|---|---|---|
AGENT |
An AI agent persona/runtime projection | blu-assistant |
HUMAN |
An operator or team member | [email protected] |
SERVICE |
A running service/process with its own credentials | ossa-deploy |
PRODUCT |
A Portfolio Product (see Portfolio Object Model) | AMCS |
RIG |
A Gas City rig | beads |
2. Required Fields¶
Every identity record MUST carry these fields, regardless of class:
| Field | Type | Description |
|---|---|---|
id |
string, unique | Canonical identifier. Never reused after retirement. |
class |
enum | One of the Identity Classes above. |
gaid |
string, optional | Global Agent ID (did:bluefly:agent:<name>) — required for AGENT class. |
did |
string, optional | Decentralized Identifier (ANP), e.g. did:web:agents.bluefly.io:<name> — required for AGENT class. |
gitlab_principal |
string | The GitLab service account or bot user this identity authenticates to GitLab as. For AGENT class: must be a dedicated service account, never a human account. For HUMAN class: the operator's own GitLab username. Omit for identities that never interact with GitLab. |
ossa_id |
string, optional | The OSSA agent registry ID for this identity, if registered in OSSA. Format: ossa:<slug>. Required for agents participating in the OSSA agent protocol. |
duadp_id |
string, optional | The DUADP agent identity ID, if this agent publishes context provenance via DUADP. Format: duadp:<slug>. Required for agents that write to the context plane. |
auth_binding |
string | The authentication system that vouches for this identity (e.g. Keycloak, 1Password, GitLab OAuth). |
owner |
string | The HUMAN or SERVICE identity accountable for this identity's actions. |
status |
enum | ACTIVE, SUSPENDED, RETIRED. |
created |
date | ISO 8601. |
3. Resolution Rule¶
An identity is never inferred from a filesystem path, a hostname, or a display name. Resolution always goes through the identity's auth_binding, never through where its files happen to live. A rig running on the NAS and the same rig running on Oracle are the same identity if their id and auth_binding match — location is not identity.
3a. Canonical Operational Identity (binding)¶
Bluefly operational GitLab identity is @bluefly; Thomas @ Bluefly.io <[email protected]>. flux423 is not an approved operational identity.
Applies to CODEOWNERS, CI and tooling configuration, package and release metadata, git-config and bootstrap templates, and any document asserting current ownership. Historical commits, pipeline records, and evidence quoting past state are preserved unchanged — a current occurrence is a misconfiguration; a historical one is history. ~/... is a workstation path, not an identity, per §3.
4. Relationship to Authority and Capability¶
An identity is who acts. Authority is what decides. Capability is what is provided. A single identity may hold zero or more authorities and may own zero or more capabilities — ownership is recorded on the Authority/Capability record, not duplicated on the identity record.
5. Worked Examples¶
AGENT class (minimal)¶
id: blu-assistant
class: AGENT
gaid: did:bluefly:agent:blu-assistant
did: did:web:agents.bluefly.io:blu-assistant
gitlab_principal: NOT_YET_PROVISIONED
ossa_id: ossa:blu-assistant
duadp_id: duadp:blu-assistant
auth_binding: blu-assistant@bluefly (Keycloak)
owner: [email protected]
status: ACTIVE
created: 2026-05-01
AGENT class (DRUPAL — Drupal.org deploy agent)¶
id: drupal-agent
class: AGENT
gaid: did:bluefly:agent:drupal-agent
did: did:web:agents.bluefly.io:drupal-agent
gitlab_principal: NOT_YET_PROVISIONED # see STD-GITLAB-SA-001 for provisioning steps
ossa_id: ossa:drupal-agent
duadp_id: duadp:drupal-agent
auth_binding: drupal-agent@bluefly (Keycloak / Gas City service identity)
owner: [email protected]
status: ACTIVE
created: 2026-09-16
HUMAN class¶
id: [email protected]
class: HUMAN
gitlab_principal: bluefly
auth_binding: [email protected] (Keycloak)
owner: [email protected]
status: ACTIVE
created: 2026-01-01
This contract governs identity record structure. Where identities live (which registry, which system of record) is an Authority question — see Authority Contract §Registry Location.