feat(authorization): hierarchical PDP, start-login helper, and PATs

ARCHITECTURE.md

@@ -64,7 +64,18 @@ application relying-party registration.
 - SAML/OIDC identity-provider desired-state validation and reconciliation;
 - LDAP/Active Directory component preflight and desired-state reconciliation;
 - OIDC relying-party preflight and secret-free desired-state reconciliation;
-- audit and user-operation lock boundaries.
+- audit and user-operation lock boundaries;
+- hierarchical software-unit, menu, inheritance, and SSO-combination
+  authorization decisions consumed from Orgmetra assignment snapshots;
+- app start-login / IdP discovery helper for relying parties;
+- hashed programmable application tokens scoped to one software unit and API.
+
+The hierarchical authorization router carries the existing operator bearer and
+privileged-path dependencies itself, so an embedding application cannot make
+grant administration public by mounting the module without the application
+factory's outer dependency list. The operator credential is a coarse
+operator-admin boundary; ``actor_identity_id`` on a grant is policy metadata,
+not an end-user principal extracted from that bearer request.
 
 The core merge and SCIM layer depends on the narrow `AdminApi` protocol.
 Product extensions are isolated behind `ProductAdminApi`; relying-party client
@@ -93,7 +104,11 @@ modules require neither protocol nor any network client.
   `relying_party_sources`, `relying_party_apply_receipts`;
 - merge audit: `account_merge_audit`;
 - cross-process user mutation lock sidecar:
-  `user_operation_lock_state`.
+  `user_operation_lock_state`;
+- hierarchical authorization grants:
+  `authorization_software_unit_grants`, `authorization_menu_grants`;
+- SSO combination scopes: `authorization_sso_combination_scopes`;
+- hashed programmable tokens: `application_access_tokens`.
 
 Database objects and namespaces use descriptive two-word-or-longer snake_case
 names.
@@ -178,9 +193,21 @@ profiles.
 Each downstream RP is a separate trust boundary. The RP must validate the
 Keyverse issuer, signature/algorithm, expiry, subject, and audience, map the
 verified tenant (`org`/deployment mapping), apply resource and purpose ABAC,
-and then apply bounded role/scope/group RBAC. A registered client or accepted
-mapper receipt never grants authorization by itself; see ADR-0008 for the
-non-fork application matrix and remediation gates.
+and then apply bounded role/scope/group RBAC. A registered client, accepted
+mapper receipt, or Keyverse PDP decision never grants authorization by itself;
+see ADR-0008 for the non-fork application matrix and remediation gates.
+ADR-0010 adds issuer-side hierarchical attributes (`group_company`,
+`legal_entity`, `business_unit`, `team`, `person`, `org_path`) and decisions.
+Those names are distinct from the unmerged LineageWeave `role`/`org`/`workspace`
+profile reserved as ADR-0009 on PR #100. Orgmetra remains employment truth;
+Keyverse binds an opaque subject and does not copy the Orgmetra tree.
+
+Relying applications start brokered login through the Keyverse start-login
+helper (ADR-0011) and may present software-unit-scoped programmable tokens
+(ADR-0012) that are hashed at rest, never inherit org-tree grants, and cannot be
+rotated after revocation, prior rotation, or expiry. Rotation writes the
+replacement and predecessor through one KV-store transaction, then compensates
+the pair through one atomic upsert/delete operation if audit persistence fails.
 
 ## Account and provisioning invariants
 
@@ -246,6 +273,8 @@ explicitly documented deployment-controller responsibility.
 
 Detailed decisions and evidence are maintained under:
 
+- `docs/adr/` — accepted architecture decisions (0001–0008 plus 0010–0012;
+  0009 reserved for the unmerged LineageWeave profile);
 - `docs/superpowers/specs/` — approved feature architecture;
 - `docs/superpowers/plans/` — executable implementation plans;
 - `docs/doctoring/` — standards interpretation and APA 7th traceability;

CHANGELOG.md

@@ -7,6 +7,31 @@ Keep a Changelog, and releases use semantic versioning.
 
 ### Added
 
