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:
- clients use a standardized resource API shared across repositories;
- Cleave validates resource names, fields, operators, pagination, and request shape;
- bearer tokens and standard JWT claims are verified when authentication is enabled;
- records can be owned by a user and associated with a group;
- Unix-style owner, group, and other permissions decide whether a record can be read, changed, or deleted;
- forbidden collections and service availability rules can reject requests before repository access;
- TLS can be served directly or terminated by deployment infrastructure;
- URI length, body length, and connection timeouts bound request cost.
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:
- an owning user;
- an owning group;
- owner permissions;
- group permissions;
- other permissions.
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:
auth.secret;- repository user names and passwords;
- TLS private keys;
- logging transport certificates or credentials;
- deployment-specific tokens supplied by surrounding infrastructure.
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:
| Responsibility | Examples |
|---|---|
| Identity issuance and sign-in | Auth0, Okta, Keycloak, Amazon Cognito, and Microsoft Entra ID. |
| Web-application firewall | AWS WAF filters web requests using application-layer rules. |
| Secrets management | HashiCorp Vault stores and manages credentials, keys, and other secrets. |
| API gateway | Amazon API Gateway manages API entry points and traffic policies. |
| Network firewall | AWS Network Firewall filters network traffic at the infrastructure boundary. |
| Security monitoring and investigation | Microsoft Sentinel collects security signals for SIEM investigation and response. |
| Endpoint protection | Microsoft Defender for Endpoint protects and monitors host endpoints. |
| Backup and recovery | AWS Backup manages backup policies and recovery points for supported resources. |
| Audit retention | Amazon S3 Object Lock can protect archived audit objects against deletion or overwrite; event collection and retention policy still need to be designed. |
| Rate limiting | Cloudflare rate limiting rules apply traffic thresholds at the edge. |
| Human security review | Internal 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.