# Conceptual Model

Status: draft. Refined after IDENTITY-WP-0003 corpus backfill and scenario
representation review. Implementation-neutral.

## Core Claim

Identity-canon models identity-related systems as scoped actors, records,
identifiers, claims, credentials, relationships, and projections. Social, legal,
operational, authentication, and authorization meanings stay visible instead of
collapsing into `user`, `group`, or `tenant`.

## Entity Families

### Actor Layer

- Actor: participation root.
- Natural Person: human actor.
- Artificial Agent: non-human automated actor.
- Collective Actor: actor composed of, representing, or organizing multiple
  actors.
- Organization, Community, Family or Household, Group, and Team: candidate
  collective actor specializations.

### Record Layer

- Account: operational access record in a scope.
- Service Account: software-oriented account.
- Identity Record: source-specific record about an actor or account.
- Commercial Record: billing, CRM, or commerce-system record linked to an actor
  or tenant (e.g., Stripe Customer).
- Profile: presentation or attribute surface.
- Persona: contextual presentation of an actor.

### Reference Layer

- Identifier: value or reference within a scope.
- Scoped Identifier: identifier designed for limited correlation.
- Credential: proof or control material.
- Claim: statement made by a source or issuer.
- Evidence Source: support for claims, relationships, and synonymity.

### Scope Layer

- Scope: boundary for meaning.
- Tenant: administrative or isolation scope.
- Realm: issuer or security namespace.
- Namespace: naming scope.
- Authorization Domain: scope in which principals, resources, actions, and
  policies are evaluated.

### Projection Layer

- Authenticated Subject: protocol projection of an identified entity.
- Authorization Principal: decision-engine projection of an actor, account, or
  subject.
- Authorization Resource, Action, Policy, and Relationship Tuple: downstream
  authorization projections, not canonical identity roots.

## Relationship Classes

Relationships are explicit model elements when they affect meaning,
authorization, privacy, or lifecycle.

Core relationship classes:

- Membership: actor participates in a collective actor or scope.
- Affiliation: actor is associated with another actor or collective.
- Following: actor subscribes to or follows another actor or profile.
- Ownership: actor controls or is responsible for a record, resource, tenant,
  or organization.
- Representation: actor acts on behalf of another actor.
- Delegation: actor grants bounded authority to another actor.
- Administration: actor manages records, relationships, or configuration in a
  scope.
- Trust: actor, issuer, verifier, or system relies on another for a purpose.
- Commercial: vendor actor provides services to customer actor; may reference a
  Commercial Record for billing or subscription state.
- Synonymity: records or identifiers are asserted to refer to the same target
  under stated evidence and scope.

Recommended relationship fields:

- relationship type;
- source and target;
- scope;
- source system or issuer;
- evidence reference;
- confidence or assurance when relevant;
- lifecycle state;
- privacy constraints;
- authorization implication, if any.

## Identity Linking Model

Identity linking does not merge records by default. It creates Synonymity
Assertions with relation types (`same_as`, `probably_same_as`, `linked_to`,
`represents`), strength bands, scope, evidence, and lifecycle state.

Weak synonymity: probabilistic entity-resolution matches, schema.org sameAs,
shared attributes without verification.

Strong synonymity: deterministic keys (OIDC iss+sub, persistent SAML NameID),
operator-verified links, VC cryptographic proof.

Privacy-limited synonymity: pairwise OIDC sub, pseudonymous persona links,
GDPR pseudonymization with separated re-identification key.

## Scenario Representation Paths

Each scenario in `scenarios/ScenarioTests.md` maps to canonical elements as
follows.

### S01 — Single Person With One Local Account

`Natural Person` → operates → `Account` (in `Scope`) → has `Identifier`(s) →
presents `Profile` → optional `Membership Relationship` to `Group` → authz
projects `Account` to `Authorization Principal`.

### S02 — Person With Multiple Accounts Across Scopes

`Natural Person` → operates → multiple `Account` (one primary `Scope` each) →
optional `Synonymity Assertion` (`linked_to` or `same_as`, scoped) between
accounts → independent `Lifecycle State` per account.

### S03 — Enterprise With Sub-Organizations

`Organization` actors → structural child/parent relationships → `Identity
Record`/`Account` per directory source (LDAP/SCIM) → `Membership Relationship`
to org units → `Legal Entity` as specialization or relationship when evidenced.

### S04 — Vendor Tenant Serving Customer Tenants

`Organization`(vendor) + `Organization`(customer) → `Commercial Relationship`
(vendor/customer roles) → separate `Tenant` scopes → optional `Commercial Record`
per customer tenant (billing) → `Trust Relationship` for federation →
`Administration Relationship` for delegated support.

### S05 — Customer Organization With Delegated Administrators

`Organization` → owns `Tenant` scope → administrator `Account`(s) →
`Delegation Relationship` + `Administration Relationship` → authz projection
via Cedar Principal or OpenFGA admin tuple.

