@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,120 @@
+/**
+ * Reading and writing the bytes of a private store (#1415, epic #1382).
+ *
+ * The store DEK "encrypts every byte in `private/{user}/{store}/`"
+ * (docs/private-stores.md, Keys). This is the one place that turns
+ * that rule into file I/O: a caller asks for the store's {@link StoreFileIO}
+ * once, through its context, and every read and write it makes with it is
+ * ciphertext at rest when the store is encrypted. Providers do not decide the
+ * policy; they are handed an I/O that already carries it.
+ *
+ * `store.json` is the one file in a store that is never sealed — it holds the
+ * wrapped DEK needed to open the rest.
+ */
+import { type PrivateStoreLayout, type PrivateStoreLayoutOverrides } from './privateStorePath.js';
+import type { ActorContext } from '../context/ActorContext.js';
+export interface StoreFileIO {
+    /** True when this store's files are ciphertext at rest. */
+    readonly sealed: boolean;
+    readText(file: string, encoding?: BufferEncoding): Promise<string>;
+    writeText(file: string, text: string, encoding?: BufferEncoding): Promise<void>;
+    /** A store file's bytes — attachments (#1400) are binary, pages are text. */
+    readBytes(file: string): Promise<Buffer>;
+    writeBytes(file: string, bytes: Buffer): Promise<void>;
+}
+/** Files outside any encrypted store: read and written as they are. */
+export declare const PLAIN_FILE_IO: StoreFileIO;
+/**
+ * The I/O for `owner`'s `store`, as this context may use it. Plain for a store
+ * that is not encrypted; sealed with the store DEK when it is. An encrypted
+ * store whose DEK this context does not hold is refused — a read as much as a
+ * write, so a locked store never falls back to reading or writing in the clear.
+ *
+ * Whether the store is encrypted is asked of both its kind and its copy
+ * (#1834): `layout` is the configured one, whose `sealedVaults` are the kinds
+ * that are sealed. A vault of a sealed kind with no `store.json` (its door not
+ * yet opened) or a `store.json` that is not sealed is refused, read and write
+ * alike, with `SealedVaultRefusedError` — never handed plain I/O.
+ */
+export declare function storeFileIO(ctx: ActorContext | undefined, args: {
+    pagesDirectory: string;
+    owner: string;
+    store: string;
+    layout: PrivateStoreLayout;
+}): Promise<StoreFileIO>;
+/**
+ * Read one text file of `owner`'s `store` synchronously, as this context may:
+ * plain for a store that is not encrypted, opened with the store DEK when it
+ * is. Null when the file does not exist, or the store is encrypted and this
+ * context does not hold its DEK — a locked store reads as nothing, never in
+ * the clear (#1456: a store's page index is small, and page lookups are
+ * synchronous).
+ *
+ * A vault of a sealed kind that is not itself sealed (#1834) reads as nothing
+ * too, with a warning: its files, if any, were written in the clear and are
+ * not served as if they were sealed.
+ */
+export declare function readStoreTextSync(ctx: ActorContext | undefined, args: {
+    pagesDirectory: string;
+    owner: string;
+    store: string;
+    file: string;
+    layout: PrivateStoreLayout;
+}): string | null;
+/**
+ * Every store id in `owner`'s container, whether or not it can be opened (#1460).
+ *
+ * Which stores EXIST is a question about a folder, not about keys: an
+ * unencrypted store has no DEK for a session to hold, so
+ * `unlockedStoreIdsFor` — which answers from the session's key bag — can only
+ * ever name the encrypted ones. A caller that wants all of the owner's stores
+ * asks here and then opens each through {@link storeFileIO}, which refuses the
+ * encrypted ones it holds no key for.
+ *
+ * Empty for a user with no container. Nothing here decides access: the
+ * container rule (`mayActInPrivateContainer`) is the caller's to apply, as it
+ * is at the page door.
+ */
+export declare function privateStoreIdsOf(pagesDirectory: string, owner: string, layout?: PrivateStoreLayoutOverrides): Promise<string[]>;
+/** The I/O for whichever store holds `file`; plain for a file in no store. */
+export declare function storeFileIOForPath(ctx: ActorContext | undefined, args: {
+    pagesDirectory: string;
+    file: string;
+    layout: PrivateStoreLayout;
+}): Promise<StoreFileIO>;
+/** The vault `file` lies in — `{privateroot}/{owner}/{store}/…` — or null for a file in no vault. */
+export declare function vaultOfFile(pagesDirectory: string, file: string, layout: PrivateStoreLayout): {
+    owner: string;
+    store: string;
+} | null;
+/**
+ * Whether `owner`'s `store` holds, or must hold, only sealed bytes (#1836):
+ * its kind is sealed, or its `store.json` is. A `store.json` that cannot be
+ * read counts as sealed — the answer that never lets plaintext in.
+ *
+ * For the paths that put bytes into a vault without its store I/O (a backup
+ * restore, a legacy migration, a tombstone put back): they hold no DEK, so
+ * where this is true they write only bytes that are already sealed, or refuse.
+ */
+export declare function vaultMustBeSealed(pagesDirectory: string, owner: string, store: string, layout: PrivateStoreLayout): Promise<boolean>;
+/**
+ * Move a folder of store files — a page's history — from one place to another
+ * through each side's I/O (#1836): every file is read as its source stores it
+ * and written as its destination does, so history moved into a sealed vault
+ * is sealed with that vault's DEK, history moved out of one is opened, and a
+ * move between two sealed vaults is re-sealed. Two plain sides are a plain
+ * rename, as before.
+ *
+ * The copy is staged beside `toDir` and renamed into place only when every
+ * file is written, so a failure leaves the source whole and no half history
+ * at the destination. The source is removed last.
+ */
+export declare function moveStoreFolder(fromDir: string, toDir: string, fromIO: StoreFileIO, toIO: StoreFileIO): Promise<void>;
+/**
+ * Move one store file — a page's footnotes (#1839) — through each side's I/O,
+ * as {@link moveStoreFolder} moves a folder: read as its source stores it,
+ * written as its destination does, so a file moved into a sealed vault is
+ * sealed there and one moved out is opened. Two plain sides are a plain move.
+ * The destination is written (atomically) before the source is removed.
+ */
+export declare function moveStoreFile(fromFile: string, toFile: string, fromIO: StoreFileIO, toIO: StoreFileIO): Promise<void>;

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

