How ModelMesa protects your API keys

ModelMesa is in development. This page describes the security design we're building to. Anything marked Planned, Coming in v1, or Later isn't done yet, and we'll update this page as things ship.

Your TypeSafe API key can spend your TypeSafe credits, so it's the most sensitive thing we'll hold for you. Our design goal is simple to state: someone who fully compromises any single part of ModelMesa (the portal, the database, a backup, a laptop, or one staff account) still can't get your key in plain text.

Your key is encrypted before it's stored

When an owner or admin adds your TypeSafe key in the portal, we check that it works with a read-only call to TypeSafe's model list. Then we encrypt it right away and wipe the plain-text copy from memory.

We use envelope encryption:

• Each key gets its own fresh data key, and is encrypted with AES-256-GCM.
• That data key is itself encrypted ("wrapped") by a master key that lives only inside a key management service (KMS), such as OpenBao or Vault transit, or a cloud KMS. The master key never leaves the KMS.
• Our database stores only the encrypted key and the wrapped data key. A copy of the database or a backup is useless without the KMS.
• Each encrypted key is bound to your organization and to its own record, and the KMS uses a separate derived key per organization. An encrypted key can't be moved to another organization and decrypted there.
• Master keys are rotated on a schedule, and stored data keys are re-wrapped to the new version without ever exposing your key.

Who can decrypt, and who can't

The parts of ModelMesa are split so that the one you talk to can't read your key, and the one that can read it has no admin functions. This is enforced by KMS policy, not just by our application code.

No one at ModelMesa has permission to decrypt customer keys in production. The only exception is a sealed emergency procedure that needs two people, is fully audited, and sets off alerts.

Never shown, never logged

• Never displayed back. After you save it, the portal shows only a label, the last four characters, its status, and when it was last checked. There's no "reveal" button, and the API has no way to read it back.
• Kept out of logs. Our logging strips authorization headers and anything that looks like a key, secret, or token. Calls to TypeSafe are never logged with their headers, and traces carry no headers at all.
• Tested. Automated tests push decoy secrets through the whole system and fail if one shows up in logs, traces, metrics, error messages, or the database (other than encrypted).

How the gateway uses your key

• The gateway decrypts your key only when it needs it, and keeps it in memory for a few minutes at most. It's never written to disk.
• It sends your key only to TypeSafe's API, over TLS with strict certificate checks. The upstream address is fixed in our code and can't be changed per customer, so a key can't be redirected somewhere else.
• If the KMS can't be reached, the gateway fails closed. It never falls back to a plain-text copy.
• The gateway runs as a minimal, non-root container with a read-only file system, and it can only make outbound connections to the services it needs.

No design removes every risk. The worst case we plan for is a compromise of the gateway itself, which is why it's locked down, why unusual decryption volume triggers alerts, and why we recommend giving ModelMesa a dedicated TypeSafe key (more on that below).

Your apps use ModelMesa keys, not your TypeSafe key

• Your services call ModelMesa with project-scoped mm_live_ keys. Your TypeSafe key stays with us and never needs to be pasted into another service.
• We store only a keyed hash of each ModelMesa key, and show the key once, when you create it.
• You can revoke or rotate one project's key without touching the others. Revocations take effect within seconds.
• Rate limits and hard monthly token caps per organization and project limit what a leaked key could spend, and spend alerts arrive by email.
• The mm_ prefix makes leaked keys easy for secret scanners to spot.
• IP allowlists, key expiry, and registration with GitHub secret scanning Coming in v1.

Every key action is audited

• Adding, rotating, or deleting your TypeSafe key, creating ModelMesa keys, and changing roles or policies all go into an audit log you can see in the portal.
• Decryptions are recorded too, and the KMS keeps its own separate audit log, with alerts on unusual activity.
• If our staff ever look at your organization for support, they see metadata only, and that access shows up in your audit log.
• Owners and admins sign in with multi-factor authentication.

Your organization's data stays separate

ModelMesa runs on shared infrastructure, with isolation at several layers:

• Your organization is determined only from your signed-in session or your ModelMesa key, never from request parameters.
• Every database row is tagged with its organization, and the database itself enforces row-level security.
• Encryption is bound to your organization, as described above.
• Rate limits are per organization, so a busy neighbor can't crowd you out.
• Automated tests try to reach another organization's data through every endpoint, and fail the build if they succeed.

Rotating and deleting

• Rotate: create a new key in TypeSafe, add it to ModelMesa, and switch your projects over. The old one is disabled, then deleted. Remember to revoke the old key in TypeSafe too, since only TypeSafe can revoke it.
• Delete: we destroy the encrypted key and its wrapped data key and clear it from gateway memory. Backups still hold the encrypted copy, but it can't be decrypted without the master key.
• If your key stops working: we mark it as failing and notify your admins.

Your request content

By default ModelMesa stores request metadata (time, token counts, status, model) but not request bodies. Bodies pass through the gateway in memory on their way to Jev. If you turn on body logging, stored bodies are encrypted per organization and run through PII redaction first.

Our PII guardrails are a data-minimization aid, not a compliance guarantee. At launch, they detect personal data and redact it from stored logs. Masking and blocking before a request reaches Jev come in v1.

What we recommend you do

• Create a dedicated TypeSafe key just for ModelMesa, so you can revoke it without affecting anything else.
• Set project caps and spend alerts when you onboard.
• Never put ModelMesa keys in browser or mobile code. Call ModelMesa from your backend.

What's planned

• An independent penetration test before general availability, then yearly Planned
• A SOC 2 readiness program, followed by SOC 2 Type I and then Type II reports after launch. ModelMesa doesn't have a SOC 2 report today Planned
• A published responsible disclosure policy and security.txt Planned
• Single sign-on (OIDC and SAML) for your company Coming in v1
• Customer-managed encryption keys, dedicated single-tenant deployments, and an EU region Later

Contact

Found a vulnerability, or have a security question? Email [email protected].