agmsg-cloud 0.0.1 → 0.1.0-rc.4

package/dist/src/vault-container.js

@@ -0,0 +1,115 @@
+// The account vault's plaintext: every team's handoff bundle in one container.
+//
+// The vault holds one account's key material, and the OSS side exports one team
+// at a time (`key.sh handoff` refuses more than one team), so something has to
+// hold the set. That something is defined here, in the cloud CLI, because the
+// vault is a cloud feature and no OSS counterpart is being created.
+//
+// The format is documented in docs/design/vault-container-v1.md. If you change
+// anything in this file, change that too — a format whose only description is
+// its parser is a format nobody can implement against.
+/** Identifies the container itself, so a reader that cannot read it says so. */
+export const CONTAINER_FORMAT = 'agmsg-cloud-vault-container';
+/** Bumped when the shape changes in a way an older reader must refuse. */
+export const CONTAINER_VERSION = 1;
+export function emptyContainer() {
+    return { format: CONTAINER_FORMAT, version: CONTAINER_VERSION, teams: [] };
+}
+export class UnreadableContainerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnreadableContainerError';
+    }
+}
+// Refuse rather than guess. A container from a future version may put different
+// meaning on the same field names, and a reader that takes the fields it
+// recognises would restore a bundle that is not what the vault holds. The
+// recovery key would be correct and the restore would be wrong, which is the
+// worst pair of properties available.
+export function parseContainer(plaintext) {
+    let value;
+    try {
+        value = JSON.parse(plaintext.toString('utf8'));
+    }
+    catch {
+        throw new UnreadableContainerError('vault content is not the expected container (not JSON)');
+    }
+    if (typeof value !== 'object' || value === null) {
+        throw new UnreadableContainerError('vault content is not the expected container');
+    }
+    const c = value;
+    if (c.format !== CONTAINER_FORMAT) {
+        throw new UnreadableContainerError(`vault content declares format '${String(c.format)}', which this version cannot read`);
+    }
+    if (c.version !== CONTAINER_VERSION) {
+        throw new UnreadableContainerError(`vault content is container version ${String(c.version)}; this version reads ` +
+            `${CONTAINER_VERSION}. Upgrade agmsg-cloud rather than restoring from it.`);
+    }
+    if (!Array.isArray(c.teams) || !c.teams.every(isTeamEntry)) {
+        throw new UnreadableContainerError('vault content has no readable team entries');
+    }
+    return { format: CONTAINER_FORMAT, version: CONTAINER_VERSION, teams: c.teams };
+}
+function isTeamEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const e = value;
+    return (typeof e.server_instance_id === 'string' &&
+        e.server_instance_id !== '' &&
+        typeof e.team_id === 'string' &&
+        e.team_id !== '' &&
+        Array.isArray(e.key_ids) &&
+        e.key_ids.every((k) => typeof k === 'string' && k !== '') &&
+        typeof e.bundle === 'string' &&
+        e.bundle !== '');
+}
+// The identity of an entry is the PAIR. A team id alone is not unique across
+// data-plane instances — it is minted by the client, and two instances can
+// legitimately carry the same one — so keying by it makes the second instance's
+// backup overwrite the first's, silently, at the moment the person is trying to
+// protect it.
+function identityOf(entry) {
+    return `${entry.server_instance_id}\u0000${entry.team_id}`;
+}
+// Add or replace ONE team, leaving every other entry byte-for-byte as it was.
+//
+// Not a stylistic choice: a vault gets re-wrapped on every put, and if adding a
+// team changed what the other entries bind, every backup would put the rest of
+// the account's key material at risk of being written wrong. Each entry carries
+// its own binding and nothing derived from its neighbours — no index, no count,
+// no digest over the set — so touching one cannot invalidate another.
+export function upsertTeam(container, entry) {
+    const key = identityOf(entry);
+    const others = container.teams.filter((t) => identityOf(t) !== key);
+    // Sorted by team id so the same set of teams always serialises identically,
+    // whatever order they were added in. Two machines backing up the same account
+    // then produce the same plaintext rather than a diff that is pure history.
+    const teams = [...others, entry].sort((a, b) => (identityOf(a) < identityOf(b) ? -1 : 1));
+    return { format: CONTAINER_FORMAT, version: CONTAINER_VERSION, teams };
+}
+export function serializeContainer(container) {
+    return Buffer.from(JSON.stringify(container), 'utf8');
+}
+// The entry for a team, checked against what the caller asked for. The AEAD
+// already proved the container is the account's; this proves the entry inside
+// it is the team's — a restore that quietly opened the wrong team's bundle
+// would look like a success.
+export function selectTeam(container, want) {
+    // Matched on the full pair, not found by team id and then checked. Finding by
+    // team id alone answers with whichever entry happens to come first, so a
+    // vault legitimately holding the same team id on two instances could never
+    // restore the second one — the check would reject an entry that was there.
+    const key = identityOf({ server_instance_id: want.serverInstanceId, team_id: want.teamId });
+    const entry = container.teams.find((t) => identityOf(t) === key);
+    if (entry)
+        return entry;
+    // Nothing for this pair. If the team id is present under a different
+    // instance, say so: "no backup for this team" would be misleading when the
+    // name matches something in the vault.
+    const elsewhere = container.teams.find((t) => t.team_id === want.teamId);
+    if (elsewhere) {
+        throw new UnreadableContainerError(`the vault's backup for this team belongs to a different server instance ` +
+            `(${elsewhere.server_instance_id}); this machine is bound to ${want.serverInstanceId}`);
+    }
+    throw new UnreadableContainerError('there is no backup for this team yet. Create one first with `agmsg-cloud recovery setup`.');
+}

