fix: keep People API FastAPI dependencies server-owned

.github/workflows/keyverse-auth-package.yml

@@ -0,0 +1,101 @@
+name: Keyverse Authorization Package
+
+on:
+  pull_request:
+    paths:
+      - "integrations/keyverse-auth/**"
+      - "services/people-api/**"
+      - "packages/orgmetra-postgres/**"
+      - "requirements/keyverse-auth-ci.txt"
+      - "requirements/keyverse-auth-package-ci.txt"
+      - ".github/workflows/keyverse-auth-package.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: keyverse-auth-package-${{ github.event.pull_request.number || github.ref }}-${{ github.sha }}
+  cancel-in-progress: false
+
+jobs:
+  package:
+    name: Python ${{ matrix.python_version }} package
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python_version:
+          - "3.12"
+          - "3.14"
+    env:
+      PIP_DISABLE_PIP_VERSION_CHECK: "1"
+      PIP_NO_INPUT: "1"
+    steps:
+      - name: Check out exact pull request head
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: ${{ matrix.python_version }}
+          cache: pip
+          cache-dependency-path: |
+            requirements/keyverse-auth-ci.txt
+            requirements/keyverse-auth-package-ci.txt
+      - name: Install exact package verification dependencies
+        run: >-
+          python -m pip install
+          --only-binary=:all:
+          --no-deps
+          -r requirements/keyverse-auth-ci.txt
+          -r requirements/keyverse-auth-package-ci.txt
+      - name: Build declared local dependency wheels
+        run: |
+          python -m build --wheel --no-isolation packages/orgmetra-postgres
+          python -m build --wheel --no-isolation services/people-api
+      - name: Build wheel and source distribution without network isolation
+        run: python -m build --no-isolation integrations/keyverse-auth
+      - name: Inspect package contents
+        run: |
+          python - <<'PY'
+          from pathlib import Path
+          from zipfile import ZipFile
+
+          wheels = list(Path("integrations/keyverse-auth/dist").glob("*.whl"))
+          if len(wheels) != 1:
+              raise SystemExit(f"expected one wheel, found {len(wheels)}")
+          with ZipFile(wheels[0]) as archive:
+              names = set(archive.namelist())
+              required = {
+                  "orgmetra_keyverse_auth/__init__.py",
+                  "orgmetra_keyverse_auth/authorizer.py",
+                  "orgmetra_keyverse_auth/contracts.py",
+                  "orgmetra_keyverse_auth/py.typed",
+              }
+              missing = required - names
+              if missing:
+                  raise SystemExit(f"wheel is missing required files: {sorted(missing)}")
+          sdists = list(Path("integrations/keyverse-auth/dist").glob("*.tar.gz"))
+          if len(sdists) != 1:
+              raise SystemExit(f"expected one source distribution, found {len(sdists)}")
+          PY
+      - name: Install local dependency chain and smoke test outside the source tree
+        run: |
+          python -m pip install --no-deps --force-reinstall \
+            packages/orgmetra-postgres/dist/*.whl \
+            services/people-api/dist/*.whl \
+            integrations/keyverse-auth/dist/*.whl
+          cd "$(mktemp -d)"
+          env -u PYTHONPATH python - <<'PY'
+          from orgmetra_keyverse_auth import KeyverseOidcAuthorizer, KeyverseOidcConfig
+
+          assert KeyverseOidcAuthorizer
+          assert KeyverseOidcConfig
+          print("installed wheel smoke: ok")
+          PY
+      - name: Verify dependency consistency
+        run: python -m pip check

.github/workflows/keyverse-auth-quality.yml

@@ -0,0 +1,92 @@
+name: Keyverse Authorization Quality
+
+on:
+  pull_request:
+    paths:
+      - "integrations/keyverse-auth/**"
+      - "services/people-api/**"
+      - "packages/orgmetra-postgres/**"
+      - "requirements/keyverse-auth-ci.txt"
+      - ".github/workflows/keyverse-auth-quality.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: keyverse-auth-quality-${{ github.event.pull_request.number || github.ref }}-${{ github.sha }}
+  cancel-in-progress: false
+
+jobs:
+  keyverse-auth-quality:
+    name: Python ${{ matrix.python_version }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python_version:
+          - "3.12"
+          - "3.14"
+    env:
+      PYTHONPATH: integrations/keyverse-auth/src:services/people-api/src:packages/orgmetra-postgres/src
+      PIP_DISABLE_PIP_VERSION_CHECK: "1"
+      PIP_NO_INPUT: "1"
+    steps:
+      - name: Check out exact pull request head
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: ${{ matrix.python_version }}
+          cache: pip
+          cache-dependency-path: requirements/keyverse-auth-ci.txt
+      - name: Install exact pinned dependencies
+        run: >-
+          python -m pip install
+          --only-binary=:all:
+          --no-deps
+          -r requirements/keyverse-auth-ci.txt
+      - name: Record exact security dependency versions
+        run: |
+          python - <<'PY'
+          from importlib.metadata import version
+
+          for package_name in ("PyJWT", "cryptography"):
+              print(f"{package_name}={version(package_name)}")
+          PY
+      - name: Compile shipped packages
+        run: |
+          python -m compileall -q integrations/keyverse-auth/src
+          python -m compileall -q services/people-api/src
+          python -m compileall -q packages/orgmetra-postgres/src
+      - name: Run authorization tests with exact coverage
+        run: >-
+          python -m coverage run
+          --branch
+          --source=orgmetra_keyverse_auth
+          -m pytest
+          integrations/keyverse-auth/tests
+      - name: Enforce production statement and branch coverage
+        run: |
+          python -m coverage report --show-missing --fail-under=100
+          python -m coverage json -o keyverse-auth-coverage.json
+          python - <<'PY'
+          import json
+
+          with open("keyverse-auth-coverage.json", encoding="utf-8") as report_file:
+              totals = json.load(report_file)["totals"]
+          if totals["percent_covered"] != 100.0:
+              raise SystemExit("production statement coverage is not 100%")
+          if totals["num_branches"] and totals["covered_branches"] != totals["num_branches"]:
+              raise SystemExit("production branch coverage is not 100%")
+          PY
+      - name: Enforce public docstring coverage
+        run: python integrations/keyverse-auth/tests/validate_docstrings.py
+      - name: Verify import and dependency consistency
+        run: |
+          python -c "import orgmetra_keyverse_auth; print(orgmetra_keyverse_auth.__all__)"
+          python -m pip check

ARCHITECTURE.md

@@ -62,3 +62,7 @@ Access is tenant, actor, purpose, resource, and lifetime scoped. High-impact dec
 ## Active implementation slice: bitemporal domain kernel
 
 `packages/orgmetra-domain` implements framework-independent invariants for effective/system time, distinct HRIS records, multiple assignments, and candidate-worker continuity. It has no persistence or transport dependency and can be embedded by future services. This section describes active-PR work until merged into the protected default branch.
+
+## Active implementation slice: purpose-bound People API
+
+`services/people-api` is an independently importable FastAPI factory. Hosts inject `TokenAuthorizer` and `PeopleRepository`. Protected routes select both an OAuth operation scope and a finer HR purpose in server code. `PurposeContext` and the repository port are runtime `Depends` values, not caller query fields. This section describes active-PR work until merged into the protected default branch.

CHANGELOG.md

@@ -20,12 +20,20 @@ All notable changes to Orgmetra will be documented in this file.
 
 - Organization and job mutable descriptions now live in version records rather than durable identity anchors, preserving normalized history and stable position references.
 - Effective and system-recorded intervals are non-empty half-open periods; equal start/end bounds are rejected.
+- People API route handlers now inject `PurposeContext` and the repository through runtime `Depends` defaults so callers cannot supply those objects as query fields.
+
+### Fixed
+
+- People API Quality no longer fails with HTTP 422 on every protected route when FastAPI 0.116 interprets postponed annotations as query parameters.
+- Bearer token parsing now splits only on the first ASCII space so C0 separators such as `\\x1f` remain visible and are rejected.
+- People API CI now pins the same Python 3.14-compatible Pydantic lock as Keyverse authorization and includes `certifi` so `pip check` can close the httpx dependency set.
 
 ### Security
 
 - Purpose-bound PII access contract.
 - LLM output constrained to draft evidence.
 - No direct cross-service database access.
+- Reject malformed, duplicate, or non-verification JWK `key_ops` declarations before constructing a signing key.
 
 ### Notes
 

changes/0007-keyverse-oidc-authorizer.md

@@ -0,0 +1,27 @@
+# Unreleased: strict Keyverse JWT authorizer
+
+## Added
+
+- independently importable offline Keyverse JWT access-token authorizer
+- strict HTTPS issuer, audience, access-token type and asymmetric algorithm profile
+- injected JWK Set and identity-reference resolver ports
+- exact signing-key selection and registered/private claim validation
+- RFC 9068/RFC 8693 space-delimited operation-scope validation independent from HR business-purpose validation
+- bounded positive token lifetime, duplicate-free scope grants and duplicate-free purpose grants
+- retryable identity-provider failure classification
+- Python 3.12/3.14 exact coverage and public docstring gate
+
+## Security
+
+- no verifier-owned discovery, DNS, HTTP, cache, persistence, environment or logging authority
+- no HMAC, unsigned token, embedded caller key, ambiguous duplicate-key or incompatible JWK `key_ops` path
+- a valid business purpose cannot enlarge a token that lacks the route's OAuth operation scope
+- external subject and tenant identifiers are mapped to opaque Orgmetra references
+- token, claims, JWK material and identity strings are not copied into audit records
+- CI uses minimal permissions, immutable action revisions and no model credentials
+
+## Known limits
+
+Discovery/JWKS acquisition, SSRF-safe egress, signed key cache and rotation,
+revocation/account-disable propagation, identity-link lifecycle, live Keyverse
+conformance, SBOM/provenance and external security review remain release gates.

docs/UML_KEYVERSE_AUTH.md

@@ -0,0 +1,68 @@
+# Keyverse authorization UML views
+
+## Component boundary
+
+```mermaid
+flowchart LR
+    token["Untrusted bearer token"] -->|"Compact JWT"| verifier["KeyverseOidcAuthorizer"]
+    route["Server-selected route policy"] -->|"Operation scope + HR purpose"| verifier
+    verifier -->|"Exact issuer"| keys["Injected JwksProvider"]
+    verifier -->|"Issuer + subject + tenant"| mapping["Injected IdentityReferenceResolver"]
+    keys -.->|"Future SSRF-safe adapter"| keyverse["Keyverse JWKS"]
+    mapping -.->|"Future identity-link adapter"| identity["Orgmetra identity links"]
+    verifier -->|"Opaque references + scopes + purposes"| principal["AuthorizedPrincipal"]
+    principal -->|"Defensive scope + purpose checks"| api["Orgmetra People API"]
+```
+
+## Successful verification sequence
+
+```mermaid
+sequenceDiagram
+    participant API as People API
+    participant Auth as KeyverseOidcAuthorizer
+    participant Keys as JwksProvider
+    participant Resolver as IdentityReferenceResolver
+
+    API->>Auth: authorize(bearer token, route scope, route purpose)
+    Auth->>Auth: Validate route scope and purpose vocabulary
+    Auth->>Auth: Validate compact JWT, alg, typ and kid
+    Auth->>Keys: get_jwks(exact issuer)
+    Keys-->>Auth: Bounded JWK Set
+    Auth->>Auth: Select exactly one compatible verification key
+    Auth->>Auth: Verify signature, issuer, audience and time
+    Auth->>Auth: Validate tenant, subject, jti, standard scope and purposes
+    Auth->>Auth: Require route scope AND route purpose independently
+    Auth->>Resolver: resolve(issuer, subject, tenant external id)
+    Resolver-->>Auth: Opaque tenant and actor references
+    Auth-->>API: AuthorizedPrincipal(scopes, purposes)
+```
+
+## Failure classification sequence
+
+```mermaid
+sequenceDiagram
+    participant API as People API
+    participant Auth as KeyverseOidcAuthorizer
+    participant Keys as JwksProvider
+    participant Resolver as IdentityReferenceResolver
+
+    API->>Auth: authorize(token, scope, purpose)
+    alt Malformed token or bad signature/claims
+        Auth-->>API: AuthenticationFailed
+    else Operation scope absent
+        Auth-->>API: AuthorizationDenied
+    else Business purpose absent
+        Auth-->>API: AuthorizationDenied
+    else Keys unavailable or ambiguous
+        Auth->>Keys: get_jwks(issuer)
+        Keys-->>Auth: Outage or invalid key set
+        Auth-->>API: IdentityProviderUnavailable
+    else Identity mapping unavailable
+        Auth->>Resolver: resolve external identities
+        Resolver-->>Auth: Outage or invalid result
+        Auth-->>API: IdentityProviderUnavailable
+    end
+```
+
+These views describe active-PR architecture only. They become protected-main
+truth after dependency merges and fresh integrated review and checks.

docs/adr/0006-purpose-bound-people-api.md

@@ -38,7 +38,12 @@ these contracts:
    problem documents with a random `err_...` support reference and actionable
    `next_action`;
 10. internal trace references never appear in response headers or problem bodies;
-11. Swagger and ReDoc UI remain disabled in the pre-GA service.
+11. Swagger and ReDoc UI remain disabled in the pre-GA service;
+12. People API route modules keep runtime annotations and `Depends` defaults so
+    FastAPI cannot treat `PurposeContext`, `Request`, or the repository port as
+    caller query fields. `from __future__ import annotations` is forbidden in
+    `app.py` because postponed annotations made those server-owned objects look
+    like request input under FastAPI 0.116.
 
 ## Alternatives considered