Security Configuration Reference

This page documents the configuration schema, endpoints, and field flags for Framework M's payload encryption subsystem.

PayloadEncryptionConfig

[tool.framework_m.security.payload_encryption]
mode = "selective"                # "disabled" | "selective" | "metadata" | "strict"
jwks_uri = "/api/v1/security/jwks"
routes = [                        # optional; merges with defaults in selective mode
    "/api/v1/auth/login",
    "/api/v1/payments/charge",
]

Key	Type	Required	Description
mode	string	Yes	Active encryption mode.
jwks_uri	string	Yes	Relative path to the JWKS endpoint.
routes	list[string]	No	Additional routes to encrypt in selective mode.

Endpoints

GET /api/v1/security/config

Returns the active encryption mode and target routes. The frontend fetches this once on application boot.

{
  "mode": "selective",
  "jwks_uri": "/api/v1/security/jwks",
  "routes": [
    "/api/v1/auth/login",
    "/api/v1/auth/register"
  ]
}

GET /api/v1/security/jwks

Returns a JWKS document containing the active public encryption key and optional signature keys.

{
  "keys": [
    {
      "kty": "RSA",
      "use": "enc",
      "alg": "RSA-OAEP-256",
      "kid": "payload-enc-2026-v1",
      "n": "u1W5...",
      "e": "AQAB"
    }
  ]
}

The frontend filters for use === "enc" and caches the key by kid.

Field Metadata Flags

DocType fields use standard Pydantic json_schema_extra:

Flag	Value	Meaning
encrypted	True	Field value is encrypted in transit when payload encryption is active.
pii	True	Field is PII; in metadata mode it is treated as encrypted=True.

Example:

ssn: str = Field(json_schema_extra={"encrypted": True})
email: str = Field(json_schema_extra={"pii": True, "encrypted": True})

caution

These flags are supported on DocType models only. Do not add them to Litestar request/response DTOs such as LoginRequest; Litestar's OpenAPI generator raises an error for unknown json_schema_extra keys.

Middleware

Middleware	Priority	Responsibility
RateLimitMiddleware	10	Drop abuse traffic before parsing.
PayloadDecryptionMiddleware	15	Decrypt application/jose payloads before downstream handlers.
CSRFMiddleware	20	Validate CSRF origin/headers.
IdempotencyMiddleware	30	Manage duplicate request keys.
AuthMiddleware	50	Run AuthChain.

Frontend API

encryptPayload(body, url, method, schema?)

Location: libs/framework-m-desk/src/crypto.ts

• Reads the cached security config.
• If mode === "disabled", returns the original body as application/json.
• In selective mode, encrypts if url matches a configured route.
• In metadata mode, encrypts if schema contains fields with encrypted or pii set to True.
• In strict mode, encrypts all mutating methods.

Returns { body: string, contentType: string }.

fetchWithCredentials(url, options, schema?)

Location: libs/framework-m-desk/src/api.ts

The low-level fetch wrapper accepts an optional schema and delegates to encryptPayload when the security policy is already loaded.

frameworkMDataProvider.create/update

Location: libs/framework-m-desk/src/data.ts

Reads meta.schema from Refine mutation params and passes it to fetchWithCredentials so Desk forms automatically encrypt flagged fields.