@@ -0,0 +1,64 @@
+/**
+ * Per-store encrypt flag on disk (#1384).
+ *
+ * Lives on `pages/vaults/{user}/{store}/store.json`, not on PageManager.
+ * Missing file = encrypt off (`default/` stays plaintext unless enabled).
+ */
+import type { StoreKeyRecord } from './privateStoreCrypto.js';
+import { type PrivateStoreLayout, type PrivateStoreLayoutOverrides } from './privateStorePath.js';
+export declare function readStoreMeta(pagesDirectory: string, creator: string, store: string, layout?: PrivateStoreLayoutOverrides): Promise<StoreKeyRecord>;
+/**
+ * How a vault stands against its kind (#1834). The vault's `store.json` says
+ * whether this copy is sealed; the kind (the system-category's `encrypt`,
+ * carried in the layout as `sealedVaults`) says whether it must be.
+ *
+ * - `plain`: the kind is not sealed and the copy is not either.
+ * - `sealed`: the copy is sealed (`store.json` `encrypt: true`).
+ * - `unopened`: the kind is sealed and there is no `store.json` — the owner
+ *   has not walked through the vault door, so there is no key to seal with.
+ * - `mismatch`: the kind is sealed and `store.json` says the copy is not
+ *   (or cannot be read as sealed).
+ *
+ * Only `plain` and `sealed` may be read or written.
+ */
+export type VaultSealState = 'plain' | 'sealed' | 'unopened' | 'mismatch';
+export declare function kindIsSealed(layout: PrivateStoreLayoutOverrides, store: string): boolean;
+/** {@link VaultSealState} of `owner`'s `store`, with the record that decided it. */
+export declare function readVaultSealState(pagesDirectory: string, owner: string, store: string, layout: PrivateStoreLayout): Promise<{
+    state: VaultSealState;
+    meta: StoreKeyRecord;
+}>;
+/** The synchronous form of {@link readVaultSealState}, for synchronous page lookups. */
+export declare function readVaultSealStateSync(pagesDirectory: string, owner: string, store: string, layout: PrivateStoreLayout): VaultSealState;
+/**
+ * A read or write refused because the vault's kind is sealed and the vault
+ * is not (#1834). Never answered with plain I/O: the bytes would be clear on
+ * disk under a kind that says they are sealed.
+ */
+export declare class SealedVaultRefusedError extends Error {
+    readonly owner: string;
+    readonly store: string;
+    readonly reason: 'unopened' | 'mismatch';
+    readonly code = "sealed-vault-refused";
+    constructor(owner: string, store: string, reason: 'unopened' | 'mismatch');
+}
+/**
+ * Throw {@link SealedVaultRefusedError} for a state that may not be read or
+ * written, logging it: an unopened vault is the owner's next step (warn), a
+ * mismatch is the site's configuration and its disk disagreeing (error).
+ * Names the owner and vault, never a page or its content.
+ */
+export declare function refuseUnsealedVault(owner: string, store: string, state: VaultSealState): void;
+/** True when `dir` is a store directory with encrypt on (`store.json`). */
+export declare function storeDirectoryIsEncrypted(dir: string, metaFilename?: string): Promise<boolean>;
+/**
+ * `store.json` as the door writes it (#1414, docs/private-stores.md,
+ * "`store.json` shape"): the kind this copy was created under, whether this
+ * copy is sealed, when the user walked through the door, and the wrapped DEK
+ * when it is sealed. Per-user state and key material only — never policy.
+ */
+export type StoreFileRecord = StoreKeyRecord & {
+    kind?: string;
+    created?: string;
+};
+export declare function writeStoreMeta(pagesDirectory: string, creator: string, store: string, record: StoreFileRecord, layout?: PrivateStoreLayoutOverrides): Promise<void>;

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