### S06 — Family With Guardian And Dependent Accounts

`Family or Household` collective actor → `Natural Person` (guardian, dependent)
→ `Representation Relationship` (guardian→dependent) → child `Account` with
privacy constraints → optional NIST IAL-capped proofing metadata.

### S07 — Spontaneous Interest Group

`Community` or `Group` collective actor → `Membership Relationship` (informal)
→ optional `Administration Relationship` (moderator) → no `Tenant` or `Legal
Entity` required.

### S08 — Community With Members, Moderators, And Followers

`Community` actor → `Membership Relationship` (members) → `Administration
Relationship` (moderators) → `Following Relationship` (followers) → `Profile`
may differ from `Account`.

### S09 — Social Media Follower Graph

`Actor`/`Persona` → `Profile` in social `Scope` → directed `Following
Relationship` edges → no implied `Membership` or authz tuple.

### S10 — Bot Or Service Account Acting For An Organization

`Artificial Agent` → `Service Account` → `Organization` actor →
`Representation` or `Delegation Relationship` → `Credential` → authz tuple
(e.g., `org#delegate@service_account`).

### S11 — AI Agent Acting Under Delegated Authority

`Artificial Agent` → `Account` or `Service Account` → `Delegation
Relationship` from `Natural Person` or `Organization` → `Evidence Source` for
actions → Cedar `Context.delegatedBy` or contextual OpenFGA tuple.

### S12 — Weak Identity Match From Imported Data

Source `Identity Record`(s) → `Synonymity Assertion` (`probably_same_as`, weak,
scoped) → `Evidence Source` (import job, match score) → `Lifecycle State`
`proposed` until reviewed.

### S13 — Strong Account Link After Explicit Verification

`Account`(s) or `Identifier`(s) → `Synonymity Assertion` (`same_as`, strong) →
`Evidence Source` (verification event, VC proof, re-authentication) →
revocation/supersession path via `Lifecycle State`.

### S14 — Pseudonymous Profile Linked Only Within Restricted Scope

`Persona`/`Profile` → `Scoped Identifier` → `Synonymity Assertion`
(privacy-limited, restricted `Scope`) → separated re-identification
`Evidence Source` per GDPR pseudonymization pattern.

### S15 — Organization Represented By Legal Entity And Operational Tenants

`Organization` actor → `Legal Entity` relationship or specialization → one or
more `Tenant` scopes → `Representation Relationship` for authorized persons or
agents.

## Scenario Gaps

No scenario requires glossary or principle changes that the current model
cannot satisfy. Remaining ambiguities are documented in `OpenQuestions.md`:

- mandatory Synonymity Assertion field set;
- Realm vs. Tenant promotion for Keycloak-heavy mappings;
- Customer Account resolved: use Commercial Record + Commercial Relationship;
  see `OpenQuestions.md`.

## Invariants

- A Natural Person can control zero, one, or many Accounts.
- An Account belongs to exactly one primary operational Scope, but can have
  relationships to other scopes.
- A Profile presents an Actor, Account, or Persona within a Scope.
- A Principal is a projection for authorization and must not replace Actor or
  Account in the canon.
- A Tenant can be related to an Organization or Customer, but is not identical
  to either.
- A Group carries Membership relationships; Role assignment and relationship
  semantics stay explicit.
- A Synonymity Assertion links records without destroying source identity or
  evidence.
- Lifecycle state applies to relationships and assertions, not only accounts.
- Authorization tuples (Zanzibar/OpenFGA) and Cedar principals are projections
  from canonical actors, accounts, and relationships — not alternate identity
  roots.
- OIDC Subject and SAML Principal are Authenticated Subject projections, not
  Natural Persons.

## External Mapping Rule

When mapping an external system, identify the canonical layer first:

1. Actor layer: who or what participates?
2. Record layer: what operational record exists?
3. Reference layer: what values, claims, or credentials refer or prove?
4. Scope layer: where is the meaning valid?
5. Relationship layer: what typed connection is asserted?
6. Projection layer: what downstream protocol or authorization view is needed?

Only after that mapping should source-specific labels such as `user`, `group`,
`organization`, `realm`, `tenant`, `subject`, or `principal` be adopted in a
downstream artifact.

## Source Grounding

This revision is grounded in the backfilled research corpus (23 source notes).
Key cross-cutting findings:

- Provisioning sources (SCIM, LDAP) model records and group membership, not
  actors directly.
- Federation sources (OIDC, SAML, NIST, SSF) define subject identifiers,
  assurance, and lifecycle events.
- Authorization sources (Zanzibar, OpenFGA, Cedar, Cerbos) are projection
  layers over opaque identifiers.
- Social sources (ActivityPub, FOAF, Schema.org, WebID) separate person, actor,
  account, and social edges.
- VC/DID sources add portable claims and decentralized identifiers.
- Entity-resolution and GDPR sources define synonymity strength and privacy
  constraints.