Implement NK-WP-0012 IAM profile specification

docs/adr/ADR-0011-iam-profile-ownership-and-version-governance.md

@@ -0,0 +1,127 @@
+# ADR-0011 - NetKingdom IAM Profile Ownership And Version Governance
+
+**Status:** Accepted
+**Date:** 2026-05-22
+**Deciders:** Bernd Worsch, Codex
+
+## Context
+
+The IAM Profile is the identity contract that applications, flex-auth,
+key-cape, Keycloak, and bootstrap identity tooling all target. It defines
+the OIDC discovery, flow, token, claim, assurance, tenant, and conformance
+requirements that make lightweight and expanded identity modes
+interchangeable at the application boundary.
+
+A draft IAM Profile v0.1 existed in the-custodian canon with an
+all-hubs scope. That draft captured useful material: OIDC discovery,
+Authorization Code + PKCE, service-account tokens, required claims,
+token lifecycle, emergency access, and local-development behavior.
+However, NetKingdom now owns the platform identity domain. SCOPE.md names
+the NetKingdom IAM Profile as an in-scope, versioned standard, and
+ADR-0006 requires key-cape and Keycloak to be implementations of the
+profile rather than the canonical source of authorization semantics.
+
+The v0.1 draft also used hub-specific scope and role vocabulary. That
+made sense for the Custodian hub landscape, but the core NetKingdom
+profile must be platform-neutral so it can serve tenant, service,
+application, and agent use cases without encoding one downstream system's
+scope names.
+
+## Decision
+
+NetKingdom is the canonical owner of the IAM Profile.
+
+The profile is versioned under `canon/standards/` in this repository. The
+first canonical NetKingdom version is
+`canon/standards/iam-profile_v0.2.md`.
+
+The relationship to the earlier the-custodian draft is:
+
+- the-custodian IAM Profile v0.1 is superseded as a core/platform
+  standard;
+- NetKingdom owns the provider-neutral core profile;
+- downstream systems may define hub-, tenant-, or application-specific
+  scopes and roles as extensions, but those extensions must map back to
+  the core identity and authorization input contract;
+- key-cape lightweight mode and Keycloak expanded mode are
+  interchangeable implementations of the same profile;
+- flex-auth consumes the profile as normative identity input and must not
+  re-derive identity facts from provider-specific state.
+
+## Versioning
+
+The IAM Profile uses explicit document versions:
+
+- Patch/editorial changes clarify wording, examples, or non-normative
+  guidance without changing the token contract.
+- Minor versions add optional claims, optional flows, or additional
+  conformance checks that existing implementations can pass unchanged.
+- Major or breaking versions change required claims, claim meanings,
+  validation rules, flow requirements, assurance semantics, tenant
+  semantics, or token acceptance rules.
+
+Every versioned profile file remains immutable enough for downstream
+references to cite. New versions are added as new files rather than
+rewriting historical versions in place, except for clearly editorial
+fixes that do not affect semantics.
+
+## Breaking-Change Governance
+
+A breaking profile change requires:
+
+1. a new ADR or ADR refinement that explains the change and migration
+   path;
+2. a new versioned profile document;
+3. an update to the executable conformance suite;
+4. a coexistence window that lets at least one previous supported profile
+   version and the new version be accepted where practical;
+5. notification in workplans or interface docs for known consumers,
+   especially key-cape, Keycloak/expanded-mode work, flex-auth, and
+   application integration docs.
+
+Breaking changes include:
+
+- removing or renaming a required claim;
+- changing the meaning, type, or allowed values of required claims such
+  as `tenant`, `principal_type`, `roles`, `groups`, `scope`/`scp`, or
+  `assurance`;
+- changing accepted issuer, audience, or signing validation rules;
+- weakening PKCE, MFA/assurance, local-development rejection, or
+  emergency-access requirements;
+- moving authorization decisions into an identity provider instead of
+  flex-auth.
+
+## Consequences
+
+- `canon/standards/iam-profile_v0.2.md` is the canonical profile.
+- the-custodian's v0.1 draft should carry a relocation/deprecation note
+  pointing to this repository.
+- Hub-specific scopes such as `hub:*`, `ops:*`, and `fin:*` are
+  downstream extensions, not core profile vocabulary.
+- key-cape and Keycloak must emit or normalize to the same claim contract
+  before applications and flex-auth consume tokens.
+- The conformance suite in `tools/iam-profile-conformance/` is the
+  executable contract for implementations.
+
+## Alternatives Considered
+
+### Keep The Custodian Draft As Canonical
+
+The draft is useful, but keeping ownership there would conflict with
+NetKingdom's repository scope and with ADR-0006's responsibility split.
+It would also leave the profile coupled to Custodian hub vocabulary.
+
+### Make Keycloak The Reference Provider
+
+Keycloak is the expanded-mode implementation and remains important for
+enterprise federation. Making it the reference provider would make
+lightweight mode, local bootstrap, and future identity adapters secondary
+to one implementation. The accepted model keeps providers
+interchangeable behind the profile.
+
+### Put Scope And Role Vocabulary In The Core Profile
+
+A shared vocabulary is useful, but core identity must stay stable across
+applications and tenants. Downstream systems can define extension scopes
+and roles as long as they map to the core claim shapes and flex-auth
+decision inputs.