End-to-end encryption

Ave can hand your app an encryption key for each user as part of sign-in. The key is created and unwrapped on the user’s device, delivered to your client code in the callback URL fragment, and stored on Ave only in a form encrypted by the user’s master key. Your backend stores ciphertext and never needs the key.

Choose a mode

Request one encryption scope per sign-in. Nothing needs to be enabled in the developer portal.

Scope	Key material	Use it for
`e2ee:symmetric`	AES-256 `app_key`	Data only the user reads: notes, files, settings, backups
`e2ee:asymmetric`	P-256 `app_public_key` and `app_private_key`	Data users send to each other: messages, shared documents, invitations
`e2ee:reset`	Modifier	Rotating keys; combine with a mode scope

e2ee:pqc:kyber and e2ee:pqc:dilithium are reserved names and return unsupported_encryption_mode. Asking for both modes in one request returns invalid_scope. Signing in again reuses the existing keys, so request the same mode every time.

Request the scope

import { startPkceLogin } from "@ave-id/sdk/client";

await startPkceLogin({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  scope: "openid profile offline_access e2ee:asymmetric",
});

import { startAveAuth } from "@ave-id/embed";

await startAveAuth({
  clientId: "YOUR_CLIENT_ID",
  redirectUri: "https://yourapp.com/callback",
  scope: "openid profile offline_access e2ee:asymmetric",
  onTokens: (tokens) => session.setTokensFromResponse(tokens),
});

import { buildAuthorizeUrl } from "@ave-id/sdk";

const url = buildAuthorizeUrl(
  { clientId: "YOUR_CLIENT_ID", redirectUri: "https://yourapp.com/callback" },
  {
    scope: ["openid", "profile", "offline_access", "e2ee:asymmetric"],
    state,
    nonce,
    codeChallenge,
    codeChallengeMethod: "S256",
  },
);

If the user’s master key is not available on the device, Ave asks them to restore it with a passkey, recovery code, or another signed-in device before it returns to your app.

Receive the keys

After consent, Ave redirects with the code in the query string and the keys in the fragment:

Mode	Fragment parameters
Symmetric	`app_key`
Asymmetric	`app_public_key`, `app_private_key`
Rotation	The new keys, plus `app_key_old`, `app_public_key_old`, `app_private_key_old`, and `app_key_reset=true`

The keys are never included in the token endpoint response. The SDK reads them from the fragment and merges them into the token response for you:

completeOAuthCallback(session, options) from @ave-id/sdk/client exchanges the code, merges the keys, removes them from the address bar, and saves them in the session.
onTokens in @ave-id/embed receives the merged token response directly.
mergeAppEncryptionFromUrl(url, tokens) from @ave-id/sdk merges them into a token response you exchanged yourself. Call stripSensitiveFragmentParams() afterwards.

Read the keys from AveSession:

await session.hydrate();

session.getAppKeyBase64();        // e2ee:symmetric
session.getAppPublicKeyBase64();  // e2ee:asymmetric
session.getAppPrivateKeyBase64(); // e2ee:asymmetric

AveSession keeps the keys in the storage adapter you give it, next to the tokens. createLocalStorageAdapter() persists them across reloads. Because Ave delivers the same key on every sign-in, createMemoryStorage() or your own AveSessionStorage implementation work too if you would rather not keep keys at rest in the browser.

Symmetric mode

Import the key as an AES-GCM key and use a fresh 12-byte IV for every encryption.

const raw = Uint8Array.from(atob(session.getAppKeyBase64()!), (c) => c.charCodeAt(0));
const key = await crypto.subtle.importKey("raw", raw, "AES-GCM", false, ["encrypt", "decrypt"]);

async function encrypt(plaintext: string) {
  const iv = crypto.getRandomValues(new Uint8Array(12));
  const data = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, new TextEncoder().encode(plaintext));
  return { iv, data };
}

async function decrypt(iv: Uint8Array, data: ArrayBuffer) {
  const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, data);
  return new TextDecoder().decode(plaintext);
}

Asymmetric mode

