Security

People work at varied desks in a sunlit office above a cutaway Cleave pipeline where small utility robots maintain JWT verification, owner/group/other access controls, and a sealed repository vault.

Security by bounded access, not scattered endpoint code.

Cleave treats security as part of the transactional boundary. It does not rely on every application endpoint independently remembering how to parse input, construct queries, apply permissions, validate request size, and log operational behavior.

The security model is intentionally layered:

Structured Query Generation

Cleave generates repository operations through a shared, structured request pipeline. Applications use the same resource API and validation rules instead of implementing query construction independently across dozens or hundreds of endpoints. That common contract reduces opportunities for inconsistent parameter handling, unsafe string concatenation, and repository query injection.

Clients express resource access through a constrained set of filters, operators, sort expressions, relationship requests, and pagination directives. Cleave parses those requests into an internal representation, then repository adapters translate them into repository-specific operations. The shared API defines what clients can request; each adapter handles how its repository executes it.

In Cleave's terminology, the application-facing contract is RIP (Repository Interface Protocol), and the common operations and authorization semantics belong to RAP (Repository Access Protocol). Repository adapters translate those operations into native execution.

Field names, operators, relationships, resource names, request body shape, and protected fields are validated before repository execution. The security principle is simple: unvalidated client input must not become repository syntax.

Prepared statements remain the correct implementation strategy inside Cleave. They provide important protections for literal values and can help the database optimize repeated query shapes. Their role changes, though. Instead of compensating for SQL being assembled across many application endpoints, prepared statements become the final safeguard inside a much more controlled pipeline.

A shared request contract makes validation and operation generation easier to review and apply consistently across applications. The security benefit comes from those common rules and controlled repository adapters, independent of how many resource URLs the API exposes.

Record-Level ACLs

Cleave's ACL model follows a Unix-like permissions idea.

Records can carry:

Users belong to groups. A request authenticated as a user can be evaluated against the record owner, the record group, or the record's other permissions. The permission digits work like file permissions: read, write, and delete capability are encoded into the record permission fields and checked before the repository operation is allowed to proceed.

This lets one collection contain records with different access posture. An internal administrative record, a customer-owned record, and a shared group record do not need to depend on separate tables merely to express basic ownership.

See Access Control for the current modes and method permission sets.

Bearer Tokens

Cleave does not issue identity. It expects identity to come from a specialist identity provider or authentication service.

When authentication is enabled, clients send:

Authorization: Bearer <jwt>

Cleave verifies the token and extracts the claims needed for the configured access-control mode.

JWT authentication validates the signed token and standard registered claims before the request reaches repository processing. That includes issued-at, expiration, not-before, issuer, and audience checks: iat, exp, nbf, iss, and aud.

Once the token has been authenticated, Cleave applies its own authorization model, including roles, ACLs, ownership rules, group membership, and Unix-style record-level permissions. Authentication establishes who the request is from and whether the token is valid. Cleave authorization decides what that request can do.

Identity providers such as Auth0, Okta, Keycloak, Amazon Cognito, Microsoft Entra ID, or an internal OAuth/OIDC service remain responsible for issuing tokens, login flows, password management, MFA, account recovery, and token refresh.

See JWT Authentication for the concrete token requirements.

Trusted Backends And Application Identities

An HTML frontend, SPA, or MPA can send its requests to an application backend while Cleave performs the repository transactions behind it. The frontend does not need to receive Cleave credentials or implement its record-permission model.

The backend can call Cleave using a dedicated application identity. Record ownership and ACLs can allow that identity to update or delete records while other identities have read-only access or no access. The backend keeps its credentials private and decides which actions each application user may invoke; Cleave enforces the permissions of the identity presented to it.

Alternatively, a trusted backend can own end-user authorization while Cleave runs with record ACLs disabled (auth.control_level = "none"). JWT verification can still be enabled independently. In this arrangement, restrict Cleave access to the backend: disabling record ACLs does not itself limit callers to one application identity.

