KynetraDB security
What is enforced, and where it stops.
This page describes the security controls in KynetraDB’s engine as of its main branch, how to reach each one, and what each leaves to you. It is an engineering overview, not an audit result. KynetraDB holds no security certification, and none of its compliance features make a deployment compliant.
- Certifications
- None held or claimed.
- Passkeys
- Not implemented. MFA is TOTP, for platform accounts.
- Encryption at rest
- Not provided by the server. Use volume encryption.
Posture
Read this first
- KynetraDB is in private preview. The controls below are those in the engine’s main branch at commit
5f8ea3af. They can change. - No certification or third-party audit is claimed. The words “tamper-evident” and “fail-closed” on this page describe code behaviour, not an assessment.
- The compliance primitives are record-keeping and workflow tools. Meeting a law remains your responsibility, and the server’s own discovery document lists the operator duties it does not cover.
- Where a control has a gap, the gap is stated next to it, together with what to do about it.
Authentication
Who is calling
Two populations authenticate. Platform users run the instance. Project end-users belong to a tenant and are signed with that project’s own secret.
| Mechanism | What it does | State | Operating note |
|---|---|---|---|
| Password sign-in | Passwords are hashed with bcrypt at cost 12. Each project has its own pool of end-users, its own signing secret and its own tokens, reached with the project’s publishable key under /auth/v1. A successful sign-in returns an HS256-signed access token and a refresh token. Access tokens last one hour and refresh tokens thirty days by default; both lifetimes are settings. | Available in preview | Passwords need at least 8 characters. There is no strength check, no breached-password check and no per-account lockout, so repeated attempts are limited by the per-address request budget. The first account in a pool becomes its administrator and later accounts become editors. Create your own first account with the service key before the publishable key is public. No setting closes project sign-up; restrict the project sign-up routes at your proxy if you need to. |
| Refresh tokens and sign-out | Refresh tokens are opaque, stored as hashes and rotated on use. A used or revoked token is refused. Sign-out revokes the user’s refresh tokens. | Beta | Access tokens are stateless, so an access token that was already issued stays valid until it expires. |
| One-time codes and magic links | A six-digit code or a link, valid for fifteen minutes, single use and stored hashed, for passwordless sign-in, email confirmation and recovery. | Beta | Needs KYNETRA_OTP_HASH_PEPPERS, or code requests fail. Email goes over SMTP without TLS, so point it at a relay on the same host or inside a private network. With no SMTP host, the message, code included, is written to the server log instead. |
| Password recovery | A recovery message with a one-time link. | Beta | Subject to the same pepper and SMTP notes as one-time codes. |
| Anonymous sign-in | Creates a viewer account with no password so a visitor can hold a session. | Beta | Each anonymous sign-in leaves a stored account behind. They are not purged automatically in this build. |
| OAuth sign-in | Redirect and callback flows for Google and GitHub, enabled by supplying client credentials in settings. | Beta | Two providers. Verify the whole flow in your own environment before relying on it. |
| API keys | Per project, a publishable key and a service key; the service key carries administrator power inside its project and is stored as a hash. The deployment also has a global key for operators, at least 32 bytes on a remote bind. | Available in preview | Keys have no names, scopes or expiry. Service and global keys bypass row-level policies, so keep them on servers. Rotation replaces everything at once, with no overlap window. |
| Managed API tokens | Organisation-owned bearer tokens stored as SHA-256 hashes, shown once, with expiry and rotation. | Available in preview | The capability set is closed. In this build these tokens administer tokens and grant no access to data. |
| Passkeys (WebAuthn) | The server has no passkey routes and no WebAuthn library. | Roadmap | The admin console shows passkey controls that do not work in this build. SMS and phone sign-in are not available either. |
Multi-factor authentication
TOTP for platform accounts
Time-based one-time passwords (RFC 6238) protect platform administrator accounts. Enrolment returns a secret and an authenticator URI, and is activated by proving a first code.
- Recovery codes. Activation issues ten single-use recovery codes, stored as hashes.
- Challenge at sign-in. When a second factor is owed, the password step returns a challenge instead of tokens, and no session exists until the code is verified.
- Lockout. Repeated wrong codes lock the factor for a period.
- Organisation mandate. An organisation owner or administrator can require every member to hold an active second factor and can bound how old that proof may be. It applies to platform accounts that are members of the organisation.
- Step-up for sensitive actions. Changing a role, resetting a password and resetting a second factor accept a short-lived, single-use step-up token, minted by proving a fresh code, when the acting administrator has a second factor.
- Enforcement is opt-in.
KYNETRA_REQUIRE_2FA_ADMINmakes administrators enrol at their next sign-in.
Limits
Project end-user accounts have no second factor in this build; they use passwords, one-time codes, anonymous sign-in or OAuth. Step-up does not apply to an administrator who never enrolled. A lost factor is cleared by an administrator, and the reset is audited. Passkeys and phone-based factors are not available. Capability pages: TOTP, organisation mandate.
Keys and rotation
Which secrets you can rotate today
Two kinds of secret have an operator procedure. Others are fixed, or have rotation code that no route or command calls.
| Secret | How it is held and rotated | Operating note | State |
|---|---|---|---|
| Token signing secret | kynetra rotate auth-secret --start stages a new secret as pending. Restart the server so it accepts both. kynetra rotate auth-secret --promote makes the new secret primary, then restart again. | The command works on the local data directory and writes no audit entry. Promotion ends the old secret at once: tokens issued before it stop verifying, so users sign in again. Do it in a planned window. | Beta |
| Project keys and project token secret | Rotate through the admin API for the project. One call replaces the publishable key, the service key and the project’s token-signing secret. The new service key is shown once. | There is no overlap window. Every end-user token of that project stops working and every client needs the new publishable key. Plan it as a maintenance event. | Available in preview |
| Stored cloud-provider credentials | Sealed with AES-256-GCM under a dedicated vault key. By default the key is generated once and stored in the data store; KYNETRA_VAULT_KEY supplies it from outside. | Rotating the token signing secret does not touch the vault key. If the key sits in the data store, whoever can read the whole data directory can open the credentials. Supply it from your secret store if that matters to you. | Available in preview |
| Audit-log HMAC key | Supplied with KYNETRA_AUDIT_HMAC_KEY, or generated and stored. | The chain can verify a history that spans several key epochs, but no route or command rotates the key in this build. Treat it as fixed. | Roadmap |
| Log encryption keys | Key ring, online rotation and revocation exist as engine library code. | The server has no setting that turns log encryption on. | Roadmap |
| Other secrets | A phased rotation state machine (overlap, rollout, verify, revoke, evidence) exists as a library. | No route, command or schedule drives it against a live secret. | Roadmap |
| TLS certificates | Not managed by the server. Your proxy or platform terminates TLS. | Replication between nodes can use mutual TLS from a configured bundle. | Outside the server |
The signing secret, like other secrets the server needs, is a record in the data store. Protect the data directory, its backups and any replica as you would protect the secrets themselves. Key creation and rotation are not written to the tamper-evident audit log in this build.
Access control
Four layers, checked in this order
Built-in roles are Administrator, Editor and Viewer, plus a platform super-administrator. Project credentials are a publishable key, a service key and end-user tokens.
The caller is identified once, then checked against rate limits by class and by project. Anonymous access is refused unless the instance is deliberately open for local development.
A project can define named roles from a fixed catalogue of permissions, such as data.read, data.mutate, schema.manage and search.execute, and bind users to them, with an optional expiry. Built-in roles and collection rules stay the ceiling: the overlay can restrict, never widen. It applies to requests that carry a user identity inside a project; service keys and the global key are not narrowed.
Each collection lists the roles allowed to list, view, create, update and delete its records, and which roles may see each field. A new collection is readable by every role, the publishable key included, until you restrict list and view. Field visibility is applied on /rest/v1, KynQL and typed views; the record routes under /v1/collections apply the role lists but do not remove hidden fields.
Policies attach to select, insert, update or delete on a collection and are evaluated per row. Several policies for one operation are combined with OR. A policy that fails to parse or evaluate denies. If a collection has no policy for an operation, row-level checks do not apply and the collection rules decide. Enforced on /rest/v1, KynQL at /v1/query, typed views and realtime subscriptions; the /v1/collections record routes apply the role lists alone.
A row-level policy
Policies are written in a small expression language with no eval and no arbitrary code. It offers field references, string, number, boolean and null literals, comparisons, &&,||, !, and the caller’s auth.uid(), auth.role(),auth.email() and auth.purpose().
auth.uid() == owner_idThat expression lets a signed-in user act on rows whose owner_id equals their own id. The same policies filter rows for POST /v1/query and for WebSocket change events, per subscriber.
Limits
Service credentials, including the global key and per-project service keys, are not subject to row-level policies, so keep them on servers and out of browsers and apps. The raw /v1 routes (entities, filter, search, vector, hybrid and transactions) accept service credentials alone and apply no row-level policy. Serve end-user traffic through /rest/v1, KynQL, typed views or the WebSocket, which apply policies. Policies run row by row after candidate rows are selected, so they restrict results and do not make a query cheaper.
Tenancy separation
Project-scoped where enforced, with a shared process
Project data is namespaced by a per-project prefix, and project-scoped credentials are confined to their own project’s namespace. A project credential is not treated as holding platform authority, even if it holds its own project’s signing secret. Platform accounts and the global key are operator credentials with deployment-wide authority: they span projects by design. The Multi-tenancy page covers both layers, lifecycle, export and purge.
- A per-project request budget bounds a noisy tenant. Per-project entity and request overrides exist in the data model, but no API in this build sets them.
- Tenants share one process, one log, one CPU and memory budget and one failure domain. There are no per-tenant encryption keys.
- A tenant export leaves out credential material by design, so it cannot restore sessions. Some internal state is not exported, so read the export manifest before you treat it as a backup.
- Platform accounts and the global key are operator credentials with deployment-wide authority. Issue them only to operators, and keep operator endpoints off the public internet.
Capability page: Multi-tenancy
Network and start-up
Defaults, and what you must supply
- TLS is yours to terminate. The server listens on plain HTTP. For a non-loopback bind it sends the HTTP Strict Transport Security header by default, on the assumption that a proxy or platform in front serves HTTPS.
- A remote bind refuses to start without credentials. It needs
KYNETRA_API_KEYof at least 32 bytes, or an existing user, unless you set an explicit insecure override intended for isolated test environments. - Loopback is open for development. On a loopback bind with no key the API accepts unauthenticated calls. If a reverse proxy on the same host fronts a loopback bind, set
KYNETRA_REQUIRE_AUTH. - Keep the platform plane private. Browsers and apps need the project-facing authentication, table, storage and realtime surfaces, served under
/auth/v1,/rest/v1,/storage/v1and/realtime/v1. Administration, platform sign-in and sign-up, operator feeds and tooling endpoints are for operators: put them on a private network or behind an allow-list at your proxy. - Rate limits apply by class (authentication, administration, writes, everything else) and by project. The class budgets and the default project budget are settings. Counts live in process memory per node, reset on restart and are not shared with replicas, and a fixed window allows a burst across a boundary of up to twice the budget. Behind a reverse proxy, every client shares the proxy’s address unless you set
KYNETRA_TRUST_PROXY_HEADERS; set it when, and because, your proxy overwrites the client-address headers it forwards. - Cross-origin access is off by default.
KYNETRA_CORS_ORIGINStakes an allow-list; a wildcard is an explicit opt-in. - Responses carry hardening headers (content-type sniffing off, framing denied, no referrer, a restrictive permissions policy). The admin console is served with a per-request content-security-policy nonce.
- Source connections of the migrator do not use TLS for Postgres and Supabase sources. Run it inside a private network or through an SSH tunnel. See Migration.
- The Postgres storage backend uses TLS when the connection URL asks for it. Set that in the URL.
Audit logging
A tamper-evident chain, not a tamper-proof one
Selected administrative and governance actions are appended to a log in which each entry’s hash is a keyed HMAC over the previous hash and the record. Without the key, rewriting the file cannot produce a consistent replacement chain.
- The head of the chain is also stored as a record in the data store and as a small anchor file. Verification recomputes the chain and cross-checks both, so truncating the end of the file is caught.
- An administrator can ask the instance to verify the chain, and list entries, through the admin API.
- Recorded actions include second-factor changes, tenant exports, webhook and residency changes, and policy changes. Coverage is not exhaustive: project key rotation and organisation membership changes are not in the chain, and a few events are recorded under a generic actor name. Do not treat the log as a record of every request.
- Audit writes are not part of the action’s own transaction. If an append fails, the failure is logged and the action proceeds.
- Key epochs let the chain move to a new key without invalidating history. No route runs a rotation yet (see Keys and rotation).
Limits
By default the key lives with the data, so anyone who controls the whole host controls the chain too. Supply the key from your own secret store and copy the log and its anchor to a system the database host cannot modify. Each node keeps its own chain, so there is no merged view across a primary and its replicas. Capability pages: audit log, key epochs.
Erasure, retention and compliance primitives
Tools for records, not a statement of compliance
POST /v1/gdpr/export and DELETE /v1/gdpr/user/:id are administrator routes. Export collects the records that reference a user id; erasure cascades through the same references.
What erasure does
- Deletes the platform account record with that id, records that carry the id in a top-level user_id attribute, files the user uploaded (including their stored bytes), and the agents and agent runs they own.
- Refuses, and records the refusal, when an active legal hold covers the user. There is no route to place or release a hold in this build.
- Writes a summary audit record with the counts.
What it does not do
- It matches by id in a top-level field. Data that links to a person through a nested field or an email address is not found, and end-user accounts in a project pool are not matched by the account step.
- A delete is a tombstone in an append-only log. Earlier records stay in retained log segments, backup bundles, replicas and exports already delivered until your retention removes them. Tenant purge compacts the log, and the Multi-tenancy page states plainly that it is not cryptographic erasure.
- Both routes are admin-only. They scan the whole engine, so they are not tenant-scoped; run them as a deliberate operator action. Export is refused above 100,000 entities. The response reports counts of matched records, so check the result before you report an erasure as complete.
DPDP and residency primitives
The instance publishes a discovery document at /.well-known/dpdp that describes the primitives it carries for India’s Digital Personal Data Protection Act. The document itself states the posture as operational readiness, not legal certification, and lists what stays with you. The records are held at deployment level, not per project, and the principal-facing routes need a platform account token, so an application with its own end-users records consent for them through an administrator route.
- Versioned purpose notices.
- Consent receipts that are appended, with withdrawals recorded as new receipts.
- Data-principal rights requests with response deadlines.
- Retention rules with a dry run that previews what would be deleted. Execution over HTTP is switched off in this build and deletes nothing, so removing expired data is yours to carry out.
- A breach register with notification clocks.
- A residency policy and a decision route that answers whether a placement is allowed. The server does not intercept storage, backup or deployment, so enforcement depends on a caller honouring the answer.
What stays with you
A privacy contact and grievance process, identity and guardian verification, processor contracts and a security programme, notifications to a regulator and to people after a breach, legal holds and the enforcement of retention, and any duties that apply if you are designated a significant data fiduciary. No primitive on this page makes a deployment compliant with the DPDP Act, the GDPR or any other law. Capability pages: export and erasure,DPDP records, data residency,policy as code.
Limits in one place
What to plan around
- No certification and no third-party audit.
- No passkeys. TOTP alone, for platform accounts. Project end-users have no second factor.
- No encryption at rest from the server. Encrypt the volume and the backups. Backup bundles can be encrypted and signed by the backup command.
- Secrets, including the token signing secret and the default vault key, are records in the data store.
- TLS is terminated outside the server, and the migrator’s Postgres and Supabase source connections do not use TLS.
- The audit log is tamper-evident under a key that sits with the data unless you supply it.
- Erasure writes tombstones into an append-only log and finds records by a top-level user id attribute. DPDP retention execution is switched off.
- Project sign-up cannot be closed by a setting. Restrict it at your proxy.
- Keep operator endpoints, including platform account creation, reachable only by operators.
- Rate-limit counters are per node and held in memory.
- Tenants share one process and one failure domain. Project data is namespaced by a kind prefix, and platform accounts and the global key are operator credentials with deployment-wide authority.
- Rotation is available for the token signing secret and for project keys. Other secrets are fixed in this build.
Reporting
If you find a vulnerability
Send a private email with the subject “KynetraDB security” tobytes@kynetra.dev. Include what you tested, the version or commit, and steps to reproduce. Please do not post details in public before we have had the chance to respond.
Review the controls against your threat model
In private preview we can walk through the controls above against your own requirements and tell you which ones the current build covers.