@jwilleke/ngdpbase-types 5.39.0 → 5.41.0

package/lib/src/utils/passwordHash.js

@@ -0,0 +1,150 @@
+/**
+ * Password hashing — scrypt, with a per-user salt and in-place upgrade (#1042).
+ *
+ * ## What was wrong
+ *
+ * Passwords were stored as ONE round of SHA-256 with a single instance-wide
+ * salt (`amdwiki-salt` by default):
+ *
+ *     sha256(password + globalSalt)
+ *
+ * SHA-256 is built to be fast, which is the opposite of what a password hash
+ * needs — an attacker holding `users.json` can try billions of candidates a
+ * second on commodity hardware. And because every account shared one salt,
+ * two users with the same password produced byte-identical hashes, so the
+ * store leaked which accounts shared a password without any cracking at all.
+ * The comparison was `===`, which is not constant-time.
+ *
+ * ## What replaces it
+ *
+ * scrypt from Node's standard library — no new dependency — with a random
+ * 16-byte salt per password and a constant-time comparison.
+ *
+ * The stored value is self-describing:
+ *
+ *     scrypt$131072$8$1$<salt base64>$<hash base64>
+ *
+ * Carrying the parameters in the hash is what makes this maintainable: the
+ * cost can be raised later and old hashes keep verifying under the parameters
+ * they were written with, then upgrade on next login. A bare digest cannot do
+ * that, which is how the SHA-256 scheme became impossible to move off.
+ *
+ * ## Migration
+ *
+ * Existing hashes cannot be converted — the plaintext is not recoverable. So
+ * legacy values keep verifying, `needsRehash()` reports them, and the caller
+ * rewrites them after a successful login. The store ages over as people sign
+ * in; nobody is locked out and no reset email is needed.
+ *
+ * An empty stored hash stays unusable by design: `isExternal` accounts (magic
+ * link, OIDC) store `''`, and no password may ever match it.
+ */
+import { createHash, randomBytes, scrypt, timingSafeEqual } from 'crypto';
+/**
+ * scrypt off the main thread (#1632). The synchronous form froze every request
+ * for the length of each hash; at N=2^17 that is ~0.2 s per sign-in, and a
+ * burst of attempts would stall the whole site. This runs on libuv's pool.
+ */
+function scryptAsync(password, salt, keylen, options) {
+    return new Promise((resolve, reject) => {
+        scrypt(password, salt, keylen, options, (err, key) => (err ? reject(err) : resolve(key)));
+    });
+}
+/** Marks the current scheme. Anything else is treated as legacy. */
+const SCHEME = 'scrypt';
+/**
+ * CPU/memory cost. 2^17 (#1632, was 2^14): ~0.2 s per hash, off the main
+ * thread, so offline guessing of a leaked user store is eight times harder and
+ * no request waits on another's sign-in. Raising it is safe: the value used is
+ * recorded in each hash, and needsRehash() upgrades a weaker one at the next
+ * successful sign-in.
+ */
+const N = 131072;
+/** A stored hash naming a cost above this is a corrupt record, not a match (bounds memory). */
+const MAX_N = 1 << 20;
+const R = 8;
+const P = 1;
+const KEYLEN = 64;
+const SALT_BYTES = 16;
+/** scrypt throws unless maxmem covers 128 * N * r; the default is too low. */
+const MAXMEM = 128 * N * R * 4;
+/** Hash a password under the current scheme. */
+export async function hashPassword(password) {
+    const salt = randomBytes(SALT_BYTES);
+    const derived = await scryptAsync(password, salt, KEYLEN, { N, r: R, p: P, maxmem: MAXMEM });
+    return [SCHEME, N, R, P, salt.toString('base64'), derived.toString('base64')].join('$');
+}
+/** The legacy scheme, kept only so old hashes still verify. */
+function legacyHash(password, globalSalt) {
+    return createHash('sha256').update(password + globalSalt).digest('hex');
+}
+/** Constant-time compare that tolerates length differences. */
+function safeEqual(a, b) {
+    const bufA = Buffer.from(a, 'utf8');
+    const bufB = Buffer.from(b, 'utf8');
+    // timingSafeEqual throws on unequal lengths, and the lengths themselves are
+    // not secret here — the scheme fixes them.
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+/**
+ * Verify `password` against a stored value in EITHER scheme.
+ *
+ * @param stored      the value from the user record
+ * @param legacySalt  instance-wide salt, for pre-#1042 hashes only
+ */
+export async function verifyPassword(password, stored, legacySalt) {
+    // External accounts store '' and must never match. Checked first so no
+    // amount of parsing can turn an empty hash into a successful comparison.
+    if (!stored)
+        return false;
+    if (!stored.startsWith(`${SCHEME}$`)) {
+        return safeEqual(legacyHash(password, legacySalt), stored);
+    }
+    const parts = stored.split('$');
+    if (parts.length !== 6)
+        return false;
+    const [, nRaw, rRaw, pRaw, saltB64, hashB64] = parts;
+    const n = Number(nRaw);
+    const r = Number(rRaw);
+    const p = Number(pRaw);
+    if (!Number.isFinite(n) || !Number.isFinite(r) || !Number.isFinite(p) || n > MAX_N)
+        return false;
+    let derived;
+    let expected;
+    try {
+        expected = Buffer.from(hashB64, 'base64');
+        derived = await scryptAsync(password, Buffer.from(saltB64, 'base64'), expected.length, {
+            N: n, r, p, maxmem: 128 * n * r * 4
+        });
+    }
+    catch {
+        // A malformed or absurd parameter set is a corrupt record, not a match.
+        return false;
+    }
+    if (derived.length !== expected.length)
+        return false;
+    return timingSafeEqual(derived, expected);
+}
+/**
+ * Should this stored value be rewritten after a successful login?
+ *
+ * True for legacy hashes, and for current-scheme hashes written under weaker
+ * parameters than today's — which is how a future cost increase rolls out.
+ * An empty hash is never rehashed; external accounts have no password.
+ */
+export function needsRehash(stored) {
+    if (!stored)
+        return false;
+    if (!stored.startsWith(`${SCHEME}$`))
+        return true;
+    const parts = stored.split('$');
+    if (parts.length !== 6)
+        return true;
+    return Number(parts[1]) < N;
+}
+/** True when the value was written by the pre-#1042 scheme. */
+export function isLegacyHash(stored) {
+    return Boolean(stored) && !stored.startsWith(`${SCHEME}$`);
+}

package/lib/src/utils/permissionCatalog.js

@@ -0,0 +1,102 @@
+/**
+ * Which permission entries are actions someone may hold (#1638 slice 3).
+ *
+ * Every audit event is declared on a permission entry, so the catalog also
+ * holds records that no one is ever permitted to do — `system-start`,
+ * `job-failed`, `authentication-failed`. Those entries carry
+ * `"grantable": false`. This is the one predicate that says so; everything
+ * that hands out, offers or lists permissions asks it: app (OIDC) scopes,
+ * the generated `CorePermission` type, the admin roles matrix and the
+ * permission listings. Omitted means grantable.
+ */
+/** True unless the entry says `"grantable": false`. */
+export function isGrantable(entry) {
+    return !(entry && typeof entry === 'object' && entry.grantable === false);
+}
+/** The names of the grantable entries in a permission catalog, in catalog order. */
+export function grantablePermissionNames(definitions) {
+    if (!definitions || typeof definitions !== 'object' || Array.isArray(definitions))
+        return [];
+    return Object.entries(definitions)
+        .filter(([, entry]) => isGrantable(entry))
+        .map(([name]) => name);
+}
+/** The grantable entries of a permission catalog, as a map in catalog order. */
+export function grantablePermissions(definitions) {
+    return Object.fromEntries(Object.entries(definitions ?? {}).filter(([, entry]) => isGrantable(entry)));
+}
+/**
+ * Permissions that were split into narrower ones, and what each stood for.
+ *
+ * A policy, an agent token or an app grant written before the split still
+ * names the old permission; it is read as all of the new ones, so nobody loses
+ * an ability on upgrade. New writing should name the new permissions.
+ */
+export const RETIRED_PERMISSIONS = new Map([
+    // #1638: one name per action — create, extend and revoke are separate.
+    ['share-manage', ['share-create', 'share-extend', 'share-revoke']],
+    // #2038: renamed (identity model, step 3); the old names are read for one release only.
+    ['contact-read', ['identity-read']],
+    ['contact-manage', ['identity-manage']]
+]);
+/** The names with every retired permission replaced by what it stood for, de-duplicated, order kept. */
+export function withRetiredExpanded(names) {
+    const out = [];
+    for (const name of names) {
+        for (const n of RETIRED_PERMISSIONS.get(name) ?? [name]) {
+            if (!out.includes(n))
+                out.push(n);
+        }
+    }
+    return out;
+}
+/**
+ * What the standard OpenID Connect sign-in scopes let an app see, in plain
+ * words (#1572). They are not permissions, so they are not in the catalog;
+ * this is their one declaration — the consent page and the "My tokens and
+ * devices" list both read it through `describeScopes`.
+ */
+export const SIGN_IN_SCOPE_LABELS = {
+    openid: 'Confirm who you are (your username)',
+    profile: 'Your name',
+    email: 'Your email address',
+    address: 'Your postal address',
+    phone: 'Your phone number',
+    offline_access: 'Stay connected while you are not using it, until you revoke it'
+};
+/**
+ * A permission entry in plain words (#1764): its `label` — the end-user line
+ * shown wherever a person reads what a permission does — else its
+ * `description` (an add-on that declares no label), else nothing.
+ */
+export function permissionLabel(entry) {
+    if (!entry || typeof entry !== 'object')
+        return null;
+    const { label, description } = entry;
+    if (typeof label === 'string' && label.trim())
+        return label;
+    if (typeof description === 'string' && description.trim())
+        return description;
+    return null;
+}
+/**
+ * Scope or permission names in plain words (#1764), in order, without
+ * repeats: a sign-in scope by `SIGN_IN_SCOPE_LABELS`, a permission by
+ * `permissionLabel` of its catalog entry. A name declared nowhere (an app's
+ * own scope, such as a host's `patient/*.read`) is shown as itself.
+ */
+export function describeScopes(names, definitions) {
+    const catalog = definitions && typeof definitions === 'object' && !Array.isArray(definitions) ? definitions : {};
+    const out = [];
+    const seen = new Set();
+    for (const name of names) {
+        if (!name || seen.has(name))
+            continue;
+        seen.add(name);
+        const description = Object.hasOwn(SIGN_IN_SCOPE_LABELS, name)
+            ? SIGN_IN_SCOPE_LABELS[name]
+            : (Object.hasOwn(catalog, name) ? permissionLabel(catalog[name]) : null);
+        out.push({ name, description: description ?? name });
+    }
+    return out;
+}

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

@@ -38,6 +38,16 @@ export interface VaultDecider {
         permit: boolean;
     }>;
 }