If Cleave must enforce permissions for each end user, the backend should forward that user's verified identity rather than presenting every request as the same application account.

Forbidden Collections

Cleave can reject configured collections before repository execution through interface.collections.forbidden.

This is useful when a repository contains tables or collections that should never be exposed through a given Cleave service instance. It is a coarse boundary, not a substitute for record-level ACLs. Use it to remove whole resources from the public contract of that service.

Service Availability

interface.service_available limits service access by client IP.

By default, this is the peer address of the actual TCP connection, not an IP claimed in an HTTP header. Spoofing that address is substantially harder than supplying a forged forwarding header because the caller must establish a working TCP connection. The allow-list restricts network access; JWT verification can additionally identify the calling application or user.

When the list is empty, Cleave does not apply an IP allow-list. When the list is populated, only matching client IP addresses are accepted and other addresses are denied. In other words, the current behavior is allow-list based. It can block traffic from addresses outside the list, but it is not a general-purpose blacklist mechanism.

For example, allow only local IPv4 callers:

[interface]
service_available = ["127.0.0.1"]

This suits an internal service called by a backend or reverse proxy on the same host. For callers on other hosts, list the specific backend or proxy IP addresses that should reach Cleave. Use the addresses Cleave actually sees; a separate container is not a loopback caller merely because it runs on the same machine.

When Cleave sits behind a proxy, forwarded client IP headers are trusted only when interface.use_forwarded_headers = true and the TCP peer is listed in interface.trusted_proxy_ips.

Leave forwarded headers disabled when the allow-list is intended to admit the proxy itself. When trusted forwarding is enabled, the allow-list applies to the resolved client address instead, so configure it for those clients.

TLS And Reverse Proxies

Cleave can serve TLS directly:

tls_enabled = true
tls_cert_path = "/etc/cleave/tls/server.crt"
tls_key_path = "/etc/cleave/tls/server.key"

When tls_enabled = false, Cleave serves plain HTTP and should sit behind infrastructure that provides the required transport security.

Direct TLS can be useful for simple deployments, internal services, and environments where Cleave owns the listener boundary. In larger deployments, TLS is often terminated at a load balancer, ingress controller, API gateway, or reverse proxy. That can centralize certificate renewal, cipher policy, HTTP/2 or HTTP/3 support, request buffering, rate limiting, and edge observability.

There is also a performance and operations tradeoff. Terminating TLS in front of Cleave can move handshake work, certificate rotation, and edge policy out of the transactional service. Serving TLS directly keeps the deployment smaller, but places certificate management and TLS CPU cost on the Cleave instance.

CORS

Cleave can allow browser access from specific frontend servers rather than every origin. Configure each allowed origin with its scheme, hostname or IP address, and port when nonstandard:

[http]
cors_allow_origins = ["https://app.example.com", "https://admin.example.com"]

These entries identify where the frontend pages are hosted, not the IP addresses of the people using them. A frontend hosted on an IP address could use an origin such as http://192.168.1.20:8080. Origins match exactly; omit paths and trailing slashes.

For an allowed requesting origin, Cleave returns that origin in the response:

Access-Control-Allow-Origin: https://app.example.com

Multiple origins belong in the configuration list; the response header contains one matching origin, not a comma-separated list. An empty configuration emits no CORS origin header. Use cors_allow_origins = ["*"] when any browser origin should be allowed, such as a public API or local demo, rather than treating the wildcard as the only option.

CORS controls browser cross-origin access. It does not authenticate a caller: non-browser clients can supply their own Origin header or omit it. Bearer-token verification, ACLs, network policy, and repository permissions still carry the access-control responsibility.

Secrets

Production Cleave deployments should treat these values as secrets:

Do not commit production secrets into application repositories or public examples. Prefer the deployment platform's secret store, environment-specific configuration packaging, file permissions, and key rotation process.

