From ce2899f3d51aa5ef1cd904b29dc8ea5f9cd1ce4a Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 5 Jun 2026 15:36:47 +0200 Subject: [PATCH] Align user-engine intent with identity canon --- INTENT.md | 78 ++++++-- ...WP-0007-identity-domain-canon-alignment.md | 179 ++++++++++++++++++ 2 files changed, 243 insertions(+), 14 deletions(-) create mode 100644 workplans/USER-WP-0007-identity-domain-canon-alignment.md diff --git a/INTENT.md b/INTENT.md index bdd8476..97f93ea 100644 --- a/INTENT.md +++ b/INTENT.md @@ -6,10 +6,11 @@ ## Purpose -`user-engine` exists to provide a reusable, headless user-domain service for -products and platforms that need account, profile, preference, membership, and -application-specific user attribute management without coupling those concerns -to a particular identity provider, authorization engine, or user interface. +`user-engine` exists to provide a reusable, headless user-domain and +identity-domain service for products and platforms that need account, profile, +preference, membership, identity-context, and application-specific user +attribute management without coupling those concerns to a particular identity +provider, authorization engine, security stack, or user interface. ## Primary Utility @@ -21,6 +22,7 @@ It manages: - users and account state; - external identity links; +- actor, principal, subject, and user-context mappings; - profile and preference data; - tenant, application, and team memberships; - application-registered customization attributes; @@ -28,24 +30,58 @@ It manages: - profile projections for consuming applications; - lifecycle and profile-change events. +## Strategic Direction + +`user-engine` is intended to become the NetKingdom identity-domain integration +layer: a headless service that exposes canonical identity, user, account, +membership, tenant, team, profile, lifecycle, and evidence-facing concepts to +applications without requiring those applications to know the technical IAM, +security, authorization, audit, or secret-management implementation details. + +NetKingdom infrastructure remains the source of truth for authentication, +credential assurance, token issuance, policy decisions, security controls, +runtime secrets, and platform audit infrastructure. `user-engine` consumes those +capabilities through explicit adapters and presents a stable domain model +aligned with identity-related InfoTechCanon concepts. + +In this role, `user-engine` should make identity-domain questions easy for +applications and agents to answer: + +- who the current actor is in a domain context; +- which user, account, external identity, principal, or subject references are + involved; +- which tenant, team, application, and membership scopes apply; +- which user-domain facts may be projected into runtime, admin, audit, agent, or + claims-enrichment contexts; +- which lifecycle, access-review, evidence, or integration gaps need attention. + ## Strategic Role `user-engine` separates user-domain management from authentication, authorization, credential lifecycle, and UI experience concerns. -It is intended to integrate through standards-aligned interfaces with identity -providers, provisioning sources, directories, authorization systems, event -sinks, and optional UI surfaces while remaining useful in simple standalone -deployments. +It is intended to integrate through standards-aligned interfaces with +NetKingdom IAM, identity providers, provisioning sources, directories, +authorization systems, security controls, event sinks, audit infrastructure, and +optional UI surfaces while remaining useful in simple standalone deployments. + +It may implement identity-canon entities when they are user-domain facts or +identity-context mappings. It should reference, map to, or consume adjacent +canon entities when their source of truth belongs to NetKingdom infrastructure, +security, access-control, governance, or organization systems. ## Intended Users - application developers adding user/account functionality to a service; -- platform teams managing users across multiple applications; +- platform teams integrating NetKingdom identity infrastructure across multiple + applications; - product teams needing self-service account and preference capabilities; - operators and tenant administrators managing scoped user populations; - agentic systems that need structured access to user preferences and profile - context. + context; +- domain services that need identity-canon aligned user, actor, principal, + subject, tenant, team, membership, and evidence references without depending + on technical IAM implementation details. ## Product Boundaries @@ -56,11 +92,15 @@ It does not aim to be: - a full identity provider; - a password, passkey, session, or MFA system; - a fine-grained authorization engine; +- the policy decision point for protected resources; +- the owner of NetKingdom security controls or runtime secrets; +- the full organization, HR, or directory authority; - a directory server; - a UI application. -It provides the user-domain APIs, catalog metadata, projections, events, and -audit records that those surrounding systems can consume. +It provides the user-domain and identity-domain APIs, mapping records, catalog +metadata, projections, events, evidence references, and audit records that those +surrounding systems can consume. ## Design Principles @@ -70,15 +110,25 @@ audit records that those surrounding systems can consume. - enterprise-integratable; - identity-provider agnostic; - authorization-engine agnostic; +- NetKingdom-integrated without hiding source-of-truth boundaries; +- canon-aligned through explicit entity and relationship mappings; - catalog-driven customization; - explicit ownership, visibility, mutability, and sensitivity of attributes; - layered profiles instead of one global metadata blob; - deterministic and inspectable effective profile resolution; +- evidence and lifecycle awareness for identity-domain changes; - concrete user-domain focus with a possible future extraction path toward a generic profile engine. ## Success Definition `user-engine` succeeds when a repository or application can add robust -user-domain capabilities with minimal coupling while keeping a clear path from -a simple local setup to a governed multi-tenant, multi-application deployment. +user-domain and identity-domain capabilities with minimal coupling while keeping +a clear path from a simple local setup to a governed multi-tenant, +multi-application NetKingdom deployment. + +It should also succeed as an implementation surface for identity-related canon +intent: applications should be able to consume user, account, identity-link, +actor, principal, subject, tenant, team, membership, profile, lifecycle, and +evidence context through stable APIs and mappings without taking a direct +dependency on the technical IAM, authorization, security, or audit substrate. diff --git a/workplans/USER-WP-0007-identity-domain-canon-alignment.md b/workplans/USER-WP-0007-identity-domain-canon-alignment.md new file mode 100644 index 0000000..f5edf69 --- /dev/null +++ b/workplans/USER-WP-0007-identity-domain-canon-alignment.md @@ -0,0 +1,179 @@ +--- +id: USER-WP-0007 +type: workplan +title: "Identity Domain Canon Alignment" +domain: netkingdom +repo: user-engine +status: proposed +owner: codex +topic_slug: netkingdom +planning_priority: high +planning_order: 7 +created: "2026-06-05" +updated: "2026-06-05" +depends_on: + - USER-WP-0006 +--- + +# USER-WP-0007 - Identity Domain Canon Alignment + +## Goal + +Bring `user-engine` scope into alignment with its revised intent: make it the +NetKingdom identity-domain integration layer that exposes identity-canon aligned +user, account, actor, principal, subject, tenant, team, membership, profile, +lifecycle, and evidence context without absorbing identity provider, +credential, authorization, security-control, audit-platform, or organization +authority responsibilities. + +## Scope Direction + +`user-engine` should implement identity-canon entities when they are +user-domain facts or identity-context mappings. It should consume or reference +NetKingdom-owned entities when the source of truth belongs to IAM, security, +authorization, governance, audit, secrets, or organization systems. + +The target integration question is: + +```text +For this domain request, who is the actor, which user/account/principal/subject +context applies, which tenant/team/application scopes are relevant, which +identity-domain facts may be projected, and what evidence or lifecycle work +exists for that context? +``` + +## Non-Goals + +- Do not turn `user-engine` into an identity provider. +- Do not implement passwords, passkeys, sessions, MFA, token issuance, or + credential lifecycle. +- Do not become the policy decision point or final authorization authority. +- Do not own NetKingdom security controls, runtime secrets, or durable platform + audit infrastructure. +- Do not become the full organization, HR, directory, or governance authority. +- Do not rename the repository as part of this workplan without a separate + naming decision record. + +## Tasks + +```task +id: USER-WP-0007-T1 +status: todo +priority: high +``` + +Create a Canon Interface Card for `user-engine` that declares produced, +consumed, owned, mapped, and explicitly non-owned InfoTechCanon concepts. Cover +User, Account, ExternalIdentity, Actor, Principal, Subject, Tenant, Team, +Membership, Organization Role reference, AccessRole reference, Policy reference, +Control reference, Evidence reference, AccessReview reference, and lifecycle +work. + +```task +id: USER-WP-0007-T2 +status: todo +priority: high +``` + +Create entity and edge mapping exports for current domain objects. Map existing +models and service operations to canon concepts and relationships including +`member_of`, `belongs_to_tenant`, `authenticates_as`, `evaluated_as`, +`assigned_role`, `scoped_to`, `governed_by`, `implemented_by`, +`evidenced_by`, and `creates_task`. + +```task +id: USER-WP-0007-T3 +status: todo +priority: high +``` + +Define the first identity-context read model. It should resolve a verified +NetKingdom actor into domain-facing user, account, identity link, principal, +subject, tenant, team, membership, application, and profile projection context +without requiring consumers to know IAM provider details. + +```task +id: USER-WP-0007-T4 +status: todo +priority: high +``` + +Add explicit canon-facing distinctions where current code only has implicit +fields. In particular, distinguish User, Actor, Principal, Subject, Account, +ExternalIdentity, Organization Role reference, AccessRole reference, +Membership, and Grant or grant-like membership facts. + +```task +id: USER-WP-0007-T5 +status: todo +priority: medium +``` + +Add NetKingdom adapter contracts for identity-domain implementation. Preserve +the existing ports while adding or documenting adapters for IAM Profile claims, +authorization decisions and obligations, membership fact export, evidence or +audit reference export, policy/control references, and lifecycle task handoff. + +```task +id: USER-WP-0007-T6 +status: todo +priority: medium +``` + +Add evidence and review references without taking over governance ownership. +Identity-domain mutations, privileged memberships, delegated agent context, +break-glass context, and tenant admin grants should be traceable to audit, +review, approval, exception, remediation, or explicit evidence gaps. + +```task +id: USER-WP-0007-T7 +status: todo +priority: medium +``` + +Add small-SaaS canon conformance scenarios. Cover Ada Admin, Acme, Globex, +tenant isolation policy, namespace-per-tenant control, access review evidence, +tenant onboarding work, explicit grant scope, and integration gaps that become +tracked work rather than silent scope drift. + +```task +id: USER-WP-0007-T8 +status: todo +priority: low +``` + +Create a naming decision record after the alignment artifacts exist. Compare +keeping `user-engine` with renaming to `identity-engine`, +`identity-domain-engine`, or another name. Decide based on actual implemented +scope, consumer expectations, and risk of implying ownership of full IAM or +organization responsibilities. + +## Acceptance Criteria + +- `INTENT.md`, `SCOPE.md`, and public docs consistently describe + `user-engine` as the NetKingdom identity-domain integration layer. +- A completed Canon Interface Card exists for `user-engine`. +- Entity and edge mapping exports cover current user-engine models and mark + gaps explicitly. +- Consumers can ask for identity-domain context without knowing the concrete IAM + provider, authorization system, audit sink, or security-control + implementation. +- User, Actor, Principal, Subject, Account, ExternalIdentity, Tenant, Team, + Membership, Organization Role reference, AccessRole reference, Grant or + grant-like fact, Policy reference, Control reference, Evidence reference, and + AccessReview reference are distinct or explicitly mapped gaps. +- Tenant-scoped privileged access can be traced to scope, decision, policy or + control reference, and evidence or evidence-gap record. +- Small-SaaS conformance scenarios pass or produce explicit, owned gap records. +- The repository name remains unchanged unless a separate naming decision is + accepted. + +## Expected Outputs + +- `docs/canon-interface-card.yaml` +- `docs/canon-mapping.md` or generated equivalent +- identity-context read model and tests +- NetKingdom adapter contract updates +- small-SaaS canon conformance tests +- evidence-gap and lifecycle task examples +- naming decision record