IAM Profile consumption doc + claim fixtures; close FLEX-WP-0005

Completes FLEX-WP-0005 T05 and closes the Foundations and Topaz
Alignment workstream.

docs/iam-profile-consumption.md captures flex-auth's input surface
against NetKingdom IAM Profile v0.1:
- boundary (flex-auth consumes verified claims; upstream layer
  validates signatures and audiences)
- normalized input envelope (matches Markitect's EnterpriseIdentity)
- required, recommended, and tolerated claim variations
- role-claim location union (top-level / realm_access / resource_access)
- scope encoding (string vs array)
- principal-type detection (human / service / emergency)
- group-overage and freshness expectations
- production vs local-development handling

examples/claims/ ships five contract fixtures:
- key-cape-lightweight.yaml (profile minimum)
- keycloak-heavy.yaml (full variation set + MFA)
- service-account.yaml (svc-* hub-to-hub)
- emergency.yaml (break-glass with incident metadata)
- keycloak-group-overage.yaml (Entra-style hasgroups: true)

All fixtures parse as valid YAML. They become contract tests for the
standalone evaluator (FLEX-WP-0002 P2.4) and the Topaz adapter
(FLEX-WP-0004 T01); both code paths must produce identical normalized
envelopes for the same fixture.

FLEX-WP-0005 workstream marked status=done in this file and completed
in the State Hub. FLEX-WP-0002 is now fully unblocked.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

examples/claims/README.md

@@ -0,0 +1,23 @@
+# examples/claims/
+
+Contract fixtures for the NetKingdom IAM Profile v0.1 claim shapes
+flex-auth must accept. Each file is the *raw verified claim map* as
+flex-auth receives it from the upstream identity layer (key-cape or
+Keycloak); flex-auth's normalization produces the same
+`EnterpriseIdentity`-shaped envelope for all of them.
+
+See `docs/iam-profile-consumption.md` for the full consumption
+surface.
+
+| Fixture | Provider | Demonstrates |
+| --- | --- | --- |
+| `key-cape-lightweight.yaml` | key-cape lightweight mode | Profile-conformant minimum: single audience, top-level `roles` array, single-factor `amr=pwd`. |
+| `keycloak-heavy.yaml` | Keycloak production | Full variation set: `realm_access.roles` + `resource_access.<client>.roles`, scope as space-separated string, MFA via `amr=otp`, multiple audiences. |
+| `service-account.yaml` | Either provider | Hub-to-hub service account; `service` + `operator` roles, no `preferred_username`, narrow scope. |
+| `emergency.yaml` | Either provider | Break-glass human identity; `emergency` role, short expiry, hardware MFA, audit-trail metadata in an `emergency` claim. |
+| `keycloak-group-overage.yaml` | Entra/Keycloak | Group-claim overage signal (`hasgroups: true`); flex-auth's directory resolver fetches the full set. |
+
+These fixtures are loaded by the standalone evaluator's contract tests
+(`FLEX-WP-0002 P2.4`) and by the Topaz adapter's contract tests
+(`FLEX-WP-0004 T01`). Both code paths MUST produce identical
+normalized envelopes for the same fixture.

examples/claims/emergency.yaml

@@ -0,0 +1,31 @@
+# Claim envelope for an emergency (break-glass) human principal. Short
+# expiry, emergency role, requires MFA per the profile, and triggers
+# durable audit recording on every flex-auth decision that involves it.
+#
+# Reference: NetKingdom IAM Profile v0.1 §"Human Override and Emergency
+# Access". flex-auth maps this to principal_type=emergency and emits a
+# `record_emergency` obligation on every decision.
+
+iss: https://sso.netkingdom.example/realms/netkingdom
+sub: f1c4f64e-2c0c-4cda-8c9f-9f3f8f3a2b0e
+aud:
+  - flex-auth
+exp: 1767226200    # iat + 10 minutes; emergency tokens are short-lived
+iat: 1767225600
+auth_time: 1767225595
+azp: ops-console
+preferred_username: ada
+email: ada@netkingdom.example
+scope: openid profile hub:admin
+roles:
+  - emergency
+  - admin
+amr:
+  - pwd
+  - otp
+  - hwk
+acr: "3"
+emergency:
+  incident_id: INC-2026-0042
+  authorized_by: "team:platform-stewards"
+  reason: "credential rotation playbook step 4"

examples/claims/key-cape-lightweight.yaml

@@ -0,0 +1,24 @@
+# Claim envelope a key-cape (lightweight mode) deployment emits for an
+# authenticated human user. Profile-conformant minimum: required claims
+# only, single audience, simple roles list, OIDC standard amr values.
+#
+# Reference: docs/iam-profile-consumption.md, NetKingdom IAM Profile v0.1
+# §"Required Claims" and §"Local Development Profile".
+
+iss: https://idp.netkingdom.local/keycape
+sub: user-7f9e2b
+aud:
+  - flex-auth
+exp: 4102444800  # 2100-01-01, kept far-future for stable fixtures
+iat: 1767225600  # 2026-01-01
+preferred_username: ada
+email: ada@netkingdom.local
+name: Ada Lovelace
+scope: openid profile hub:read
+roles:
+  - viewer
+amr:
+  - pwd
+acr: "1"
+groups:
+  - /markitect/readers

examples/claims/keycloak-group-overage.yaml

@@ -0,0 +1,26 @@
+# Claim envelope when the token-side `groups` list has been clipped by
+# the IdP. Both Microsoft Entra and Keycloak signal this differently;
+# this fixture shows the Entra-style `hasgroups: true` flag. flex-auth
+# sets directory.group_overage = true and depends on the directory
+# resolver (FLEX-WP-0004 T05) to fetch the full set.
+#
+# Reference: docs/iam-profile-consumption.md §"Group Overage and
+# Freshness".
+
+iss: https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0
+sub: f1c4f64e-2c0c-4cda-8c9f-9f3f8f3a2b0e
+aud:
+  - flex-auth
+exp: 4102444800
+iat: 1767225600
+preferred_username: ada
+name: Ada Lovelace
+scope: openid profile hub:read
+roles:
+  - viewer
+hasgroups: true
+_claim_names:
+  groups: src1
+_claim_sources:
+  src1:
+    endpoint: https://graph.microsoft.com/v1.0/users/f1c4f64e/getMemberObjects

examples/claims/keycloak-heavy.yaml

@@ -0,0 +1,43 @@
+# Claim envelope a Keycloak (heavy mode) deployment emits for an
+# authenticated human user with MFA. Demonstrates the full set of
+# variations flex-auth must normalize: roles in realm_access AND
+# resource_access, scope as space-separated string, multiple audiences,
+# enriched assurance via amr=otp.
+#
+# Reference: docs/iam-profile-consumption.md §"Tolerated Variations".
+
+iss: https://sso.netkingdom.example/realms/netkingdom
+sub: f1c4f64e-2c0c-4cda-8c9f-9f3f8f3a2b0e
+aud:
+  - flex-auth
+  - markitect-tool
+exp: 4102444800
+iat: 1767225600
+auth_time: 1767225590
+azp: markitect-cli
+preferred_username: ada
+email: ada@netkingdom.example
+email_verified: true
+name: Ada Lovelace
+given_name: Ada
+family_name: Lovelace
+scope: openid profile email hub:read hub:write hub:capability
+realm_access:
+  roles:
+    - default-roles-netkingdom
+    - operator
+resource_access:
+  flex-auth:
+    roles:
+      - reader
+  markitect-tool:
+    roles:
+      - editor
+groups:
+  - /platform/architecture
+  - /markitect/readers
+amr:
+  - pwd
+  - otp
+acr: "2"
+sid: 4c0a3a8a-3a47-4f2f-8e89-9e5f9b0a0a0a

examples/claims/service-account.yaml

@@ -0,0 +1,20 @@
+# Claim envelope for a hub-to-hub service account (client_credentials
+# grant). Profile-required `service` role, scoped tightly to the
+# operation it performs. No preferred_username (service identities are
+# named after the service and environment per the profile).
+#
+# Reference: NetKingdom IAM Profile v0.1 §"Service Account Flow" and
+# §"Hub-to-Hub Service Account Pattern".
+
+iss: https://sso.netkingdom.example/realms/netkingdom
+sub: svc-markitect-tool-prod
+aud:
+  - flex-auth
+exp: 4102444800
+iat: 1767225600
+azp: svc-markitect-tool-prod
+client_id: svc-markitect-tool-prod
+scope: hub:read hub:capability
+roles:
+  - service
+  - operator