identity-canon/DownstreamRecommendations.md

# Downstream Recommendations

Status: draft. Updated after IDENTITY-WP-0003 corpus backfill. Implementation
ideas derived from the canon; no implementation in this repository.

## Recommended Consumption Pattern

Downstream repositories should consume identity-canon as a conceptual reference.
Map schemas, APIs, CLI commands, UI labels, and authorization policies to
canonical terms. Do not depend on this repository as a runtime package unless a
later explicit package is extracted.

## Schema Design

- Separate Natural Person, Account, Profile, Credential, and Principal in
  user-management schemas. Corpus confirms SCIM/LDAP use "user" for records,
  Keycloak/ZITADEL for accounts.
- Model Tenant as Scope; relate explicitly to Organization, Customer role, Vendor
  role, Commercial Relationship, and Realm. ZITADEL org-as-tenant and Keycloak
  realm-as-namespace are common mapping patterns.
- Store Stripe Customer / CRM Account as Commercial Record; link to Tenant and
  Organization via Identifier binding. Do not create a `customer_account` table
  that merges billing and login semantics.
- Map Auth0/Stytch "subscriber" to Organization + Customer role + Tenant; treat
  Subscriber as convenience label only.
- Store Synonymity Assertions with relation type, strength, scope, evidence,
  source system, lifecycle state, and privacy classification. Never default to
  destructive merge for duplicate detection.
- Attach IAL/AAL/FAL (or equivalent) to bindings and federation relationships,
  not as a single account trust field.
- Preserve source record IDs (SCIM id, LDAP DN, externalId, OIDC iss+sub) as
  Identifiers with provenance.

## Authorization Adapters

- Project canonical Membership, Delegation, and Administration relationships
  into Zanzibar/OpenFGA tuples rather than encoding social meaning in authz
  graphs.
- Map Cedar Principal/Resource/Action/Context from Account and Relationship;
  carry delegation in Context, not by overloading Principal identity.
- When using Cerbos derived roles, trace ownership/admin derived roles back to
  canonical Ownership or Administration relationships where possible.
- Keep authz `user:` identifiers aligned with Account IDs or Authenticated
  Subject bindings via explicit mapping table.

## Federation Adapters

- Treat OIDC iss+sub and SAML persistent NameID as strong Synonymity Assertion
  candidates after RP verification policy.
- Treat pairwise OIDC sub as Scoped Identifier with privacy-limited assertion.
- Subscribe to SSF/CAEP/RISC events to drive Lifecycle State on accounts,
  credentials, and identifier bindings.
- Separate OIDC authentication (Authenticated Subject) from VC claims
  (Credential + Claim) per OpenID4VC patterns.

## Provisioning Adapters

- SCIM User → Identity Record; map Group → Group + Membership edges.
- LDAP inetOrgPerson → Identity Record; posixAccount → Account facet on same
  or linked record.
- Do not promote SCIM `organization` string to Organization actor without
  separate org entity.

## Social and Profile Adapters

- ActivityPub Actor → Actor + Profile on origin Scope; Follow → Following
  Relationship only.
- FOAF OnlineAccount → Account with service Scope from accountServiceHomepage.
- Schema.org sameAs → weak Synonymity Assertion only; require review before
  promotion to strong.

## Privacy and Entity Resolution

- Implement probabilistic matching as weak `probably_same_as` assertions in
  `proposed` lifecycle state with review queue.
- Store GDPR pseudonymization re-identification keys in separately secured
  scope with restricted access.
- Support assertion revocation and supersession (SSF identifier-changed, manual
  unlink) without deleting source records.

## UI Copy

- Use product-friendly labels externally; maintain internal canonical mappings.
- Avoid showing "user" in schema or API names without a mapping note.

## Avoid For Now

- Do not implement identity provider integrations in this repository.
- Do not add database migrations or production APIs here.
- Do not treat the glossary as a finalized schema.
- Do not use MDM golden-record merge as default linking behavior.
- Do not collapse Realm, Tenant, and Organization into one table without
  relationship modeling.
