App encryption

bun add @ave-id/sdk

import { E2EE_RESET_SCOPE, E2EE_SCOPES } from "@ave-id/sdk";

E2EE_SCOPES.SYMMETRIC;  // "e2ee:symmetric"
E2EE_SCOPES.ASYMMETRIC; // "e2ee:asymmetric"
E2EE_RESET_SCOPE;       // "e2ee:reset"

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

const url = buildAuthorizeUrl(
  { clientId, redirectUri },
  { scope: ["openid", "profile", E2EE_SCOPES.ASYMMETRIC], state, nonce, codeChallenge },
);

function mergeAppEncryptionFromUrl(url: string | URL, tokens: TokenResponse): TokenResponse

extractAppKeyFromUrl(url);           // app_key
extractAppPublicKeyFromUrl(url);     // app_public_key
extractAppPrivateKeyFromUrl(url);    // app_private_key
extractAppKeyOldFromUrl(url);        // app_key_old
extractAppPublicKeyOldFromUrl(url);  // app_public_key_old
extractAppPrivateKeyOldFromUrl(url); // app_private_key_old
extractAppKeyResetFromUrl(url);      // true when app_key_reset is set

session.getAppKeyBase64();          // string | undefined
session.getAppPublicKeyBase64();    // string | undefined
session.getAppPrivateKeyBase64();   // string | undefined
await session.setAppKeyBase64(key); // replace, or pass null to clear

function lookupAppPublicKeyByHandle(
  config: { clientId: string; issuer?: string },
  handle: string,
): Promise<AppEncryptionUserRecord>

function lookupAppUserByPublicKey(
  config: { clientId: string; issuer?: string },
  publicKey: string,
): Promise<AppEncryptionUserRecord>

interface AppEncryptionUserRecord {
  clientId: string;
  identityId: string;
  handle: string;
  displayName: string;
  publicKey: string;       // base64 SPKI, P-256
  encryptionMode: string;  // "asymmetric"
}

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

try {
  const recipient = await lookupAppPublicKeyByHandle({ clientId }, "alice");
} catch (error) {
  if (error instanceof AppEncryptionLookupError && error.status === 404) {
    showInvite("alice");
  }
}

function encryptForAppUser(
  payload: string | Uint8Array | ArrayBuffer,
  recipientPublicKey: string,
): Promise<AppEncryptedPayload>

interface AppEncryptedPayload {
  encryptedPayload: string; // base64 of IV followed by ciphertext
  senderPublicKey: string;  // base64 SPKI of the ephemeral key
}

function encryptForAppHandle(
  payload: string | Uint8Array | ArrayBuffer,
  params: { clientId: string; handle: string; issuer?: string },
): Promise<AppEncryptedPayload>

function decryptFromAppSender(
  envelope: AppEncryptedPayload,
  recipientPrivateKeyBase64: string,
): Promise<ArrayBuffer>

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

// Sender
const envelope = await encryptForAppHandle(JSON.stringify({ roomKey }), { clientId, handle: "alice" });
await api.sendInvite({ to: "alice", envelope });

// Recipient
const plaintext = await decryptFromAppSender(envelope, session.getAppPrivateKeyBase64()!);
const { roomKey } = JSON.parse(new TextDecoder().decode(plaintext));