@@ -0,0 +1,37 @@
+/**
+ * What a private store has already been migrated for (#1457, epic #1382).
+ *
+ * A one-time migration over private pages cannot ask a global record whether
+ * it has run: a store is self-contained (docs/private-stores.md), an
+ * encrypted one is unreadable until its owner unlocks it, and each store
+ * therefore reaches its migration at a different moment. So the record lives
+ * in the store, beside its own indexes — `{store}/migrations.json`, the shape
+ * `files-index.json` and `pages-index.json` already use — and says only which
+ * migrations this store has had and when. No page, title or count: the file
+ * is per-store state, and a count of somebody's pages is theirs.
+ *
+ * It is read and written through the store's own I/O, so a sealed store's
+ * record is ciphertext at rest like everything else in it but `store.json`.
+ * A store that has not been migrated has no file, which is the same answer as
+ * a file that cannot be read — the migration then runs again, and it is
+ * idempotent by construction (`rewriteToPrivateLinks`).
+ */
+import type { ActorContext } from '../context/ActorContext.js';
+import { type PrivateStoreLayout } from './privateStorePath.js';
+/** The link migration of #1457: `[Title]` → `[store/Title]` within a store. */
+export declare const PRIVATE_LINK_MIGRATION = "private-links";
+export interface StoreMigrationTarget {
+    pagesDirectory: string;
+    owner: string;
+    store: string;
+    layout: PrivateStoreLayout;
+}
+/**
+ * Has this store had the migration `id`?
+ *
+ * @returns false when the record is missing or unreadable — running a
+ *   migration a second time is safe, and skipping one that never ran is not.
+ */
+export declare function storeMigrationDone(ctx: ActorContext, where: StoreMigrationTarget, id: string): Promise<boolean>;
+/** Record that this store has had the migration `id`, keeping any others. */
+export declare function recordStoreMigration(ctx: ActorContext, where: StoreMigrationTarget, id: string): Promise<void>;

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