- Do not introduce `CustomerAccount` as a canonical type; use Commercial Record
  for billing and Organization + Customer role for subscribing parties.

## Suggested Adapter Inventory

| Source family | Primary canonical mapping | Common projection |
| --- | --- | --- |
| SCIM / LDAP | Identity Record, Group, Membership | Account, Principal |
| Keycloak / ZITADEL | Account, Organization, Realm/Tenant | Role, OIDC Subject |
| OIDC / SAML | Authenticated Subject, Identifier | Account link assertion |
| Zanzibar / OpenFGA | Relationship Tuple | Membership, admin edges |
| Cedar / Cerbos | Principal, Resource, Action, Context | Role, derived ownership |
| ActivityPub / FOAF | Actor, Profile, Following | — |
| DID / VC | Identifier, Credential, Claim | Trust relationship |
| Entity resolution | Synonymity Assertion | — |
| Stripe / CRM billing | Commercial Record, Commercial Relationship | Subscription state |
| Auth0 / Stytch B2B | Organization, Customer role, Tenant, Membership | Account, Subscriber label |
| KYC / AML / LEI / DUNS | Commercial Record, Beneficial Ownership Relationship, Registry Identifier, Proxy Commercial Identifier | Assurance, Evidence |
| Salesforce / CRM | Commercial Record, Contact as Natural Person | Account hierarchy |

## Commercial Binding

- Model fluid identity (trials, leads, pseudonyms) without Commercial Commitment until
  counterparty reliance exists.
- On subscription, contract, or KYC acceptance, create Commercial Commitment with
  Evidence Source and lifecycle state.
- Model LEI, UEI, and company registration numbers as Registry Identifier with
  `authority_class` and renewal lifecycle (LEI annual).
- Model DUNS as Proxy Commercial Identifier (ICD 0060); do not treat as
  incorporating-register authority.
- Model KYC beneficial owners as Beneficial Ownership Relationship with
  ownership_prong / control_prong metadata — not Ownership subtype or authz owner.
- Link registry identifiers for the same entity via Synonymity Assertion when
  multiple registries describe one Organization/Legal Entity.
- Separate CRM Account and Stripe Customer as Commercial Records; never merge with login Account.
- Use qualified credentials (eIDAS seal, VC) as Evidence for Commercial Commitment where applicable.
- Map reviews and star ratings to Reputation Signal (opinion tier); never merge with credit scores or legal outcomes.
- Map PAYDEX, SLA metrics, and credit bureau data to Performance Evidence (observed tier).
- Map bonds, escrow, and signed SLAs to Commercial Commitment (committed tier).
- Map arbitration awards and court judgments to Adjudication Outcome (adjudicated tier).
- Trust Relationship projections must cite assurance_basis tier; weight opinion weak by default.
- Never store PAN/CVV in identity-layer stores; use Payment Instrument Reference only.
- Map SetupIntent/mandate success to Payment Mandate Commercial Commitment.
- Map CRM Opportunity to Pipeline Pursuit; promote to Commercial Commitment only on binding_trigger.
- Do not treat Salesforce Forecast "Commit" as Commercial Commitment active state.
- Use settled enums from `commercial-identity-nuance-settlement.md`: `control_basis`,
  `binding_trigger`, `commitment_type`, cross-registry Synonymity strengths.
- Person Account adapters: split Natural Person + Commercial Record; export combined
  projection only with `projection_mode: person_account_combined`.
- FinCEN ID → Registry Identifier on Natural Person; BO exemptions → explicit Evidence.
- LEI↔DUNS Synonymity default medium; LEI↔company reg default strong.
- Reputation portability: `linked_to` Synonymity weak between Reputation Signals.
- Oracle/escrow release → Performance Evidence; ADR/court → Adjudication Outcome.