@jwilleke/ngdpbase-types 5.39.0 → 5.41.0

package/lib/src/utils/privateStoreTakeout.js

@@ -0,0 +1,149 @@
+/**
+ * Reading a private store back out, byte for byte (#1387, epic #1382).
+ *
+ * Two features need the same thing and must not grow two answers to it:
+ *
+ *   - the instance backup, which copies every store so a disk failure is
+ *     survivable, and
+ *   - a user's own download, which is how someone leaves with their data.
+ *
+ * What they share is this module: walk a store directory and hand back every
+ * file in it as bytes. Packaging and permission are the callers' business.
+ *
+ * ## Bytes, never text
+ *
+ * `FileSystemProvider.backup()` reads pages with an encoding, which is right
+ * for a public page and destroys a private one: a sealed store's `.md` files
+ * are ciphertext, and decoding them as UTF-8 substitutes U+FFFD for every byte
+ * that is not valid UTF-8. The file would still be in the backup, and would
+ * still look like a file, and would never decrypt again.
+ *
+ * So everything here is `Buffer`. A caller that wants text can decode what it
+ * knows to be text; nothing in this module ever does.
+ *
+ * ## The whole store, including its keys
+ *
+ * A store is self-contained by design (see `privateStorePath`), so a takeout is
+ * "copy this directory" — pages, their versions, the trash, the attachments and
+ * every index. The user's `user-keys.json` is copied too, deliberately: it is a
+ * WRAPPED key, useless without the password or the twelve words, and without it
+ * a restored sealed store could never be opened again by anyone, including its
+ * owner. Copying the wrapped key does not make the copier a keyholder.
+ */
+import path from 'path';
+import fs from 'fs-extra';
+import { vanishedDuringBackup } from './treeArchive.js';
+import { privateUserDir, privateStoreRoot, resolvePrivateStoreLayout } from './privateStorePath.js';
+/** Recursively list every file under `dir`, relative to it, `/`-separated. */
+async function walkFiles(dir, prefix = '') {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        // Not there (any more): nothing to list. Any other error is a real one (#1563).
+        if (vanishedDuringBackup(err))
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const entry of entries) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            out.push(...await walkFiles(path.join(dir, entry.name), rel));
+        }
+        else if (entry.isFile()) {
+            out.push(rel);
+        }
+        // Anything else — a symlink, a socket — is not a store file. Following a
+        // symlink here would copy whatever it points at into a takeout.
+    }
+    return out;
+}
+/** Read the named files under `root` as bytes, skipping any that vanish mid-walk. */
+async function readAll(root, relPaths) {
+    const files = [];
+    for (const rel of relPaths) {
+        const abs = path.join(root, ...rel.split('/'));
+        try {
+            const [bytes, stat] = await Promise.all([fs.readFile(abs), fs.stat(abs)]);
+            files.push({ path: rel, bytes, mtime: stat.mtime });
+        }
+        catch (err) {
+            // A page purged while the walk was running is not an error: the takeout
+            // is a point-in-time copy, and the file is simply no longer part of it.
+            // Any other error (EACCES, EIO) is, and is not hidden (#1563).
+            if (!vanishedDuringBackup(err))
+                throw err;
+        }
+    }
+    return files;
+}
+/**
+ * Every file of one store, as bytes.
+ *
+ * Returns an empty file list when the store does not exist, so a caller can ask
+ * about a store without first proving it is there.
+ */
+export async function collectStore(pagesDirectory, owner, store, layout, skip) {
+    const root = privateStoreRoot(pagesDirectory, owner, store, layout);
+    // `skip` leaves a file out unread (#1876: the instance backup leaves the
+    // vault's attachments to AttachmentManager, so they are never read here).
+    const files = await readAll(root, (await walkFiles(root)).filter((rel) => !skip?.(rel)));
+    return {
+        owner,
+        store,
+        files,
+        totalBytes: files.reduce((sum, f) => sum + f.bytes.length, 0)
+    };
+}
+/** The store ids a user has on disk, in directory order. */
+export async function listStoreIds(pagesDirectory, owner, layout) {
+    const userDir = privateUserDir(pagesDirectory, owner, layout);
+    try {
+        const entries = await fs.readdir(userDir, { withFileTypes: true });
+        return entries.filter(e => e.isDirectory()).map(e => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/** The users who have a private directory on disk, in directory order. */
+export async function listPrivateOwners(pagesDirectory, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    try {
+        const entries = await fs.readdir(path.join(pagesDirectory, L.privateRoot), { withFileTypes: true });
+        return entries.filter(e => e.isDirectory()).map(e => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Everything one user keeps privately: each of their stores, plus the files
+ * that sit at the user level beside them (`user-keys.json` and any legacy
+ * catalogue still there).
+ *
+ * This is the unit both callers work in — an instance backup asks for it once
+ * per owner, and a user's own download asks for it once, for themselves.
+ */
+export async function collectUser(pagesDirectory, owner, layout, skip) {
+    const userDir = privateUserDir(pagesDirectory, owner, layout);
+    // Files directly in the user directory — not the store directories.
+    let topLevel;
+    try {
+        const entries = await fs.readdir(userDir, { withFileTypes: true });
+        topLevel = entries.filter(e => e.isFile()).map(e => e.name);
+    }
+    catch {
+        topLevel = [];
+    }
+    const userFiles = await readAll(userDir, topLevel);
+    const stores = [];
+    for (const store of await listStoreIds(pagesDirectory, owner, layout)) {
+        stores.push(await collectStore(pagesDirectory, owner, store, layout, skip));
+    }
+    const totalBytes = userFiles.reduce((sum, f) => sum + f.bytes.length, 0) +
+        stores.reduce((sum, s) => sum + s.totalBytes, 0);
+    return { owner, userFiles, stores, totalBytes };
+}

package/lib/src/utils/privateStoreUnlock.d.ts

@@ -123,6 +123,9 @@ export declare function newPrivateStoreHandle(): string;
  * owner's own bag — DEKs are keyed by store id, and every user has a
  * `default` — or, for someone acting for the owner, from the key copy their
  * grant carries (#1762 slice 5).
+ *
+ * A shared folder's key is the server's, never in a bag (#2125): handed only
+ * to a context the PDP has permitted on that folder (`sharedFolderKeyFor`).
  */
 export declare function dekFor(ctx: ActorContext | undefined, owner: string, store: string): Buffer | undefined;
 /**

package/lib/src/utils/privateStoreUnlock.js

@@ -0,0 +1,499 @@
+/**
+ * Process-level unlock bag for private-store keys (#1384, #1391).
+ *
+ * Keyed by an opaque random handle — never the session id — created at
+ * password login ({@link newPrivateStoreHandle}), stored on the session as
+ * `privateStoreHandle`, and carried on the request subject so a caller reaches
+ * its keys through the context it was given ({@link dekFor}; security-posture
+ * P1). Key bytes never go into express-session JSON, a context, or a record.
+ * Logout calls {@link lockPrivateStores}.
+ *
+ * There is no ambient slot: `AsyncLocalStorage` is refused by P1 because the
+ * call site does not show what identity it runs under. Every caller reaches
+ * its keys through the context it was handed.
+ */
+import { randomUUID } from 'node:crypto';
+import fs from 'fs-extra';
+import logger from './logger.js';
+import { assertEncryptedStoreWritable, newPersonKey, openKekCopy, personPublicKey, recoveryWordsId, rewrapPassword, sealKekCopy, rewrapPasswordWithKek, unwrapDek, unwrapKekWithMnemonic, unwrapKekWithPassword } from './privateStoreCrypto.js';
+import { readStoreMeta, readVaultSealState, refuseUnsealedVault } from './privateStoreMeta.js';
+import { dropPendingWords } from './privateStoreDoor.js';
+import { PRIVATE_USER_CATALOG_FILES, isSharedFolderOwner, isValidStoreId, privateUserDir, privateUserKeysPath } from './privateStorePath.js';
+import { emptyUserCatalog, readUserCatalog } from './privateStoreCatalogs.js';
+import { isJobContext } from '../context/ActorContext.js';
+import { writeFileAtomic } from './atomicWrite.js';
+import { SECRET_FILE_MODE } from './secretFileMode.js';
+import { mixesProxyWithDelegation, proxyCarries } from './proxyClaim.js';
+import { sharedFolderKeyFor } from './sharedFolderAccess.js';
+const bags = new Map();
+export function unlockPrivateStores(sessionId, username, kek) {
+    bags.set(sessionId, {
+        username,
+        kek: Buffer.from(kek),
+        deks: new Map(),
+        userIndex: emptyUserCatalog()
+    });
+}
+export function getSessionUserIndex(sessionId) {
+    return bags.get(sessionId)?.userIndex;
+}
+/**
+ * Replace a user-keys.json (#1625): the only copy of both wraps of the KEK, so
+ * atomic (a crash leaves the old file or the new one, never a truncated one),
+ * owner-only and flushed to the device.
+ */
+async function writeUserKeyEnvelope(file, envelope) {
+    await writeFileAtomic(file, JSON.stringify(envelope), 'utf8', { mode: SECRET_FILE_MODE, fsync: true });
+}
+function wipeCopy(bag) {
+    if (!bag.copy)
+        return;
+    bag.copy.kek.fill(0);
+    for (const dek of bag.copy.deks.values())
+        dek.fill(0);
+    bag.copy.deks.clear();
+    delete bag.copy;
+}
+export function lockPrivateStores(sessionId) {
+    const bag = bags.get(sessionId);
+    if (bag) {
+        wipeCopy(bag);
+        bag.kek.fill(0);
+        for (const dek of bag.deks.values())
+            dek.fill(0);
+        bag.deks.clear();
+        bags.delete(sessionId);
+    }
+}
+export function getUnlockedKek(sessionId) {
+    const kek = bags.get(sessionId)?.kek;
+    return kek ? Buffer.from(kek) : undefined;
+}
+export function setUnlockedDek(sessionId, storeId, dek) {
+    const bag = bags.get(sessionId);
+    if (!bag)
+        throw new Error('private stores are locked for this session');
+    bag.deks.set(storeId, Buffer.from(dek));
+}
+export function getUnlockedDek(sessionId, storeId) {
+    const dek = bags.get(sessionId)?.deks.get(storeId);
+    return dek ? Buffer.from(dek) : undefined;
+}
+/** DEK from the process bag for this request's session (or an explicit id). */
+export function sessionDekForStore(storeId, handle) {
+    return getUnlockedDek(handle, storeId);
+}
+function isUserKeyEnvelope(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const rec = value;
+    return rec.version === 1 && rec.passwordWrap !== undefined && rec.kdf !== undefined;
+}
+/**
+ * After password login: unwrap the user KEK into the bag and load store DEKs.
+ * No-ops when the user has no envelope yet. Never writes key bytes to session JSON.
+ */
+export async function unlockPrivateStoresWithPassword(args) {
+    const envelope = await readUserKeyEnvelope(args.pagesDirectory, args.username);
+    if (!envelope)
+        return;
+    await unlockWithKek(args, envelope, await unwrapKekWithPassword(envelope, args.password));
+}
+/**
+ * Unlock with the 12 recovery words instead of the password (#1453).
+ *
+ * The words unwrap the SAME key the password does — the envelope holds it
+ * twice, once per wrap — so everything after the unwrap is the password
+ * path's, shared. Wrong words fail the authenticated unwrap and return
+ * `false`; nothing is unlocked and nothing is written. The words are never
+ * logged, stored or returned.
+ */
+export async function unlockPrivateStoresWithMnemonic(args) {
+    const envelope = await readUserKeyEnvelope(args.pagesDirectory, args.username);
+    if (!envelope)
+        return false;
+    let kek;
+    try {
+        kek = unwrapKekWithMnemonic(envelope, args.words);
+    }
+    catch {
+        return false;
+    }
+    await unlockWithKek(args, envelope, kek);
+    return true;
+}
+/** The user's key envelope, or null when they have none (or it is not one). */
+async function readUserKeyEnvelope(pagesDirectory, username) {
+    const keysPath = privateUserKeysPath(pagesDirectory, username);
+    if (!await fs.pathExists(keysPath))
+        return null;
+    const raw = await fs.readJson(keysPath);
+    return isUserKeyEnvelope(raw) ? raw : null;
+}
+/**
+ * Everything an unlock does once it holds the user's key: the key into the
+ * session's bag, each encrypted store's data key, and the user's catalogue.
+ * One implementation, whichever wrap the key came out of.
+ */
+async function unlockWithKek(args, envelope, kek) {
+    unlockPrivateStores(args.handle, args.username, kek);
+    for (const [store, dek] of await storeDeks(args.pagesDirectory, args.username, kek)) {
+        setUnlockedDek(args.handle, store, dek);
+        dek.fill(0);
+    }
+    try {
+        await ensurePersonKey(args.pagesDirectory, args.username, envelope, kek);
+    }
+    catch {
+        logger.warn('[private-store] the person key pair could not be made at unlock');
+    }
+    const bag = bags.get(args.handle);
+    if (bag) {
+        try {
+            bag.userIndex = await readUserCatalog(args.pagesDirectory, args.username, kek);
+        }
+        catch {
+            logger.warn('[private-store] the user page catalog stayed sealed after login');
+        }
+    }
+}
+/**
+ * The data key of each of `username`'s encrypted stores that `kek` opens. One
+ * walk of the container, for an unlock and for a proxy's key copy alike; a
+ * store that does not open stays locked and is left out.
+ */
+async function storeDeks(pagesDirectory, username, kek) {
+    const deks = new Map();
+    const userDir = privateUserDir(pagesDirectory, username);
+    if (!await fs.pathExists(userDir))
+        return deks;
+    const entries = await fs.readdir(userDir, { withFileTypes: true });
+    for (const ent of entries) {
+        if (!ent.isDirectory())
+            continue;
+        if (PRIVATE_USER_CATALOG_FILES.has(ent.name))
+            continue;
+        // Only store folders: a folder whose name is not a store id is not a store,
+        // and must not abort the unlock of the stores that are.
+        if (!isValidStoreId(ent.name))
+            continue;
+        const meta = await readStoreMeta(pagesDirectory, username, ent.name);
+        if (meta.encrypt !== true)
+            continue;
+        try {
+            deks.set(ent.name, unwrapDek(kek, meta));
+        }
+        catch {
+            logger.warn('[private-store] an encrypted store stayed locked');
+        }
+    }
+    return deks;
+}
+/**
+ * Give the person a key pair if their envelope has none (#1762 slice 5):
+ * enrolment makes one (`createUserKeys`); a person enrolled before it existed
+ * gets theirs the first time their store is unlocked. Only the new field is
+ * added; every wrap of the KEK is written back as it was read.
+ */
+async function ensurePersonKey(pagesDirectory, username, envelope, kek) {
+    if (envelope.personKey)
+        return;
+    await writeUserKeyEnvelope(privateUserKeysPath(pagesDirectory, username), { ...envelope, personKey: await newPersonKey(kek) });
+}
+/** Whether `username` has keys at all, i.e. a store that can be encrypted. */
+export async function hasUserKeys(pagesDirectory, username) {
+    return (await readUserKeyEnvelope(pagesDirectory, username)) !== null;
+}
+/** Which set of recovery words `username` has (#1928, `recoveryWordsId`), or null when they have no keys. */
+export async function recoveryWordsIdOf(pagesDirectory, username) {
+    const envelope = await readUserKeyEnvelope(pagesDirectory, username);
+    return envelope ? recoveryWordsId(envelope) : null;
+}
+/**
+ * The public half of `username`'s key pair (#1762 slice 5), or null when they
+ * have no keys or no pair yet. Public: anyone may seal to it.
+ */
+export async function personKeyOf(pagesDirectory, username) {
+    const envelope = await readUserKeyEnvelope(pagesDirectory, username);
+    return envelope ? personPublicKey(envelope) : null;
+}
+/**
+ * Seal a copy of this context's OWN unlocked KEK to `recipient` (#1762 slice
+ * 5): what a proxy grant made while the owner's store is open carries. Null
+ * when the context holds no key — a locked store, a token, a proxy (it holds
+ * no KEK of its own through `kekFor`). The KEK copy taken here is zeroed.
+ */
+export async function sealKekCopyFor(ctx, recipient) {
+    const kek = kekFor(ctx);
+    if (!kek)
+        return null;
+    try {
+        return await sealKekCopy(recipient, kek);
+    }
+    finally {
+        kek.fill(0);
+    }
+}
+/**
+ * Open the key copy a proxy grant carries (#1762 slice 5) into the actor's
+ * own bag (`handle`), when the actor's store is unlocked: their KEK unwraps
+ * their private key, which opens the copy of the owner's KEK, which opens the
+ * owner's encrypted stores. Replaces any copy the bag held. False — nothing
+ * held — when the actor's store is locked, the bag is not the actor's, or the
+ * copy does not open (it is then not retried for this bag). No key byte is
+ * returned or logged.
+ */
+export async function openKeyCopy(args) {
+    const bag = bags.get(args.handle);
+    if (!bag || bag.username !== args.actor)
+        return false;
+    if (bag.copy?.grantId === args.grantId && bag.copy.owner === args.owner)
+        return true;
+    if (bag.copyRefused === args.grantId)
+        return false;
+    wipeCopy(bag);
+    const envelope = await readUserKeyEnvelope(args.pagesDirectory, args.actor);
+    let kek;
+    try {
+        if (!envelope)
+            throw new Error('no keys');
+        kek = await openKekCopy(envelope, bag.kek, args.copy);
+    }
+    catch {
+        bag.copyRefused = args.grantId;
+        return false;
+    }
+    const deks = await storeDeks(args.pagesDirectory, args.owner, kek);
+    // The bag may have been locked while the stores were read.
+    if (bags.get(args.handle) !== bag) {
+        kek.fill(0);
+        for (const dek of deks.values())
+            dek.fill(0);
+        return false;
+    }
+    delete bag.copyRefused;
+    bag.copy = { grantId: args.grantId, owner: args.owner, kek, deks };
+    return true;
+}
+/** The grant and person whose key copy this handle's bag holds, if any — ids only, no key. */
+export function heldKeyCopy(handle) {
+    const copy = typeof handle === 'string' ? bags.get(handle)?.copy : undefined;
+    return copy ? { grantId: copy.grantId, owner: copy.owner } : undefined;
+}
+/** Wipe the key copy this handle's bag holds (#1762 slice 5): switching back, or to someone else. The actor's own keys stay. */
+export function dropKeyCopy(handle) {
+    if (typeof handle !== 'string')
+        return;
+    const bag = bags.get(handle);
+    if (!bag)
+        return;
+    wipeCopy(bag);
+    delete bag.copyRefused;
+}
+/** Wipe every copy opened under this grant, in every session (#1762 slice 5): the grant was revoked or its account closed. */
+export function dropKeyCopiesOfGrant(grantId) {
+    let dropped = 0;
+    for (const bag of bags.values()) {
+        if (bag.copy?.grantId !== grantId)
+            continue;
+        wipeCopy(bag);
+        dropped++;
+    }
+    return dropped;
+}
+/**
+ * Password change: re-wrap the user envelope. Recovery wrap is unchanged.
+ * No-ops when there is no envelope yet. Not a manager — any caller can use this.
+ */
+export async function rewrapUserKeysOnPasswordChange(args) {
+    const keysPath = privateUserKeysPath(args.pagesDirectory, args.username);
+    if (!await fs.pathExists(keysPath))
+        return;
+    const raw = await fs.readJson(keysPath);
+    if (!isUserKeyEnvelope(raw))
+        return;
+    const next = await rewrapPassword(raw, args.oldPassword, args.newPassword);
+    await fs.ensureDir(privateUserDir(args.pagesDirectory, args.username));
+    await writeUserKeyEnvelope(keysPath, next);
+}
+/**
+ * A forgotten password, reset with the recovery words (#1452): the words
+ * unwrap the KEK, and the password wrap is replaced with one made from the
+ * new password. The recovery wrap and the KEK are untouched.
+ *
+ * Returns `false` — writing nothing — when the user has no keys or the words
+ * do not open them. The words are never logged or stored.
+ */
+export async function resetPasswordWrapWithMnemonic(args) {
+    const envelope = await readUserKeyEnvelope(args.pagesDirectory, args.username);
+    if (!envelope)
+        return false;
+    let kek;
+    try {
+        kek = unwrapKekWithMnemonic(envelope, args.words);
+    }
+    catch {
+        return false;
+    }
+    try {
+        await writeUserKeyEnvelope(privateUserKeysPath(args.pagesDirectory, args.username), await rewrapPasswordWithKek(envelope, kek, args.newPassword));
+    }
+    finally {
+        kek.fill(0);
+    }
+    return true;
+}
+/** A fresh handle for a session's key bag: random, never the session id. */
+export function newPrivateStoreHandle() {
+    return randomUUID();
+}
+/**
+ * The handle a context carries to its session's key bag. Only a password
+ * session's request subject has one; a `JobContext`, a bearer-token request
+ * and a share visitor carry none, so they reach no keys.
+ *
+ * A subject acting for someone (`viaProxy`, #1762) reaches none of the bag's
+ * own keys, whatever handle it carries: the session's bag is the actor's own.
+ * The represented person's encrypted stores open to it only through the key
+ * copy its grant carries ({@link copyFor}).
+ */
+function handleOf(ctx) {
+    // A caller that passed no context reaches no keys — a refusal, not a crash.
+    const subject = ctx;
+    return subject?.viaProxy ? undefined : subject?.privateStoreHandle;
+}
+/**
+ * The key copy a proxy subject reaches (#1762 slice 5), or none. All of it
+ * must hold: a `proxy` claim (never `impersonation`) carrying `vault-proxy`
+ * and no token or share; the bag at its `keyHandle` belongs to the claim's
+ * actor; and the copy there was opened under this very grant for the person
+ * the subject represents. Whether the grant is still in force is the
+ * request's (`AuthManager.subjectActingFor` rebuilds the claim from the live
+ * grant and wipes the copy when it is not).
+ */
+function copyFor(ctx) {
+    // A job carries no key (#2047): `jobContextFromRequest` drops the handle, and
+    // a job context that still names one is refused here as well.
+    if (!ctx || isJobContext(ctx))
+        return undefined;
+    const subject = ctx;
+    const claim = subject?.viaProxy;
+    if (!claim?.keyHandle || !proxyCarries(claim, 'vault-proxy') || mixesProxyWithDelegation(subject))
+        return undefined;
+    const bag = bags.get(claim.keyHandle);
+    if (!bag || bag.username !== claim.actor)
+        return undefined;
+    const copy = bag.copy;
+    return copy && copy.grantId === claim.grantId && copy.owner === subject?.username ? copy : undefined;
+}
+/**
+ * The DEK for `owner`'s `store` that this context holds, if any. Only from the
+ * owner's own bag — DEKs are keyed by store id, and every user has a
+ * `default` — or, for someone acting for the owner, from the key copy their
+ * grant carries (#1762 slice 5).
+ *
+ * A shared folder's key is the server's, never in a bag (#2125): handed only
+ * to a context the PDP has permitted on that folder (`sharedFolderKeyFor`).
+ */
+export function dekFor(ctx, owner, store) {
+    if (isSharedFolderOwner(owner))
+        return sharedFolderKeyFor(ctx, store);
+    const copy = copyFor(ctx);
+    if (copy) {
+        const dek = copy.owner === owner ? copy.deks.get(store) : undefined;
+        return dek ? Buffer.from(dek) : undefined;
+    }
+    const handle = handleOf(ctx);
+    if (!handle || bags.get(handle)?.username !== owner)
+        return undefined;
+    return getUnlockedDek(handle, store);
+}
+/**
+ * The ids of the requester's OWN stores whose DEK its session holds (#1400) —
+ * the encrypted stores it can open right now. Another user's, or a locked
+ * store, is never listed; acting for someone, the represented person's stores
+ * the grant's key copy opened (#1762 slice 5). Ids only: no key bytes leave
+ * the bag.
+ */
+export function unlockedStoreIdsFor(ctx) {
+    const copy = copyFor(ctx);
+    if (copy)
+        return [...copy.deks.keys()];
+    const handle = handleOf(ctx);
+    const bag = handle ? bags.get(handle) : undefined;
+    if (!bag || bag.username !== ctx.username)
+        return [];
+    return [...bag.deks.keys()];
+}
+/** The unlocked sealed-store page catalog this context's session holds, if any (#1385). */
+export function userIndexFor(ctx) {
+    const handle = handleOf(ctx);
+    return handle ? getSessionUserIndex(handle) : undefined;
+}
+/**
+ * Refuse a write into an encrypted store unless this context holds its DEK
+ * (#1394). The context-carrying form of {@link assertCurrentSessionCanWriteStore}.
+ */
+export async function assertContextCanWriteStore(ctx, args) {
+    // #1834: a sealed kind's vault that is not sealed itself is refused, never
+    // written in the clear; the kind is the layout's `sealedVaults`.
+    const { state, meta } = await readVaultSealState(args.pagesDirectory, args.owner, args.store, args.layout);
+    refuseUnsealedVault(args.owner, args.store, state);
+    assertEncryptedStoreWritable({
+        encrypt: meta.encrypt,
+        dek: meta.encrypt ? dekFor(ctx, args.owner, args.store) : undefined
+    });
+}
+/**
+ * Whether this context's session holds an unlocked user key (#1448).
+ *
+ * A yes/no, deliberately. {@link kekFor} hands back a COPY of the key bytes,
+ * which is right for a caller that is about to use them and wrong for one that
+ * only needs to know they exist — every page render asks this, and none of
+ * them should be copying key material into a buffer it then has to remember
+ * to zero.
+ */
+export function hasUnlockedKey(ctx) {
+    const handle = handleOf(ctx);
+    return !!handle && bags.get(handle)?.kek !== undefined;
+}
+/** The user KEK this context's session holds, if any. */
+export function kekFor(ctx) {
+    const handle = handleOf(ctx);
+    return handle ? getUnlockedKek(handle) : undefined;
+}
+/**
+ * The one door for a session ending (#1626): whatever ends it — logout, idle
+ * timeout, a password change, an admin revoke, a new sign-in on the same
+ * browser — calls this with the session's private-store handle before the
+ * session is gone, so its keys are zeroed and dropped and no recovery words
+ * stay pending. Takes the raw session value, so a caller never re-implements
+ * the "is there a handle" check.
+ */
+export function endSessionKeys(handle) {
+    if (typeof handle !== 'string' || !handle)
+        return;
+    lockPrivateStores(handle);
+    dropPendingWords(handle);
+}
+/**
+ * Drop every unlocked bag whose handle no live session holds (#1626): a
+ * session that expired in the store, or one destroyed by a path that could
+ * not reach endSessionKeys, leaves its keys with no owner. Returns how many
+ * bags were dropped.
+ */
+export function sweepOrphanedKeys(liveHandles) {
+    let dropped = 0;
+    for (const handle of [...bags.keys()]) {
+        if (liveHandles.has(handle))
+            continue;
+        endSessionKeys(handle);
+        dropped++;
+    }
+    return dropped;
+}
+/** Test teardown only. */
+export function clearUnlockedPrivateStores() {
+    for (const id of [...bags.keys()])
+        lockPrivateStores(id);
+}