identity-canon/model/ConceptualModel.md

# 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, Salesforce Account).
- Commercial Commitment: evidenced obligation binding commercial parties (contract,
  subscription, payment mandate, regulated onboarding).
- 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 and one or more Commercial Commitments.
- Ownership (beneficial): natural person owns or controls organization customer
  (KYC beneficial owner pattern).
- 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.

## Commercial Binding Gradient

Identity representations vary in persistence based on commercial stake:

- **Fluid**: no Commercial Commitment; personas and scoped identifiers may rotate
  freely (low counterparty reliance).
- **Bound**: Commercial Commitment + Evidence + often Commercial Record; identifiers
  stabilize because counterparties bear risk (billing, contract, KYC, LEI).

Commercial binding does not merge layers. It increases assurance requirements and
lifecycle rigor on the records and relationships already in the model.

## 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;
- Beneficial Owner as dedicated relationship type vs. Ownership subtype.

## 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.