Implement identity canon alignment

docs/canon-interface-card.yaml

@@ -0,0 +1,118 @@
+subsystem: user-engine
+description: >
+  NetKingdom identity-domain integration layer for user, account, identity-link,
+  tenant, membership, profile, lifecycle, and evidence-facing context.
+status: candidate
+owner: codex
+updated: "2026-06-05"
+
+implements:
+  - identity-canon conceptual model as an implementation-facing domain facade
+  - InfoTechCanon user-engine evaluation pack
+  - small-saas user-management alignment surface
+
+produces:
+  - User
+  - Account
+  - Identity Record
+  - Scoped Identifier
+  - Profile
+  - Tenant
+  - Membership Relationship
+  - Authenticated Subject reference
+  - Authorization Principal reference
+  - Evidence Source reference
+  - Access Grant or grant-like membership fact
+
+consumes:
+  - NetKingdom IAM Profile claims
+  - verified issuer and subject identifiers
+  - assurance and principal type claims
+  - authorization decisions and obligations
+  - policy, control, review, exception, and evidence references
+  - lifecycle task references from downstream task systems
+  - platform audit and event sinks
+
+owned_concepts:
+  user_record: User-engine local user record mapped to identity-canon User as a convenience term.
+  account_record: Operational account state for a user-engine scope.
+  external_identity_link: Source-specific issuer and subject link to a user record.
+  profile_value: Scoped profile or preference value.
+  membership_fact: User-domain relationship to tenant, team, application, or scope.
+  identity_context: Canon-facing read model over user, account, actor, subject, principal, scope, memberships, profile, and evidence references.
+
+mapped_not_owned:
+  Actor: Consumed from verified identity claims and represented as canon reference.
+  Authenticated Subject: Projected from issuer and subject after authentication.
+  Authorization Principal: Projected for the authorization system; final decisions remain outside user-engine.
+  Policy: Referenced from authorization/governance systems.
+  Control: Referenced from security/governance systems.
+  Evidence Source: Referenced from audit, review, approval, or verification systems.
+  AccessReview: Referenced from governance or review systems.
+  Organization: Referenced when tenants, teams, or users map to organization systems.
+  Credential: Explicitly not stored or lifecycle-managed by user-engine.
+
+accepted_relationships:
+  - identity_link
+  - belongs_to_tenant
+  - authenticates_as
+  - evaluated_as
+  - member_of
+  - role_label
+  - scoped_to
+  - governed_by
+  - implemented_by
+  - evidenced_by
+  - creates_task
+
+emitted_events:
+  - user.created
+  - account.status_changed
+  - tenant_account.status_changed
+  - identity.linked
+  - membership.added
+  - profile.value_set
+  - application.registered
+  - catalog.published
+
+required_identifiers:
+  actor_key: "issuer + subject"
+  user_id: "opaque user-engine user id"
+  account_id: "opaque user-engine account id"
+  identity_id: "opaque user-engine external identity id"
+  tenant: "NetKingdom-aligned tenant or platform scope"
+  application_id: "registered application id when projection is application-scoped"
+  correlation_id: "operation-level audit and event correlation id"
+
+mapping_rules:
+  - Resolve source terms such as user, group, role, tenant, subject, and principal into identity-canon layers before exposing them as implementation concepts.
+  - Keep account records, authenticated subjects, and authorization principals distinct even when they share issuer or subject identifiers.
+  - Treat memberships as relationship facts that may produce grant-like access facts, not as final authorization decisions.
+  - Preserve source system, scope, lifecycle state, and evidence reference whenever a relationship affects access, privacy, or lifecycle.
+  - Link policy, control, review, exception, and task concepts by reference unless user-engine is the actual source of truth.
+
+validation_rules:
+  - User, Account, Actor, Authenticated Subject, Authorization Principal, Tenant, Team, Membership, and Profile must remain distinguishable in the identity context read model.
+  - Tenant-scoped privileged membership must expose scope and evidence or an explicit evidence gap.
+  - Cross-tenant context must be denied unless the actor is a platform operator.
+  - Claims enrichment projections must not imply token issuance ownership.
+  - Credential, MFA, policy decision, and durable platform audit ownership must remain outside user-engine.
+
+source_of_truth:
+  user_records: user-engine
+  account_state: user-engine
+  external_identity_links: user-engine
+  profile_values: user-engine
+  membership_facts_created_here: user-engine
+  authentication: NetKingdom IAM infrastructure
+  credential_assurance: NetKingdom IAM/security infrastructure
+  authorization_decisions: NetKingdom authorization infrastructure
+  policy_and_control_definitions: NetKingdom governance/security infrastructure
+  durable_platform_audit: NetKingdom audit infrastructure
+  organization_authority: NetKingdom organization or directory systems
+
+known_deviations:
+  - User remains a local implementation class even though identity-canon treats user as a non-root convenience term; mappings must state whether it represents actor-facing profile holder, account owner, or local user record.
+  - Access Grant is currently a grant-like reference derived from memberships, not a durable authorization grant table.
+  - Evidence Source references currently derive from local audit records unless an external evidence exporter is supplied.
+  - AccessReview, Policy, Control, Exception, and lifecycle Task are references or gaps, not first-class owned records.