net-kingdom/workplans/NK-WP-0012-iam-profile-specification.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, depends_on, state_hub_workstream_id, enables

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	depends_on	state_hub_workstream_id	enables
NK-WP-0012	workplan	NetKingdom IAM Profile Specification	netkingdom	net-kingdom	finished	worsch	netkingdom	high	12	2026-05-21	2026-05-22	NK-WP-0006	9b8e4afc-eb71-47d9-8750-799a082b320a	NK-WP-0011

NK-WP-0012 — NetKingdom IAM Profile Specification

The IAM Profile is referenced everywhere as "the contract all applications target," but it does not exist as a net-kingdom artifact. A draft v0.1 exists in the-custodian canon (canon/standards/iam-profile_v0.1.md), scoped "all-hubs" and Custodian-flavored. SCOPE.md says net-kingdom owns the IAM Profile. This workplan resolves that: net-kingdom becomes the canonical owner, and the profile is made provider-neutral, tenant- and agent-aware, and conformance-testable.

Goal

Produce the canonical, versioned NetKingdom IAM Profile in net-kingdom canon — the OIDC/PKCE contract every implementation issues and every application and the authorization layer consume — together with an executable conformance check.

The profile is the contract that makes the rest of the architecture coherent:

• it is what key-cape (lightweight) and Keycloak (expanded) each implement, interchangeably (capability ladder C1/C5);
• it is the identity input flex-auth consumes for authorization decisions (responsibility map: the identity layer owns the claim contract — that contract is this profile);
• it is the thing NK-WP-0011-T6 runs conformance checks against, so this workplan enables NK-WP-0011.

Why now / what exists

The v0.1 draft is a strong base — discovery contract, Authorization Code + PKCE human flow, service-account flow, required claims, token lifecycle, emergency/break-glass, and a local-development profile. But it has gaps for the current architecture:

Gap in v0.1	Needed because
Lives in the-custodian, scoped "all-hubs"	net-kingdom owns the profile (SCOPE.md, responsibility map)
Keycloak named as the reference provider	provider-neutral now: key-cape lightweight / Keycloak expanded are interchangeable implementations
Scope/role vocabulary is hub-specific (hub:*, ops:*, fin:*)	the core profile must be platform-neutral; hub/app scopes are downstream extensions
No tenant claim	recursive tenant:platform vs tenant model (NK-WP-0006) needs tenant in the token
Only human/service identities	architecture distinguishes human / service / agent principals
Assurance is implicit	flex-auth decision envelopes require explicit assurance evidence
No executable conformance check	NK-WP-0011-T6 and every implementation need a runnable contract test

Scope

In scope:

• ownership and reconciliation decision (ADR) with the-custodian v0.1
• a provider-neutral, platform-neutral v0.2 profile in net-kingdom canon
• tenant- and agent-aware claims, and explicit assurance evidence
• the identity→authorization claim contract consumed by flex-auth
• an executable conformance check
• versioning and breaking-change governance for the profile
• migration of downstream references to the canonical net-kingdom spec

Out of scope:

• implementing the profile in key-cape or Keycloak (their repos own that)
• defining tenant- or application-specific scope vocabularies
• deploying any identity provider

Tasks

id: NK-WP-0012-T1
state_hub_task_id: 284dda38-b778-445a-a7dc-9b5a12fa380f
status: done
priority: high

Ownership & reconciliation decision (ADR-0011). Record that net-kingdom is the canonical owner of the IAM Profile. Decide how the-custodian's all-hubs v0.1 reconciles: net-kingdom owns the core/platform profile; hub- and app-specific scope vocabularies (hub:*, ops:*, fin:*) become downstream extensions that map back to the core, not part of it. Define the profile's versioning and breaking-change governance (what a breaking change is, how downstream is notified, how versions coexist).

id: NK-WP-0012-T2
state_hub_task_id: 0070398d-b0a4-4c11-a6fa-000166e1108f
status: done
priority: high

Author IAM Profile v0.2 (provider-neutral core). Create canon/standards/iam-profile_v0.2.md in net-kingdom. Carry forward the solid v0.1 material — discovery contract, Authorization Code + PKCE human flow, service-account flow, required/recommended claims, token lifecycle, emergency/break-glass, local-development profile — and make it provider-neutral: key-cape (lightweight) and Keycloak (expanded) are named as interchangeable implementations, neither as "the" reference. Remove hub-specific vocabulary from the core.

