# Praxis API Quickstart Security Config

> Praxis API Quickstart Security Config

- Skill: `codexrodrigues/praxis-api-quickstart-security-config` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add codexrodrigues/praxis-api-quickstart-security-config`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/praxis-api-quickstart-security-config/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: codexrodrigues (https://skillmd.com/u/codexrodrigues)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/codexrodrigues/praxis-api-quickstart-security-config

---


# Praxis API Quickstart Security Config

Use this skill for host security and exposure policy in `praxis-api-quickstart`. The quickstart hosts `praxis-metadata-starter` and `praxis-config-starter` in real HTTP; it owns how their public contracts are exposed, not the contracts' business, metadata, persistence, AI, or authorization semantics.

Security here is an executable policy matrix, not a collection of `permitAll` calls. Every public route, method, header, cookie, origin, rate-limit bucket, firewall exception, and filter exemption needs a named reason and a focused proof.

Pair it with:

- `praxis-api-quickstart-operational-proof` for host-versus-starter ownership and HTTP proof.
- `praxis-config-runtime-persistence` for `ui_user_config`, ETag, runtime context, and config header semantics.
- `praxis-config-agentic-authoring-streaming` for AI authoring/SSE security under `/api/praxis/config/**`.
- `praxis-metadata-schema-contracts` for `/schemas/**`, `ETag`, `X-Schema-Hash`, and structural metadata ownership.
- `praxis-api-quickstart-cockpit-http-validation` when security changes affect official cockpit HTTP examples or browser evidence.

## Canonical Boundary

- The quickstart owns Spring Security matcher order, CORS, CSRF, cookie/session bridge, trusted proxy treatment, rate limiting, HTTP firewall policy, local/prod properties, and downstream HTTP tests.
- `praxis-config-starter` owns config persistence, AI registry/context/authoring behavior, ETag semantics, tenant/user/environment headers, and endpoint contracts under `/api/praxis/config/**`.
- `praxis-metadata-starter` owns schemas, schema hashes, `x-ui`, actions, surfaces, capabilities, and structural discovery semantics.
- Angular and other browser clients consume the headers and exposure policy; they must not invent local storage, origins, cache validators, or authorization fallbacks to compensate for a host policy defect.

If a config or schema endpoint is `permitAll` but receives `403`, inspect host origin, CORS, CSRF, firewall, and rate-limit policy first. If the HTTP contract itself is wrong, fix the appropriate starter and keep quickstart as the operational proof.

## Required Source Inventory

Read `praxis-api-quickstart/AGENTS.md`, then inspect:

- `src/main/java/com/example/praxis/apiquickstart/config/SecurityConfig.java`
- `security/ConfigOriginRestrictionFilter.java`
- `security/PublicApiRateLimitFilter.java`
- `security/CookieJwtAuthenticationFilter.java`
- `security/SpaCsrfTokenLifecycle.java`, `SpaCsrfTokenRequestHandler.java`, and `CsrfCookieFilter.java`
- `security/EnterpriseSessionLifecycle.java`, `EnterpriseSessionStore.java`, `VerifiedJwtCredential.java`, and `JwtTokenService.java`
- `/auth/**` controller issuance, revocation and identity-switch behavior
- `src/main/resources/application.properties`, `application-dev.properties`, and `application-prod.properties`
- `docs/security-overview.md`, `docs/security-read-open.md`, README exposure notes, and official HTTP examples
- focused SecurityConfig, CORS, config-origin, rate-limit, CSRF, config AI, and schema integration tests

Treat effective properties and executable tests as source evidence. Documentation is a required derived surface, not proof that a default or route policy is actually configured.

## Enterprise context and Config write admission

Inspect `EnterpriseRuntimeConfiguration`, `EnterpriseRuntimeProperties`,
`QuickstartEnterprisePresentationSource`, `QuickstartUiConfigAdmission`, its MVC
interceptor and `QuickstartUiConfigAdmissionConfiguration` together. Config owns
runtime/context DTOs and the `UiConfigWriteAuthorizer` SPI; the host composes its
actual SESSION, membership, presentation and admission sources.

Require two distinct managed 32-byte reference keys and an explicitly configured
presentation catalog. A missing catalog is incomplete composition; an explicitly
empty catalog is valid and grants nothing. With an empty authoritative directory,
authenticated context returns selection-required with no effective context and
no choices. Never seed production tenants, organizations or memberships to make
the endpoint ready. Presentation labels and JWT roles do not authorize access.

Before generating or rotating reference keys, inventory the effective deployment
configuration privately, including `SPRING_APPLICATION_JSON`, environment aliases
and property precedence. Missing individual environment variables do not prove
missing keys. Record only presence, validity and source, never values or a full
environment/JSON dump. Preserve valid managed keys; rotation is a separate explicit
operation affecting issued references, not a remedy for an empty catalog.
An explicitly empty `app.security.enterprise.presentation.contexts` is different
from missing configuration, missing membership storage and an empty authoritative
membership directory. Diagnose each independently.

Inspect `JdbcEnterpriseMembershipSource`, `EnterpriseRuntimeProperties` and
`QuickstartEnterprisePresentationSource` together. Persistent membership supplies
the exact subject/tenant/environment/optional-selector tuple, revision, validity,
revocation and capabilities; presentation supplies only reviewed public labels.
`AUTH_*` lab identities establish authentication, not enterprise grants. Neither
an ADMIN role, a presentation entry nor successful login can replace membership.
Provision access through a separately authorized administrative operation with a
reviewable plan, explicit compare-and-set precondition and bounded validity;
startup, migrations and demo authentication must not insert or renew grants.

Inventory the actual membership catalog before installation: column types,
nullability/defaults, constraints, foreign keys, ownership and effective ACLs.
An empty table is not permission to replace its schema or drop directory FKs.
For PostgreSQL `SELECT ... FOR UPDATE`, UPDATE on an innocuous column may provide
the lock privilege even when table-level UPDATE is false. Preserve the admitted
lock anchor and check its effective column grant; do not alter its type or grant
UPDATE on capability, selector or revision columns to satisfy a fixture shape.

For every canonical UserConfigController handler, including both identifier
transports and conditional reads, revalidate the active SESSION, current selected
membership, contextVersion and exact tenant/environment/user headers before the
controller. Non-read methods additionally require the current membership's
`ui.authoring.configure`; USER scope is not a personal-preference exemption.
Install the existing write-authorizer SPI too, rechecking admission immediately
before persistence. USER targets the authenticated subject; TENANT targets the
selected tenant; an optional updated-by value must match the subject. Distinguish
unauthenticated, forbidden, stale-context and unavailable-source results. The
separate API and Config transactions do not provide an XA revocation fence.

Validate through real HTTP on an exclusively assigned Neon child using ordinary
runtime identities, TLS and actual column privileges. Membership FOR UPDATE may rely on the innocuous lock-anchor column UPDATE
privilege; verify SESSION issuance, selection and revocation column grants
separately. Do not widen grants because table-level UPDATE is false. Prove empty directory, session-bound choices,
concurrent selection CAS, Config ETag and fallback, denied capability/forged
identity, revoked membership, stale context, scoped cleanup and logout204 plus
old-SESSION401. Preserve failed receipts and resolve uncertain issuance before
retrying. Readiness warming is not proof of first-request behavior after an idle
pool; record that boundary explicitly. For error responses such as Config's
textual412, capture status and body hash before attempting JSON decoding.

## Cost of enterprise authority admissions

For repeated enterprise/page admissions, inspect `EnterpriseContextSessionService`,
`JdbcEnterpriseContextSnapshotReader`, `EnterpriseSessionStore` and
`JdbcEnterpriseMembershipSource` before changing budgets or transaction managers.
The host reader composes the existing SESSION and membership snapshot; Config still
owns lifecycle checkpoints and persistence. Keep two fresh observations around each
admission unit and compare the session revision and complete membership. Do not cache grants,
remove checkpoints, raise the page validation budget or widen runtime privileges.

Audit `QuickstartPageHost.require` before multiplying operational reads inside one
callback: app/namespace shape and complete invocation/capability/source policy can
share one `requireCurrent` admission with both observations still around the policy.
Do not reuse that result in the next callback or globally weaken `requireContext`.
For the canonical
`PageCreationHost.requireCreation(principal, contextVersion, expected, source)`
contract, evaluate the FULL resolve policy plus CREATE_PAGE, READ_SOURCE and
COPY_SOURCE in one admission using the supplied Principal. Do not substitute
thread identity or the expected actor. Preserve
`QuickstartUiLayoutContextAuthorization.authorize`'s existing identity check:
the supplied Authentication must be the ambient SecurityContext Authentication;
do not accept a detached credential or replace the supplied identity to pass it.
Return the freshly observed context only
after both observations succeed; Config requires exact equality with expected
and rejects null. Expected grants no authority and must not silently rebase scope.
This is an explicit joint decision
window, with the same operational locks and fresh before/after observations around
all three pure policies; it changes their former separate linearization points.
No Config work, source I/O or arbitrary extension belongs between these policies.
Config still invokes the unit at each creation/replay/commit checkpoint, and
revocation between units must deny the later call. Test policy completeness,
stale scope and expiry, retaining independent admissions for other callbacks.
Do not generalize this grouping to unrelated policies or claim the unchanged
40-second operational budget is met from an observation-count reduction alone.
The separate canonical `requireNativeProvenance` unit is restricted to captures
classified by Config as Native with wholly non-generated root/child metadata.
In the closed Quickstart producer, `documents.requirePage` checks the exact
historical producer, root metadata and every child's source/metadata inside one
`requireCurrent` policy, without arbitrary extensions or Config I/O. Config calls
that unit before and after structural extensions; both calls retain their own
fresh before/after SESSION/membership observations. Prove the second call rejects
revocation or expiry during those extensions and that no child policy is omitted.
It also includes the FULL resolveLifecycle policy, including custom registration
restrictions, and returns a fresh context for Config's exact-equality check.
Ledger-derived comparison values never authorize the call. Preserve pre-catalog
admission and the post-extension call; post-I/O authority is resolved inside the
joint unit, not reused from the earlier context. Test a stricter custom resolver,
null or divergent returned context, and the supplied Principal boundary.
Mixed captures still use `requireNative` with independent metadata/child checks
and Config provenance correlation; published traversal is unchanged. Do not let
the host select this route from labels or generated-marker guesses.
For child evidence, implement `requirePageChildEvidence` as one current admission
covering source, document, reproduction and full metadata; the default denies.
Do not delegate to an old callback or omit restored/frozen children. Config owns
generated-child correlation and its provenance traversal, not a host grant cache.
The configured lifecycle admission bean itself must implement
`PageLifecycleAdmission`. Its `requirePage` preserves all operation/domain
policies of `require` while attesting current context in the same authority
window. A separate provider or ignored delegate would bypass custom restrictions.
Retain fresh before/after observations, post-catalog context checks and renewed
admission after provenance/at commit. Unknown page UUIDs need admission before
lookup; non-page invocations still use `require`. Test plain-bean rejection and
restrictive custom policies as well as stale context and revocation.
For the closed pilot, structure validation may be pure: retain `validation.require`,
registered tenant/environment/unit, exact root/sole composition/target, canonical
schema/reproduction, icons, Form restrictions and selectors. Inspect
`QuickstartPageFormContentPolicy` before evolving content: the native B0 stays
empty, while revisions/copied baselines may contain the admitted SDK local fields
(`controlType`, `source: local`, `transient: true`, `submitPolicy: omit`) and
field-only sections/rows/columns. Text controls use `input`, not `text`. Keep
field references/order consistent with metadata and reject unknown properties;
do not silently strip editor output. No resource/API bindings, actions, hooks,
rules, option sources, default values or entered preview data are admitted by
this presentation-only cut. Validate real public-editor projection fixtures and
negative widening cases with `QuickstartPageFormContentPolicyTest`; an accepted
structure is not a business-data submission or HTTP publication proof.
Structural acceptance grants no operation or source access. Outside these explicit joint units,
preserve independent current admissions for invocation, lifecycle, mapping,
native source, metadata and children; historical
captures are never grants. Use `QuickstartPageHostTest` and
`QuickstartPageStructureTest` for forged/stale scope, revocation between callbacks
and absence of structural authority I/O. Confirm the Config owner budget propagation
separately; reducing host calls does not repair nested deadline renewal or prove
that the real Neon operation fits forty seconds.

Use the same physical writable operational transaction and datasource for both
stores. The composed query locks materialized SESSION before the exact membership
lookup (NULL selectors are significant), reuses verified identity and the original
parsers/clocks, and evaluates validity after lock waits. Invalid SESSION must be
rejected before interpreting grant JSON; technical membership failures must not
become successful absence or authentication failures.

At READ COMMITTED, a membership inserted while the statement waits on SESSION may
be conservatively absent even when the changed SESSION is visible. Preserve denial;
never recover an old grant or silently retry using an alternate read. A subsequent
fresh request can observe the new membership. Document this availability boundary.

Use `JdbcEnterpriseContextSnapshotReaderTest` for physical guards/choreography and
the assigned-Neon `JdbcEnterpriseContextSnapshotReaderNeonTest` for actual two-query
admissions, SESSION-before-membership locks, revocation, expiry after waits and
coherence rollback. For group-draft HTTP acceptance, use
`QuickstartPageCorporateHttpNeonTest#groupsDraftCreateReadAndCommitRollback` only
with the explicitly resolved compatible Config artifact. Require create/read below
the unchanged budget; force failure after draft and metadata are staged, observe
transaction rollback, and independently read their absence through another ordinary
runtime connection before retrying the same creation key. Fixture cleanup is not
rollback proof. Bind receipts to source, dependencies, branch, privileges and timings;
these focal gates do not certify publication, navigation, browser or deployment.

## Current Operational Grants And Context

For bulk-provider composition, inspect `security/QuickstartOperationalContextResolver.java`,
`QuickstartPrincipalGrantRepository.java`, `docs/OPERATIONAL-GRANTS-CONTEXT.md` and the
canonical `db/operational-migrations/V20260914_001__operational_binding_and_principal_grants.sql`.
Do not use token authorities or the demo catalog as a revocable authorization source.

- The host reference profile binds one dedicated operational database to an immutable
  namespace/tenant/environment. Configure all three `app.security.operational-binding.*`
  properties explicitly; absence blocks resolution, partial values fail bean creation.
  Future registry readiness must verify persisted binding before advertising availability.
- Provision binding/grants administratively after the official migration. Runtime needs
  schema USAGE and only SELECT on the authorization tables, with no owner/admin role
  membership. Reads reject effective table/column write privileges; this is not a universal
  proof against role escalation or an administrator disabling triggers.
- Revoke by deactivation, preserving UUID/subject/namespace and monotonic row version.
  Administrative UPDATE must condition on the expected version and verify one returned row;
  the trigger increments versions but cannot enforce an administrator's WHERE predicate.
- Resolve the authenticated subject, reject divergent/repeated identity headers, and load
  the current grant on a separate READ COMMITTED `governanceReaderDataSource` connection.
  Never reuse an ambient transaction or the Config datasource for admission; account for
  an extra pool connection. Authorized result readers use `readCurrentInSnapshot` on their
  caller-owned physical read-only REPEATABLE READ connection, preserving one coherent snapshot.
  Publish Config server attributes only after authorization and clear previous bridge values
  on every attempt. Missing grants deny; infrastructure/binding failures stay unavailable.
- Validate well-formed Unicode scalar values before JDBC and identity hashing. Isolated
  UTF-16 surrogates can survive a signed JWT and be silently replaced by `?` by JDBC or
  a permissive UTF-8 encoder, borrowing another subject's grant and colliding fingerprints.
  Reject malformed input rather than normalizing/replacing it, use strict digest encoding,
  and compare the stored subject exactly with the authenticated subject. Keep valid
  supplementary characters distinct; Java limits remain UTF-16 code-unit limits. Prove
  both malformed high/low surrogates via real JWT/HTTP/PG and positive valid Unicode.
- The context's grant fingerprint does not authorize fields/targets/references, and its
  ResourceVersionScope is not installed globally. No new bulk route, job authorization or
  READY is implied. Review session versus legacy internal-delegation token admission when
  composing the actual provider/executor. Revocation applies to the next fresh lookup,
  not retroactively to an admitted transaction.

For financial action-policy admission, inspect `config/OperationalPolicyGate`
and `OperationalPolicyGateTest`. The G4 candidate resolves the exact canonical
action first; its declared `PAYROLL_APPROVE` requirement selects the current
operational grant, never a route-name heuristic. Replace only that authority in
the local availability context after exact subject/tenant/environment agreement;
preserve other authorities and do not mint a claim or mutate authentication.
Missing/revoked authority denies with 403; unavailable storage fails with a safe
503 before Config, without a JWT/demo/owner fallback. Other required authorities
remain mandatory. This bridge does not grant target coverage or replace final
domain authorization, locking or CAS, and does not generalize to all JWT authorities.

Run `QuickstartOperationalIdentityTest`, `QuickstartPrincipalGrantRepositoryPostgresTest`, `QuickstartOperationalContextHttpTest`
and the operational migrator tests in the smallest applicable scope. Every database-backed
case requires an isolated remote Neon branch explicitly assigned to the run, with actual
ordinary runtime/control-plane roles and a separate migration owner where required.
Verify project/branch, endpoint, PostgreSQL version, TLS and effective identity/privileges;
bind raw results to the exact source, dependencies and assignment without exposing secrets.
Legacy embedded test fixtures and binary-version overrides remain historical evidence,
not a current execution recipe or substitute for Neon. Confirm the selected harness is
available and compatible in the actual baseline; if not, leave its gate pending without
local fallback or assuming an unmerged AssignedNeon integration. The HTTP fixture proves context resolution only;
write admission/CSRF, domain effects, replay/status/cancel and worker delegation need their
own integration gates. Existing route policies and demo grounding are not replaced by this source.

## Mission Participant Grants

When extending mission-participant update authorization, inspect the host's
`QuickstartPrincipalGrantRepository`, `V20261002_001__mission_participant_grants.sql`,
mission grant PostgreSQL proofs and `OPERATIONAL-GRANTS-CONTEXT.md`. These are host-owned
operational entitlements; Metadata owns the bulk protocol and Config the governed policy.

- Reuse the revocable parent grant and its revision. `MISSION_PARTICIPANT_UPDATE` requires
  explicit mission coverage, wire fields (`funcionarioId`, `papel`, `ordem`, `principal`,
  `resultado`) and employee-reference coverage. Department coverage or JWT authorities
  cannot grant this access. Empty references deny access to references; they never mean all.
- Persist employee references as relational rows with individual FK `RESTRICT`, not only
  arrays. Require administrative revocation before mission/employee deletion. Audit keeps
  historical identifiers without domain FKs so deletion cannot erase evidence. Keep the
  grant identity and append-only audit protected; do not provision grants through demo seeds.
- Administrative replacement requires expected revision and evidence, locks grant before
  the sorted union of old/new employees and mission, increments the parent once and records
  before/after scope atomically. Canonical no-op changes neither revision nor audit. Grant
  deactivation/authority removal clears mission scope before changing the parent and keeps
  departmental authorization/audit behavior intact. Mixed revocation uses grant → employees
  → missions → departments. Do not silently replace existing applied migrations.
- Keep runtime SELECT-only for coverage and without admin function, audit or sequence access.
  Harden new-object default/PUBLIC ACLs and provision administrator EXECUTE explicitly for
  the new P3 replacement function. Preserve intentional P1/P2 administrator grants.
  The reader must check unsafe effective privileges, use one SQL instruction for all scope
  in both RC admission and RR result reads, and avoid Cartesian products that duplicate rows.
  Validate exact typed rows/collections and fail closed on inconsistent or orphan scope.
- Prove real PostgreSQL FK denial followed by governed revocation/deletion with retained
  audit, stale revision/no-op, rollback, runtime privilege denial and coherent immutable
  scope reads. Update every constructor and fixture that consumes the extended grant.
  Schema-only fixtures still need domain key tables and the real migration; do not mask a
  missing migration by fabricating an empty mission scope in the reader. Run the official
  migrator PostgreSQL proof with separate migration/runtime identities; a Docker skip is
  not this proof. The host uses EmbeddedPostgres for this gate, including concurrent
  hosted bootstrap and migration history. Check actual baseline/version ordering before
  changing expected counts; do not weaken assertions to hide a missing or duplicate migration.

For the mission-participant mutation fence, inspect the additive
`V20261002_002__mission_participant_authorization_fence.sql`,
`MissionParticipantScopeAuthorizer` and the concrete bulk preparation before wiring adapters.
Retain the exact authenticated grant revision with a boolean-only SECURITY DEFINER function
on the same writable physical transaction. Check the real runtime login, binding, subject,
UUID, active authority and revision; runtime EXECUTE is restricted and defaults/PUBLIC are
revoked. Administrative G1 writers must acquire this parent grant before changing scope.

Require coverage of every target mission, explicit field (including SET to the same value)
and both current/proposed employee references. Bulk omission preserves intent; ordinary PUT
has separate effective-change semantics and must not be inferred from a mapper. Initial
missing and out-of-scope targets share one sanitized 404. Drift after authorized coordinate
discovery conflicts without acquiring a late employee or mission lock. Discover only scalar
target/population coordinates before E; fix the authorized missions, acquire sorted E→M,
recheck targets, then read/lock P and private team facts. Do not reread full target facts and
compare only afterwards: that leaves a reparenting window. Peers needed for aggregate checks
are not automatically editable. Prove the concrete preparation, grant fence and domain
mutation together on PostgreSQL with two connections; separate mock/lock tests alone do not
prove the complete chain. Keep the caller's live deadline throughout.
A scope-race oracle must distinguish forbidden private reads from rejection after such a
read: an HTTP conflict and absence of new locks alone are insufficient. Inspect prepared SQL
on the caller's session and require no private projection before denial. Verify the oracle
with a temporary test-only negative control that attempts the forbidden projection, fails
that specific assertion, and is restored byte for byte; never add a production bypass.

For the concrete mission protected-read provider, inspect
`MissionParticipantBulkReadAuthorizationProvider` and its unit/PostgreSQL proofs.
Capture and readback must reuse the caller-owned physical read-only REPEATABLE READ
connection. Reload the grant in that snapshot and use its actual revision and complete
scope evidence in the authorization fingerprint; an earlier READ COMMITTED admission
fingerprint cannot certify captured facts. Authorize the complete target set, explicit
fields and captured/current/proposed employee references using scalar coordinates before
any private team projection. A different reader may access results only with full current
coverage; creator identity alone neither grants access nor forbids an authorized delegate.
Keep namespace, operation and subject bound to trusted composition, reject unsupported
connections, and consume the caller's live deadline without renewing it. A tested provider
without concrete wiring does not expose an endpoint or certify READY. Distinguish these
public-release proofs from a later evaluator that requires an explicitly named candidate
Metadata coordinate; never install candidate code under the public version number.

For mission bulk mutation, distinguish that complete read-scope fingerprint from
`BulkEvaluationGovernance.authorizationFingerprint`. The latter must identify the grant
revision observed by the evaluator's RR capture through the existing
`Grant.fingerprint(MISSION_PARTICIPANT_UPDATE)`, never the earlier admission RC grant.
It is not field/reference coverage. All governed coverage/authority writers must bump that
revision by CAS; retain the exact revision by G in the operational transaction and check
captured/current/proposed coverage before private facts. A fingerprint incorporating every
target's mutable version cannot serve as per-unit grant evidence: a confirmed earlier item
would invalidate unrelated later items. Keep the read provider's complete fingerprint intact.

Revalidate a unit from its immutable intent through the Metadata protocol reader/codec;
compare structural binding, typed policy state/fingerprint and complete protected domain
facts. Acquire G→E→M→P once, reuse the protected graph for candidate validation and JPA
flush, and keep the SDK receipt on that same physical transaction. Do not recapture domain
in REQUIRES_NEW to pretend the mutation is fenced. Compare integral values by their exact
validated domain types across storage round trips, without JsonNode implementation equality
or a host canonical-JSON protocol. Preserve cohort versions: an earlier confirmed write in
the same mission may conflict with the next unit; never absorb that drift to allow a joint
leader swap. Unrelated missions must remain independently executable.

Use the SDK's protected reservation and advance flow. Receipt/admission replay precedes
gates exclusive to new effects; recovery reconciles evidence without dispatching fresh
mutations. Prove real domain+receipt commit/rollback, no repeated callback on replay,
revocation waiting for retained G, stale facts/policy rejection and the unchanged live unit
budget with PostgreSQL/JPA. Internal adapters and test-only composition do not prove HTTP,
production READY, public dependency adoption or cross-database atomicity with Config.

The SQL timeout bounds the instruction, not the number of authorization rows or Java
materialization time. IAM coverage is not the bulk target limit. Before P3 execution/READY
or B7 closure, prove expected scope volume, pool pressure and memory limits; do not claim
an end-to-end SLA from setQueryTimeout alone.

This persistence/read foundation does not expose READY, execute a bulk mutation, authorize
peer editing, or prove an HTTP adapter. Evaluation and execution must still authorize all
current/proposed references, share grant fencing and protect domain+receipt in one physical
transaction. Do not infer deployment/public adoption from local candidate proofs.

## Exposure Matrix Before Editing

Inventory the route with all of these columns before adding a matcher or exception:

| Surface | Owner | Method | Browser credential/CSRF mode | Origin/CORS rule | Required response headers | Rate-limit class | Default policy |
| --- | --- | --- | --- | --- | --- | --- | --- |
| static docs/Swagger | host | GET/HEAD | none | public docs policy | only intended public headers | optional public-read | explicitly public |
| actuator health/info | host | GET | none | health-check policy | no sensitive values | health policy | public only when intended |
| actuator env/configprops | host | GET | authenticated | no public exposure | sanitized diagnostics only | protected | never read-open |
| `/schemas/**` | metadata starter | GET and filtered POST | contract-specific | schemas aggregator gate | `ETag`, `X-Schema-Hash` when published | public-query | host-gated public surface |
| `/api/praxis/config/**` | config starter | contract-specific | config CSRF/origin/auth policy | explicit allowed browser/proxy policy | `ETag` and config headers | config | host-governed, not automatically open |
| `/api/praxis/runtime/**` | config starter | contract-specific | principal/context policy | explicit CORS | safe projection headers only | runtime policy | never inferred from read-open labels |
| `/api/**` resources | quickstart/metadata | method-specific | session + CSRF unless explicit public query | explicit CORS | schema/config headers where contract says so | read/query/action class | authenticated by default |

Classify the proposed change before coding: `ja-suportado-so-ux`, `ja-suportado-mal-nomeado-ou-mal-materializado`, `suportado-parcialmente`, or `lacuna-real-de-contrato`. Only a real host exposure gap belongs in quickstart security; never create a local endpoint, header alias, schema, or config persistence rule to patch a starter gap.

## Matcher And Method Rules

Spring matcher order is policy. Review the complete ordered chain, not the one matcher being changed.

- Start from deny/authenticated-by-default; document every `permitAll`, method exception, and public POST.
- `read-open` is a demonstration policy, not generic authorization. Scope it by HTTP method and canonical endpoint class; public filter/options/locate/export/stats calls need explicit data-sensitivity and rate-limit evidence.
- When a governed mutation shares a path pattern with a broad demo exception (for example, a POST action wildcard), place the explicit mutation matcher first. Require a non-anonymous authenticated principal and apply the global write kill switch before the application performs current-grant and resource-scope authorization; do not let the demo exception bypass either gate. Prove anonymous requests receive the canonical 401 and authenticated requests under the write-disabled policy receive 403 on every governed mutation route.
- `write-disabled` deny rules interact with earlier exceptions. Prove which public query/config/workflow calls intentionally win and which writes remain denied.
- `schemasAggregatorEnabled` may expose only the metadata routes required for the structural contract. It does not make all metadata or actuator routes public.
- Keep `/actuator/env` and sensitive actuator diagnostics authenticated and non-exposed even when `read-open` is enabled.
- `OPTIONS` is a CORS preflight concern, not authorization evidence. Test preflight separately from the actual credentialed request.
- Do not route policy by URL labels, aliases, keyword checks, or ad hoc regexes. Use explicit Spring path patterns, methods, canonical `ApiPaths`, and property-backed policy decisions.
- Scope authentication entry points with the same care as authorization matchers. In Spring Security, a lone `defaultAuthenticationEntryPointFor(entryPoint, matcher)` mapping can be promoted to the default entry point for the whole filter chain; do not assume its matcher will constrain it. When an entry point is meant for one surface, configure an explicit fallback that preserves the legacy response elsewhere and test both an in-scope anonymous request and an out-of-scope protected route/method.

## CORS And Contract Headers

CORS is part of the browser-visible Praxis contract.

- Use explicit official origins whenever cookies or credentials are enabled. A wildcard origin must disable credentials.
- Do not invent ports or origins. Use the documented official local origins and deployment origins from properties.
- Allowed methods and headers must match the public API surface, including preflight for `PUT`, `PATCH`, `DELETE`, config/AI calls, and schema reads only when actually supported.
- Expose non-simple canonical response headers that browser consumers must read. This includes `ETag` for config conditional persistence and `X-Schema-Hash` or other starter-published schema validators when applicable. `Access-Control-Expose-Headers` must come from the host CORS policy; clients cannot recover an unexposed header.
- Test allowed credentialed origins, blocked origins, wildcard-without-credentials behavior, allowed methods, and exposed headers with browser-equivalent requests.

## Config Origin, Proxy, And Rate-Limit Trust

`ConfigOriginRestrictionFilter` is operational host governance for `/api/praxis/config/**`; it complements but does not replace authentication, authorization, CSRF, tenant/user/environment resolution, ETag, or server-side AI principal policy.

- `permitAll` never means ungoverned config access. Preserve an explicit allowed-origin and method policy for browser traffic.
- Prefer canonical `Origin`; use `Referer` only as a parsed origin fallback. Missing/invalid browser provenance must fail closed unless an explicit, separately authenticated service-to-service policy applies.
- Do not treat caller-controlled `Host`, `X-Forwarded-Host`, `X-Forwarded-Proto`, `Forwarded`, or `X-Forwarded-For` headers as trusted facts on a directly reachable app.
- Honor forwarded headers only behind an explicitly configured trusted-proxy boundary. Origin reconstruction and rate-limit client identity must use the same trust policy.
- A proxy normalization policy belongs to the host/deployment boundary. Do not solve it with an Angular header, a config-starter bypass, or permissive origin fallback.
- Rate limiting is abuse protection, not authorization. Use distinct buckets for login, public read, public query, bulk action, config, and any high-cost AI/SSE surface; never let a forged forwarding header create arbitrary buckets.
- Include `Retry-After`, bounded/safe error bodies, and diagnostics that do not leak secrets, tokens, or private config values.

Apply the dedicated AI per-client rate limit before the broader config limit for
`/api/praxis/config/ai/**`. Keep its limit/window externally configurable and
prove denial without triggering a provider call. The reference in-memory
limiter is host baseline only; production gateway/WAF and provider project
budgets remain separate controls. Pair provider-cost or probe work with
`praxis-config-ai-provider-operations`.

## CSRF, Session, And Filter Chain

Cookie JWT authentication, CSRF, origin governance, and rate limiting have separate responsibilities.

- Inspect `EnterpriseSessionStore`, `EnterpriseSessionLifecycle`, and `CookieJwtAuthenticationFilter` together. A signed JWT of kind `SESSION` is accepted only with an active persisted issuance. In JDBC/real HTTP fixtures, issue it through `EnterpriseSessionLifecycle.issue` after server-side authentication/grant preparation and verify the persisted credential/subject before the first request. Direct `JwtTokenService.generate` does not establish that session; never replace SESSION with INTERNAL_DELEGATION or mock active-session checks to claim this proof.
- Prepare session storage on the operational datasource before issuance, with only the fixture runtime privileges actually required. A disposable test schema may use an explicitly sourced current schema snapshot, but must be labeled TESTONLY. It does not recover original migration bytes/checksums or prove Flyway, deployment, membership selection, or production grants. Preserve the original failed run and repeat only the affected focal after diagnosis/review.
- Distinguish direct ACL entries from effective privileges and from the role actually configured in the running host. Check relevant SELECT/INSERT/UPDATE privileges without copying user/session data; do not silently repair hosted grants during a fixture test.
- Both cookie and bearer credentials of kind SESSION need the same active issuance bound to UUID, subject and exact expiry. Changing the transport to bearer does not remove SESSION admission. INTERNAL_DELEGATION is an explicit internal bearer kind, not a substitute for browser-session/context/grant fixtures.
- In real HTTP fixtures, issue once per intended session and reuse the credential through its journey. Cleanup must address only that fixture's issuance UUID and subject, preserving unrelated credentials. Reissuing on every request can mask revocation negatives.
- In WebMvc policy slices that exclude persistence, retain real JWT validation, the JWT filter, controller and SecurityConfig. A narrow stateful lifecycle double may simulate issuance/revocation only when it binds UUID, subject and exact expiry and rejects unissued, revoked or expired credentials. Clear only its own state between scenarios. Never return isActive=true unconditionally or inject a principal to bypass the JWT filter. This boundary proves slice policy, not PostgreSQL, transaction participation, tenant/context or grants; a CSRF-disabled role slice is not CSRF evidence.
- Keep reachable positives and existing role/grant negatives. For SPA policy, prove signed-but-unissued token rejection, old-cookie denial after identity switch, and active-session writes rejecting absent or mismatched XSRF while matching tokens reach the intended action. Do not weaken statuses, filters, permission policy or CSRF exceptions to repair fixture prerequisites. Reuse valid evidence from unaffected classes and preserve the failed campaign; repeat only corrected paths unless a separate adoption gate requires broader verification.
- Cookie authentication establishes the Spring principal; validate cookie attributes (`Secure`, `HttpOnly`, `SameSite`, lifetime, a

…(truncated)
