generated from coulomb/repo-seed
Align user-engine intent with identity canon
This commit is contained in:
78
INTENT.md
78
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.
|
||||
|
||||
179
workplans/USER-WP-0007-identity-domain-canon-alignment.md
Normal file
179
workplans/USER-WP-0007-identity-domain-canon-alignment.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user