Encryption keys

keys encrypts each record with its own data key, wrapped by a regional KMS key, so one call erases a person everywhere, backups included.

keys:
  driver: aws-kms
  key: { us: arn:aws:kms:us-east-1:…, eu: arn:aws:kms:eu-west-1:…, in: arn:aws:kms:ap-south-1:… }
  per-user: true
  rotate: 365d

import { keys } from "mainsdk";

const sealed = await keys.encrypt(note, { owner: user, region: "eu", label: "phi" });
const receipt = await keys.destroyUser(user);   // crypto-erasure

import assert from "node:assert/strict";
import { describe, it } from "node:test";
import { createTestApp } from "@mainsdk/testing";
import { keys } from "mainsdk";

describe("keys", () => {
  it("keys AC3 makes a destroyed user's data unreadable", async () => {
    createTestApp({ yaml: "schema: 1\nproject: prj_test\nkeys:\n  driver: local\n  per-user: true\n" });
    const sealed = await keys.encrypt("note", { owner: "u1", region: "eu", label: "phi" });

    const receipt = await keys.destroyUser("u1");
    assert.equal(receipt.keyId, "user:u1");
    await assert.rejects(keys.decrypt(sealed, { purpose: "test" }), { code: "MAIN-KEYS-0004" });
  });
});

keys:
  driver: aws-kms

Quick start

Point keys at your KMS with one wrapping key per region.

keys:
  driver: aws-kms
  key:
    us: arn:aws:kms:us-east-1:111122223333:alias/pinecart-us
    eu: arn:aws:kms:eu-west-1:111122223333:alias/pinecart-eu
    in: arn:aws:kms:ap-south-1:111122223333:alias/pinecart-in
  per-user: true
  rotate: 365d

import { keys } from "mainsdk";

export async function sealNote(note: string, userId: string) {
  return keys.encrypt(note, { owner: userId, region: "eu", label: "phi" });
  // { v, alg: "AES-256-GCM", ciphertext, wrappedKey, keyId: "user:<id>", kmsKeyId, version, region, label }
}

use mainsdk::prelude::*;
let app = App::test();
Context::new().tenant("tnt_a").user("u1").scope(async {
let sealed = app.keys().for_user("u1").encrypt(b"secret").await?;
assert_eq!(app.keys().for_user("u1").decrypt(&sealed).await?, b"secret");
app.keys().destroy_user("u1").await?;
assert_eq!(app.keys().for_user("u1").decrypt(&sealed).await.unwrap_err().code, ErrorCode::MainKeys0004);
Ok::<_, MainError>(())
}).await?;

owner is the user id as a string. The label is one of personal, sensitive, child or phi.

KMS credentials come from workload identity or the secrets driver, never from code. A cloud driver needs your KMS client: wrap it with its adapter and pass it as the kms option when you create the app (see Swapping drivers).

Configuration

keys:
  driver: aws-kms          # aws-kms | gcp-kms | azure-keyvault | vault-transit | local
  key:                     # one wrapping key per region; a record is wrapped with its owner's region key
    us: arn:aws:kms:us-east-1:…
    eu: arn:aws:kms:eu-west-1:…
    in: arn:aws:kms:ap-south-1:…
  per-user: true           # a key per person, for crypto-erasure
  per-tenant: false        # a key per tenant; destroyed when the tenant is erased
  rotate: 365d             # automatic rotation period

With the local driver, key may name a secret that holds the master key. Without it, the master key is random per process and sealed data cannot be read after a restart, so set it for anything you keep.

Overlays by environment

Use the local driver while you develop, and a real KMS in production. mainsdk check refuses the local driver in production.

keys:
  driver: local

keys:
  driver: aws-kms

What you get

Every record or file gets its own data key, and that data key is wrapped by a key that lives in your cloud KMS and never leaves it. There is one wrapping key per region, and with per-user keys each person has their own key, so deleting it erases them everywhere. Most of the time you don't call keys directly: db fields with encrypt: true, files and crypto use it for you. Reach for it when you seal a value yourself or need crypto-erasure.

Tenant keys

With per-tenant: true, each tenant has its own key under the region key, like a person's key.

Build keys yourself

The app's keys is built from main.yaml. Tests and tooling can build one directly.

import { Keys, MemoryKeyStore } from "mainsdk/keys";
import { LocalKms } from "mainsdk/kms";

const keys = new Keys({
  client: new LocalKms("a-test-master-secret-of-16-or-more"),
  regions: { eu: "local:eu" },
  perTenant: true,
  store: new MemoryKeyStore(),
});
await keys.forTenant("tnt_acme", { region: "eu" });

Sign with a key

keys.sign() signs with a key held by your key service, so the private key never reaches your app. A profile picks the algorithm, such as secp256k1 for chains or ed25519. Each use is logged without the key. The local driver signs both profiles; keys.verify checks a signature against the public key sign returns.

import { keys } from "mainsdk";

export async function signOrder(bytes: Uint8Array) {
  const { signature, publicKey } = await keys.sign({ profile: "secp256k1", data: bytes, purpose: "settle-order", keyId: "treasury" });
  return keys.verify({ profile: "secp256k1", publicKey, data: bytes, signature });   // true
}

On a vendor driver that does not sign, keys.sign fails with MAIN-KEYS-0003; use the local driver in development. An unknown profile fails the same way.

Examples

Seal and open a value