id: NK-WP-0012-T3
state_hub_task_id: 6fc2a5e1-1480-42f1-86a2-3e714359e1ba
status: done
priority: high

Extend for the recursive and agent model. Add a tenant claim (tenant:platform vs tenant id), formalize the human / service / agent principal types and how each is represented, and define an explicit assurance evidence claim (how authentication strength / MFA is conveyed in the token). Align with NK-WP-0006 and the responsibility map.

id: NK-WP-0012-T4
state_hub_task_id: 0e52ed45-afa7-4832-9d6a-1ebbbab43872
status: done
priority: high

Define the identity→authorization claim contract. Specify exactly which claims the profile guarantees as inputs to flex-auth decision envelopes — subject, issuer, audience, tenant, groups, roles, scopes, assurance — so flex-auth treats the profile as normative input and never re-derives identity. This is the contract named in the responsibility map.

id: NK-WP-0012-T5
state_hub_task_id: f0a62e77-b781-4625-b8bd-d191b48af58e
status: done
priority: high

Executable conformance check. Build a runnable suite that validates an issuer/implementation against the profile: discovery document completeness, PKCE enforcement, claim shape, JWKS and key-rotation tolerance, token validation (issuer/audience/expiry/signature), and rejection of local-development issuers in production. This is the artifact NK-WP-0011-T6 consumes; it must run against both a key-cape and a Keycloak issuer.

id: NK-WP-0012-T6
state_hub_task_id: a1fd53a9-526f-4d87-89db-6073710c885d
status: done
priority: medium

Migration & cross-references. Supersede or relink the-custodian v0.1 (deprecation note pointing at the net-kingdom canonical spec), and update downstream references — key-cape and flex-auth interface docs, NK-WP-0011, and any architecture docs — to cite the canonical net-kingdom profile. Per ADR-0010, downstream intents are not touched; only interface/reference docs.

Acceptance Criteria

• The canonical IAM Profile lives in net-kingdom canon, versioned, and an ADR records ownership and the reconciliation with the-custodian v0.1.
• The core profile is provider-neutral and platform-neutral (no hub-specific scopes in the core; no single "reference provider").
• The profile carries tenant, principal-type (human/service/agent), and assurance claims, aligned with the recursive model.
• The claims flex-auth consumes are specified as a normative contract.
• An executable conformance check exists and passes against both a key-cape and a Keycloak issuer.
• Versioning and breaking-change governance is documented.
• Downstream reference docs point at the canonical spec; the custodian v0.1 carries a deprecation/relocation note.

Completion Notes

• ADR: docs/adr/ADR-0011-iam-profile-ownership-and-version-governance.md
• Canonical profile: canon/standards/iam-profile_v0.2.md
• Executable conformance suite: tools/iam-profile-conformance/iam_profile_conformance.py
• Fixture tests cover key-cape-like and Keycloak-like issuers, local-dev rejection in production mode, tenant claim enforcement, provider-native role normalization warnings, and delegated-agent claim shape.
• Cross-repo reference docs updated without touching downstream INTENT.md: key-cape README/spec references now point at v0.2, and flex-auth consumption docs plus claim fixtures now include v0.2 tenant, principal, and assurance inputs.

Dependencies & Sequencing

• Depends on NK-WP-0006 for the recursive tenant model the claims encode.
• Enables NK-WP-0011 — T6 (IAM Profile conformance) cannot pass without the spec and the conformance check from this workplan. NK-WP-0012 should land before NK-WP-0011-T6.
• Coordinates with flex-auth (the consumed claim contract, T4) and with key-cape/Keycloak as the implementations the conformance check runs against — those repos implement, this workplan specifies and tests.

Resolved Questions

• Canonical role claim: roles is canonical. realm_access.roles is a transitional/provider-native source that must be mapped before production consumption.
• Audience granularity: the core profile requires the receiving service in aud; endpoint/resource granularity belongs to flex-auth resource/action policy.
• Agent principals differ from service accounts through principal_type: agent, an agent object, and delegated actor context (actor_sub or act.sub) when applicable.
• The conformance check is a standalone tool in net-kingdom for v0.2. Other repos consume it as an executable contract rather than importing a shared library for now.