Skip to content

docs(adr): record contextual-orchestrator identity and tenant boundary #86

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
seonghobae merged 1 commit into from
Aug 12, 2026
+3 −2
Merged

docs(adr): record contextual-orchestrator identity and tenant boundary #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/TRACEABILITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
| naruon Keyverse OIDC acceptance boundary | ADR-0008; exact issuer/audience/JWKS validation and required OIDC NumericDate claims | naruon PR #1321 `6a5cf11` names the Keyverse issuer and `naruon-web` audience, requires verified `iat`, tests explicit org/workspace/role acceptance plus missing-`iat` denial, and strips orphaned HTML comment terminators; protected-branch checks/review remain required | active-PR |
| semantic-data-portal Keyverse claim boundary | ADR-0008; bounded claim mapping and fail-closed tenant/role/JWT-header validation | semantic-data-portal PR #58 `0b40e77` aliases `org`/`role`, validates every present tenant alias, rejects malformed/conflicting aliases before `ActorContext`, explicitly rejects unsupported JWT `crit` headers, and keeps the cryptography floor; protected-branch approval remains required | active-PR |
| pg-erd-cloud Keyverse organization boundary | ADR-0008; verified tenant binding before project authorization | pg-erd-cloud PR #855 `e4b4771` exact `org`/audience/`iat` checks, single-tenant profile, API-key bypass denial; shared multi-tenant persistence remains unimplemented | active-PR |
| contextual-orchestrator Keyverse identity and tenant boundary | ADR-0008; deployment-owned OIDC validation plus downstream scope RBAC and org/workspace ABAC | PR #109 `2a4270a` adds the injected verifier seam; stacked PR #110 `38dc50a` requires `VerifiedIdentity`, rejects boolean-only authorization, binds workflow/evaluation/batch resources to secret-free tenant context, and denies cross-tenant or ownerless reads; main remains unchanged until both protected PRs merge | active-PR |

@coderabbitai coderabbitai Bot Aug 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win

이 행에 재현 가능한 acceptance evidence를 추가하십시오.

PR #109, PR #110 및 짧은 commit ID만으로는 어떤 검증이 통과했는지 확인할 수 없습니다. ADR-0008 Lines 164-169는 각 RP에 대해 정확한 issuer/audience/JWKS 설정, claim mapping, ABAC/RBAC 테스트, 교차 테넌트 거부 테스트, production-mode 설정을 요구합니다. docs/THREAT_MODEL.md Lines 80-85도 invalid issuer/signature/expiry/audience, tenant mismatch, role elevation, ownership, purpose, cross-tenant denial 검증을 요구합니다.