package/dist/src/vault-crypto.js

@@ -0,0 +1,190 @@
+import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+import { argon2id } from 'hash-wasm';
+// Argon2id at 64 MiB / 3 passes. The server's schema permits 8 MiB..1 GiB; this
+// sits where a laptop pays well under a second and a cracker pays real memory.
+export const DEFAULT_KDF = {
+    kdf: 'argon2id',
+    m: 65536,
+    t: 3,
+    p: 1,
+};
+// The same bounds the server enforces (routes.ts kdfMetaSchema), re-checked here
+// because on restore the kdf_meta arrives *from* the server and we must derive
+// with it before we can tell whether it is honest. Binding the params into the
+// AAD makes a tampered set fail — but only after we have already spent the
+// memory and time it asked for, so a hostile server could bill us 1 GiB per
+// attempt. Bound it first, then derive.
+export const KDF_LIMITS = {
+    m: { min: 8192, max: 1048576 }, // KiB
+    t: { min: 1, max: 16 },
+    p: { min: 1, max: 16 },
+};
+function assertUsableKdf(meta) {
+    if (meta.kdf !== 'argon2id')
+        throw new Error(`unsupported kdf: ${meta.kdf}`);
+    for (const field of ['m', 't', 'p']) {
+        const value = meta[field];
+        const { min, max } = KDF_LIMITS[field];
+        if (!Number.isInteger(value) || value < min || value > max) {
+            throw new Error(`kdf parameter ${field} is out of range: ${value} (want ${min}..${max})`);
+        }
+    }
+    const salt = Buffer.from(meta.salt, 'base64');
+    // Round-trip, so a string Buffer.from would silently partial-decode is refused
+    // rather than quietly deriving from fewer bytes than the sender encoded.
+    if (salt.toString('base64') !== meta.salt || salt.length < 8) {
+        throw new Error('kdf salt is not valid base64 of at least 8 bytes');
+    }
+}
+const SALT_BYTES = 16;
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+export function newSalt() {
+    return randomBytes(SALT_BYTES).toString('base64');
+}
+// The VDK itself: random, not derived.
+//
+// It used to be argon2id(recovery key, salt), which made the recovery key and
+// the VDK the same secret wearing two shapes. Re-issuing a key then meant
+// re-encrypting everything under a new derivation, and there was nowhere to
+// put a second way in — a device slot has no recovery key to derive from.
+//
+// Random, wrapped once per way of opening it (recovery-vault-v1.md:506-513):
+// the key wraps it, and later a device KEK wraps the same VDK, and neither
+// knows about the other. Re-issuance still means a FRESH VDK and a full
+// re-encrypt — never rewrapping the old one, because a leaked key that opens
+// the old version yields the same VDK and opens the new one too.
+export function newVdk() {
+    return randomBytes(KEY_BYTES);
+}
+function slotAad(context) {
+    const fields = [
+        'agmsg-vault-slot-v1',
+        context.vaultId,
+        String(context.recoveryGeneration),
+        context.slotId,
+        context.slotType,
+        context.wrapProfile,
+        // The kind-specific tail. The union makes both branches exhaustive, so a
+        // new slot kind cannot be added without deciding what it binds.
+        ...(context.slotType === 'recovery-key'
+            ? [
+                context.kdfProfile,
+                String(context.kdfParams.m),
+                String(context.kdfParams.t),
+                String(context.kdfParams.p),
+                context.salt,
+            ]
+            : [context.vaultServiceId, context.accountId]),
+    ];
+    return Buffer.from(fields.map((f) => `${Buffer.byteLength(f, 'utf8')}:${f}`).join(''), 'utf8');
+}
+export function wrapVdk(kek, vdk, context) {
+    // Checked at the boundary rather than trusted. Without it this API accepts a
+    // short "VDK" and returns something that unwraps to it perfectly — a
+    // 16-byte key would round-trip and look correct everywhere except in how
+    // much work it costs to guess.
+    if (vdk.length !== KEY_BYTES) {
+        throw new Error(`a VDK is ${KEY_BYTES} bytes; got ${vdk.length}`);
+    }
+    if (kek.length !== KEY_BYTES) {
+        throw new Error(`a KEK is ${KEY_BYTES} bytes; got ${kek.length}`);
+    }
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv('aes-256-gcm', kek, iv);
+    cipher.setAAD(slotAad(context));
+    const sealed = Buffer.concat([cipher.update(vdk), cipher.final()]);
+    return Buffer.concat([iv, cipher.getAuthTag(), sealed]);
+}
+const WRAP_BYTES = IV_BYTES + TAG_BYTES + KEY_BYTES;
+export function unwrapVdk(kek, wrapped, context) {
+    // A wrap is exactly iv + tag + a 32-byte key. Refusing anything else here
+    // means a truncated or padded blob fails as a malformed wrap rather than as
+    // an authentication error, which are different problems with different
+    // causes.
+    if (wrapped.length !== WRAP_BYTES) {
+        throw new Error(`a wrapped VDK is ${WRAP_BYTES} bytes; got ${wrapped.length}`);
+    }
+    const iv = wrapped.subarray(0, IV_BYTES);
+    const tag = wrapped.subarray(IV_BYTES, IV_BYTES + TAG_BYTES);
+    const body = wrapped.subarray(IV_BYTES + TAG_BYTES);
+    const decipher = createDecipheriv('aes-256-gcm', kek, iv);
+    decipher.setAAD(slotAad(context));
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(body), decipher.final()]);
+}
+// Argon2id over the recovery key, producing the KEK that unwraps a stored VDK
+// from a recovery-key slot.
+//
+// The name says that now because it is now true. It was deriveKeyFromRecoveryKey
+// while callers still sealed the bundle directly under this value — naming it
+// for the KEK then would have described a format that had not arrived. This is
+// the change that moved the callers, so the name moves with them.
+//
+// It is NOT the vault's data key. The data key is random (newVdk) and this
+// value only opens one wrap of it, which is what makes a second way in — and
+// re-issuance — expressible at all.
+export async function deriveRecoveryKek(recoveryKey, meta) {
+    assertUsableKdf(meta);
+    const salt = Buffer.from(meta.salt, 'base64');
+    const hex = await argon2id({
+        password: recoveryKey,
+        salt,
+        memorySize: meta.m,
+        iterations: meta.t,
+        parallelism: meta.p,
+        hashLength: KEY_BYTES,
+        outputType: 'hex',
+    });
+    return Buffer.from(hex, 'hex');
+}
+function additionalData(context, meta) {
+    // Length-prefixed rather than delimiter-joined. wrap_profile is a free-form
+    // string, so with a separator its contents could impersonate a field boundary
+    // and make two different contexts produce the same AAD. Today's schema happens
+    // to make that unreachable; the framing should not depend on that staying true
+    //. Order is fixed because the other side recomputes this — a
+    // JSON.stringify over an object would make key order part of the format by
+    // accident.
+    const fields = [
+        // The format identifier the design's AAD tuple calls for, and the reason
+        // this is v2: the vault stopped being per-team, so a v1 ciphertext (which
+        // bound a team id) must fail to open rather than appear compatible. A
+        // change that breaks stored data should break it detectably.
+        'agmsg-vault-v2',
+        context.accountId,
+        context.vaultId,
+        context.vaultServiceId,
+        context.wrapProfile,
+        String(context.revision),
+        meta.kdf,
+        meta.salt,
+        String(meta.m),
+        String(meta.t),
+        String(meta.p),
+    ];
+    return Buffer.from(fields.map((f) => `${Buffer.byteLength(f, 'utf8')}:${f}`).join(''), 'utf8');
+}
+// iv || tag || ciphertext. Length-prefix-free because both leading parts are
+// fixed width for AES-256-GCM.
+export function wrapWithVdk(vdk, plaintext, context, meta) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv('aes-256-gcm', vdk, iv);
+    cipher.setAAD(additionalData(context, meta));
+    const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return Buffer.concat([iv, cipher.getAuthTag(), body]);
+}
+export function unwrapWithVdk(vdk, wrapped, context, meta) {
+    if (wrapped.length < IV_BYTES + 16 + 1)
+        throw new Error('vault ciphertext is truncated');
+    const iv = wrapped.subarray(0, IV_BYTES);
+    const tag = wrapped.subarray(IV_BYTES, IV_BYTES + 16);
+    const body = wrapped.subarray(IV_BYTES + 16);
+    const decipher = createDecipheriv('aes-256-gcm', vdk, iv);
+    decipher.setAAD(additionalData(context, meta));
+    decipher.setAuthTag(tag);
+    // `final()` is what raises on a bad tag; without it a caller reading only
+    // `update()` would accept forged bytes.
+    return Buffer.concat([decipher.update(body), decipher.final()]);
+}

