@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/utils/privateStorePath.js

@@ -0,0 +1,436 @@
+/**
+ * Private-store paths (#1383, epic #1382).
+ *
+ * On-disk join (law): resolved pages `storagedir` + `privateroot` + userid + storeid + file.
+ * That is `{pagesDirectory}/{privateroot}/{user}/{store}/…` — a segment under the
+ * existing pages directory (SLOW), not `${SLOW_STORAGE}/private` and not FAST_STORAGE.
+ * User catalogs (`user-index.json` and siblings) live in that same user dir.
+ *
+ * Helpers take an optional layout override so unit tests need no live engine.
+ *
+ * ## What a store holds, and where these names are set
+ *
+ * A store is self-contained: everything about its pages is inside it, so a
+ * takeout is "copy this directory" and nothing of it sits in a shared index.
+ *
+ * ```
+ * private/{user}/user-keys.json        the user's wrapped keys (#1414)
+ * private/{user}/user-index.json       legacy: read once at unlock, then removed (#1385, #1456)
+ * private/{user}/{store}/store.json    this store: its kind, encrypt, wrapped DEK (#1414)
+ * private/{user}/{store}/pages-index.json    its pages (#1456)
+ * private/{user}/{store}/files-index.json    its files (#1400)
+ * private/{user}/{store}/search-index.json   its saved search index (#1458)
+ * private/{user}/{store}/deleted-index.json  its trash (#1459)
+ * private/{user}/{store}/migrations.json     the one-time migrations it has had (#1457)
+ * private/{user}/{store}/{uuid}.md           a page
+ * private/{user}/{store}/versions/{uuid}/    that page's history
+ * private/{user}/{store}/deleted/{uuid}.md   a deleted page, until it is purged
+ * private/{user}/{store}/attachments/        its files (#1400)
+ * private/{user}/{store}/footnotes/{uuid}.json   a page's footnotes (#1839)
+ * private/{user}/{store}/comments/{uuid}/        a page's comments (#1839)
+ * ```
+ *
+ * Every one of those names is DEFINED HERE, in
+ * {@link DEFAULT_PRIVATE_STORE_LAYOUT} — not in `config/app-default-config.json`.
+ * They are a disk convention this code owns, not a setting anyone tunes. An
+ * instance that must override one may still set the matching
+ * `ngdpbase.page.provider.filesystem.private.files.*` key (see
+ * {@link privateStoreLayoutFromConfig}); the default it overrides lives here.
+ *
+ * Every file but `store.json` is written through the store's `StoreFileIO`, so
+ * it is ciphertext at rest exactly when the store is encrypted. `store.json` is
+ * the one that cannot be: it holds the wrapped key needed to open the rest.
+ */
+import path from 'path';
+export const DEFAULT_PRIVATE_STORE_LAYOUT = {
+    privateRoot: 'vaults',
+    defaultStoreId: 'default',
+    versionsDir: 'versions',
+    deletedDir: 'deleted',
+    attachmentsDir: 'attachments',
+    footnotesDir: 'footnotes',
+    commentsDir: 'comments',
+    files: {
+        userkeys: 'user-keys.json',
+        userindex: 'user-index.json',
+        storemeta: 'store.json',
+        storefiles: 'files-index.json',
+        storepages: 'pages-index.json',
+        storesearch: 'search-index.json',
+        storemigrations: 'migrations.json',
+        storedeleted: 'deleted-index.json'
+    },
+    sealedVaults: []
+};
+export const DEFAULT_PRIVATE_STORE = DEFAULT_PRIVATE_STORE_LAYOUT.defaultStoreId;
+export const STORE_META_FILENAME = DEFAULT_PRIVATE_STORE_LAYOUT.files.storemeta;
+export function resolvePrivateStoreLayout(overrides) {
+    if (!overrides)
+        return DEFAULT_PRIVATE_STORE_LAYOUT;
+    return {
+        privateRoot: overrides.privateRoot ?? DEFAULT_PRIVATE_STORE_LAYOUT.privateRoot,
+        defaultStoreId: overrides.defaultStoreId ?? DEFAULT_PRIVATE_STORE_LAYOUT.defaultStoreId,
+        versionsDir: overrides.versionsDir ?? DEFAULT_PRIVATE_STORE_LAYOUT.versionsDir,
+        deletedDir: overrides.deletedDir ?? DEFAULT_PRIVATE_STORE_LAYOUT.deletedDir,
+        attachmentsDir: overrides.attachmentsDir ?? DEFAULT_PRIVATE_STORE_LAYOUT.attachmentsDir,
+        footnotesDir: overrides.footnotesDir ?? DEFAULT_PRIVATE_STORE_LAYOUT.footnotesDir,
+        commentsDir: overrides.commentsDir ?? DEFAULT_PRIVATE_STORE_LAYOUT.commentsDir,
+        files: {
+            ...DEFAULT_PRIVATE_STORE_LAYOUT.files,
+            ...overrides.files
+        },
+        sealedVaults: overrides.sealedVaults ?? DEFAULT_PRIVATE_STORE_LAYOUT.sealedVaults
+    };
+}
+/** The user-level catalog filenames from layout (not a second hardcoded list). */
+export function privateUserCatalogFiles(layout) {
+    const files = resolvePrivateStoreLayout(layout).files;
+    return new Set([files.userkeys, files.userindex]);
+}
+export const PRIVATE_USER_CATALOG_FILES = privateUserCatalogFiles();
+/**
+ * A system-category's vault, read from its `storageLocation.privatestore`
+ * (#1504): `pages/vaults/{user}/journal/` → `{ root: 'vaults', vaultId: 'journal' }`.
+ * The shape is fixed — `pages/`, the vaults' parent folder, the `{user}`
+ * placeholder, the vault id — and `null` for anything else, so a malformed
+ * entry never names a folder.
+ */
+export function parsePrivatestore(value) {
+    if (typeof value !== 'string')
+        return null;
+    const parts = value.replace(/\/$/, '').split('/');
+    if (parts.length !== 4 || parts[0] !== 'pages' || parts[2] !== '{user}')
+        return null;
+    const [, root, , vaultId] = parts;
+    if (!isSafePathSegment(root) || !isValidStoreId(vaultId))
+        return null;
+    return { root, vaultId };
+}
+/** The entries of `ngdpbase.system-category` that declare a vault, in config order. */
+export function systemCategoryVaults(categories) {
+    if (!categories || typeof categories !== 'object')
+        return [];
+    const vaults = [];
+    for (const [key, entry] of Object.entries(categories)) {
+        const e = entry;
+        const parsed = parsePrivatestore(e?.storageLocation?.privatestore);
+        // `encrypt` is read as the boolean it is and nothing else: a string "true" is not a switch.
+        if (parsed)
+            vaults.push({ key, ...parsed, isDefault: e?.default === true, encrypt: e?.encrypt === true });
+    }
+    return vaults;
+}
+/**
+ * The vault ids whose kind is sealed (#1834). Where two entries name the
+ * same vault, the first is the kind, as `storeKindFromConfig` reads it.
+ */
+function sealedVaultIds(vaults) {
+    const seen = new Set();
+    const sealed = [];
+    for (const v of vaults) {
+        if (seen.has(v.vaultId))
+            continue;
+        seen.add(v.vaultId);
+        if (v.encrypt)
+            sealed.push(v.vaultId);
+    }
+    return sealed;
+}
+export function privateStoreLayoutFromConfig(getProperty) {
+    const str = (key, fallback) => {
+        const value = getProperty(key, fallback);
+        return typeof value === 'string' && value.length > 0 ? value : fallback;
+    };
+    const d = DEFAULT_PRIVATE_STORE_LAYOUT;
+    // #1504: where the vaults live, and which one is a person's ordinary vault,
+    // are said once — by the system-category entries' privatestore — not by
+    // settings of their own. Startup refuses entries that disagree on the parent
+    // (ValidationManager), so the first vault's parent is every vault's.
+    const vaults = systemCategoryVaults(getProperty('ngdpbase.system-category', ''));
+    return {
+        privateRoot: vaults[0]?.root ?? d.privateRoot,
+        defaultStoreId: vaults.find((v) => v.isDefault)?.vaultId ?? d.defaultStoreId,
+        versionsDir: str('ngdpbase.page.provider.filesystem.versionsdir', d.versionsDir),
+        deletedDir: str('ngdpbase.page.provider.filesystem.deleteddir', d.deletedDir),
+        attachmentsDir: str('ngdpbase.page.provider.filesystem.attachmentsdir', d.attachmentsDir),
+        footnotesDir: str('ngdpbase.page.provider.filesystem.footnotesdir', d.footnotesDir),
+        commentsDir: str('ngdpbase.page.provider.filesystem.commentsdir', d.commentsDir),
+        files: {
+            userkeys: str('ngdpbase.page.provider.filesystem.private.files.userkeys', d.files.userkeys),
+            userindex: str('ngdpbase.page.provider.filesystem.private.files.userindex', d.files.userindex),
+            storemeta: str('ngdpbase.page.provider.filesystem.private.files.storemeta', d.files.storemeta),
+            storefiles: str('ngdpbase.page.provider.filesystem.private.files.storefiles', d.files.storefiles),
+            storepages: str('ngdpbase.page.provider.filesystem.private.files.storepages', d.files.storepages),
+            storesearch: str('ngdpbase.page.provider.filesystem.private.files.storesearch', d.files.storesearch),
+            storemigrations: str('ngdpbase.page.provider.filesystem.private.files.storemigrations', d.files.storemigrations),
+            storedeleted: str('ngdpbase.page.provider.filesystem.private.files.storedeleted', d.files.storedeleted)
+        },
+        sealedVaults: sealedVaultIds(vaults)
+    };
+}
+/** A store id is a plain slug — an addon slug or `default` — never a path (#1383). */
+const STORE_ID_SOURCE = '[a-z0-9]+(?:-[a-z0-9]+)*';
+const STORE_ID_PATTERN = new RegExp(`^${STORE_ID_SOURCE}$`);
+export function isValidStoreId(store) {
+    return STORE_ID_PATTERN.test(store);
+}
+/**
+ * A private page's name (#1456, operator 2026-09-22): `vaults/{owner}/{store}/{title}` —
+ * the same string as its URL without the leading slash. Wherever the system
+ * passes a page name, a private page is named this way; a plain title always
+ * means a public page. Titles never contain `/` (#1455), so the parts are
+ * unambiguous. Was `private/` until #1506.
+ */
+export const PRIVATE_PAGE_NAME_PREFIX = 'vaults/';
+/** The first path segment of a private page's URL: `/vaults/{owner}/{store}/{title}`. */
+export const PRIVATE_URL_SEGMENT = PRIVATE_PAGE_NAME_PREFIX.slice(0, -1);
+/**
+ * The vault parent folder, page-name prefix and URL segment before #1506
+ * (operator, 2026-09-28): `pages/private/`, `private/{owner}/{store}/{title}`,
+ * `/private/…`. Read only by the one-time move to `vaults` and by the things
+ * that must never mistake a leftover `private/` folder for public pages.
+ */
+export const LEGACY_PRIVATE_ROOT = 'private';
+/**
+ * The reserved start of a private page's slug: `vaults--{owner}-{vault}-{title}`.
+ * No public slug contains `--`, so the two can never collide. Was `private--`
+ * until #1507 (operator, 2026-09-29), for the same reason the page name moved
+ * from `private/` to `vaults/` in #1506.
+ */
+export const PRIVATE_SLUG_PREFIX = 'vaults--';
+export function formatPrivatePageName(owner, store, title) {
+    return `${PRIVATE_PAGE_NAME_PREFIX}${owner}/${store}/${title}`;
+}
+/** The parts of a private page name, or null when `name` is not one. */
+export function parsePrivatePageName(name) {
+    if (typeof name !== 'string' || !name.startsWith(PRIVATE_PAGE_NAME_PREFIX))
+        return null;
+    const parts = name.slice(PRIVATE_PAGE_NAME_PREFIX.length).split('/');
+    if (parts.length !== 3)
+        return null;
+    const [owner, store, title] = parts;
+    if (!owner || !isSafePathSegment(owner) || !isValidStoreId(store) || !title.trim())
+        return null;
+    return { owner, store, title };
+}
+/**
+ * The name a page an identifier opened is known by: its title — the
+ * identifier may be a uuid or slug, and every downstream index is keyed by
+ * title — or, for a vault page, its vault name (#1539). A vault page's bare
+ * title is a PUBLIC page's name, so the door would judge, and a write would
+ * hit, a different page.
+ */
+export function canonicalPageName(identifier, metadata) {
+    const privateName = parsePrivatePageName(identifier);
+    return privateName
+        ? formatPrivatePageName(privateName.owner, privateName.store, metadata?.title || privateName.title)
+        : metadata?.title || identifier;
+}
+/**
+ * A private page's LINK target, written inside brackets as `{store}/{Title}`
+ * (#1457). The store belongs to the owner of the page the link sits in, so the
+ * target names no user — {@link formatPrivatePageName} supplies the owner.
+ *
+ * `null` for anything else, including a target whose first segment is not a
+ * store id (`Docs/Setup`) and one with a second `/`: titles never contain one
+ * (#1455), so a deeper path is not a private page.
+ */
+export function parsePrivateLinkTarget(target) {
+    const slash = target.indexOf('/');
+    if (slash <= 0)
+        return null;
+    const store = target.slice(0, slash);
+    const title = target.slice(slash + 1);
+    if (!isValidStoreId(store) || !title.trim() || title.includes('/'))
+        return null;
+    return { store, title };
+}
+/**
+ * Could this content hold a `[store/Title]` link? A cheap pre-test so only a
+ * page that may carry one pays for the owner lookup a render needs (#1457).
+ * Non-global, so it is stateless and safe to share.
+ */
+const PRIVATE_LINK_CANDIDATE = new RegExp(`\\[(?:[^|\\]\\n]*\\|)?${STORE_ID_SOURCE}/[^\\]\\n]+\\]`);
+export function mayContainPrivateLink(content) {
+    return PRIVATE_LINK_CANDIDATE.test(content);
+}
+/** Refuse a store id that is not a plain slug. Every join below runs it. */
+export function assertStoreId(store) {
+    if (!isValidStoreId(store)) {
+        throw new Error(`Invalid private store id ${JSON.stringify(store)}: must be a lowercase slug`);
+    }
+    return store;
+}
+/**
+ * A user folder or file name is exactly one path segment. Usernames have no
+ * enforced shape, so this refuses only what could leave the folder: empty,
+ * `.`, `..`, a separator, or NUL.
+ */
+export function isSafePathSegment(segment) {
+    return segment.length > 0 && segment !== '.' && segment !== '..' && !/[/\\\0]/.test(segment);
+}
+export function assertPathSegment(segment, what) {
+    if (!isSafePathSegment(segment)) {
+        throw new Error(`Invalid private store ${what} ${JSON.stringify(segment)}: must be one path segment`);
+    }
+    return segment;
+}
+function pageBasename(uuidOrBasename) {
+    return assertPathSegment(uuidOrBasename.endsWith('.md') ? uuidOrBasename : `${uuidOrBasename}.md`, 'file name');
+}
+export function privatePageFilePath(pagesDirectory, creator, uuidOrBasename, store, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    const storeId = store ?? L.defaultStoreId;
+    return path.join(pagesDirectory, L.privateRoot, assertPathSegment(creator, 'user'), assertStoreId(storeId), pageBasename(uuidOrBasename));
+}
+export function privateUserDir(pagesDirectory, username, layout) {
+    return path.join(pagesDirectory, resolvePrivateStoreLayout(layout).privateRoot, assertPathSegment(username, 'user'));
+}
+export function privateUserKeysPath(pagesDirectory, username, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateUserDir(pagesDirectory, username, L), L.files.userkeys);
+}
+export function privateUserIndexPath(pagesDirectory, username, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateUserDir(pagesDirectory, username, L), L.files.userindex);
+}
+export function privateStoreRoot(pagesDirectory, creator, store, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateUserDir(pagesDirectory, creator, L), assertStoreId(store ?? L.defaultStoreId));
+}
+/**
+ * Folder for a store's non-page files: `{privateroot}/{user}/{store}/{attachmentsdir}` (#1386).
+ * Never the store root — an uploaded `.md` there would scan as a page.
+ */
+export function privateStoreAttachmentsDir(pagesDirectory, creator, store, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateStoreRoot(pagesDirectory, creator, store, L), L.attachmentsDir);
+}
+/** Non-page file in `{privateroot}/{user}/{store}/{attachmentsdir}/{file}` (#1386). */
+export function privateStoreFilePath(pagesDirectory, creator, fileName, store, layout) {
+    return path.join(privateStoreAttachmentsDir(pagesDirectory, creator, store, layout), assertPathSegment(fileName, 'file name'));
+}
+/**
+ * True when `relParts` (path relative to the pages directory, split) names a
+ * store's attachments folder: `{privateroot}/{user}/{store}/{attachmentsdir}`.
+ * Depth-checked so a user or store that happens to be called `attachments` is not skipped.
+ */
+export function isPrivateStoreAttachmentsRel(relParts, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return relParts.length === 4 && relParts[0] === L.privateRoot && relParts[3] === L.attachmentsDir;
+}
+export function storeMetaPath(pagesDirectory, creator, store, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateStoreRoot(pagesDirectory, creator, store, L), L.files.storemeta);
+}
+/** A store's own file index: `{privateroot}/{user}/{store}/{storefiles}` (#1400). */
+export function storeFileIndexPath(pagesDirectory, creator, store, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateStoreRoot(pagesDirectory, creator, store, L), L.files.storefiles);
+}
+/** A store's own page index: `{privateroot}/{user}/{store}/{storepages}` (#1456). */
+export function storePageIndexPath(pagesDirectory, creator, store, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateStoreRoot(pagesDirectory, creator, store, L), L.files.storepages);
+}
+/** A store's own saved search index: `{privateroot}/{user}/{store}/{storesearch}` (#1458). */
+export function storeSearchIndexPath(pagesDirectory, creator, store, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateStoreRoot(pagesDirectory, creator, store, L), L.files.storesearch);
+}
+/**
+ * A store's own trash record: `{privateroot}/{user}/{store}/{storedeleted}` (#1459).
+ *
+ * Beside the store's other indexes, so it is sealed exactly when the store is
+ * and travels with it — a deleted private page leaves no trace outside its own
+ * store, not in the global trash and not in `page-index.json`.
+ */
+export function storeDeletedIndexPath(pagesDirectory, creator, store, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateStoreRoot(pagesDirectory, creator, store, L), L.files.storedeleted);
+}
+/** A store's record of the one-time migrations it has had (#1457). */
+export function storeMigrationsPath(pagesDirectory, creator, store, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateStoreRoot(pagesDirectory, creator, store, L), L.files.storemigrations);
+}
+export function privateVersionDirectory(pagesDirectory, creator, uuid, store, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateStoreRoot(pagesDirectory, creator, store, L), L.versionsDir, assertPathSegment(uuid, 'page id'));
+}
+/**
+ * Where a vault page's footnotes or comments are kept (#1839): a folder of
+ * the vault, `{privateroot}/{user}/{store}/{footnotesDir|commentsDir}`, so
+ * they are written through the vault's store I/O and sealed exactly when its
+ * pages are. A public page's are in the managers' own folders.
+ */
+export function privateStoreNotesDir(pagesDirectory, creator, store, kind, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateStoreRoot(pagesDirectory, creator, store, L), kind === 'footnotes' ? L.footnotesDir : L.commentsDir);
+}
+export function privateDeletedDirectory(pagesDirectory, creator, store, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(privateStoreRoot(pagesDirectory, creator, store, L), L.deletedDir);
+}
+/** Pre-#1383 live file: `{pages}/{privateroot}/{user}/{file}.md`. */
+export function legacyPrivatePageFilePath(pagesDirectory, creator, uuidOrBasename, layout) {
+    return path.join(privateUserDir(pagesDirectory, creator, layout), pageBasename(uuidOrBasename));
+}
+/** Legacy `pages/versions/private` = join(versionsdir, privateroot). No extra key. */
+export function legacyPrivateVersionsRoot(pagesDirectory, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    return path.join(pagesDirectory, L.versionsDir, L.privateRoot);
+}
+/**
+ * True when `filePath` is inside the private root of `pagesDirectory`. Measured
+ * from the pages directory, not by searching the absolute path for `/private/`
+ * — which matched every page on a host whose data sits under `/private/var`
+ * or `/private/tmp` (macOS).
+ */
+export function pathContainsPrivateRoot(pagesDirectory, filePath, layout) {
+    return isUnderPrivateRoot(path.relative(pagesDirectory, filePath).split(path.sep), layout);
+}
+/**
+ * Relative path from the pages directory, split on the platform separator.
+ * `{privateroot}/{user}/{store}/{file}.md` → store layout.
+ * `{privateroot}/{user}/{file}.md` → legacy layout (pre-#1383).
+ *
+ * `null` for anything else, including a store folder whose name is not a valid
+ * store id. A caller that finds `null` for a path under the private root must
+ * skip the file, never treat it as a public page ({@link isUnderPrivateRoot}).
+ */
+export function parsePrivatePageRel(relParts, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    if (relParts[0] !== L.privateRoot)
+        return null;
+    const last = relParts[relParts.length - 1];
+    if (!last || !last.toLowerCase().endsWith('.md'))
+        return null;
+    if (!isSafePathSegment(relParts[1] ?? ''))
+        return null;
+    if (relParts.length === 4) {
+        return isValidStoreId(relParts[2]) ? { creator: relParts[1], store: relParts[2] } : null;
+    }
+    if (relParts.length === 3) {
+        return { creator: relParts[1], store: L.defaultStoreId };
+    }
+    return null;
+}
+/**
+ * The store that holds a file at any depth — the live page, a version blob,
+ * a trash record or an attachment: `{privateroot}/{user}/{store}/…`. `null`
+ * for a file that is not inside a store, including the user-level catalogues
+ * beside the stores (#1415).
+ */
+export function parsePrivateStoreRel(relParts, layout) {
+    const L = resolvePrivateStoreLayout(layout);
+    if (relParts.length < 4 || relParts[0] !== L.privateRoot)
+        return null;
+    if (!isSafePathSegment(relParts[1]) || !isValidStoreId(relParts[2]))
+        return null;
+    return { creator: relParts[1], store: relParts[2] };
+}
+/** True when a path relative to the pages directory is inside the private root. */
+export function isUnderPrivateRoot(relParts, layout) {
+    return relParts[0] === resolvePrivateStoreLayout(layout).privateRoot;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * 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 { type PrivateStoreLayoutOverrides } from './privateStorePath.js';
+/** One file of a store, exactly as it sits on disk. */
+export type StoreFile = {
+    /** Path relative to what was walked, with `/` separators on every platform. */
+    path: string;
+    /** The file's bytes. Ciphertext stays ciphertext. */
+    bytes: Buffer;
+    /** Last-modified time, so a restore can preserve it. */
+    mtime: Date;
+};
+/** A store found on disk, and everything in it. */
+export type StoreTakeout = {
+    owner: string;
+    store: string;
+    /** Files of the store directory itself, relative to the store root. */
+    files: StoreFile[];
+    /** Total bytes, for a caller that wants to refuse an unreasonable download. */
+    totalBytes: number;
+};
+/**
+ * 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 declare function collectStore(pagesDirectory: string, owner: string, store: string, layout?: PrivateStoreLayoutOverrides): Promise<StoreTakeout>;
+/** The store ids a user has on disk, in directory order. */
+export declare function listStoreIds(pagesDirectory: string, owner: string, layout?: PrivateStoreLayoutOverrides): Promise<string[]>;
+/** The users who have a private directory on disk, in directory order. */
+export declare function listPrivateOwners(pagesDirectory: string, layout?: PrivateStoreLayoutOverrides): Promise<string[]>;
+/**
+ * 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 declare function collectUser(pagesDirectory: string, owner: string, layout?: PrivateStoreLayoutOverrides): Promise<{
+    owner: string;
+    userFiles: StoreFile[];
+    stores: StoreTakeout[];
+    totalBytes: number;
+}>;