+- Hierarchical authorization plane (ADR-0010): software-unit ACL, menu
+  ABAC/RBAC decisions, SSO combination scopes, and most-specific org-path
+  inheritance consumed from Orgmetra assignment snapshots. ADR-0008 stays
+  the PEP boundary. Hierarchical attributes use `group_company`,
+  `legal_entity`, `business_unit`, `team`, `person`, and `org_path` so they
+  do not collide with the unmerged LineageWeave `role`/`org`/`workspace`
+  profile reserved as ADR-0009 on PR #100.
+- App start-login helper (ADR-0011) that discovers enabled brokered IdPs from
+  the local registry and returns a Keycloak `kc_idp_hint` authorization URL
+  without metadata or discovery fetch; encoded discovery markers are rejected
+  after URL normalization at the same boundary.
+- Programmable application tokens (ADR-0012) hashed at rest, purpose-bound,
+  software-unit and API scoped, rotatable, auditable, and never a password
+  substitute or inherited secret; failed issue/rotation audit and storage
+  writes are compensated, and runtime verification uses a separate service
+  credential.
+- Authorization decisions now require a tenant-qualified assignment snapshot;
+  grant matching, ABAC constraints, duplicate identity, and KV keys preserve
+  tenant boundaries.
+- Authorization decision metadata now marks strict menu-prefix inheritance
+  correctly when the org path is an exact match.
+- Ambiguous same-named authorization grants can now be read or deleted through
+  an explicit tenant-scoped GET/DELETE query without weakening fail-closed
+  behavior.
+- Start-login issuer input is bound to configured Keyverse public issuer state.
 - ADR-0008 and the non-fork RP authorization matrix, requiring explicit
   Keyverse token validation, tenant/resource ABAC, bounded RBAC, and
   cross-tenant acceptance evidence per application.
@@ -55,6 +80,21 @@ Keep a Changelog, and releases use semantic versioning.
 
 ### Changed
 
+- Authorization decisions now require explicit tenant-bound assignment
+  snapshots, grants, SSO combinations, and application-token verification;
+  software-unit grants reject menu-only ABAC constraints.
+- Start-login now uses a configured Keycloak public issuer and is exposed as a
+  front-channel runtime helper, while PAT management remains operator-gated
+  and PAT verification remains token-gated.
+- Application-token rotation now persists the replacement and rotated
+  predecessor through one atomic KV-store batch before recording the audit
+  event, and restores that pair with one atomic upsert/delete compensation if
+  audit persistence fails.
+
+- The hierarchical authorization router now carries its operator-authentication
+  and privileged-path dependencies at the module boundary, so direct CWL/Naruon
+  embedding cannot accidentally mount grant administration without the existing
+  operator gate.
 - Relying-party deployment controllers now send validated, secret-free metadata
   to Keyverse desired-state PUT instead of applying client representations
   directly to Keycloak; confidential credential placement remains a separate
@@ -89,6 +129,12 @@ Keep a Changelog, and releases use semantic versioning.
 
 ### Fixed
 
+- Application-token rotation now rejects revoked, already-rotated, and expired
+  predecessors instead of reviving retired credentials.
+- Prevented cross-tenant authorization selection, SSO-name collisions, PAT
+  tenant confusion, expired-token revival, and audit-failure state leakage;
+  start-login can no longer reflect an attacker-selected issuer.
+
 - Prevented relying-party inventory from silently accepting a KV key/body
   identity mismatch, rejected unsafe live or `Location`-derived client UUIDs,
   and aligned exact client discovery with Keycloak's documented
@@ -118,6 +164,9 @@ Keep a Changelog, and releases use semantic versioning.
   state storage lock is held.
 - Prevented unknown federation configuration keys, credentials, and private
   values from being echoed through list, get, or update responses.
+- Application-token rotation now validates the replacement purpose,
+  capabilities, lifetime, and software-unit binding before revoking the
+  active token, so invalid rotation requests preserve the working credential.
 - Rejected Unicode-confusable federation aliases outside the explicit ASCII
   slug alphabet.
 - Rejected raw C0 controls, DEL, invalid ports, insecure HTTP SSO or metadata

DOCUMENTATION.md

@@ -16,6 +16,7 @@ Keyverse already has strong feature-specific specifications, doctoring, federati
 | Requirements/evidence traceability | [`docs/TRACEABILITY.md`](docs/TRACEABILITY.md) |
 | Architecture decisions | [`docs/adr/README.md`](docs/adr/README.md) |
 | Federation onboarding | [`docs/federation-onboarding.md`](docs/federation-onboarding.md) |
+| Authorization onboarding | [`docs/authorization-onboarding.md`](docs/authorization-onboarding.md) |
 | RP onboarding | [`docs/rp-onboarding.md`](docs/rp-onboarding.md) |
 | Account merge/unification | [`docs/merge-unification-flow.md`](docs/merge-unification-flow.md) |
 | Standards/APA 7 evidence | [`docs/doctoring/`](docs/doctoring/) and [`docs/papers/`](docs/papers/) |