Each user gets a P-256 keypair for your app. Ave stores the public key in plaintext so other users of your app can look it up, and stores the private key wrapped by the user’s master key.

Encrypt for another user

encryptForAppHandle looks up the recipient’s public key for your app and encrypts with an ephemeral ECDH key and AES-GCM. No round trip through the recipient is needed.

import { encryptForAppHandle } from "@ave-id/sdk";

const envelope = await encryptForAppHandle("the room key", {
  clientId: "YOUR_CLIENT_ID",
  handle: "alice",
});

// { encryptedPayload, senderPublicKey } — store or send both

If you already have the recipient’s public key, for example from your own user table, call encryptForAppUser(payload, publicKey) instead.

Decrypt

The recipient decrypts with the private key from their session:

import { decryptFromAppSender } from "@ave-id/sdk";

const plaintext = await decryptFromAppSender(envelope, session.getAppPrivateKeyBase64()!);
new TextDecoder().decode(plaintext);

Look up users

import { AppEncryptionLookupError, lookupAppPublicKeyByHandle, lookupAppUserByPublicKey } from "@ave-id/sdk";

try {
  const alice = await lookupAppPublicKeyByHandle({ clientId: "YOUR_CLIENT_ID" }, "alice");
  // alice.identityId, alice.handle, alice.displayName, alice.publicKey
} catch (error) {
  if (error instanceof AppEncryptionLookupError && error.status === 404) {
    // Alice has not signed in to this app with e2ee:asymmetric yet
  }
}

const sender = await lookupAppUserByPublicKey({ clientId: "YOUR_CLIENT_ID" }, envelope.senderPublicKey);

A lookup returns 404 when the handle does not exist, the identity has never authorized your app, or it has no asymmetric key yet. Show an invitation instead of generating keys on the user’s behalf. Lookups are scoped to a client ID, so a user’s public key for your app is unrelated to their keys for any other app. Store each user’s public key on your own user record as well. Lookups by handle follow handle changes, but your records should point at the identityId.

Rotate keys

Add e2ee:reset to a sign-in to replace the user’s keys for your app. The consent screen warns the user that their previous keys will be replaced.

scope=openid profile e2ee:symmetric e2ee:reset

The callback includes the new keys, the previous keys as *_old parameters, and app_key_reset=true. Decrypt existing data with the old key, re-encrypt it with the new key, then discard the old key. Only request e2ee:reset from an explicit user action; a normal sign-in never rotates keys.

Identities and devices

Keys belong to one app and one identity. Switching identity means switching key context; keep each identity’s ciphertext separate.
The same identity gets the same keys on every device where its Ave account is unlocked.
Different apps get different keys. Another app cannot request yours.
When a user disconnects your app in Ave, its wrapped keys for that identity are deleted and the next sign-in provisions new ones. If your data must survive that, keep an encrypted backup of the key under your own recovery scheme.

Failure modes

Symptom	Cause
No key in the token response	The sign-in did not request an encryption scope, or you exchanged the code without merging the fragment
`atob` throws	The key was read from `URLSearchParams` without restoring `+`; use the SDK helpers or `normalizeAppKeyBase64`
Decryption fails after sign-in	The user signed in with a different identity, the keys were rotated, or the user disconnected and reconnected your app
Key visible in history or logs	The fragment was not stripped after reading

See the integration checklist, the encryption model, and the SDK reference.

Encryption

Sign-in

Building on Ave

Frameworks

End-to-end encryption

Choose a mode

Request the scope

Receive the keys

Symmetric mode

Asymmetric mode

Encrypt for another user

Decrypt

Look up users

Rotate keys

Identities and devices

Failure modes

​Choose a mode

​Request the scope

​Receive the keys

​Symmetric mode

​Asymmetric mode

​Encrypt for another user

​Decrypt

​Look up users

​Rotate keys

​Identities and devices

​Failure modes

Choose a mode

Request the scope

Receive the keys

Symmetric mode

Asymmetric mode

Encrypt for another user

Decrypt

Look up users

Rotate keys

Identities and devices

Failure modes