From d323276e1d5b8e3edd5c0f65d1b0e03d5a5ea4c6 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 24 Aug 2026 21:56:58 +0000 Subject: [PATCH] docs(adr): expand 0001-0008 with verified APA 7th citations Add Context, Decision, and Consequences to the thin live-main ADRs and attach APA 7th references whose DOI or official catalog URL was opened from IETF, OpenID, OASIS, NIST, W3C, Keycloak, or SLSA records. Co-authored-by: Seongho Bae --- CHANGELOG.md | 5 ++ docs/adr/0001-keycloak-hub.md | 69 ++++++++++++++++- docs/adr/0002-passwordless-local-accounts.md | 64 +++++++++++++++- docs/adr/0003-identity-matching.md | 75 ++++++++++++++++++- docs/adr/0004-desired-state-reconciliation.md | 70 ++++++++++++++++- docs/adr/0005-secret-ownership.md | 64 +++++++++++++++- docs/adr/0006-user-operation-lock.md | 51 +++++++++++-- docs/adr/0007-automation-authority.md | 58 +++++++++++++- ...0008-keyverse-rp-authorization-boundary.md | 47 +++++++++++- docs/adr/README.md | 8 ++ 10 files changed, 490 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5462dfb..ce941cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -55,6 +55,11 @@ Keep a Changelog, and releases use semantic versioning. ### Changed +- Expanded architecture decision records 0001–0008 with Context, Decision, + Consequences, and APA 7th references whose DOI or official catalog URL was + opened from the IETF RFC Editor, OpenID Foundation, OASIS, NIST CSRC/nvlpubs, + W3C, Keycloak documentation, or SLSA specification. Decision intent is + unchanged. - 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 diff --git a/docs/adr/0001-keycloak-hub.md b/docs/adr/0001-keycloak-hub.md index 1dd0af9..9759844 100644 --- a/docs/adr/0001-keycloak-hub.md +++ b/docs/adr/0001-keycloak-hub.md @@ -1,6 +1,71 @@ # ADR-0001: Keep Keycloak and Keyverse as the ecosystem identity hub **Status:** Accepted -**Date:** 2026-08-09 +**Date:** 2026-08-09 +**Updated:** 2026-08-24 -Keyverse uses Keycloak as the standards-based identity engine and adds CWL-owned control services around it. Employer/customer ADFS, LDAP/AD, external OIDC, and HR/IGA are federation/provisioning sources rather than peer hubs. CWL relying parties trust the Keyverse/Keycloak boundary instead of administering those external systems directly. Customer-specific federation remains deployment data, not portable realm code. \ No newline at end of file +## Context + +ContextualWisdomLab products need one identity control plane that can run +standalone and also be called by composition hubs such as Naruon and CWL. +OpenID Connect Core 1.0 is an identity layer on OAuth 2.0: a relying party +verifies the end user from authentication performed by an authorization server +and receives interoperable claims (Sakimura et al., 2023; Hardt, 2012). SAML 2.0 +defines XML assertions and protocols for the same federation role when the +upstream source is an employer ADFS or similar SAML identity provider (OASIS +Security Services Technical Committee, 2005). NIST SP 800-63C-4 describes +federation as a credential service provider that supplies authentication and +optional subscriber attributes to separately administered relying parties +(Temoshok, Richer, et al., 2025). + +Keycloak is the Apache-2.0 engine that already executes OIDC, OAuth, SAML +brokering, WebAuthn, LDAP user storage, and client lifecycle. Keycloak's Server +Administration Guide documents identity brokering so an external IdP +authenticates the user and Keycloak issues its own tokens to applications +(Keycloak, n.d.). Treating each employer directory or ADFS farm as a peer hub +would force every CWL relying party to administer those systems, duplicate +trust policy, and lose a portable realm. + +This ADR records a product and deployment-boundary choice. It does not claim +NIST, OASIS, or OpenID conformance. + +## Decision + +Keyverse uses Keycloak as the standards-based identity engine and adds CWL-owned +control services around it. Employer/customer ADFS, LDAP/AD, external OIDC, and +HR/IGA are federation/provisioning sources rather than peer hubs. CWL relying +parties trust the Keyverse/Keycloak boundary instead of administering those +external systems directly. Customer-specific federation remains deployment data, +not portable realm code. + +## Consequences + +- Ecosystem applications obtain tokens from Keyverse/Keycloak. They do not + become identity hubs for sibling products. +- The portable `cwl` realm stays free of employer-specific SAML, OIDC, LDAP, or + application client registrations. +- Keyverse remains a leaf that must start independently and remain callable from + Naruon or CWL. Composition does not transfer hub ownership to the caller. +- Identity matching, desired-state onboarding, secret ownership, and downstream + authorization stay in later ADRs; this decision only names the hub. + +## References + +Hardt, D. (Ed.). (2012). *The OAuth 2.0 authorization framework* (RFC 6749). +Internet Engineering Task Force. https://doi.org/10.17487/RFC6749 + +Keycloak. (n.d.). *Server Administration Guide*. Retrieved August 24, 2026, from +https://www.keycloak.org/docs/latest/server_admin/ + +OASIS Security Services Technical Committee. (2005). *Assertions and protocols +for the OASIS Security Assertion Markup Language (SAML) V2.0* (OASIS Standard). +OASIS. https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf + +Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., & Mortimore, C. (2023). +*OpenID Connect Core 1.0 incorporating errata set 2*. OpenID Foundation. +https://openid.net/specs/openid-connect-core-1_0.html + +Temoshok, D., Richer, J., Choong, Y.-Y., Fenton, J., Lefkovitz, N., +Regenscheid, A., & Galluzzo, R. (2025). *Digital identity guidelines: +Federation and assertions* (NIST SP 800-63C-4). National Institute of Standards +and Technology. https://doi.org/10.6028/NIST.SP.800-63C-4 diff --git a/docs/adr/0002-passwordless-local-accounts.md b/docs/adr/0002-passwordless-local-accounts.md index 0ff62ca..e0b524c 100644 --- a/docs/adr/0002-passwordless-local-accounts.md +++ b/docs/adr/0002-passwordless-local-accounts.md @@ -1,6 +1,66 @@ # ADR-0002: Keep ecosystem-local accounts passwordless-first **Status:** Accepted -**Date:** 2026-08-09 +**Date:** 2026-08-09 +**Updated:** 2026-08-24 -The portable local browser flow uses WebAuthn/passkeys and does not include an ordinary password authenticator. Registration creates no password and uses a controlled enrollment action. External federation may rely on its upstream authentication policy, but Keyverse does not silently add a local password fallback for ecosystem-local accounts. Changing this boundary requires explicit security/product review and migration evidence. \ No newline at end of file +## Context + +Ecosystem-local accounts authenticate at Keyverse rather than at an employer +IdP. Ordinary passwords are reusable, resettable, and phishable. Web +Authentication Level 2 defines scoped public-key credentials created by +authenticators with user consent, which is the protocol basis for passkeys +(Hodges et al., 2021). NIST SP 800-63B-4 is the current final authentication +and authenticator-management volume of the Digital Identity Guidelines; it +supersedes the withdrawn 2017 SP 800-63B and defines authenticator assurance +for phishing-resistant authenticators (Temoshok, Fenton, et al., 2025). OAuth +2.0 bearer tokens can be used by any party that possesses them, so local login +must not add a password that can be stolen and replayed beside a short-lived +bearer (Jones & Hardt, 2012). + +Keycloak's Server Administration Guide documents WebAuthn passwordless +credentials and required actions that enroll those credentials without a +password form (Keycloak, n.d.). External federated users may still follow their +upstream authentication policy. This ADR is a Keyverse policy choice for the +portable `cwl` browser flow. It does not claim a NIST authenticator-assurance +level. + +## Decision + +The portable local browser flow uses WebAuthn/passkeys and does not include an +ordinary password authenticator. Registration creates no password and uses a +controlled enrollment action. External federation may rely on its upstream +authentication policy, but Keyverse does not silently add a local password +fallback for ecosystem-local accounts. Changing this boundary requires explicit +security/product review and migration evidence. + +## Consequences + +- The bound browser flow and realm validator reject `auth-password-form`, + `auth-username-password-form`, and other password authenticators. +- Headless registration accepts identity and profile data only, then uses a + bounded Keycloak action email for address verification and passkey enrollment. +- A local password reset surface is not part of the portable realm. +- Federated authentication remains an upstream policy. Linking still requires + the evidence rules in ADR-0003. +- Reintroducing a password authenticator is a new architecture change, not a + configuration toggle. + +## References + +Hodges, J., Jones, J. C., Jones, M. B., Kumar, A., & Lundberg, E. (Eds.). +(2021, April 8). *Web authentication: An API for accessing public key +credentials Level 2*. World Wide Web Consortium. +https://www.w3.org/TR/webauthn-2/ + +Jones, M., & Hardt, D. (2012). *The OAuth 2.0 authorization framework: Bearer +token usage* (RFC 6750). Internet Engineering Task Force. +https://doi.org/10.17487/RFC6750 + +Keycloak. (n.d.). *Server Administration Guide*. Retrieved August 24, 2026, from +https://www.keycloak.org/docs/latest/server_admin/ + +Temoshok, D., Fenton, J., Choong, Y.-Y., Lefkovitz, N., Regenscheid, A., +Galluzzo, R., & Richer, J. (2025). *Digital identity guidelines: Authentication +and authenticator management* (NIST SP 800-63B-4). National Institute of +Standards and Technology. https://doi.org/10.6028/NIST.SP.800-63B-4 diff --git a/docs/adr/0003-identity-matching.md b/docs/adr/0003-identity-matching.md index 4045434..4668a00 100644 --- a/docs/adr/0003-identity-matching.md +++ b/docs/adr/0003-identity-matching.md @@ -1,6 +1,77 @@ # ADR-0003: Use exact external subject, then verified email, then explicit link **Status:** Accepted -**Date:** 2026-08-09 +**Date:** 2026-08-09 +**Updated:** 2026-08-24 -Account matching precedence is exact `(identity_provider, subject)`, then verified email under policy, then explicit operator link. Unverified email never authorizes automatic linking or merge. Merged duplicate accounts remain disabled tombstones with survivor lineage. This decision is shared by account unification, federation, and SCIM so one path cannot weaken another's identity evidence. \ No newline at end of file +## Context + +One human can arrive through several sources: an employer SAML subject, an +external OIDC `sub`, a SCIM provisioned user, and a local passkey account. +OpenID Connect Core 1.0 requires a unique, never-reassigned `sub` issuer +subject and treats `email_verified` as a boolean that is true only when the +OpenID provider has verified control of the address (Sakimura et al., 2023). +SAML 2.0 name identifiers likewise identify a subject in a given issuer +namespace rather than a shared email string (OASIS Security Services Technical +Committee, 2005). NIST SP 800-63C-4 requires relying parties to treat +federation assertions as evidence about a specific federated identifier and +not to infer a new identity from an unverified attribute (Temoshok, Richer, et +al., 2025). SCIM's protocol and core schema identify users by a resource `id` +and optional external identifiers, not by an unconfirmed email coincidence +(Hunt, Grizzle, Ansari, et al., 2015; Hunt, Grizzle, Wahlstroem, & Mortimore, +2015). + +Automatic merge on an unverified email would let an attacker bind a victim +account to an address they do not control. Identity fields used for matching +are therefore handled through purpose-bound access, encryption in transit and +at rest, and audit of privileged outcomes. They are not masked in a way that +would hide the exact subject or verified-email evidence required to decide a +link. + +This ADR is a Keyverse evidence-precedence policy. It does not claim NIST +federation-assurance conformance. + +## Decision + +Account matching precedence is exact `(identity_provider, subject)`, then +verified email under policy, then explicit operator link. Unverified email +never authorizes automatic linking or merge. Merged duplicate accounts remain +disabled tombstones with survivor lineage. This decision is shared by account +unification, federation, and SCIM so one path cannot weaken another's identity +evidence. + +## Consequences + +- Exact external subject wins even when emails differ or are missing. +- Verified email may suggest a candidate only when both sides hold the same + verified address and policy allows it. +- An operator link is an explicit privileged action and is audited. +- Unverified email never authorizes link or merge, including when a caller + supplies an explicit-link flag. +- Tombstoned duplicates stay disabled and retain survivor lineage so later + SCIM or login events cannot revive the wrong account. +- Account unification, federation onboarding, and inbound SCIM share this + order. A later path cannot add a weaker automatic rule. + +## References + +Hunt, P. (Ed.), Grizzle, K., Ansari, M., Wahlstroem, E., & Mortimore, C. +(2015). *System for Cross-domain Identity Management: Protocol* (RFC 7644). +Internet Engineering Task Force. https://doi.org/10.17487/RFC7644 + +Hunt, P. (Ed.), Grizzle, K., Wahlstroem, E., & Mortimore, C. (2015). *System +for Cross-domain Identity Management: Core schema* (RFC 7643). Internet +Engineering Task Force. https://doi.org/10.17487/RFC7643 + +OASIS Security Services Technical Committee. (2005). *Assertions and protocols +for the OASIS Security Assertion Markup Language (SAML) V2.0* (OASIS Standard). +OASIS. https://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf + +Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., & Mortimore, C. (2023). +*OpenID Connect Core 1.0 incorporating errata set 2*. OpenID Foundation. +https://openid.net/specs/openid-connect-core-1_0.html + +Temoshok, D., Richer, J., Choong, Y.-Y., Fenton, J., Lefkovitz, N., +Regenscheid, A., & Galluzzo, R. (2025). *Digital identity guidelines: +Federation and assertions* (NIST SP 800-63C-4). National Institute of Standards +and Technology. https://doi.org/10.6028/NIST.SP.800-63C-4 diff --git a/docs/adr/0004-desired-state-reconciliation.md b/docs/adr/0004-desired-state-reconciliation.md index 35ba95c..cc5543e 100644 --- a/docs/adr/0004-desired-state-reconciliation.md +++ b/docs/adr/0004-desired-state-reconciliation.md @@ -1,6 +1,72 @@ # ADR-0004: Use side-effect-free preflight and re-observed desired-state reconciliation **Status:** Accepted -**Date:** 2026-08-09 +**Date:** 2026-08-09 +**Updated:** 2026-08-24 -Federation, directory, and relying-party onboarding separate deterministic local preflight from external apply. Where Keyverse owns desired state, intent is persisted before remote mutation, duplicate remote matches fail closed, and a canonical apply receipt is written only after exact live re-observation. Delete uses remote-first ordering where local-first deletion could create false success. Preflight success never means external login/bind/provisioning success. \ No newline at end of file +## Context + +Federation, LDAP/AD, and relying-party onboarding accept hostile or incomplete +deployment payloads. Applying those payloads directly to Keycloak would create +live identity-provider, directory, or client objects before Keyverse could +prove they meet the closed local policy. OAuth 2.0 security BCP 240 updates +RFC 6749 and RFC 6750 and requires authorization servers and clients to reject +unsafe redirect, token, and client configurations rather than discovering them +at runtime (Lodderstedt et al., 2025; Hardt, 2012). OpenID Connect Core 1.0 +assumes the relying party already has provider configuration; it does not +require a preflight validator to fetch discovery or metadata (Sakimura et al., +2023). LDAP distinguished-name strings must follow RFC 4514 before any bind or +search is attempted (Zeilenga, 2006). + +Keycloak's Admin REST and Server Administration Guide execute the remote apply +after an operator or controller decides to mutate (Keycloak, n.d.). Keyverse +therefore splits deterministic local validation from that remote mutation. +SAML and OIDC preflight perform no metadata or discovery fetch. LDAP preflight +performs no DNS, socket, bind, search, storage write, or Keycloak call. + +This ADR is a control-plane lifecycle choice. Preflight success is not login, +bind, or provisioning success. + +## Decision + +Federation, directory, and relying-party onboarding separate deterministic +local preflight from external apply. Where Keyverse owns desired state, intent +is persisted before remote mutation, duplicate remote matches fail closed, and +a canonical apply receipt is written only after exact live re-observation. +Delete uses remote-first ordering where local-first deletion could create +false success. Preflight success never means external login/bind/provisioning +success. + +## Consequences + +- Operators can reject a payload without creating a live Keycloak object. +- Desired-state rows exist before network I/O so a crash during apply is + recoverable from stored intent. +- Duplicate remote clients, identity providers, or directory components fail + closed instead of being silently merged. +- Receipts record only what live re-observation returned. They are not a + promise that a user can log in. +- Remote-first delete prevents a local row from disappearing while the live + object remains. +- Expanding preflight to fetch metadata, resolve DNS, or bind LDAP would + contradict this decision and needs a separate ADR. + +## References + +Hardt, D. (Ed.). (2012). *The OAuth 2.0 authorization framework* (RFC 6749). +Internet Engineering Task Force. https://doi.org/10.17487/RFC6749 + +Keycloak. (n.d.). *Server Administration Guide*. Retrieved August 24, 2026, from +https://www.keycloak.org/docs/latest/server_admin/ + +Lodderstedt, T., Bradley, J., Labunets, A., & Fett, D. (2025). *Best current +practice for OAuth 2.0 security* (BCP 240, RFC 9700). Internet Engineering +Task Force. https://doi.org/10.17487/RFC9700 + +Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., & Mortimore, C. (2023). +*OpenID Connect Core 1.0 incorporating errata set 2*. OpenID Foundation. +https://openid.net/specs/openid-connect-core-1_0.html + +Zeilenga, K. (Ed.). (2006). *Lightweight Directory Access Protocol (LDAP): +String representation of distinguished names* (RFC 4514). Internet Engineering +Task Force. https://doi.org/10.17487/RFC4514 diff --git a/docs/adr/0005-secret-ownership.md b/docs/adr/0005-secret-ownership.md index 5e79284..d53078b 100644 --- a/docs/adr/0005-secret-ownership.md +++ b/docs/adr/0005-secret-ownership.md @@ -1,6 +1,66 @@ # ADR-0005: Separate portable configuration from deployment-private values **Status:** Accepted -**Date:** 2026-08-09 +**Date:** 2026-08-09 +**Updated:** 2026-08-24 -Portable realm configuration and ordinary desired-state records contain only the fields needed for reproducible identity policy. Deployment-specific confidential values remain owned by the deployment controller and its approved configuration store. Public repository artifacts, ordinary responses, and routine logs do not copy those private values. This keeps the portable realm reusable across tenants and supports controlled rotation and rollback. \ No newline at end of file +## Context + +The portable realm and public desired-state templates must be reusable across +tenants and reviewable in this repository. OAuth 2.0 client credentials and +refresh or access tokens are confidential protocol values (Hardt, 2012). Bearer +tokens can be used by any party that possesses them and must be protected in +storage and transport (Jones & Hardt, 2012). OAuth 2.0 security BCP 240 +requires deployments to keep client secrets and tokens out of unauthorized +channels and to treat leakage as a credential-compromise event (Lodderstedt et +al., 2025). Keycloak's Server Administration Guide stores client secrets, +identity-provider client secrets, and LDAP bind credentials in the engine's +private configuration, not in a portable realm export intended for source +control (Keycloak, n.d.). + +Copying those values into templates, ordinary API responses, logs, command +arguments, or screenshots would make the portable tree tenant-specific and +would disclose credentials. Hardcoded relying-party routing claims such as +`role`, `org`, and `workspace` are visible product data and must not carry +credentials or personal secrets. + +This ADR is a secret-ownership boundary. It does not replace encryption, +purpose-bound operator access, or audit of privileged reads. + +## Decision + +Portable realm configuration and ordinary desired-state records contain only +the fields needed for reproducible identity policy. Deployment-specific +confidential values remain owned by the deployment controller and its approved +configuration store. Public repository artifacts, ordinary responses, and +routine logs do not copy those private values. This keeps the portable realm +reusable across tenants and supports controlled rotation and rollback. + +## Consequences + +- Templates keep `{{placeholders}}`. Resolved secrets stay in the deployment + controller and KV/secret store. +- Confidential relying-party credentials are placed through a separate + secret-management port after secret-free client reconciliation. +- Operator and SCIM responses redact unknown and secret-bearing fields. +- Rotation and rollback can replace a secret without rewriting portable + policy. +- Reviewers can read the public tree without receiving tenant credentials. +- Putting a live secret into the portable realm, a desired-state template, or + a changelog is a boundary violation, not an onboarding shortcut. + +## References + +Hardt, D. (Ed.). (2012). *The OAuth 2.0 authorization framework* (RFC 6749). +Internet Engineering Task Force. https://doi.org/10.17487/RFC6749 + +Jones, M., & Hardt, D. (2012). *The OAuth 2.0 authorization framework: Bearer +token usage* (RFC 6750). Internet Engineering Task Force. +https://doi.org/10.17487/RFC6750 + +Keycloak. (n.d.). *Server Administration Guide*. Retrieved August 24, 2026, from +https://www.keycloak.org/docs/latest/server_admin/ + +Lodderstedt, T., Bradley, J., Labunets, A., & Fett, D. (2025). *Best current +practice for OAuth 2.0 security* (BCP 240, RFC 9700). Internet Engineering +Task Force. https://doi.org/10.17487/RFC9700 diff --git a/docs/adr/0006-user-operation-lock.md b/docs/adr/0006-user-operation-lock.md index 1a912ad..32743c4 100644 --- a/docs/adr/0006-user-operation-lock.md +++ b/docs/adr/0006-user-operation-lock.md @@ -1,23 +1,58 @@ # ADR-0006: Share one user-operation lock across merge and SCIM full replacement **Status:** Accepted -**Date:** 2026-08-09 +**Date:** 2026-08-09 +**Updated:** 2026-08-24 ## Context -Account merge/link operations and a SCIM full user replacement can target the same Keycloak user. The full replacement path reads tombstone state and then writes the user representation, so it must not race a merge that creates the tombstone between those operations. +Account merge/link operations and a SCIM full user replacement can target the +same Keycloak user. The full replacement path reads tombstone state and then +writes the user representation, so it must not race a merge that creates the +tombstone between those operations. -Protected `main` also supports the narrower `PATCH active=false` deprovisioning path. That PATCH path currently performs its read/deactivate/read sequence outside the shared cross-process lock. This ADR therefore must not imply that every SCIM mutation is serialized with merge. +SCIM Protocol RFC 7644 defines HTTP `PUT` as a full resource replacement and +`PATCH` as a partial modification (Hunt, Grizzle, Ansari, et al., 2015). SCIM +Core Schema RFC 7643 defines the user representation being replaced (Hunt, +Grizzle, Wahlstroem, & Mortimore, 2015). Those documents specify resource +semantics; they do not specify a cross-process lock. Keyverse therefore adds a +product concurrency boundary so replacement cannot observe a user, lose a +merge, and rewrite the pre-merge representation. + +Protected `main` also supports the narrower `PATCH active=false` deprovisioning +path. That PATCH path currently performs its read/deactivate/read sequence +outside the shared cross-process lock. This ADR therefore must not imply that +every SCIM mutation is serialized with merge. ## Decision -Keyverse uses one cross-process user-operation lock boundary for account merge/link and SCIM `PUT /Users/{id}` full replacement. Those operations serialize consistently, preserve tombstone/survivor invariants, and can be retried or recovered from observed durable state. +Keyverse uses one cross-process user-operation lock boundary for account +merge/link and SCIM `PUT /Users/{id}` full replacement. Those operations +serialize consistently, preserve tombstone/survivor invariants, and can be +retried or recovered from observed durable state. -The current SCIM `PATCH active=false` path is explicitly outside this Accepted shared-lock guarantee. If PATCH or any future SCIM read-modify-write operation can affect tombstone, survivor, or reactivation invariants, it must join the same lock boundary and add a concurrency regression before documentation may claim equivalent serialization. +The current SCIM `PATCH active=false` path is explicitly outside this Accepted +shared-lock guarantee. If PATCH or any future SCIM read-modify-write operation +can affect tombstone, survivor, or reactivation invariants, it must join the +same lock boundary and add a concurrency regression before documentation may +claim equivalent serialization. ## Consequences - Merge and SCIM full replacement share one documented concurrency authority. -- The protected-main PATCH behavior remains usable but must not be described as transactionally serialized with merge. -- Expanding the lock guarantee requires a source/test change, not a documentation-only promotion. -- Clustered deployments must provide the same shared-lock semantics for every operation included in this boundary. \ No newline at end of file +- The protected-main PATCH behavior remains usable but must not be described as + transactionally serialized with merge. +- Expanding the lock guarantee requires a source/test change, not a + documentation-only promotion. +- Clustered deployments must provide the same shared-lock semantics for every + operation included in this boundary. + +## References + +Hunt, P. (Ed.), Grizzle, K., Ansari, M., Wahlstroem, E., & Mortimore, C. +(2015). *System for Cross-domain Identity Management: Protocol* (RFC 7644). +Internet Engineering Task Force. https://doi.org/10.17487/RFC7644 + +Hunt, P. (Ed.), Grizzle, K., Wahlstroem, E., & Mortimore, C. (2015). *System +for Cross-domain Identity Management: Core schema* (RFC 7643). Internet +Engineering Task Force. https://doi.org/10.17487/RFC7643 diff --git a/docs/adr/0007-automation-authority.md b/docs/adr/0007-automation-authority.md index 8e1b264..1d065f5 100644 --- a/docs/adr/0007-automation-authority.md +++ b/docs/adr/0007-automation-authority.md @@ -1,6 +1,60 @@ # ADR-0007: Separate autonomous development from review, merge, and release authority **Status:** Accepted -**Date:** 2026-08-09 +**Date:** 2026-08-09 +**Updated:** 2026-08-24 -Autonomous development may inspect exact repository state, produce a bounded patch, and submit ordinary reviewable work after independent verification. It cannot create its own qualifying approval, bypass branch protection, merge protected main, tag, or publish a release. Model-provider credentials remain separate from reviewer, publication, and release credentials. PR #74 refines the hourly implementation while preserving this authority boundary. \ No newline at end of file +## Context + +Keyverse allows scheduled or agent-assisted development to inspect exact +repository state and propose a bounded patch. NIST SP 800-218, Secure Software +Development Framework version 1.1, is the current final SSDF publication. It +requires organizations to protect the development environment, review changes, +and keep release authority separate from untrusted production of code +(Souppaya et al., 2022). NIST later published SP 800-218 Revision 1 as an +Initial Public Draft; this ADR does not treat that draft as a final standard. +SLSA version 1.2 is an approved specification for describing supply-chain +provenance and incremental integrity, not a license to skip review (Supply-chain +Levels for Software Artifacts, 2025). + +Generated model output is untrusted. It may be digest-sealed and independently +verified, then published only through an ordinary draft pull request. Model- +provider credentials must stay separate from reviewer, publication, and release +credentials so a development loop cannot approve or merge its own work. + +This ADR is an authority boundary. It does not claim NIST SSDF or SLSA +conformance. PR #74 refined the hourly implementation while preserving this +boundary. + +## Decision + +Autonomous development may inspect exact repository state, produce a bounded +patch, and submit ordinary reviewable work after independent verification. It +cannot create its own qualifying approval, bypass branch protection, merge +protected main, tag, or publish a release. Model-provider credentials remain +separate from reviewer, publication, and release credentials. PR #74 refines +the hourly implementation while preserving this authority boundary. + +## Consequences + +- Automation may open at most a normal draft pull request after independent + verification. Draft is not Ready for review, not an approval, and not a + merge instruction. +- Existing review agents keep their own credential system. Development + automation must not repurpose, rename, or broaden those credentials. +- Branch protection, required checks, unresolved-thread gates, and human + release criteria remain authoritative. +- A merged pull request is still not a release. Release requires exact-main + regression, immutable image digest, SBOM/provenance, rollback evidence, and + the documented release criteria. +- Agents do not self-approve, force merge, tag, or publish. + +## References + +Souppaya, M., Scarfone, K., & Dodson, D. (2022). *Secure software development +framework (SSDF) version 1.1: Recommendations for mitigating the risk of +software vulnerabilities* (NIST SP 800-218). National Institute of Standards +and Technology. https://doi.org/10.6028/NIST.SP.800-218 + +Supply-chain Levels for Software Artifacts. (2025). *SLSA specification, +version 1.2*. https://slsa.dev/spec/v1.2/ diff --git a/docs/adr/0008-keyverse-rp-authorization-boundary.md b/docs/adr/0008-keyverse-rp-authorization-boundary.md index 51a65b7..0e33177 100644 --- a/docs/adr/0008-keyverse-rp-authorization-boundary.md +++ b/docs/adr/0008-keyverse-rp-authorization-boundary.md @@ -1,10 +1,30 @@ # ADR-0008: Make Keyverse RP authorization explicit across non-fork applications **Status:** Accepted -**Date:** 2026-08-11 +**Date:** 2026-08-11 +**Updated:** 2026-08-24 ## Context +OpenID Connect Core 1.0 defines a relying party as an OAuth 2.0 client that +verifies the end user from tokens issued by an OpenID provider (Sakimura et +al., 2023). JSON Web Token RFC 7519 requires recipients to validate the +signed claims they consume (Jones, Bradley, & Sakimura, 2015). JWT BCP 225 +updates that guidance and requires audience checks when a JWT is intended for +a specific recipient (Sheffer et al., 2020). The JWT profile for OAuth 2.0 +access tokens requires a resource server to reject a token whose `aud` does +not identify that resource (Bertocci, 2021). Bearer tokens can be used by any +party that possesses them (Jones & Hardt, 2012). NIST SP 800-63C-4 treats +federation assertions as evidence for a separately administered relying party, +not as an authorization decision inside that party's resources (Temoshok, +Richer, et al., 2025). + +Those records specify authentication and token-acceptance rules. They do not +grant authorization from a README listing, a shared GitHub organization, or a +hardcoded routing claim. Identity attributes used for tenant binding are +handled through purpose-bound access, encryption, and audit. This ADR does not +claim NIST, IETF, or OpenID conformance. + Keyverse is the ContextualWisdomLab identity hub, but an application does not inherit that trust merely because it is listed in the Keyverse README or lives in the same GitHub organization. The ecosystem RPs are separate, non-fork @@ -169,3 +189,28 @@ link its exact issuer/audience/JWKS configuration, claim mapping, ABAC/RBAC tests, cross-tenant denial tests, and production-mode configuration. Until that evidence exists, the app's status is `planned`, `gap-not-claimed`, or `deployment-restricted`, never `authorization-ready`. + +## References + +Bertocci, V. (2021). *JSON Web Token (JWT) profile for OAuth 2.0 access tokens* +(RFC 9068). Internet Engineering Task Force. https://doi.org/10.17487/RFC9068 + +Jones, M., Bradley, J., & Sakimura, N. (2015). *JSON Web Token (JWT)* +(RFC 7519). Internet Engineering Task Force. https://doi.org/10.17487/RFC7519 + +Jones, M., & Hardt, D. (2012). *The OAuth 2.0 authorization framework: Bearer +token usage* (RFC 6750). Internet Engineering Task Force. +https://doi.org/10.17487/RFC6750 + +Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., & Mortimore, C. (2023). +*OpenID Connect Core 1.0 incorporating errata set 2*. OpenID Foundation. +https://openid.net/specs/openid-connect-core-1_0.html + +Sheffer, Y., Hardt, D., & Jones, M. (2020). *JSON Web Token best current +practices* (BCP 225, RFC 8725). Internet Engineering Task Force. +https://doi.org/10.17487/RFC8725 + +Temoshok, D., Richer, J., Choong, Y.-Y., Fenton, J., Lefkovitz, N., +Regenscheid, A., & Galluzzo, R. (2025). *Digital identity guidelines: +Federation and assertions* (NIST SP 800-63C-4). National Institute of Standards +and Technology. https://doi.org/10.6028/NIST.SP.800-63C-4 diff --git a/docs/adr/README.md b/docs/adr/README.md index e53fc6d..aea77c7 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -18,3 +18,11 @@ Create or update an ADR for changes to authenticator policy, federation hub ownership, identity matching evidence, merge/tombstone semantics, SCIM authority, directory write/trust policy, RP credential/claim ownership, desired-state mutation order, persistent state, secret handling, or autonomous/release authority. Each implementation PR should reconcile PRD/TRD/Architecture/UML/ERD/Threat/Test/Operability/Traceability and the relevant `docs/doctoring/`, `docs/papers/`, or `docs/operations/` research/standards/runbook record when those contracts move. + +Each accepted ADR now includes Context, Decision, Consequences, and an APA 7th +References list. Citations use a DOI or official catalog URL opened from the +IETF RFC Editor, OpenID Foundation, OASIS, NIST CSRC/nvlpubs, W3C, Keycloak +documentation, or SLSA specification on 2026-08-24. The 2017 NIST SP 800-63B +and SP 800-63C volumes named in `docs/papers/` are superseded by the July 2025 +SP 800-63B-4 and SP 800-63C-4 finals cited in these ADRs. Citations are +standards evidence, not conformance claims.