Enterprise Permission Upgrade Planning¶
This document is the step 49 design record for the 15.3 enterprise compliance preparation scope. It is a planning contract only: it does not introduce Keycloak, OPA, PostgreSQL RLS, Kubernetes, Helm, or any human console as current runtime capabilities.
The current application boundary remains authoritative. CoreServiceBoundary
continues to call application-layer authorization, tenant isolation, license,
schema/provenance, and audit controls before returning machine-readable facts or
governance metadata. Investment intent does not block otherwise permitted facts.
RBAC To ABAC Mapping¶
Existing RBAC grants map to ABAC attributes without changing the current PermissionRequest contract.
| Current RBAC rule | ABAC attribute | Source of truth | Required decision behavior | Test matrix id |
|---|---|---|---|---|
assigned_roles |
subject.roles |
InstitutionPermissionPolicy.assigned_roles |
A caller must hold at least one assigned role with an eligible grant. | abac-role-map |
required_scopes |
subject.scopes |
Machine credential claims or local machine identity policy | Missing scopes deny before any data is returned. | abac-scope-map |
tools whitelist |
action.tool and action.interface |
RoleGrant.tools and AccessInterface |
CLI, REST, MCP, and task-worker calls must match an allowed tool binding. | abac-tool-map |
data_modules |
resource.data_module |
Core request metadata | A grant for one module cannot authorize another module. | abac-module-map |
field_categories |
resource.field_categories |
Field catalog and core request metadata | Every requested field category must be covered. | abac-field-map |
purposes |
environment.request_purpose |
Caller-supplied purpose used for permission and license checks | Unapproved or unlicensed purposes deny with machine-readable details. | abac-purpose-map |
output_levels |
output.level |
Output policy request metadata | Richer output cannot be obtained through a different access layer. | abac-output-map |
institution_id |
tenant.id |
Machine identity and request context | Cross-tenant access denies even when a tool is otherwise whitelisted. | abac-tenant-map |
caller_id |
subject.id |
Machine identity | A credential cannot act as another caller without a matching policy. | abac-subject-map |
Enterprise SSO may provide identity claims, group hints, and credential lifecycle data. It does not own authorization, data-license, schema/provenance, or audit decisions. Those decisions remain inside the application core.
Enterprise Boundary Matrix¶
| Capability | Enterprise component | Current application authority | Boundary rule | Test matrix id |
|---|---|---|---|---|
| Identity federation | Keycloak | Machine identity context consumed by core | Keycloak authenticates identity only; it cannot change DataPackage, SourceEvidence, license, output policy, or audit contracts. |
keycloak-identity-only |
| Policy enhancement | OPA | PermissionService, OutputPolicyService, LicenseService, and AuditLogService |
OPA can provide supplemental access-policy signals, but cannot replace audit, license, or provenance controls. | opa-enhancement-only |
| Tenant isolation | PostgreSQL RLS | TenantIsolationService and CoreServiceBoundary |
RLS strengthens database isolation; application-layer tenant isolation and explicit permission checks still run first. | rls-defense-in-depth |
| Deployment packaging | Kubernetes and Helm | Existing Python services and core rules | Deployment descriptors cannot change business rules, tool semantics, data contracts, or governance order. | deploy-no-business-rule-change |
| User-facing surfaces | None | Machine CLI, REST, and MCP interfaces | The enterprise plan adds no web page, control console, dashboard, chat surface, account self-service page, or manual form. | no-human-console |
Isolation Matrix¶
| Scenario | Current boundary | Future database-layer enhancement | Required outcome | Test matrix id |
|---|---|---|---|---|
| Request targets another institution id | TenantIsolationService rejects target institution fields. |
RLS policy filters rows by tenant key. | Deny with machine-readable reason and audit id. | isolation-target-institution |
| Tenant-filtered field selection requests restricted data | Shared core service authorizes before repository access. | RLS applies after core has already authorized the request. | Deny or redact according to core, license, and output policy. | isolation-field-selection |
| Object URI points outside tenant prefix | TenantIsolationService rejects object path fields. |
Storage and database metadata remain tenant-scoped. | Deny before object access. | isolation-object-uri |
| Task status references another institution | Core task permission checks compare institution and caller. | RLS prevents cross-tenant task row reads. | Deny with audit record. | isolation-task-status |
OPA Failure Matrix¶
| Failure mode | Conservative behavior | Required audit and response | Test matrix id |
|---|---|---|---|
opa_unavailable during high-risk request |
Fail closed. | Return policy denial with audit id and safe alternative tools. | opa-unavailable-high-risk |
opa_timeout before output policy decision |
Fail closed for restricted output levels. | Return output-policy denial and preserve request metadata in audit-safe summary. | opa-timeout-output-policy |
opa_partial_response missing required attributes |
Treat as deny. | Record missing policy attributes and do not return facts. | opa-partial-response |
opa_unavailable for factual lookup |
Use current application policy only when existing core checks are sufficient. | Record OPA degraded mode and keep license, provenance, and audit checks active. | opa-low-risk-core-fallback |
OPA failure handling must never make the system more permissive than the current core boundary.
Data Package Contract Check¶
Keycloak, OPA, RLS, Kubernetes, and Helm are not allowed to add, remove, rename, or reinterpret public data package fields. Enterprise identity and policy metadata may appear only as additional audit-safe policy hits, denial reasons, or internal deployment metadata.
The unchanged external contracts are:
| Contract | Stability rule | Test matrix id |
|---|---|---|
DataPackage |
Required fields, license block, quality block, source evidence, audit id, and output policy version remain unchanged. | contract-data-package-unchanged |
SourceEvidence |
Source id, source type, original fragment, location, confidence, and trust metadata remain unchanged. | contract-source-evidence-unchanged |
| Error envelopes | Permission, tenant isolation, license, schema, and output-origin denials remain machine-readable and include audit ids. | contract-denial-envelope-unchanged |
| Access layers | CLI, REST, and MCP keep calling the same core capability; no access layer owns a separate authorization rule. | contract-access-layer-unchanged |
Enterprise Governance Preparation¶
| Preparation item | Design constraint | Data contract impact | Audit matrix | Access consistency matrix |
|---|---|---|---|---|
| Workflow Audit Trace | Workflow steps must chain existing audit ids instead of creating a separate audit system. | May reference audit ids; cannot alter data package facts or evidence. | workflow.started, workflow.step.allowed, workflow.step.denied, workflow.completed, workflow.failed. |
CLI, REST, MCP, and task-worker steps must preserve core audit ids. |
| Agent Quota / Rate Limit / Cost Attribution | Quota and cost checks run before expensive work but after machine identity resolution. | May add governance metadata to audit summaries only; cannot remove source evidence or license fields. | quota.allowed, quota.denied, rate_limit.denied, cost.attributed. |
Denial shape must match existing machine-readable envelopes across access layers. |
| Data Contract / Schema Compatibility | Schema evolution is additive unless a migration explicitly declares a breaking change and blocks release. | Data package, evidence, license, quality, and denial envelopes are versioned contracts. | schema.compatible, schema.breaking_change_blocked, schema.version_recorded. |
Generated client tests must compare payload semantics, not interface-specific wrappers. |
| Client Agent Conformance Test Kit | Test kit verifies client behavior; it does not become a new product interface. | Uses published contracts and safe fixtures only. | conformance.started, conformance.case_passed, conformance.case_failed. |
Clients must prove that permission, license, schema/provenance, output-origin, and tenant denials are handled consistently. |
These preparation items cannot bypass CoreServiceBoundary, license,
schema/provenance, tenant-isolation, or append-only audit controls. They also
cannot introduce a policy that blocks otherwise permitted facts solely because of
client investment intent.
Release Gate For Step 49¶
Step 49 is complete only when the design-level tests confirm:
- RBAC rules map to ABAC attributes.
- Database-layer isolation and application-layer isolation remain defense in depth.
- OPA outage or partial policy response cannot create a permissive path for high-risk requests.
- Keycloak planning leaves the data package contract unchanged.
- Enterprise deployment planning does not add a human console.
- Workflow audit trace, quota, cost attribution, schema compatibility, and conformance tests stay behind the existing core governance boundary.