PR objective에서 말한 validation passed를 근거로 사용하려면 실제 테스트 경로와 protected-check 또는 deployment acceptance 결과를 이 행에 기록하십시오. 해당 증거가 없으면 검증 대기 상태로 명시하십시오.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/TRACEABILITY.md` at line 27, Update the contextual-orchestrator
traceability row to include reproducible acceptance evidence: list the actual
test paths and protected-check or deployment-acceptance results covering OIDC
issuer/audience/JWKS, claim mapping, RBAC/ABAC, tenant and ownership boundaries,
purpose, role elevation, and invalid-token cases. If this evidence is
unavailable, change the row’s status to explicitly indicate validation is
pending rather than relying only on PR and commit references.

| sidecar anonymous-access boundary | ADR-0008; private service-boundary and least-privilege policy | newsdom-api protected `develop` `3d0426b` (PR #595) fail-closed token gate, startup credential registry, explicit anonymous opt-in, review-fixed authenticated examples/healthcheck/401 contract, and pypdf Trivy remediation; Keyverse-aware gateway evidence remains required for exposure | implemented-main |
| 100% production statement/branch/docstring | CWL quality contract | CI/pytest/interrogate | implemented-main |

Expand Down
4 changes: 2 additions & 2 deletions docs/adr/0008-keyverse-rp-authorization-boundary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ The snapshot is reproducible from the Keyverse README at immutable revision
- `pg-erd-cloud`: PR #855 at `e4b4771fa0c46cbbcbd9ca7e777e20b5179b0bcd` (open; based on `main` at `72afe6db712b145baaba084f64a1ff4fb36d9fd0`);
- `semantic-data-portal`: PR #58 at `0b40e7718e7f5c8bbd169596fed2fa371e2881f9` (open; based on `main` at `e48aa13c4af7a4875d4b53e6a60b50405c265a2f`);
- `clearfolio`: `main` at `55d7ae8647208e301f282350f076eeddaba61d11`;
- `contextual-orchestrator`: `main` at `6841b71935e0b7cb98fb52bcb4709cc5100c8d87`;
- `contextual-orchestrator`: `main` at `6841b71935e0b7cb98fb52bcb4709cc5100c8d87`; PR #109 at `2a4270a31ca9ab61c001c8b368a5252851ae093f` adds the deployment-injected Keyverse verifier seam, and stacked PR #110 at `38dc50a64dba224929d5ca58b81a525c59519f12` adds identity-carrying RBAC/ABAC;
- `newsdom-api`: protected `develop` at `3d0426bf45ad9d3395effb602811a75cbe700cf4` (PR #595 squash-merged; based on `develop` at `2f29e69c99a1201ce6b4e43370a463701efdc81c`).

| Application | Keyverse recognition | Current authorization | Finding and required direction |
Expand All @@ -35,7 +35,7 @@ The snapshot is reproducible from the Keyverse README at immutable revision
| `pg-erd-cloud` | Generic OIDC/JWKS verification is present; PR #855 adds an opt-in `OIDC_ORGANIZATION` profile that requires an exact typed Keyverse `org`, audience, and `iat` after token verification | Project-member RBAC (`viewer`/`editor`/`owner`) exists in `backend/app/permissions.py`; the profile adds deployment-level single-tenant `org` ABAC and rejects `pgerd_` API-key bypasses | Use the profile for one-tenant-per-database deployments. A shared multi-tenant database still needs a persisted tenant key, tenant-qualified membership/resource queries, composite constraints, and cross-tenant denial tests before authorization-ready status. |
| `semantic-data-portal` | OIDC verification exists; PR #58 maps bounded Keyverse `org`/`role` aliases, validates every present tenant alias, rejects conflicting aliases and malformed tenant/role claim shapes before authorization context creation, and explicitly rejects unsupported JWT `crit` headers | RBAC and ABAC/purpose/sensitivity/evidence policy exists in `src/sdp/policy.py` | Merge PR #58 after independent review and protected checks; preserve tenant, purpose, row-filter, masking, and evidence checks. Keep the repo-wide security gate green: `cryptography` must be pinned at `50.0.0` or newer in the source and every hash-locked requirements artifact after CVE-2026-69247. |
| `clearfolio` | No production OIDC/JWT verifier; current runtime is a gateway/header tenant scaffold documented in `docs/security/2026-07-02-auth-tenant-model.md` | Permission checks and tenant ownership are implemented, with optional gateway HMAC; the caller identity is not yet a Keyverse-verified token | Keep production fail-closed. Replace public header trust with Keyverse issuer/audience/JWKS verification at the service or a cryptographically trusted gateway, then map `org`/`sub`/roles/scopes and retain same-tenant checks. |
| `contextual-orchestrator` | Bearer-token configuration distinguishes `admin` and `inference` scopes but has no OIDC/JWT Keyverse validation | Coarse token-scope RBAC exists; resource/tenant ABAC is not established | Add a user-facing Keyverse OIDC resource-server boundary or a separately authenticated service-token/mTLS boundary for internal calls. Keep admin and inference scopes separate and add tenant/resource ownership conditions before exposing multi-tenant work. |
| `contextual-orchestrator` | PR #109 recognizes the Keyverse RP boundary through a deployment-injected verifier; stacked PR #110 requires a verified identity with subject/org/workspace/scopes and rejects boolean-only decisions | Scope RBAC is enforced by the requested scope; PR #110 adds exact org/workspace metadata ABAC plus tenant ownership checks for workflow, evaluation, and batch resources. Main is still unchanged and the deployment adapter must still prove issuer/audience/signature/expiry/JWKS/rotation. | Merge #109 then #110 through normal protected review. Keep the external adapter fail-closed, do not add JWT parsing to the stdlib core, migrate or recreate ownerless legacy resources, and add deployment acceptance evidence before exposing multi-tenant work. |

@coderabbitai coderabbitai Bot Aug 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

set -eu
printf '%s\n' '--- candidate files ---'
git ls-files | grep -E '(^|/)(ARCHITECTURE\.md|0008-keyverse-rp-authorization-boundary\.md)$' || true
printf '%s\n' '--- ADR structure ---'
ast-grep outline docs/adr/0008-keyverse-rp-authorization-boundary.md --match 'authorization' --view expanded || true
printf '%s\n' '--- relevant ADR context ---'
sed -n '20,75p' docs/adr/0008-keyverse-rp-authorization-boundary.md
printf '%s\n' '--- architecture context ---'
rg -n -C 5 'algorithm|subject|sub|VerifiedIdentity|granted scopes|scope|authorization' ARCHITECTURE.md docs/adr/0008-keyverse-rp-authorization-boundary.md

Repository: ContextualWisdomLab/keyverse

Length of output: 30554

🏁 Script executed:

set -eu
printf '%s\n' '--- all scope-related contract text ---'
rg -n -C 4 'requested scope|granted scopes|scope RBAC|scopes|algorithm|non-empty.*subject|subject.*non-empty' \
  --glob '*.md' --glob '*.yaml' --glob '*.yml' --glob '*.json' --glob '*.py' --glob '*.ts' --glob '*.tsx' .
printf '%s\n' '--- complete decision and gates ---'
sed -n '53,146p' docs/adr/0008-keyverse-rp-authorization-boundary.md
printf '%s\n' '--- repository content and git metadata ---'
git status --short
git ls-files | wc -l
git show --stat --oneline HEAD

Repository: ContextualWisdomLab/keyverse

Length of output: 49744

권한 입력과 토큰 검증 조건을 명확히 기술하십시오.

Scope RBAC is enforced by the requested scope 문구는 호출자 입력을 권한 근거로 사용할 수 있다는 의미가 될 수 있습니다. 필수 operation scope를 검증된 VerifiedIdentity의 granted scopes와 비교한다고 명시하십시오.

외부 어댑터 검증 목록에도 허용 algorithm, 비어 있지 않은 sub, iat 검증을 추가하십시오. 이는 ADR의 공통 토큰 계약과 일치해야 합니다.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/adr/0008-keyverse-rp-authorization-boundary.md` at line 38, Update the
ADR entry for contextual-orchestrator to state that the required operation scope
is checked against the verified VerifiedIdentity.granted scopes, not treated as
authorization based on caller-provided input. Extend the external adapter
verification requirements to include an allowed algorithm, a non-empty sub
claim, and iat validation, matching the shared token contract.

| `newsdom-api` | No Keyverse OIDC integration; protected `develop` now contains PR #595, which makes the local bearer boundary fail closed by default and permits anonymous parsing only through explicit `NEWSDOM_ALLOW_ANONYMOUS=true` | No application RBAC/ABAC; it is a PDF-to-DOM sidecar | Keep it private infrastructure while it has no user authorization model. If reachable beyond a trusted internal gateway, require a Keyverse-aware gateway or verified service boundary; never enable the anonymous opt-in on an exposed deployment. The merged change also remediates the current `pypdf` Trivy findings and includes the review fixes at `3025be1` (startup credential registry, authenticated examples, healthcheck executable-bit check, and complete 401 assertions). |

Keyverse itself also has two boundaries that must not be confused with
Expand Down
Loading