The example configuration is a teaching artifact. Its placeholder values are not production policy.

Repository Least Privilege

Cleave should connect to the repository with credentials scoped to the resources that the service is meant to expose.

For a production service, avoid using an administrator or migration account for normal runtime traffic. Prefer a dedicated runtime account with only the database, schema, tables, collections, and operations required by that Cleave instance.

This matters because Cleave is intentionally close to operational data. If the service configuration, network boundary, or application token policy is wrong, least-privilege repository credentials reduce the blast radius.

Size Limits And Timeouts

Cleave keeps transactional request shape bounded.

The URI limit prevents unbounded query strings:

req_uri_maxlength = 500

The body limit prevents oversized write payloads:

req_body_maxlength = 8000

Write methods must include Content-Length, and the value must fit within the configured body limit. GET requests must not include request content.

Connection timeouts provide another operational boundary:

connection_timeout = 5
graceful_shutdown_timeout = 2

These limits do not replace repository indexing, query planning, rate limiting, reverse proxy controls, or deployment-level protections. They give each Cleave instance a clear default posture for bounded transactional work.

Logging And Metrics Sensitivity

Logs are operational data and may contain sensitive context.

debug should be treated as a development level because it can expose critical or sensitive implementation details. info can include user-specific or request-specific sensitive information, depending on the enabled logging path.

For production, prefer notice or stricter unless additional operational detail is needed. Enable counters and latency reporting separately through [metrics]; they do not require increasing operational log verbosity. Protect both reporting destinations.

See Logging and Metrics for level behavior.

Abuse Controls

Cleave provides resource validation, request-size limits, URI-size limits, authorization, and bounded method handling. It is not a full edge-abuse prevention layer.

Public deployments should still use the surrounding infrastructure for rate limiting, request throttling, WAF policy, DDoS protection, bot controls, IP reputation, request buffering, and centralized TLS policy.

Those controls are especially important when Cleave is exposed directly to browsers, mobile applications, partner integrations, or public networks.

Backups And Audit Policy

Repository backup, retention, point-in-time recovery, encryption at rest, audit trails, and regulatory retention policy remain repository and platform responsibilities.

Cleave can log request and metric activity, but that is not the same thing as a complete audit system. Production systems should decide where durable audit events live, how long they are retained, who can read them, and how they are correlated with identity-provider, gateway, repository, and application logs.

Security Boundary

Cleave is not a complete security product. It does not replace an identity provider, web-application firewall, secrets manager, API gateway, network firewall, SIEM, endpoint protection platform, backup system, audit archive, rate limiter, or human security review.

These responsibilities belong to specialist products and security teams:

ResponsibilityExamples
Identity issuance and sign-inAuth0, Okta, Keycloak, Amazon Cognito, and Microsoft Entra ID.
Web-application firewallAWS WAF filters web requests using application-layer rules.
Secrets managementHashiCorp Vault stores and manages credentials, keys, and other secrets.
API gatewayAmazon API Gateway manages API entry points and traffic policies.
Network firewallAWS Network Firewall filters network traffic at the infrastructure boundary.
Security monitoring and investigationMicrosoft Sentinel collects security signals for SIEM investigation and response.
Endpoint protectionMicrosoft Defender for Endpoint protects and monitors host endpoints.
Backup and recoveryAWS Backup manages backup policies and recovery points for supported resources.
Audit retentionAmazon S3 Object Lock can protect archived audit objects against deletion or overwrite; event collection and retention policy still need to be designed.
Rate limitingCloudflare rate limiting rules apply traffic thresholds at the edge.
Human security reviewInternal security engineers and independent penetration testers assess application logic, configuration, and deployment.

These are examples of the surrounding responsibilities, not a required vendor stack.

Its security value is narrower and more concrete: Cleave centralizes the repetitive transactional path, validates structured resource requests, applies configured authorization, restricts exposed collections, bounds request sizes, and keeps repository operation generation inside one audited service.