@@ -0,0 +1,259 @@
+/**
+ * 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.
+ */
+export type PrivateStoreLayoutFiles = {
+    userkeys: string;
+    userindex: string;
+    storemeta: string;
+    /** A store's own file index, beside `store.json` (#1400). */
+    storefiles: string;
+    /** A store's own page index, beside `store.json` (#1456). */
+    storepages: string;
+    /** A store's own saved search index, beside its page index (#1458). */
+    storesearch: string;
+    /** Which one-time migrations this store has had, beside its indexes (#1457). */
+    storemigrations: string;
+    /** A store's own trash record, beside its page index (#1459). */
+    storedeleted: string;
+};
+export type PrivateStoreLayout = {
+    privateRoot: string;
+    defaultStoreId: string;
+    versionsDir: string;
+    deletedDir: string;
+    /** Non-page files inside a store: `{store}/{attachmentsDir}/{uuid}.ext` (#1400) */
+    attachmentsDir: string;
+    /** A page's footnotes: `{store}/{footnotesDir}/{uuid}.json` (#1839) */
+    footnotesDir: string;
+    /** A page's comments: `{store}/{commentsDir}/{uuid}/{id}.json` (#1839) */
+    commentsDir: string;
+    files: PrivateStoreLayoutFiles;
+    /**
+     * The vault ids whose kind is sealed: the system-category entries that
+     * declare the vault with `encrypt: true` (#1834). Read from configuration
+     * with the rest of the layout, so every store I/O decision — which already
+     * carries the layout — consults the kind as well as the vault's
+     * `store.json`, and a sealed kind's vault without a sealed `store.json`
+     * fails closed instead of being read and written in the clear.
+     */
+    sealedVaults: readonly string[];
+};
+export type PrivateStoreLayoutOverrides = Partial<Omit<PrivateStoreLayout, 'files'>> & {
+    files?: Partial<PrivateStoreLayoutFiles>;
+};
+export declare const DEFAULT_PRIVATE_STORE_LAYOUT: PrivateStoreLayout;
+export declare const DEFAULT_PRIVATE_STORE: string;
+export declare const STORE_META_FILENAME: string;
+export declare function resolvePrivateStoreLayout(overrides?: PrivateStoreLayoutOverrides): PrivateStoreLayout;
+/** The user-level catalog filenames from layout (not a second hardcoded list). */
+export declare function privateUserCatalogFiles(layout?: PrivateStoreLayoutOverrides): Set<string>;
+export declare const PRIVATE_USER_CATALOG_FILES: Set<string>;
+/**
+ * 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 declare function parsePrivatestore(value: unknown): {
+    root: string;
+    vaultId: string;
+} | null;
+/** One `ngdpbase.system-category` entry that declares a vault. */
+export interface SystemCategoryVault {
+    key: string;
+    root: string;
+    vaultId: string;
+    isDefault: boolean;
+    /** Whether a copy of this vault is sealed: the entry's own `encrypt`. */
+    encrypt: boolean;
+}
+/** The entries of `ngdpbase.system-category` that declare a vault, in config order. */
+export declare function systemCategoryVaults(categories: unknown): SystemCategoryVault[];
+export declare function privateStoreLayoutFromConfig(getProperty: (key: string, defaultValue: string) => unknown): PrivateStoreLayout;
+export declare function isValidStoreId(store: string): boolean;
+/**
+ * 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 declare const PRIVATE_PAGE_NAME_PREFIX = "vaults/";
+/** The first path segment of a private page's URL: `/vaults/{owner}/{store}/{title}`. */
+export declare const PRIVATE_URL_SEGMENT: string;
+/**
+ * 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 declare 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 declare const PRIVATE_SLUG_PREFIX = "vaults--";
+export interface PrivatePageName {
+    owner: string;
+    store: string;
+    title: string;
+}
+export declare function formatPrivatePageName(owner: string, store: string, title: string): string;
+/** The parts of a private page name, or null when `name` is not one. */
+export declare function parsePrivatePageName(name: unknown): PrivatePageName | null;
+/**
+ * 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 declare function canonicalPageName(identifier: string, metadata: {
+    title?: string;
+} | null | undefined): string;
+/**
+ * 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 declare function parsePrivateLinkTarget(target: string): {
+    store: string;
+    title: string;
+} | null;
+export declare function mayContainPrivateLink(content: string): boolean;
+/** Refuse a store id that is not a plain slug. Every join below runs it. */
+export declare function assertStoreId(store: string): string;
+/**
+ * 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 declare function isSafePathSegment(segment: string): boolean;
+export declare function assertPathSegment(segment: string, what: string): string;
+export declare function privatePageFilePath(pagesDirectory: string, creator: string, uuidOrBasename: string, store?: string, layout?: PrivateStoreLayoutOverrides): string;
+export declare function privateUserDir(pagesDirectory: string, username: string, layout?: PrivateStoreLayoutOverrides): string;
+export declare function privateUserKeysPath(pagesDirectory: string, username: string, layout?: PrivateStoreLayoutOverrides): string;
+export declare function privateUserIndexPath(pagesDirectory: string, username: string, layout?: PrivateStoreLayoutOverrides): string;
+export declare function privateStoreRoot(pagesDirectory: string, creator: string, store?: string, layout?: PrivateStoreLayoutOverrides): string;
+/**
+ * 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 declare function privateStoreAttachmentsDir(pagesDirectory: string, creator: string, store?: string, layout?: PrivateStoreLayoutOverrides): string;
+/** Non-page file in `{privateroot}/{user}/{store}/{attachmentsdir}/{file}` (#1386). */
+export declare function privateStoreFilePath(pagesDirectory: string, creator: string, fileName: string, store?: string, layout?: PrivateStoreLayoutOverrides): string;
+/**
+ * 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 declare function isPrivateStoreAttachmentsRel(relParts: string[], layout?: PrivateStoreLayoutOverrides): boolean;
+export declare function storeMetaPath(pagesDirectory: string, creator: string, store?: string, layout?: PrivateStoreLayoutOverrides): string;
+/** A store's own file index: `{privateroot}/{user}/{store}/{storefiles}` (#1400). */
+export declare function storeFileIndexPath(pagesDirectory: string, creator: string, store?: string, layout?: PrivateStoreLayoutOverrides): string;
+/** A store's own page index: `{privateroot}/{user}/{store}/{storepages}` (#1456). */
+export declare function storePageIndexPath(pagesDirectory: string, creator: string, store?: string, layout?: PrivateStoreLayoutOverrides): string;
+/** A store's own saved search index: `{privateroot}/{user}/{store}/{storesearch}` (#1458). */
+export declare function storeSearchIndexPath(pagesDirectory: string, creator: string, store?: string, layout?: PrivateStoreLayoutOverrides): string;
+/**
+ * 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 declare function storeDeletedIndexPath(pagesDirectory: string, creator: string, store?: string, layout?: PrivateStoreLayoutOverrides): string;
+/** A store's record of the one-time migrations it has had (#1457). */
+export declare function storeMigrationsPath(pagesDirectory: string, creator: string, store?: string, layout?: PrivateStoreLayoutOverrides): string;
+export declare function privateVersionDirectory(pagesDirectory: string, creator: string, uuid: string, store?: string, layout?: PrivateStoreLayoutOverrides): string;
+/**
+ * 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 declare function privateStoreNotesDir(pagesDirectory: string, creator: string, store: string, kind: 'footnotes' | 'comments', layout?: PrivateStoreLayoutOverrides): string;
+export declare function privateDeletedDirectory(pagesDirectory: string, creator: string, store?: string, layout?: PrivateStoreLayoutOverrides): string;
+/** Pre-#1383 live file: `{pages}/{privateroot}/{user}/{file}.md`. */
+export declare function legacyPrivatePageFilePath(pagesDirectory: string, creator: string, uuidOrBasename: string, layout?: PrivateStoreLayoutOverrides): string;
+/** Legacy `pages/versions/private` = join(versionsdir, privateroot). No extra key. */
+export declare function legacyPrivateVersionsRoot(pagesDirectory: string, layout?: PrivateStoreLayoutOverrides): string;
+/**
+ * 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 declare function pathContainsPrivateRoot(pagesDirectory: string, filePath: string, layout?: PrivateStoreLayoutOverrides): boolean;
+/**
+ * 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 declare function parsePrivatePageRel(relParts: string[], layout?: PrivateStoreLayoutOverrides): {
+    creator: string;
+    store: string;
+} | 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 declare function parsePrivateStoreRel(relParts: string[], layout?: PrivateStoreLayoutOverrides): {
+    creator: string;
+    store: string;
+} | null;
+/** True when a path relative to the pages directory is inside the private root. */
+export declare function isUnderPrivateRoot(relParts: string[], layout?: PrivateStoreLayoutOverrides): boolean;