+/** The PDP surface {@link holdsInVault} needs. */
+export interface VaultHolder {
+    holds(subject: unknown, action: string, on: {
+        resource: {
+            type: string;
+            id: string;
+        };
+        attributes: Record<string, unknown>;
+    }): Promise<boolean>;
+}
 export declare function mayActInPrivateContainer(ctx: ActorContext, owner: string, opts?: {
     vault?: string;
 }): boolean;
@@ -49,9 +59,24 @@ export declare function mayActInPrivateContainer(ctx: ActorContext, owner: strin
  * vault page's name, or a file in the vault); it never matches `page: *`, so a
  * site-wide role does not reach in. The one rule for vault pages
  * (`BaseContext.hasPermissionOn`) and vault files (`AttachmentManager`).
+ *
+ * A shared folder (#2125) is asked by permission instead:
+ * `shared-folder-read` or `shared-folder-file` on the folder
+ * (`permitsInSharedFolder`), never the vault policy.
  */
 export declare function permitsInVault(pdp: VaultDecider | null | undefined, ctx: ActorContext, action: string, where: {
     owner: string;
     vault: string;
     resource: string;
 }): Promise<boolean>;
+/**
+ * Does `ctx` HOLD `action` inside `owner`'s vault (#2120)? {@link permitsInVault}
+ * without the step-up rule, for an affordance, and to tell a refusal for a
+ * stale sign-in (answered with the step-up prompt) from a plain one. Shared
+ * folders are not asked: `permitsInVault` decides them by permission alone.
+ */
+export declare function holdsInVault(pdp: VaultHolder | null | undefined, ctx: ActorContext, action: string, where: {
+    owner: string;
+    vault: string;
+    resource: string;
+}): Promise<boolean>;

package/lib/src/utils/privateStoreAccess.js

@@ -27,8 +27,12 @@
 import { isJobContext } from '../context/ActorContext.js';
 import { shareNamesVault } from '../types/Share.js';
 import { mixesProxyWithDelegation, proxyCarries } from './proxyClaim.js';
+import { isSharedFolderOwner } from './privateStorePath.js';
+import { permitsInSharedFolder } from './sharedFolderAccess.js';
 export function mayActInPrivateContainer(ctx, owner, opts = {}) {
-    if (!owner)
+    // #2125: the shared folders' container has no owner who acts; a folder is
+    // decided by permission (`permitsInSharedFolder`), never by this rule.
+    if (!owner || isSharedFolderOwner(owner))
         return false;
     // #1762: a proxy's subject carries the represented person's username, so
     // the owner test below would admit it unasked. It gets in only when the
@@ -55,9 +59,26 @@ export function mayActInPrivateContainer(ctx, owner, opts = {}) {
  * vault page's name, or a file in the vault); it never matches `page: *`, so a
  * site-wide role does not reach in. The one rule for vault pages
  * (`BaseContext.hasPermissionOn`) and vault files (`AttachmentManager`).
+ *
+ * A shared folder (#2125) is asked by permission instead:
+ * `shared-folder-read` or `shared-folder-file` on the folder
+ * (`permitsInSharedFolder`), never the vault policy.
  */
 export async function permitsInVault(pdp, ctx, action, where) {
+    if (isSharedFolderOwner(where.owner))
+        return permitsInSharedFolder(pdp, ctx, action, where.vault);
     if (!pdp || !mayActInPrivateContainer(ctx, where.owner, { vault: where.vault }))
         return false;
     return (await pdp.decide(ctx, { action, resource: { type: 'page', id: where.resource }, attributes: { vault: where.vault } })).permit;
 }
+/**
+ * Does `ctx` HOLD `action` inside `owner`'s vault (#2120)? {@link permitsInVault}
+ * without the step-up rule, for an affordance, and to tell a refusal for a
+ * stale sign-in (answered with the step-up prompt) from a plain one. Shared
+ * folders are not asked: `permitsInVault` decides them by permission alone.
+ */
+export async function holdsInVault(pdp, ctx, action, where) {
+    if (isSharedFolderOwner(where.owner) || typeof pdp?.holds !== 'function' || !mayActInPrivateContainer(ctx, where.owner, { vault: where.vault }))
+        return false;
+    return pdp.holds(ctx, action, { resource: { type: 'page', id: where.resource }, attributes: { vault: where.vault } });
+}

package/lib/src/utils/privateStoreCatalogs.js

@@ -0,0 +1,57 @@
+/**
+ * The encrypted user-level page catalog (#1385, epic #1382).
+ *
+ * `user-index.json` is wrapped with the user KEK; login decrypts it into the
+ * process session bag. Global `page-index.json` never receives sealed-store
+ * titles.
+ *
+ * What is left here is a MIGRATION path, not a live index: a store keeps its
+ * own page index (#1456), its own search index (#1458) and its own trash
+ * (#1459), and `adoptUserPageCatalog` moves what this file still holds into
+ * them and deletes it. The sibling `user-versions.json` and `user-trash.json`
+ * catalogs this module also wrote were never read by anything and went with
+ * #1459.
+ */
+import fs from 'fs-extra';
+import { writeFileAtomic } from './atomicWrite.js';
+import { decryptJson, encryptJson } from './privateStoreCrypto.js';
+import { privateUserIndexPath, privateUserDir } from './privateStorePath.js';
+function looksLikeWrap(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const blob = value;
+    return typeof blob.iv === 'string' && typeof blob.tag === 'string' && typeof blob.ct === 'string';
+}
+export function emptyUserCatalog() {
+    return { version: 1, pages: {} };
+}
+export async function readUserCatalog(pagesDirectory, username, kek) {
+    const file = privateUserIndexPath(pagesDirectory, username);
+    if (!await fs.pathExists(file))
+        return emptyUserCatalog();
+    const raw = await fs.readJson(file);
+    if (!raw || typeof raw !== 'object')
+        return emptyUserCatalog();
+    const rec = raw;
+    if (rec.version !== 1 || !looksLikeWrap(rec.wrap))
+        return emptyUserCatalog();
+    const payload = decryptJson(kek, rec.wrap);
+    if (!payload || payload.version !== 1 || !payload.pages || typeof payload.pages !== 'object') {
+        return emptyUserCatalog();
+    }
+    return payload;
+}
+export async function writeUserCatalog(pagesDirectory, username, kek, catalog) {
+    await fs.ensureDir(privateUserDir(pagesDirectory, username));
+    const file = {
+        version: 1,
+        wrap: encryptJson(kek, catalog)
+    };
+    await writeFileAtomic(privateUserIndexPath(pagesDirectory, username), JSON.stringify(file, null, 2), 'utf8');
+}
+export async function upsertUserIndexPage(pagesDirectory, username, kek, page) {
+    const catalog = await readUserCatalog(pagesDirectory, username, kek);
+    catalog.pages[page.uuid] = page;
+    await writeUserCatalog(pagesDirectory, username, kek, catalog);
+    return catalog;
+}

package/lib/src/utils/privateStoreCrypto.js

@@ -0,0 +1,266 @@
+/**
+ * Private-store crypto (#1384, epic #1382).
+ *
+ * Random user KEK, wrapped by the login password and by a BIP39 12-word
+ * phrase. Each encrypted store has its own DEK wrapped by that KEK.
+ * Not on PageManager — see docs/private-stores.md.
+ */
+import { createCipheriv, createDecipheriv, createHash, timingSafeEqual, pbkdf2Sync, randomBytes, scrypt } from 'crypto';
+import { BIP39_ENGLISH } from './bip39English.js';
+import { newLinkKeyPair, openLockbox, parseLinkPublicKey, sealForLink } from './shareLockbox.js';
+export const mnemonicWordCount = 12;
+/** Production wrap cost — same ballpark as login hashes. */
+export const PRIVATE_STORE_KDF = { N: 16384, r: 8, p: 1 };
+/** Unit tests only — still a valid scrypt N, cheap enough for the suite. */
+export const TEST_PRIVATE_STORE_KDF = { N: 16, r: 8, p: 1 };
+const KEYLEN = 32;
+const IVLEN = 12;
+function maxmem(kdf) {
+    return 128 * kdf.N * kdf.r * 4;
+}
+function wrap(key, plaintext) {
+    const iv = randomBytes(IVLEN);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return {
+        iv: iv.toString('base64'),
+        tag: cipher.getAuthTag().toString('base64'),
+        ct: ct.toString('base64')
+    };
+}
+function unwrap(key, blob, kind) {
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(blob.iv, 'base64'));
+        decipher.setAuthTag(Buffer.from(blob.tag, 'base64'));
+        return Buffer.concat([
+            decipher.update(Buffer.from(blob.ct, 'base64')),
+            decipher.final()
+        ]);
+    }
+    catch {
+        if (kind === 'password')
+            throw new Error('password does not unwrap the user KEK');
+        if (kind === 'recovery')
+            throw new Error('recovery phrase does not unwrap the user KEK');
+        if (kind === 'catalog')
+            throw new Error('cannot decrypt catalog');
+        if (kind === 'person')
+            throw new Error('cannot unwrap the person key');
+        throw new Error('cannot unwrap store DEK');
+    }
+}
+/** Off the main thread (#1632): a sign-in that unlocks stores never stalls other requests. */
+function derivePasswordKey(password, salt, kdf) {
+    return new Promise((resolve, reject) => {
+        scrypt(password, salt, KEYLEN, { N: kdf.N, r: kdf.r, p: kdf.p, maxmem: maxmem(kdf) }, (err, key) => (err ? reject(err) : resolve(key)));
+    });
+}
+function normalizeMnemonic(mnemonic) {
+    return mnemonic.normalize('NFKD').trim().toLowerCase().split(/\s+/).join(' ');
+}
+function mnemonicToWrapKey(mnemonic) {
+    const seed = pbkdf2Sync(normalizeMnemonic(mnemonic), 'mnemonic', 2048, 64, 'sha512');
+    return seed.subarray(0, KEYLEN);
+}
+function entropyToMnemonic(entropy) {
+    if (entropy.length !== 16)
+        throw new Error('12-word BIP39 uses 128 bits of entropy');
+    const checksum = createHash('sha256').update(entropy).digest()[0] >> 4;
+    let bits = '';
+    for (const byte of entropy)
+        bits += byte.toString(2).padStart(8, '0');
+    bits += checksum.toString(2).padStart(4, '0');
+    const words = [];
+    for (let i = 0; i < mnemonicWordCount; i++) {
+        const idx = Number.parseInt(bits.slice(i * 11, i * 11 + 11), 2);
+        words.push(BIP39_ENGLISH[idx]);
+    }
+    return words.join(' ');
+}
+export async function createUserKeys(password, opts = {}) {
+    const kdf = opts.kdf ?? PRIVATE_STORE_KDF;
+    const kek = randomBytes(KEYLEN);
+    const passwordSalt = randomBytes(16);
+    const mnemonic = entropyToMnemonic(randomBytes(16));
+    return {
+        kek,
+        mnemonic,
+        envelope: {
+            version: 1,
+            kdf: { ...kdf, salt: passwordSalt.toString('base64') },
+            passwordWrap: wrap(await derivePasswordKey(password, passwordSalt, kdf), kek),
+            recoveryKdf: { alg: 'bip39-pbkdf2' },
+            recoveryWrap: wrap(mnemonicToWrapKey(mnemonic), kek),
+            personKey: await newPersonKey(kek)
+        }
+    };
+}
+/** A fresh key pair for a person (#1762 slice 5), its private half wrapped under their KEK. */
+export async function newPersonKey(kek) {
+    const pair = await newLinkKeyPair();
+    const secret = Buffer.from(pair.linkKey, 'utf8');
+    try {
+        return { publicKey: pair.publicKey, privateWrap: wrap(kek, secret) };
+    }
+    finally {
+        secret.fill(0);
+    }
+}
+/** The public half of a person's key pair, checked strictly; null when they have none. */
+export function personPublicKey(envelope) {
+    return parseLinkPublicKey(envelope.personKey?.publicKey);
+}
+/**
+ * Seal a copy of `kek` to `recipient`'s public key (#1762 slice 5): the copy a
+ * proxy grant carries. Only the recipient's private key opens it.
+ */
+export function sealKekCopy(recipient, kek) {
+    return sealForLink(recipient, kek);
+}
+/**
+ * Open a KEK copy sealed to this person (#1762 slice 5): `ownKek` unwraps
+ * their private key from `envelope`, which opens `copy`. Throws when any step
+ * fails; the private key never leaves this function.
+ */
+export async function openKekCopy(envelope, ownKek, copy) {
+    if (!envelope.personKey)
+        throw new Error('cannot unwrap the person key');
+    const secret = unwrap(ownKek, envelope.personKey.privateWrap, 'person');
+    let opened;
+    try {
+        opened = await openLockbox(secret.toString('utf8'), copy);
+        if (opened.length !== KEYLEN)
+            throw new Error('not a key copy');
+        return Buffer.from(opened);
+    }
+    catch {
+        throw new Error('cannot open the key copy');
+    }
+    finally {
+        secret.fill(0);
+        opened?.fill(0);
+    }
+}
+export async function unwrapKekWithPassword(envelope, password) {
+    const salt = Buffer.from(envelope.kdf.salt, 'base64');
+    const key = await derivePasswordKey(password, salt, envelope.kdf);
+    return unwrap(key, envelope.passwordWrap, 'password');
+}
+export function unwrapKekWithMnemonic(envelope, mnemonic) {
+    return unwrap(mnemonicToWrapKey(mnemonic), envelope.recoveryWrap, 'recovery');
+}
+/**
+ * A fresh set of 12 recovery words for a KEK that has not been committed yet
+ * (#1414): the store door's words screen, where a failed confirmation discards
+ * the words it showed and never re-shows them. The KEK and its password wrap
+ * are kept; only the recovery wrap is replaced.
+ */
+export function newRecoveryWords(kek) {
+    const mnemonic = entropyToMnemonic(randomBytes(16));
+    return { mnemonic, recoveryWrap: wrap(mnemonicToWrapKey(mnemonic), kek) };
+}
+/**
+ * Which set of recovery words an envelope holds (#1928), as a short id: a
+ * digest of the recovery wrap, which a new set of words replaces and nothing
+ * else changes (a password change or a new person key keep it). Reveals
+ * nothing about the words or the key; it is what a recorded "I saved my
+ * recovery words" is bound to, so a new set asks again.
+ */
+export function recoveryWordsId(envelope) {
+    const w = envelope.recoveryWrap;
+    return createHash('sha256').update(`${w.iv}.${w.tag}.${w.ct}`).digest('hex').slice(0, 32);
+}
+/** True when two phrases are the same 12 words, compared as the recovery wrap reads them. */
+export function sameMnemonic(entered, expected) {
+    const a = Buffer.from(normalizeMnemonic(entered));
+    const b = Buffer.from(normalizeMnemonic(expected));
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+export async function rewrapPassword(envelope, oldPassword, newPassword, opts = {}) {
+    return rewrapPasswordWithKek(envelope, await unwrapKekWithPassword(envelope, oldPassword), newPassword, opts);
+}
+/**
+ * Replace the password wrap, given the KEK itself (#1452): how the recovery
+ * words set a new password when the old one is forgotten. The KEK bytes and
+ * the recovery wrap are unchanged, so every store's wrapped DEK stays valid
+ * and the same words keep working.
+ */
+export async function rewrapPasswordWithKek(envelope, kek, newPassword, opts = {}) {
+    const kdf = opts.kdf ?? { N: envelope.kdf.N, r: envelope.kdf.r, p: envelope.kdf.p };
+    const passwordSalt = randomBytes(16);
+    return {
+        ...envelope,
+        kdf: { ...kdf, salt: passwordSalt.toString('base64') },
+        passwordWrap: wrap(await derivePasswordKey(newPassword, passwordSalt, kdf), kek)
+    };
+}
+export function createEncryptedStore(kek) {
+    const dek = randomBytes(KEYLEN);
+    return { encrypt: true, dekWrap: wrap(kek, dek) };
+}
+export function unwrapDek(kek, store) {
+    return unwrap(kek, store.dekWrap, 'DEK');
+}
+/** Encrypt a JSON value with the user KEK (user-index / versions / trash). */
+export function encryptJson(key, value) {
+    return wrap(key, Buffer.from(JSON.stringify(value), 'utf8'));
+}
+/** Decrypt a JSON value wrapped by {@link encryptJson}. */
+export function decryptJson(key, blob) {
+    const buf = unwrap(key, blob, 'catalog');
+    try {
+        return JSON.parse(buf.toString('utf8'));
+    }
+    catch {
+        throw new Error('cannot decrypt catalog');
+    }
+}
+/**
+ * A file in an encrypted store on disk (#1415): `SEALED_MAGIC`, then the IV,
+ * the GCM tag and the ciphertext. Binary, so page text and attachment bytes
+ * (#1400) share one format; the magic lets a reader tell a sealed file from a
+ * plaintext one without trying the key.
+ */
+const SEALED_MAGIC = Buffer.from('NGDPSEAL1', 'ascii');
+const TAGLEN = 16;
+/** True when `bytes` start with the sealed-file magic. */
+export function isSealedBytes(bytes) {
+    return bytes.length >= SEALED_MAGIC.length + IVLEN + TAGLEN
+        && bytes.subarray(0, SEALED_MAGIC.length).equals(SEALED_MAGIC);
+}
+/** Encrypt the bytes of one store file with the store DEK. */
+export function sealBytes(dek, plaintext) {
+    if (dek.length !== KEYLEN)
+        throw new Error('encrypted store is locked: missing DEK');
+    const iv = randomBytes(IVLEN);
+    const cipher = createCipheriv('aes-256-gcm', dek, iv);
+    const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return Buffer.concat([SEALED_MAGIC, iv, cipher.getAuthTag(), ct]);
+}
+/** Decrypt a store file written by {@link sealBytes}. */
+export function openBytes(dek, sealed) {
+    if (!isSealedBytes(sealed))
+        throw new Error('not a sealed store file');
+    const ivStart = SEALED_MAGIC.length;
+    const tagStart = ivStart + IVLEN;
+    const ctStart = tagStart + TAGLEN;
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', dek, sealed.subarray(ivStart, tagStart));
+        decipher.setAuthTag(sealed.subarray(tagStart, ctStart));
+        return Buffer.concat([decipher.update(sealed.subarray(ctStart)), decipher.final()]);
+    }
+    catch {
+        throw new Error('cannot open sealed store file');
+    }
+}
+/**
+ * Shared encrypt-on write gate. Callers pass the DEK from the session bag.
+ * Not a PageManager method.
+ */
+export function assertEncryptedStoreWritable(args) {
+    if (!args.encrypt)
+        return;
+    if (!args.dek || args.dek.length !== KEYLEN) {
+        throw new Error('encrypted store is locked: missing DEK');
+    }
+}

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

@@ -121,6 +121,16 @@ export declare function holdWordsForConfirmation(handle: string, args: {
 }): void;
 /** Whether this session is part-way through the words screen for `store`. */
 export declare function hasPendingWords(handle: string, username: string, store: string): boolean;
+/**
+ * The words this session is part-way through confirming for `store`, to
+ * download or print (#2144), or undefined: none, or they expired. Once
+ * confirmed or abandoned they are gone.
+ */
+export declare function pendingWordsOf(handle: string, username: string, store: string): {
+    words: string[];
+    madeAt: Date;
+    envelope: UserKeyEnvelope;
+} | undefined;
 export type ConfirmOutcome = {
     status: 'confirmed';
     kek: Buffer;