keys.decrypt() takes a purpose, which goes to the audit log with the key ID. It returns bytes.

import { auth, keys } from "mainsdk";
import type { Sealed } from "mainsdk/keys";

declare function loadSealedNote(user: string, id: string): Promise<Sealed>;   // your storage

export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
  const session = await auth.require(req);
  const { id } = await params;
  const sealed = await loadSealedNote(session.user, id);   // session.user is the user id

  const plain = await keys.decrypt(sealed, { purpose: "show note to owner" });   // Uint8Array
  return Response.json({ note: new TextDecoder().decode(plain) });
}

Erase a person with one call

With per-user: true, every record sealed for a person uses their own key. Destroying it makes all of it unreadable, including copies in backups that can't be deleted at once.

import { auth, keys, log } from "mainsdk";

export async function DELETE(req: Request, { params }: { params: Promise<{ id: string }> }) {
  await auth.require(req, { role: "admin", fresh: "5m" });
  const { id } = await params;
  const receipt = await keys.destroyUser(id);   // { keyId, scope, destroyedAt, versions }
  log.info("user key destroyed", { userId: id });
  return Response.json(receipt);
}

Reading a destroyed person's data afterwards fails with MAIN-KEYS-0004. For a full erasure across every driver, with a signed record, call privacy.erase(), which uses this for backups.

Rotate keys

With rotate set, a person's or tenant's key gets a new version on its next use once the newest is old enough. Old data still decrypts. To move a value to the new version, keys.rewrap(sealed, { purpose }) wraps its data key again and leaves the ciphertext alone. You can also rotate on demand, for example from a Hono admin API after an incident:

import { Hono } from "hono";
import { auth, keys } from "mainsdk";

const app = new Hono();

app.post("/admin/keys/rotate", async (c) => {
  await auth.require(c.req.raw, { role: "admin", aal: "aal2", fresh: "5m" });
  const report = await keys.rotate();               // or keys.rotate({ keyId: "user:u1" })
  // { rotated: [{ keyId, from, to }], at }
  return c.json(report);
});

export default app;

Look up a person's key

import { keys } from "mainsdk";

export async function userKey(userId: string) {
  return keys.forUser(userId, { region: "eu" });   // a KeyRef, never key material; the first call creates the key
}

Errors and checks

Swapping drivers

Change one line. Your keys.encrypt(), decrypt(), destroyUser() and rotate() calls, and every db and files field that uses them, stay the same.

keys:
  driver: vault-transit   # was aws-kms; point key.us, key.eu and key.in at the new service's keys

A cloud driver also needs a client. The adapters awsKmsDriver, gcpKmsDriver, azureKeyVaultDriver and vaultTransitDriver take the few calls they use from your vendor client, so MainSDK adds no dependency. You pass the result as kms:

import { awsKmsDriver, configure } from "mainsdk";
import type { AwsKmsApi } from "mainsdk/kms";

// Your vendor client (for example `KMSClient` from `@aws-sdk/client-kms`) wrapped in the two calls the driver uses.
declare const aws: AwsKmsApi;

configure({ kms: awsKmsDriver(aws) });

Hardware security modules through PKCS#11 or KMIP, and keys your enterprise customers hold themselves, come in phase 3 as a main.yaml change with the same envelope encryption. When you need a KMS-only feature, keys.raw() returns the KMS client.

Testing

The local driver needs no KMS account. createTestApp makes it the app behind keys.

import assert from "node:assert/strict";
import { describe, it } from "node:test";
import { createTestApp } from "@mainsdk/testing";
import { keys } from "mainsdk";

describe("keys", () => {
  it("keys AC3 makes a destroyed user's data unreadable", async () => {
    createTestApp({ yaml: "schema: 1\nproject: prj_test\nkeys:\n  driver: local\n  per-user: true\n" });
    const sealed = await keys.encrypt("note", { owner: "u1", region: "eu", label: "phi" });

    const receipt = await keys.destroyUser("u1");
    assert.equal(receipt.keyId, "user:u1");
    await assert.rejects(keys.decrypt(sealed, { purpose: "test" }), { code: "MAIN-KEYS-0004" });
  });
});

Security and privacy

• Data keys use AES-256-GCM. MD5, SHA-1, DES and home-made crypto are never used.
• Plaintext data keys are zeroed after use and never logged or cached beyond one call.
• Every wrap, unwrap, rewrap, destroy and rotate is written to the audit log (keys.wrap, keys.use, keys.rewrap, keys.destroy, keys.rotate) with key ID, version and purpose, never the key material.
• One wrapping key per region keeps sealed data tied to its owner's region.

What Cloud adds

On the Fleet plan, rotate or revoke a key everywhere during an incident. Encryption, per-user keys, crypto-erasure and rotation in your app are free. See Free in-app and Cloud.

FAQ

Do I need to call keys myself? Rarely. db fields with encrypt: true, files and crypto use it for you.

Can I read old data after rotation? Yes. Old versions stay usable for decrypt. Call keys.rewrap() to move a value to the new version.

Does erasure reach backups? Yes, when per-user is on: the backup still holds ciphertext, but the key to open it is gone. Keep the key store out of backups of the data it protects, or a copy of a destroyed key survives.

Next

• Data and records: encrypted fields on your models.
• Privacy and data rights: erase a person across every driver.
• Secrets: where KMS credentials come from.