Praxis Authorization Decision Platform
Use this skill whenever work touches decisionKind = AUTHORIZATION across praxis-authz-contracts, praxis-authz-enforcement-core, praxis-authz-opa, praxis-authz-starter, or host integrations consuming governed authorization, row-level DataScopePlan, attribute-level FIELD_USE/FIELD_WRITE, server-side MASK, and OBLIGATION barriers.
1. Canonical Architectural Boundary (decisionKind = BUSINESS vs decisionKind = AUTHORIZATION)
Never conflate deterministic business rules with authorization/data-protection policies:
decisionKind = BUSINESS(praxis-rules-engine): Owns domain invariants, eligibility, calculations, and 5-state business outcomes (RULE_TRUE,RULE_FALSE,NOT_APPLICABLE,INDETERMINATE,ERROR) in JSON Logic (RuleSet). Governed inpraxis-policy-studiounder the Business Rules Lens.decisionKind = AUTHORIZATION(praxis-authz-*+ OPA/Rego v1): Owns access control (ACCESS), row-level query scoping (DATA_SCOPE), field read/inference restrictions (FIELD_USEacrossVALUE | FILTER | SORT | GROUP | AGGREGATE | JOIN), field mutation authorization (FIELD_WRITEoverWriteIntent), detached DTO masking (MASK), and conditional obligations (OBLIGATIONacrossBEFORE_EXECUTION | BEFORE_COMMIT_OUTBOX | BEFORE_DISCLOSURE). Governed inpraxis-policy-studiounder the Access & Data Protection Lens usingDomainRuleDefinition(ruleType = "authorization_policy", schemapraxis.authorization-policy/v1).
2. Source Audit Before Editing
Inspect the canonical owners and contracts before changing code or authoring policies:
- Published Maven Central coordinates (
0.1.0-beta.*line underio.github.codexrodrigues):io.github.codexrodrigues:praxis-authz-contracts:0.1.0-beta.2io.github.codexrodrigues:praxis-authz-enforcement-core:0.1.0-beta.2io.github.codexrodrigues:praxis-authz-opa:0.1.0-beta.2io.github.codexrodrigues:praxis-authz-starter:0.1.0-beta.7(includes starter-only hotfixes consuming0.1.0-beta.2upstream modules andpraxis-metadata-starter:8.0.0-rc.195)
- Architecture & Contract Closure Pack (
CC01–CC12):docs/architecture/praxis-policy-starter/README.mddocs/architecture/praxis-policy-starter/decision-platform-contract-closure-pack.mddocs/architecture/praxis-policy-starter/MATRIZ-INTEGRACAO-E-GATES.md
- Pure contracts (
praxis-authz-contracts— no Spring, no Hibernate/JPA, no HTTP SDKs):org.praxisplatform.authz.contracts.annotation.*(@AuthzTenantScope,@AuthzScopeAnchor,@AuthzCustodyPartition,@AuthzMask,@AuthzMasks,@AuthzActionRule,AuthzTenantScopeMode,AuthzDelegationSplitMode,AuthzCustodyRole,AuthzMaskStrategy,EvaluationMode)org.praxisplatform.authz.contracts.decisionpoint.*(DecisionPointIdentity,DecisionPointDescriptor,EnforcementCapability,FieldUseCategory,PointAuthorityMode)org.praxisplatform.authz.contracts.context.*(FactDescriptor,FactContract,ContextCompositionProfile,ResolvedFactValue,FactResolutionStatus,ProviderInputProjection)org.praxisplatform.authz.contracts.datascope.*(QueryableResourceProjection,SearchPredicateIr,DataScopePlan,KleeneSearchPredicateEvaluator)org.praxisplatform.authz.contracts.binding.*(RuntimeEnforcementBinding,WriteIntent,ReadinessStage)org.praxisplatform.authz.contracts.policy.*(AuthorizationPolicyDefinition,AuthorizationPolicyCandidateValidator,DefaultAuthorizationPolicyCandidateValidator,DualScopeDelegationSpec)org.praxisplatform.authz.contracts.masking.*(MaskStrategyRegistry,DefaultMaskStrategyRegistry)org.praxisplatform.authz.contracts.obligation.*(ObligationHandlerRegistry,DefaultObligationHandlerRegistry)org.praxisplatform.authz.contracts.digest.*(DigestDomainKind,CanonicalDigestCalculator,PolicyDigestChain,OpaRuntimeRelease,OpaRuntimeHead)org.praxisplatform.authz.contracts.compatibility.*(HostPolicyCompatibilityManifest,ImpactGraphBaseline,DefaultHostPolicyCompatibilityVerifier)
- Runtime enforcement core (
praxis-authz-enforcement-core— no Spring Boot, no Hibernate ORM):org.praxisplatform.authz.enforcement.context.*(UntrustedRequestHeaderGuard,ContextCompositionCoordinator,TrustedFactSource)org.praxisplatform.authz.enforcement.writeintent.*(DtoWriteIntentExtractor,FieldWriteAuthorizer)org.praxisplatform.authz.enforcement.fielduse.FieldUseQueryGuardorg.praxisplatform.authz.enforcement.jpa.*(JpaDataScopeAdapter,QueryAdapterFieldBinding,CompiledDataScopeCriterion,RelationTraversalStrategy)org.praxisplatform.authz.enforcement.masking.DetachedDtoMaskingProcessororg.praxisplatform.authz.enforcement.obligation.ObligationBarrierCoordinatororg.praxisplatform.authz.enforcement.pipeline.*(EnforcementPipelineExecutor,HostDecisionNormalizationEngine,AuthorizationProviderPort)
- OPA compiler, bundle assembler, and client (
praxis-authz-opa— no Spring, no JPA):org.praxisplatform.authz.opa.compiler.RegoV1PolicyCompilerorg.praxisplatform.authz.opa.bundle.OpaBundleAssemblerorg.praxisplatform.authz.opa.revision.SameInstanceSearchRevisionGuardorg.praxisplatform.authz.opa.client.*(OpaAuthorizationProviderAdapter,HttpClientOpaTransport,DeterministicLocalOpaTransport)org.praxisplatform.authz.opa.governance.GovernedOpaReleaseCoordinator
- Spring Boot starter & end-to-end pilot (
praxis-authz-starter):org.praxisplatform.authz.autoconfigure.*(PraxisAuthzAutoConfiguration,PraxisAuthzProperties,PraxisAuthzHostBridgeAutoConfiguration,PraxisAuthzAgentBridgeAutoConfiguration)org.praxisplatform.authz.agent.*(AuthzAgentAuthorizationBridge,AuthzAgentThreadContextPropagator)org.praxisplatform.authz.compatibility.*(HostPolicyCompatibilityStartupVerifier,HostRuntimePolicyCoordinates,PraxisAuthzReadinessHealthIndicator)org.praxisplatform.authz.catalog.*(SemanticDecisionPointCatalogService,FieldLineageCatalogEntry,MethodBindingAdmissionRecord)org.praxisplatform.authz.channel.GovernedChannelInvocationExecutororg.praxisplatform.authz.export.GovernedCollectionExportGuardorg.praxisplatform.authz.pilot.*(WorkforceLeaveAuthzPilotBlueprint,WorkforceLeavePilotRuntimeHost,JdbcSessionContextIsolationGuard,GovernedPolicyAuthoringGateway)org.praxisplatform.authz.host.metadata.*(AbstractAuthzGovernedResourceService,AbstractAuthzGovernedReadOnlyResourceService,AuthzResourceGovernanceSpec,AuthzResourceGovernanceInterceptor,AuthzResourceOperationAvailabilityRule,MultiOrganizationHardScopeResolver,MetadataDtoGovernanceIntrospector,AuthzHostPolicyBootstrapBuilder,AuthzHostReadinessReviewer[AUTHZ-HOST-001..014],PraxisAuthzExceptionHandlerusing"fieldUseCategory"inCustomProblemDetailinstead of the reserved"category"extension key)
Read contracts-and-gates-matrix.md for the CC01–CC12 contract summary, the 15-step enforcement pipeline order, and the 8 acyclic digest domains.
3. Non-Negotiable Platform Invariants
- Zero Trust on Request Headers (
P01,P42,P61):UntrustedRequestHeaderGuardblocks allx-authz-*,x-praxis-authz-*,x-bypass-*, andx-workflow-*headers unconditionally, and forbids authority spoofing acrossx-tenant-id,x-org-id,x-organization-unit-ids,x-delegated-destination-org-ids, roles, and principal headers.- Any other request header (
X-Org-Id,X-Tenant-Id,x-delegated-destination-org-ids) may only narrow asubject.*fact that is alreadyFactResolutionStatus.PRESENTin the authenticated principal's server-side envelope; it can never assertresource.*,transition.*, orcontext.*facts or expand scope. Inpraxis-authz-starter:0.1.0-beta.3,AuthzCallerContextFilterretains capturedincomingHeadersonAuthzCallerContextandAuthzCallerContext.effectiveHeaderProbeMap()passes real request header values (alongside authoritativetenantId/subject.*facts) toUntrustedRequestHeaderGuard, preventing false-positiveAUTHZ_HEADER_SPOOFINGdenials on legitimateX-Tenant-ID/X-User-IDheaders while preserving synthetic probe fallback and fail-closed rejection on tampered headers.
- 6-State Fact Resolution & Fail-Closed Missing Facts (
P04,P30):- Facts resolve to
PRESENT,NULL,ABSENT,STALE,UNAVAILABLE, orERRORacrossEXTRACT -> ENRICH -> DERIVE. DERIVEsources short-circuit toUNAVAILABLEif any upstream dependency is notPRESENT/NULL.- In both Rego v1 (
input.facts["..."].status == "PRESENT") andDeterministicLocalOpaTransport,UNAVAILABLE/ABSENT/ERRORfacts never satisfy equality or membership predicates.
- Facts resolve to
- Persistence-Neutral
DataScopePlan& Kleene 3VL SQL Pushdown (CC03,P06,P24):DataScopePlan(format = "praxis.data-scope/v1") andSearchPredicateIrreference only canonicalfieldPathandattributeIdfromQueryableResourceProjection. JPA/SQL paths (nativeJpaPath,RelationTraversalStrategy) live exclusively insideQueryAdapterFieldBindinginJpaDataScopeAdapter.IS_NULL(MISSING) = UNKNOWNandIS_NOT_NULL(MISSING) = UNKNOWNinKleeneSearchPredicateEvaluator.JpaDataScopeAdapterpushes negation into Negation Normal Form via De Morgan's laws, uses correlatedEXISTS/NOT EXISTSsubqueries for collection/optional paths, escapesLIKE ... ESCAPE ''wildcards, appliesLOWER(col)whencaseInsensitive == true, and always composes dynamic scope with the host's mandatoryhardScopeviaAND.
- Algebraic Combining Without Numeric Priority (
CC12,PCB-ORDER-001):- Numeric rule priority is banned.
ACCESScombines asDENY > ALLOW > NOT_APPLICABLE(anyRESTRICTveto dominates anyGRANT).DATA_SCOPEcombinesGRANTpredicates by union (OR) andRESTRICTpredicates by intersection (AND), intersected with the hosthardScope.
- Complete
WriteIntentExtraction & Dual-Scope Custody (CC06,P13,P14,P45):DtoWriteIntentExtractorclassifies mutations intoSET,CLEAR_EXPLICIT_NULL, andREMOVE(for omitted mapped fields whenpartialPatch == falseon full-replacementPUT). Any business JSON wire path not mapped inattributeIdByWirePath(and not explicitly listed inignoredTechnicalWirePaths) fails closed withAUTHZ_UNMAPPED_WRITE_WIRE_PATH.FieldWriteAuthorizerenforces neutralDualScopeDelegationSpecmodes (ORIGIN_DESTINATION_SPLIT,ORIGIN_ONLY_WRITE,READ_ONLY_DESTINATION, constructed viaDualScopeDelegationSpec.ofOriginAndDestination(...)) and rejects callers matching neither custody scope. Organizational scope transfers (OLD->NEW) require custody over bothOLDandNEWscopes (P14).
- Detached DTO Masking & Commutative Lattice (
CC09,P12,P25,P36):- Never mutate managed JPA entities for masking.
DetachedDtoMaskingProcessoroperates exclusively on detached DTO maps/projections (including nested paths and collections) usingMaskStrategyRegistry(OMIT > NULLIFY > REDACT_CONSTANT > HASH_TOKEN_KEYED > SUMMARY_ONLY > CPF_CNPJ_PARTIAL / PARTIAL_MASK).FIELD_USE(VALUE) = DENYdominates any mask. - In
praxis-authz-starter:0.1.0-beta.4+,AuthzGovernedResourceServiceSupport/AuthzPolicySimulationHarness/AbstractAuthzGovernedResourceServicere-hydrate sanitized detached projections through a dedicatedmaskedProjectionMapper(createMaskedProjectionObjectMapper(), disablingFAIL_ON_UNKNOWN_PROPERTIESfor computed read-only getters and treating@JsonProperty(access = READ_ONLY)asAUTOon internal response re-hydration soid/status fields are never wiped), whilecreateWriteIntentBeanObjectMapper()excludesREAD_ONLYbean default initializers from inbound Java DTOWriteIntentextraction. Inpraxis-authz-starter:0.1.0-beta.6+,AuthzEntityUnproxySupporttransparently unwrapsHibernateProxyinstances acrossAuthzResourceGovernanceSpecandAuthzResourceGovernanceInterceptor(includingScopedBatchReferenceHydratorL1-cached lazy proxies) whenorg.hibernate.Hibernateis on the classpath;0.1.0-beta.7+adds AOP-proxy-safeunwrapServiceTarget(...)and@Id/@EmbeddedIdextraction (extractJpaEntityId), merges un-enriched host pre-resolved snapshots with enrichedAuthzResourceGovernanceSpectenant/null-fact metadata, admitsAUTHENTICATED_SHAREDitems with empty target facts viaitemStateVerified, and denies mutating operations/actions/form surfaces in read-only consolidation (consolidation-read-only-scope).
- Never mutate managed JPA entities for masking.
- 3-Step
SEARCHSame-Instance Revision Guard (CC11,P17,P18):OpaAuthorizationProviderAdapter.evaluateSearchexecutessearch_preflight -> compile_data_scope -> runtime_headpinned to the same OPAinstanceIdviaSameInstanceSearchRevisionGuard. Instance hops fail closed immediately; same-instance bundle rotations allow at most the configured bounded retry (default1).
- Governed Release Coordinator & Anti-
denyAllCorpus Gate (P28,P32,P53,P55,P63):GovernedOpaReleaseCoordinatorrequiresPOLICY_ADMIN_PUBLISH, verifies pinneddefinitionFingerprint(Stage 1of the 8-domain digest chain covering the full semantic policy AST), rejects competingpolicyUnitKey/policyId(P38), and executes mandatory positive (ALLOW/FILTER) and negative (DENY/NOT_APPLICABLE/NONE) corpus cases before emitting aPolicyCandidateActivationReceipt.
- Channel Admission, Cache-Hit Re-Authorization & Governed Collection Export (
P11,P12,P18,P21,P25,P26,P29,P34,P41,P42,P56,P60):GovernedChannelInvocationExecutorblocks unproxied self-invocation (P41), verifies admitted invocation channels (P34), restores outerEvaluationContextSnapshots after nested calls (P29), never skips inner decision point evaluation (P42), frames scoped cache/ETag keys with length prefixes (P21), and re-executes authorization + detached masking on every cache hit (P26).GovernedCollectionExportGuardverifies liveOpaRuntimeHeadfreshness before and after row processing (P18), enforces static and inheritedexportable = falselineage across all representations (P56,P60), applies per-row detached masking (P12,P25), and neutralizes CSV/TSV delimiter/formula injection.
- JDBC Session Context Isolation & Governed Policy Authoring Gateway (
P27,P33,P51..P55,P61,P63):
JdbcSessionContextIsolationGuardbinds transaction-scoped RLS variables (app.current_tenant_id,app.current_principal_id,app.current_org_id) before the first SQL statement, scrubs pooled connections infinally, and rejectsBYPASSRLS/superuser database roles fail-closed.GovernedPolicyAuthoringGatewayisolates untrusted prompt/document text from execution (P54), validates target decision points against the caller's delegatedserviceKeyhard scope, verifiesFactContractmembership, provider fact support, andADMISSION/TARGETphase compatibility (P52,P61), and delegates release activation toGovernedOpaReleaseCoordinator.
- Zero-Blueprint Resource Introspection (
PLAT-EVO-10), Pure@Authz*Annotations (0.1.0-beta.2/starter:0.1.0-beta.7) & Metadata PAP Discovery (PLAT-EVO-07):
- Instead of writing ~350-line manual
*AuthzBlueprintclasses per resource, decorate entities/DTOs/controllers with pure annotations fromorg.praxisplatform.authz.contracts.annotation.*(@AuthzTenantScopewithAuthzTenantScopeMode.TENANT_ONLY | ORGANIZATIONAL_UNIT | AUTHENTICATED_SHARED,@AuthzScopeAnchor,@AuthzCustodyPartition,@AuthzMask,@AuthzActionRule) and buildAuthzResourceGovernanceSpecviaAuthzResourceGovernanceSpec.fromAnnotatedResource(...)(6-arg, 7-arg, orcreateDtoClass/updateDtoClass/serviceClassoverloads) orAuthzResourceGovernanceSpec.<E>builder(resourceKey)...introspectFromResource(...). Opt in toaction.verbprojection onTARGETevaluations via.withActionVerbFact()(populated byMetadataResourceAuthorizationSeam), register extrasubject.rolesvia.withSubjectRolesFact(), or declare custom subject facts cleanly via.subjectFact(factPath, valueType, cardinality, presenceModel). Enable.allowGlobalNullScope(true)on global-or-organization resources (tenantField IS NULL OR tenantField IN orgs):0.1.0-beta.4+automatically marks the nullable tenant binding asFactPresenceModel.MAY_BE_ABSENT, omits it frommandatoryScopeAnchorAttributeIds, emitsFactResolutionStatus.NULLfornullentity properties viaextractEntityTargetFactStatuses/resolveFactStatuses(...), and synthesizes distributedor(in(...), is_null(...))rules inaddOrganizationalScopePolicyandaddBulkActionPolicy. - Auto-Synthesized Policy Bootstrap (
AuthzHostPolicyBootstrapBuilder): CalladdAnnotatedResource(spec[, responseDtoClass, createDtoClass, updateDtoClass])oraddAnnotatedResources(specs)to automatically synthesize primary tenant/organization scope rules,@AuthzActionRulegates, and@AuthzMask+@DomainGovernance-derived redactions (MetadataDtoGovernanceIntrospectorautomatically derivesREDACT_CONSTANT("***")forString,NULLIFYfor nullable non-String, andVALUE+DENYfor non-nullable/primitive non-StringandSECRET/CREDENTIALfields). Inpraxis-authz-starter:0.1.0-beta.3+(0.1.0-beta.7latest),addOrganizationalScopePolicy,addSurfacePolicy, andaddAuthenticatedSharedPolicyalso acceptList<MaskContributionSpec>and optionalList<AuthorizationPolicyRule> additionalRuleswithout host-side helper duplication;0.1.0-beta.4+addsaddSharedBulkActionPolicy(...), auto-synthesizesdefaultSearchFieldUsefor unmaskedAUTHENTICATED_SHAREDresources, and honorsallowGlobalNullScope(true)across scope/bulk rules;0.1.0-beta.7+enriches AOP-proxied service snapshots, non-idprimary keys,AUTHENTICATED_SHAREDsurface availability, and read-only consolidation discovery guards;AuthzHostPolicyBootstrapBundle.resourceSpecs()exposes all registered specs automatically. - Zero-Inheritance Enforcement & Operational Agent Bridge: Register
AuthzResourceGovernanceInterceptor(ResourceGovernanceInterceptor,DEFAULT_ORDER = HIGHEST_PRECEDENCE + 200, automatically consumingAuthzHostPolicyBootstrapBundle.resourceSpecs()in0.1.0-beta.3without separate per-spec bean registrations),AuthzResourceOperationAvailabilityRule(ResourceOperationAvailabilityRule,DEFAULT_ORDER = HIGHEST_PRECEDENCE + 300, composing cleanly insideCompositeResourceOperationAvailabilityEvaluator),MultiOrganizationHardScopeResolver(HARD_TENANT_IDS_PARAM), andPraxisAuthzAgentBridgeAutoConfiguration(AuthzAgentAuthorizationBridge+AuthzAgentThreadContextPropagatorwiringpraxis-config-starter'sOperationalAgentAutoConfigurationfail-closed through OPA/caller context). fromAnnotatedResource/introspectFromResourceautomatically introspects@ApiResource+ MVC mappings (including root@GetMappingempty-subpath list endpoints alongside/{id},/filter,@WorkflowAction,@UiSurface, and/export), maps@DomainGovernance/@DomainLineageand@Authz*annotations, treats@ManyToOne(optional = false),@OneToOne(optional = false), and@JoinColumn(nullable = false)asFactPresenceModel.ALWAYS_PRESENT, coerces tenanthardScopevalues to the JPA attribute type (String,Integer,Long,Short,UUID), and enforces readiness checksAUTHZ-HOST-001..014inAuthzHostReadinessReviewer(includingAUTHZ-HOST-010: verifyingHostRuntimePolicyCoordinatesbinding coverage across CRUD/action/surface methods,QueryableProjectionRefon bulkSEARCHactions, andoperationModifiedAttributeson customFIELD_WRITEactions).- Pair runtime enforcement in
praxis-authz-starterwithResourceDecisionPointCatalogService(deriveForController/deriveForResourceinpraxis-metadata-starter,PLAT-EVO-07) when publishing PAP catalog inventories topraxis-policy-studio.
4. Validation & Release Order
Run focused Maven gates with JDK 21 on the affected modules:
- Contracts (
P1):mvn -f praxis-authz-contracts/pom.xml test - Enforcement Core (
P2):mvn -f praxis-authz-enforcement-core/pom.xml test - OPA Compiler, Bundle & Client (
P3):mvn -f praxis-authz-opa/pom.xml test - Spring Boot Starter,
P01..P64Conformance Matrix & HTTP/Reentrant Suites (P4+P5):mvn -f praxis-authz-starter/pom.xml test(P01ToP64CompleteConformanceMatrixTest,P11HttpAndReentrantServiceIntegrationTest)
When publishing a coordinated Maven Central release across the four repositories (see each repository's RELEASING.md), always release in strict dependency order and wait for Maven Central HTTP 200 on each stage before tagging the next:
praxis-authz-contracts -> praxis-authz-enforcement-core -> praxis-authz-opa -> praxis-authz-starter.
5. Companion Skills
praxis-java-domain-governance-field-accessfor@DomainGovernance,@DomainLineage,@AiUsagePolicy,LegalTreatmentPurpose, and/schemas/domain.praxis-config-domain-decisionsfor/api/praxis/config/domain-rules/**lifecycle, maker-checker approvals, and snapshot control plane.praxis-rules-engine-runtimewhen working ondecisionKind = BUSINESSJSON LogicRuleSets rather than authorization policies.