package/dist/src/vault-protocol.js

@@ -0,0 +1,358 @@
+import { randomUUID } from 'node:crypto';
+import { DEFAULT_KDF, deriveRecoveryKek, newSalt, newVdk, unwrapVdk, unwrapWithVdk, wrapVdk, wrapWithVdk, } from './vault-crypto.js';
+// The vault exchange with the server: read, create, append, open. Split from the
+// command layer so that what talks to the server is separable from what shells
+// out to the OSS tooling and prompts the terminal — the integration test drives
+// this half against a real server, and the half it cannot reach is then exactly
+// two named shell-outs rather than a vague remainder.
+//
+// The shape of a vault, since the wrap list:
+//
+//   the bundle    sealed under a RANDOM data key (the VDK), not under anything
+//                 derived from the recovery key
+//   the slots     one row per way of getting that VDK. The recovery-key slot
+//                 lives on the server; the device slot lives in this machine's
+//                 secure store and is never uploaded (recovery-vault-v1.md:528)
+//
+// Which is why the functions below come in pairs. The `WithVdk` half is the
+// real one: given the data key, open or append. The other half is a shell that
+// obtains the data key from the recovery key first. A caller holding a device
+// slot skips the shell — which is the whole point of the device slot, and the
+// owner's requirement that the master key not come out unless a machine is
+// lost.
+/** How the bundle is sealed under the VDK. Unchanged by the wrap list. */
+export const WRAP_PROFILE = 'argon2id-aes256gcm-v1';
+/**
+ * How a recovery-key slot wraps the VDK. Distinct from WRAP_PROFILE because
+ * they describe different things: one is how the bundle is sealed, the other is
+ * how the key to it is wrapped, and a change to either must be namable without
+ * implying the other changed.
+ */
+export const RECOVERY_SLOT_WRAP_PROFILE = 'aes256gcm-v1';
+/**
+ * The generation a vault is created at.
+ *
+ * It is NOT sent — the server refuses a client-supplied generation and takes
+ * this from its column default. The two must agree: the generation is bound
+ * into the slot's AEAD, so a vault stored at a generation the slot was not
+ * wrapped for cannot be opened by the recovery key that created it. The create
+ * checks what the server actually recorded rather than assuming, for the same
+ * reason `assertLanded` checks the revision.
+ */
+const INITIAL_RECOVERY_GENERATION = 1;
+export class WrongRecoveryKeyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WrongRecoveryKeyError';
+    }
+}
+/** A vault this version cannot open, for a reason that is not the key. */
+export class UnopenableVaultError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnopenableVaultError';
+    }
+}
+// The outer AAD tuple (recovery-vault-v1.md): format and profile, the account,
+// the vault, and the deployment. The team is NOT here any more — the vault
+// stopped being per-team, and each team's binding moved inside the container.
+function contextFor(identity, vaultId, wrapProfile, revision) {
+    return {
+        accountId: identity.accountId,
+        vaultServiceId: identity.vaultServiceId,
+        vaultId,
+        wrapProfile,
+        revision,
+    };
+}
+// The server assigns revisions itself: create is always 1, and an append under
+// If-Match is always current + 1 (app/src/handoff/vault.ts). Nothing rewrites an
+// existing version in place, so "which revision these bytes are" is knowable at
+// wrap time — which is what makes binding the revision into the AAD possible.
+//
+// If a write ever landed as a different revision than we sealed for, the stored
+// version would be unopenable. That is fail-closed rather than silent, but it
+// should never happen, so it is checked instead of assumed.
+function assertLanded(expected, actual) {
+    if (actual !== expected) {
+        throw new Error(`server stored revision ${actual} where ${expected} was sealed; ` +
+            'that version cannot be opened and must be rewritten');
+    }
+}
+// Everything the server returns is attacker-controlled if the server is. The wrap
+// profile decides which primitive and which plaintext contract apply, so it must
+// match exactly before anything is derived or opened: an unknown or future
+// profile has to be refused, not opened with today's cipher and passed onward as
+// "authenticated".
+function usableMeta(version) {
+    if (version.wrap_profile !== WRAP_PROFILE) {
+        throw new Error(`vault uses wrap profile '${version.wrap_profile}', which this version cannot open`);
+    }
+    if (version.kdf_meta.kdf !== 'argon2id') {
+        throw new Error(`vault uses kdf '${version.kdf_meta.kdf}', which this version cannot use`);
+    }
+    return { ...version.kdf_meta, kdf: 'argon2id' };
+}
+// Which slot the recovery key opens.
+//
+// The design forbids trial-unwrap: policy picks the slot, the key does not go
+// looking for one that happens to work (:517). The policy here is the narrowest
+// one that is true — this version writes exactly one recovery-key slot at
+// create, and nothing it can do produces a second. More than one is therefore a
+// state this client did not create, and guessing between them would be exactly
+// the trial-unwrap the design rules out.
+function recoverySlot(version) {
+    const slots = version.vdk_wraps.filter((w) => w.slot_type === 'recovery-key');
+    // No slot means the vault predates the wrap list: its bundle is sealed
+    // directly under a key derived from the recovery key. Null rather than an
+    // error — that vault is intact and its key still opens it, and a schema
+    // change must not be what makes recovery data unreadable. See
+    // `vdkFromRecoveryKey`.
+    if (slots.length === 0)
+        return null;
+    if (slots.length > 1) {
+        throw new UnopenableVaultError(`this vault has ${slots.length} recovery-key slots; this version writes one and ` +
+            'will not choose between them');
+    }
+    return slots[0];
+}
+// The KDF header a slot carries, as the parameters to derive with.
+//
+// Read from the SLOT, not from the version's kdf_meta. They hold the same values
+// — the create writes both from one variable — but only one of them can be the
+// one that is read, or a server could serve two and each reader would answer
+// differently. The design puts the parameters in the slot (:519-522), so that is
+// the one.
+//
+// (The version's kdf_meta stays on the wire and stays bound into the bundle's
+// AAD, where it protects stored bytes that were sealed with it. It is redundant
+// with the slot header and goes when the bundle's AAD can be changed without
+// making existing vaults unopenable.)
+function slotKdf(slot) {
+    if (slot.kdf_profile !== 'argon2id') {
+        throw new UnopenableVaultError(`this vault's recovery slot uses kdf '${slot.kdf_profile}', which this version cannot use`);
+    }
+    return {
+        kdf: 'argon2id',
+        salt: slot.salt,
+        m: slot.kdf_params.m,
+        t: slot.kdf_params.t,
+        p: slot.kdf_params.p,
+    };
+}
+// What the slot's wrap is bound to. Built from the slot's own header, so the
+// create and the open compute it from the same fields — the create from the
+// slot it is about to send, the open from the slot it was handed back.
+function slotContext(vaultId, recoveryGeneration, slot) {
+    return {
+        vaultId,
+        recoveryGeneration,
+        slotId: slot.slot_id,
+        wrapProfile: slot.wrap_profile,
+        slotType: 'recovery-key',
+        kdfProfile: slot.kdf_profile,
+        kdfParams: slot.kdf_params,
+        salt: slot.salt,
+    };
+}
+/**
+ * Get the vault's data key out of its recovery-key slot.
+ *
+ * This is the only place the recovery key is used against the server's copy of
+ * anything. Everything downstream takes the VDK, so a caller that already has
+ * it — from this machine's device slot — never reaches here, and never asks a
+ * person for the key.
+ */
+export async function vdkFromRecoveryKey(version, recoveryKey) {
+    const slot = recoverySlot(version);
+    // ------------------------------------------------------------------------
+    // LEGACY, read and append only. A vault created before the wrap list has no
+    // slot: its bundle is sealed directly under the key derived from the recovery
+    // key, so that derived key IS the data key.
+    //
+    // Kept because a schema change must not be what makes someone's recovery data
+    // unreadable. The per-team vault is kept alive for exactly this reason and
+    // says so where it lives (app/src/handoff/vault.ts); nothing here has a better
+    // claim to be deleted than that one does.
+    //
+    // A vault on this path cannot gain a device slot: there is no key to wrap that
+    // the recovery key does not also derive, and wrapping the derived key would
+    // put a copy of it in the secure store while the vault stayed openable by
+    // derivation — two ways in with one secret behind both.
+    //
+    // A hostile server cannot use this as a downgrade. Serving `vdk_wraps: []`
+    // for a vault that HAS a slot sends the client down this path, and the key it
+    // derives is not the random data key the bundle was sealed under — the tag
+    // fails. The result is a refusal, not a weaker open.
+    //
+    // WHAT REMOVES IT: a count of account vaults with no wrap row, from the
+    // production database. Zero means nothing is reachable only through here, and
+    // then this branch and the tests below it go in one change.
+    // ------------------------------------------------------------------------
+    if (slot === null)
+        return deriveRecoveryKek(recoveryKey, usableMeta(version));
+    if (slot.wrap_profile !== RECOVERY_SLOT_WRAP_PROFILE) {
+        throw new UnopenableVaultError(`this vault's recovery slot uses wrap profile '${slot.wrap_profile}', ` +
+            'which this version cannot open');
+    }
+    const kek = await deriveRecoveryKek(recoveryKey, slotKdf(slot));
+    try {
+        return unwrapVdk(kek, Buffer.from(slot.wrapped_vdk, 'base64'), slotContext(version.vault_id, version.recovery_generation, slot));
+    }
+    catch {
+        // A wrong key, a tampered slot, and a slot lifted from another vault or
+        // generation all land here and genuinely cannot be told apart — the tag
+        // fails and says nothing about why.
+        throw new WrongRecoveryKeyError('that recovery key does not open this vault — the key is wrong, or the ' +
+            'stored slot does not match the vault and generation it belongs to');
+    }
+}
+// The account's vault and the identifiers the client cannot derive. A first run
+// returns `version: null` rather than failing: those identifiers are what a
+// create needs.
+export async function readAccountVault(client) {
+    const out = await client.getAccountVault();
+    return {
+        identity: { accountId: out.accountId, vaultServiceId: out.vaultServiceId },
+        version: out.version,
+    };
+}
+/**
+ * The account's first write: mint the vault identity, the data key, and the one
+ * slot the recovery key opens.
+ *
+ * Returns the VDK. The caller needs it to save this machine's device slot, and
+ * deriving it again would mean running Argon2id a second time for a value that
+ * is already in hand. It is a Buffer in memory for the length of one command and
+ * is never written anywhere by this module.
+ */
+export async function createVault(client, identity, recoveryKey, content) {
+    const vaultId = randomUUID();
+    // One salt for the vault's whole life, so one recovery key. It is written into
+    // both the slot header and the version's kdf_meta from this one variable —
+    // they cannot disagree because there is nothing here that could make them.
+    const meta = { ...DEFAULT_KDF, salt: newSalt() };
+    const vdk = newVdk();
+    const kek = await deriveRecoveryKek(recoveryKey, meta);
+    const header = {
+        slot_id: randomUUID(),
+        slot_type: 'recovery-key',
+        wrap_profile: RECOVERY_SLOT_WRAP_PROFILE,
+        kdf_profile: meta.kdf,
+        kdf_params: { m: meta.m, t: meta.t, p: meta.p },
+        salt: meta.salt,
+    };
+    const slot = {
+        ...header,
+        wrapped_vdk: wrapVdk(kek, vdk, slotContext(vaultId, INITIAL_RECOVERY_GENERATION, header)).toString('base64'),
+    };
+    const wrapped = wrapWithVdk(vdk, content, contextFor(identity, vaultId, WRAP_PROFILE, 1), meta);
+    const result = await client.putAccountVault({
+        vault_id: vaultId,
+        wrap_profile: WRAP_PROFILE,
+        ciphertext: wrapped.toString('base64'),
+        kdf_meta: meta,
+        operation_id: randomUUID(),
+        vdk_wraps: [slot],
+    });
+    assertLanded(1, result.revision);
+    assertGeneration(INITIAL_RECOVERY_GENERATION, result.recovery_generation);
+    // The generation is returned, not left for the caller to write as 1. The
+    // caller's next move is to address this machine's local slot with it, and a
+    // second place that says "a new vault is generation 1" is a second place that
+    // has to be found when re-issuance makes it false.
+    //
+    // The SERVER's value, after the assert above proved it is the one this slot
+    // was wrapped for. Returning the constant instead would satisfy "no default
+    // in the caller" while quietly making this the second place — which is the
+    // thing the sentence above claims not to do.
+    return {
+        revision: result.revision,
+        vaultId,
+        recoveryGeneration: result.recovery_generation,
+        vdk,
+    };
+}
+// The generation is bound into the slot's AEAD but is the server's to assign, so
+// the one it recorded is checked against the one the slot was wrapped for. A
+// mismatch means the slot cannot ever unwrap the VDK, and the recovery key just
+// shown to a person opens nothing — a failure that would otherwise surface at
+// restore time, which is the one moment there is no way back.
+function assertGeneration(expected, actual) {
+    if (actual !== expected) {
+        throw new Error(`server recorded recovery generation ${actual} where the slot was wrapped for ` +
+            `${expected}; the recovery key would not open this vault and it must be rewritten`);
+    }
+}
+/**
+ * Append a version, given the data key.
+ *
+ * This is where the check that the key is *this vault's* key lives, and it stays
+ * on this side rather than in the shell below: a device slot opening is evidence
+ * about the slot, not about the vault. Both routes to a VDK therefore pass it.
+ */
+export async function appendVaultVersionWithVdk(client, identity, existing, vdk, content) {
+    const meta = usableMeta(existing);
+    // Prove the key opens what is already stored before writing anything. A VDK
+    // that is not this vault's is perfectly valid as a key, and appending under it
+    // would store a version the real recovery key cannot open — the failure would
+    // surface at restore time, which is exactly the moment there is no way back.
+    // Opening the version we already fetched is the only check available, and it
+    // costs nothing.
+    try {
+        unwrapWithVdk(vdk, Buffer.from(existing.ciphertext, 'base64'), contextFor(identity, existing.vault_id, existing.wrap_profile, existing.revision), meta);
+    }
+    catch {
+        throw new WrongRecoveryKeyError('that key does not open this vault — nothing was uploaded. ' +
+            'A version stored under the wrong key would be unopenable at restore time.');
+    }
+    const next = existing.revision + 1;
+    const wrapped = wrapWithVdk(vdk, content, contextFor(identity, existing.vault_id, existing.wrap_profile, next), meta);
+    const result = await client.putAccountVault({
+        vault_id: existing.vault_id,
+        wrap_profile: existing.wrap_profile,
+        ciphertext: wrapped.toString('base64'),
+        kdf_meta: meta,
+        operation_id: randomUUID(),
+        if_match: existing.etag,
+        // No vdk_wraps. An append re-seals the same bundle under the same VDK, so
+        // the slots that wrap that VDK are unchanged, and the server rejects a body
+        // that says otherwise.
+    });
+    assertLanded(next, result.revision);
+    return { revision: result.revision };
+}
+/** Open a version, given the data key. */
+export function openVaultWithVdk(identity, version, vdk) {
+    const meta = usableMeta(version);
+    let content;
+    try {
+        content = unwrapWithVdk(vdk, Buffer.from(version.ciphertext, 'base64'), contextFor(identity, version.vault_id, version.wrap_profile, version.revision), meta);
+    }
+    catch {
+        // One message for a wrong key, for tampering, and for a rolled-back version:
+        // we genuinely cannot tell them apart, and guessing which it was would be a
+        // claim we cannot support.
+        throw new WrongRecoveryKeyError('could not open the vault: the key is wrong, or the stored version ' +
+            'does not match what this account, vault, and revision were sealed against');
+    }
+    return { content, revision: version.revision };
+}
+// Later writes, from the recovery key. The shell: get the VDK out of the slot,
+// then do the real thing. A caller with a device slot calls the real thing
+// directly and never asks for the key.
+export async function appendVaultVersion(client, identity, existing, recoveryKey, content) {
+    const vdk = await vdkFromRecoveryKey(existing, recoveryKey);
+    return appendVaultVersionWithVdk(client, identity, existing, vdk, content);
+}
+// Pull the current version and open it, from the recovery key. The revision the
+// server calls current is bound into the AAD, so replaying an older ciphertext
+// under a newer revision number fails the tag rather than quietly restoring a
+// superseded key bundle.
+// It no longer takes a client. Opening is now entirely local — the version was
+// already fetched — and a parameter that is accepted and never used reads as a
+// dependency this function has, which the next caller would then arrange for.
+export async function openCurrentVault(identity, version, recoveryKey) {
+    const vdk = await vdkFromRecoveryKey(version, recoveryKey);
+    return openVaultWithVdk(identity, version, vdk);
+}