@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

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

@@ -0,0 +1,42 @@
+/**
+ * `[Title]` → `[store/Title]` inside a private store (#1457, epic #1454).
+ *
+ * A private page's links were written before the syntax existed: inside
+ * `private/{owner}/{store}/…`, `[Diary]` was the only way to name a sibling,
+ * and it resolves against the PUBLIC name list — so it renders red and points
+ * at `/edit/Diary`. `[store/Title]` is the syntax that reaches the page
+ * (slice A); the one-time migration below writes it.
+ *
+ * ## What it rewrites, and what it must not
+ *
+ * Only a target that names a page in the SAME store as the page the link sits
+ * in. Never a title that store does not have — a link to a public page is a
+ * link to a public page, and pointing it into a store would break it. Never a
+ * cross-store target: `[other/Diary]` already parses as a private link
+ * ({@link parsePrivateLinkTarget}) and is left exactly as it is, which is also
+ * what makes a second run write nothing.
+ *
+ * ## The text half only
+ *
+ * Pure, synchronous, no engine, no I/O — the split `renameLinkRewrite`
+ * established. Which pages to feed it, reading them and writing the results
+ * are `PageManager.migratePrivateLinks`'s job.
+ *
+ * The matching rules are not restated here: this hands a resolver to
+ * {@link rewriteLinkTargetsBy}, so the bracket forms, the checkbox case, the
+ * non-page targets and the `#fragment` handling are the ones the rename
+ * rewrite uses, and the two cannot drift. The case rule comes with them —
+ * `[Title]` byte-exact, `[Display|title]` case-insensitively — for the same
+ * reason: in the display form the target is prose somebody wrote.
+ */
+import { type LinkRewriteResult } from './renameLinkRewrite.js';
+/**
+ * Point this page's `[Title]` links at the store they are already in.
+ *
+ * @param content - The private page's markdown.
+ * @param store - The store the page lives in; the prefix its links gain.
+ * @param titles - Every page title in that store.
+ * @returns The rewritten content and a report — the input unchanged, and
+ *   `rewritten: 0`, when nothing in it names a page of this store.
+ */
+export declare function rewriteToPrivateLinks(content: string, store: string, titles: Iterable<string>): LinkRewriteResult;

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

@@ -0,0 +1,57 @@
+/**
+ * Who may act inside a user's private container — `pages/vaults/{user}/` and
+ * every vault below it (docs/private-stores.md, Access).
+ *
+ * The owner, a share link the owner issued, or someone acting for the owner
+ * under a proxy grant that carries `vault-proxy` (#1762). No role reaches in,
+ * admin included.
+ *
+ * A share link gets in only for a vault it names (#1388), and only when the
+ * caller names that vault: a question about the owner's container as a whole
+ * — their list of vaults, their trash, their takeout — is the owner's alone.
+ * Which pages of the vault the link may read, that it has not expired, and
+ * that its issuer still holds the action, are the share ceiling's to decide
+ * (`PolicyDecisionPoint.ceiling`), as for every share; this is only the
+ * container rule.
+ *
+ * An encrypted vault additionally needs a key in the session
+ * (`assertContextCanWriteStore`); a share link carries none until #1388's
+ * encrypted slices, and a proxy only the key copy its grant carries (#1762
+ * slice 5, `dekFor`).
+ *
+ * The container rule reads the proxy claim the subject carries; whether the
+ * grant is still in force is re-read live by the PDP on every decision, and
+ * the subject itself is rebuilt from the live grant on every request (#1762
+ * slice 4).
+ */
+import { type ActorContext } from '../context/ActorContext.js';
+/** The PDP surface a vault decision needs. */
+export interface VaultDecider {
+    decide(subject: unknown, request: {
+        action: string;
+        resource: {
+            type: string;
+            id: string;
+        };
+        attributes: Record<string, unknown>;
+    }): Promise<{
+        permit: boolean;
+    }>;
+}
+export declare function mayActInPrivateContainer(ctx: ActorContext, owner: string, opts?: {
+    vault?: string;
+}): boolean;
+/**
+ * May `ctx` do `action` inside `owner`'s vault `vault` (#1539)? The container
+ * rule first — the owner, or a share link of theirs for this vault; never a
+ * role — then the capability asked with the vault, so a policy on the `vault`
+ * resource type (`vault-owner`) decides. `resource` names what is acted on (a
+ * 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`).
+ */
+export declare function permitsInVault(pdp: VaultDecider | null | undefined, ctx: ActorContext, action: string, where: {
+    owner: string;
+    vault: string;
+    resource: string;
+}): Promise<boolean>;

package/lib/src/utils/privateStoreAccess.js

@@ -0,0 +1,65 @@
+/**
+ * Who may act inside a user's private container — `pages/vaults/{user}/` and
+ * every vault below it (docs/private-stores.md, Access).
+ *
+ * The owner, a share link the owner issued, or someone acting for the owner
+ * under a proxy grant that carries `vault-proxy` (#1762). No role reaches in,
+ * admin included.
+ *
+ * A share link gets in only for a vault it names (#1388), and only when the
+ * caller names that vault: a question about the owner's container as a whole
+ * — their list of vaults, their trash, their takeout — is the owner's alone.
+ * Which pages of the vault the link may read, that it has not expired, and
+ * that its issuer still holds the action, are the share ceiling's to decide
+ * (`PolicyDecisionPoint.ceiling`), as for every share; this is only the
+ * container rule.
+ *
+ * An encrypted vault additionally needs a key in the session
+ * (`assertContextCanWriteStore`); a share link carries none until #1388's
+ * encrypted slices, and a proxy only the key copy its grant carries (#1762
+ * slice 5, `dekFor`).
+ *
+ * The container rule reads the proxy claim the subject carries; whether the
+ * grant is still in force is re-read live by the PDP on every decision, and
+ * the subject itself is rebuilt from the live grant on every request (#1762
+ * slice 4).
+ */
+import { isJobContext } from '../context/ActorContext.js';
+import { toPermissionSubject } from '../context/JobContext.js';
+import { shareNamesVault } from '../types/Share.js';
+import { mixesProxyWithDelegation, proxyCarries } from './proxyClaim.js';
+export function mayActInPrivateContainer(ctx, owner, opts = {}) {
+    if (!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
+    // grant carries `vault-proxy`, and never alongside a token or a share.
+    if (ctx.viaProxy && (mixesProxyWithDelegation(ctx) || !proxyCarries(ctx.viaProxy, 'vault-proxy')))
+        return false;
+    if (ctx.viaShare) {
+        return opts.vault !== undefined
+            && ctx.viaShare.issuer === owner
+            && shareNamesVault(ctx.viaShare.resources, owner, opts.vault);
+    }
+    // A request must be an authenticated session of the owner: an anonymous
+    // visitor never matches, even a page whose recorded owner is `Anonymous`.
+    // A job carries who asked for it.
+    if (!isJobContext(ctx) && ctx.isAuthenticated !== true)
+        return false;
+    return ctx.username === owner;
+}
+/**
+ * May `ctx` do `action` inside `owner`'s vault `vault` (#1539)? The container
+ * rule first — the owner, or a share link of theirs for this vault; never a
+ * role — then the capability asked with the vault, so a policy on the `vault`
+ * resource type (`vault-owner`) decides. `resource` names what is acted on (a
+ * 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`).
+ */
+export async function permitsInVault(pdp, ctx, action, where) {
+    if (!pdp || !mayActInPrivateContainer(ctx, where.owner, { vault: where.vault }))
+        return false;
+    const subject = isJobContext(ctx) ? toPermissionSubject(ctx) : ctx;
+    return (await pdp.decide(subject, { action, resource: { type: 'page', id: where.resource }, attributes: { vault: where.vault } })).permit;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+export interface UserCatalogPage {
+    title: string;
+    uuid: string;
+    slug?: string;
+    filename?: string;
+    currentVersion: number;
+    location: 'private';
+    creator: string;
+    store: string;
+    lastModified: string;
+    created?: string;
+    editor: string;
+    author?: string;
+    hasVersions: boolean;
+    audienceRoles?: string[];
+    isPrivate: true;
+    addon?: string;
+}
+export interface UserCatalog {
+    version: 1;
+    pages: Record<string, UserCatalogPage>;
+}
+export declare function emptyUserCatalog(): UserCatalog;
+export declare function readUserCatalog(pagesDirectory: string, username: string, kek: Buffer): Promise<UserCatalog>;
+export declare function writeUserCatalog(pagesDirectory: string, username: string, kek: Buffer, catalog: UserCatalog): Promise<void>;
+export declare function upsertUserIndexPage(pagesDirectory: string, username: string, kek: Buffer, page: UserCatalogPage): Promise<UserCatalog>;

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

@@ -0,0 +1,127 @@
+/**
+ * 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 { type LinkPublicKey, type Lockbox } from './shareLockbox.js';
+export declare const mnemonicWordCount = 12;
+export interface ScryptKdf {
+    N: number;
+    r: number;
+    p: number;
+}
+/** Production wrap cost — same ballpark as login hashes. */
+export declare const PRIVATE_STORE_KDF: ScryptKdf;
+/** Unit tests only — still a valid scrypt N, cheap enough for the suite. */
+export declare const TEST_PRIVATE_STORE_KDF: ScryptKdf;
+export interface WrappedBlob {
+    iv: string;
+    tag: string;
+    ct: string;
+}
+/**
+ * A person's own key pair (#1762 slice 5): what lets someone else's grant hand
+ * them a copy of a vault key while they are offline. The pair is the share
+ * lockbox's (ECDH P-256, `shareLockbox.ts`); no other crypto.
+ */
+export interface PersonKey {
+    /** The public half, readable: a grant seals a copy of the owner's KEK to it. */
+    publicKey: LinkPublicKey;
+    /** The private half (the lockbox key string), wrapped under the person's own KEK. */
+    privateWrap: WrappedBlob;
+}
+export interface UserKeyEnvelope {
+    version: 1;
+    kdf: ScryptKdf & {
+        salt: string;
+    };
+    passwordWrap: WrappedBlob;
+    recoveryKdf: {
+        alg: 'bip39-pbkdf2';
+    };
+    recoveryWrap: WrappedBlob;
+    /**
+     * The person's key pair (#1762 slice 5). Made with the KEK at enrolment, or
+     * the first time the store is unlocked after this field existed; absent
+     * until then.
+     */
+    personKey?: PersonKey;
+}
+export interface EncryptedStoreRecord {
+    encrypt: true;
+    dekWrap: WrappedBlob;
+}
+export interface PlainStoreRecord {
+    encrypt: false;
+}
+export type StoreKeyRecord = EncryptedStoreRecord | PlainStoreRecord;
+export declare function createUserKeys(password: string, opts?: {
+    kdf?: ScryptKdf;
+}): Promise<{
+    envelope: UserKeyEnvelope;
+    kek: Buffer;
+    mnemonic: string;
+}>;
+/** A fresh key pair for a person (#1762 slice 5), its private half wrapped under their KEK. */
+export declare function newPersonKey(kek: Buffer): Promise<PersonKey>;
+/** The public half of a person's key pair, checked strictly; null when they have none. */
+export declare function personPublicKey(envelope: UserKeyEnvelope): LinkPublicKey | null;
+/**
+ * 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 declare function sealKekCopy(recipient: LinkPublicKey, kek: Buffer): Promise<Lockbox>;
+/**
+ * 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 declare function openKekCopy(envelope: UserKeyEnvelope, ownKek: Buffer, copy: Lockbox): Promise<Buffer>;
+export declare function unwrapKekWithPassword(envelope: UserKeyEnvelope, password: string): Promise<Buffer>;
+export declare function unwrapKekWithMnemonic(envelope: UserKeyEnvelope, mnemonic: string): Buffer;
+/**
+ * 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 declare function newRecoveryWords(kek: Buffer): {
+    mnemonic: string;
+    recoveryWrap: WrappedBlob;
+};
+/** True when two phrases are the same 12 words, compared as the recovery wrap reads them. */
+export declare function sameMnemonic(entered: string, expected: string): boolean;
+export declare function rewrapPassword(envelope: UserKeyEnvelope, oldPassword: string, newPassword: string, opts?: {
+    kdf?: ScryptKdf;
+}): Promise<UserKeyEnvelope>;
+/**
+ * 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 declare function rewrapPasswordWithKek(envelope: UserKeyEnvelope, kek: Buffer, newPassword: string, opts?: {
+    kdf?: ScryptKdf;
+}): Promise<UserKeyEnvelope>;
+export declare function createEncryptedStore(kek: Buffer): EncryptedStoreRecord;
+export declare function unwrapDek(kek: Buffer, store: EncryptedStoreRecord): Buffer;
+/** Encrypt a JSON value with the user KEK (user-index / versions / trash). */
+export declare function encryptJson(key: Buffer, value: unknown): WrappedBlob;
+/** Decrypt a JSON value wrapped by {@link encryptJson}. */
+export declare function decryptJson<T>(key: Buffer, blob: WrappedBlob): T;
+/** True when `bytes` start with the sealed-file magic. */
+export declare function isSealedBytes(bytes: Buffer): boolean;
+/** Encrypt the bytes of one store file with the store DEK. */
+export declare function sealBytes(dek: Buffer, plaintext: Buffer): Buffer;
+/** Decrypt a store file written by {@link sealBytes}. */
+export declare function openBytes(dek: Buffer, sealed: Buffer): Buffer;
+/**
+ * Shared encrypt-on write gate. Callers pass the DEK from the session bag.
+ * Not a PageManager method.
+ */
+export declare function assertEncryptedStoreWritable(args: {
+    encrypt: boolean;
+    dek: Buffer | undefined;
+}): void;

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

@@ -0,0 +1,181 @@
+/**
+ * The store door (#1414, epic #1382).
+ *
+ * A user's copy of a store kind is created when they first walk through its
+ * door — never at login and never mid-save. Decisions in
+ * docs/private-stores.md: "Recovery words: at first deliberate entry
+ * into the store", "The words are confirmed before anything is committed",
+ * "Core owns the door", "The door asks for the password when the user has no
+ * key", "`store.json` shape".
+ *
+ * This module holds what the door does, not how it is shown: which kinds
+ * exist, the words that are pending confirmation, and the commit. The route
+ * renders; nothing here touches HTTP.
+ *
+ * What exists only while the words screen is open lives in a process Map keyed
+ * by the session's private-store handle — never in express-session JSON, never
+ * logged, never in a record. Abandon the flow and nothing was written.
+ */
+import { type UserKeyEnvelope } from './privateStoreCrypto.js';
+import { type PrivateStoreLayout, type PrivateStoreLayoutOverrides } from './privateStorePath.js';
+type GetProperty = (key: string, defaultValue: unknown) => unknown;
+/**
+ * A vault kind (#1505): a system-category entry that declares a vault
+ * (`storageLocation.privatestore`). Its id is the vault id, the last folder
+ * of `privatestore`; `encrypt` is the entry's own. `ngdpbase.stores.{kind}`
+ * no longer defines kinds (operator, 2026-09-29).
+ */
+export interface StoreKind {
+    id: string;
+    /** Whether a copy of this kind is created sealed: the system-category's `encrypt`. */
+    encrypt: boolean;
+    /**
+     * Who decides about this vault (operator, 2026-09-29): `admin` for the
+     * site's own system-categories, or the slug of the add-on that declared it.
+     * The owner's declaration stands — an add-on that declares its vault
+     * `encrypt: true` (a health-record add-on, say) keeps it sealed; nobody else
+     * turns that off. The system-category entry's `owner`; absent means `admin`.
+     */
+    owner: string;
+}
+/** The site itself, as the owner of its own vault kinds; no add-on may claim it. */
+export declare const ADMIN_STORE_OWNER = "admin";
+/**
+ * The kind named `id`, or `null` when no system-category declares that vault.
+ * `encrypt` is read as the boolean it is and nothing else (a string "true" is
+ * not a switch).
+ */
+export declare function storeKindFromConfig(getProperty: GetProperty, id: string): StoreKind | null;
+/** Where the addon that owns a kind stands, as the door needs to know it. */
+export type StoreOwnerState = 'loaded' | 'failed' | 'disabled' | 'absent';
+/**
+ * Whether a kind's door is open (#1414). A kind the site owns is always open.
+ * An addon's kind is open only while that addon is loaded; otherwise the kind
+ * and every user's copy stay exactly as they are — nothing is removed — and
+ * the door says why it is shut.
+ */
+export type StoreDoorState = {
+    open: true;
+} | {
+    open: false;
+    reason: 'unavailable' | 'disabled' | 'not-installed';
+    message: string;
+};
+export declare function storeDoorState(kind: StoreKind, ownerState: StoreOwnerState | null): StoreDoorState;
+/** Every vault kind, by id: the vault each system-category declares (#1505). */
+export declare function storeKindIds(allProperties: Record<string, unknown>): string[];
+/**
+ * How many users hold a copy of a kind: whose `store.json` for it exists.
+ * The copy is what the door creates, so this is "who has walked through".
+ */
+export declare function countStoreCopies(pagesDirectory: string, kindId: string, layout?: PrivateStoreLayoutOverrides): Promise<number>;
+/** A vault of a sealed kind whose copy is not sealed (#1834). */
+export interface UnsealedVault {
+    owner: string;
+    vault: string;
+    /** `unopened`: files but no `store.json`; `mismatch`: a `store.json` that is not sealed. */
+    state: 'unopened' | 'mismatch';
+}
+/**
+ * Every vault of a sealed kind that holds files in the clear (#1834): a folder
+ * with something in it but no `store.json` (written before its door was
+ * opened), or a `store.json` that is not sealed. Read only — nothing is moved,
+ * sealed or deleted; what to do with the files is an administrator's call.
+ */
+export declare function findUnsealedVaults(pagesDirectory: string, layout: PrivateStoreLayout): Promise<UnsealedVault[]>;
+/** A sealed vault holding files that are not sealed (#1836). */
+export interface PlaintextInSealedVault {
+    owner: string;
+    vault: string;
+    /** How many files in it are not sealed bytes. */
+    files: number;
+    /** Where they are: the vault's own folders (`versions`, `attachments`, …), `.` for its root. */
+    areas: string[];
+}
+/**
+ * Every sealed vault (its `store.json` says `encrypt: true`) that holds files
+ * in the clear (#1836): a page's history moved in with `fs.move`, an
+ * attachment adopted without its I/O, a backup restored from before the vault
+ * was sealed. A sealed file starts with the `sealBytes` magic, so each file's
+ * first bytes tell them apart without the key. `store.json` is the one file
+ * that is never sealed; an empty file holds nothing and is not counted.
+ *
+ * Read only — nothing is moved, sealed or deleted; what to do with the files
+ * is an administrator's call. Vaults that are not sealed at all are
+ * {@link findUnsealedVaults}'s.
+ */
+export declare function findPlaintextInSealedVaults(pagesDirectory: string, layout: PrivateStoreLayout): Promise<PlaintextInSealedVault[]>;
+/** Attempts at confirming the words: one, plus `ngdpbase.stores.recovery.confirmretries`. */
+export declare function confirmAttempts(getProperty: GetProperty): number;
+/**
+ * Hold a new user KEK and its words while the user writes them down. Replaces
+ * anything this session had pending: starting over is always allowed.
+ */
+export declare function holdWordsForConfirmation(handle: string, args: {
+    username: string;
+    store: string;
+    kek: Buffer;
+    envelope: UserKeyEnvelope;
+    mnemonic: string;
+    attempts: number;
+}): void;
+/** Whether this session is part-way through the words screen for `store`. */
+export declare function hasPendingWords(handle: string, username: string, store: string): boolean;
+export type ConfirmOutcome = {
+    status: 'confirmed';
+    kek: Buffer;
+    envelope: UserKeyEnvelope;
+} | {
+    status: 'retry';
+    mnemonic: string;
+    attemptsLeft: number;
+} | {
+    status: 'exhausted';
+} | {
+    status: 'none';
+};
+/**
+ * Check the words the user typed back. A match hands over the KEK and envelope
+ * to commit and forgets the words. A miss discards the words it showed — they
+ * are never shown again — and, while attempts remain, makes a new set for the
+ * same uncommitted KEK. No attempts left: everything is forgotten and nothing
+ * was ever written.
+ */
+export declare function confirmWords(handle: string, username: string, store: string, entered: string): ConfirmOutcome;
+/** Logout, or a new login in this session: nothing pending survives it. */
+export declare function dropPendingWords(handle: string): void;
+/** Test teardown only. */
+export declare function clearPendingWords(): void;
+/** Whether `username` already has a copy of `store` — the door is then just a way in. */
+export declare function storeCopyExists(args: {
+    pagesDirectory: string;
+    username: string;
+    store: string;
+    layout?: PrivateStoreLayoutOverrides;
+}): Promise<boolean>;
+/** Whether `username` has a user KEK on disk. */
+export declare function userKeysExist(args: {
+    pagesDirectory: string;
+    username: string;
+    layout?: PrivateStoreLayoutOverrides;
+}): Promise<boolean>;
+/**
+ * Write the user's copy of a store kind: `user-keys.json` first when this
+ * commit creates the user's KEK, then `store.json` — each written only if it
+ * does not exist yet. Returns the store DEK for a sealed copy, so the caller
+ * can put it in the session that walked through the door.
+ */
+export declare function commitStoreCopy(args: {
+    pagesDirectory: string;
+    username: string;
+    kind: StoreKind;
+    /** The user KEK — required for a sealed copy. */
+    kek?: Buffer;
+    /** The new envelope, when this commit creates the user's KEK. */
+    newEnvelope?: UserKeyEnvelope;
+    layout?: PrivateStoreLayoutOverrides;
+    now?: Date;
+}): Promise<{
+    dek?: Buffer;
+}>;
+export {};

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

@@ -0,0 +1,72 @@
+/**
+ * Building a person's takeout of their own private store (#1387).
+ *
+ * The decisions this implements, all recorded on #1387:
+ *
+ *   - **It is decrypted.** There is one form of takeout, and it is readable.
+ *     Someone who leaves with their data can open it in any text editor on the
+ *     laptop or phone they downloaded it to.
+ *   - **It is a copy you can read, not a copy you can pour back.** Pages under
+ *     their real titles and attachments under the names they were uploaded
+ *     with; no `versions/`, no `deleted/`, none of the store's indexes, and no
+ *     `user-keys.json` — a wrapped key guards nothing that is not already in
+ *     the clear beside it. Restoring a store as it was is the instance
+ *     backup's job, which does it better by keeping the encryption.
+ *   - **Full frontmatter is kept.** Title, uuid, author, timestamps, keywords.
+ *     It stays perfectly readable, and the uuid is what lets a later import
+ *     (#1472) recognise a page as the same page rather than duplicating it.
+ *   - **The store's `files-index.json` is kept** (operator, 2026-09-25,
+ *     revising the list above). It is the one "index" that is content: pages
+ *     reference files as `/attachments/{id}`, and nothing else maps an id to
+ *     its file or holds its description, author and dates. Each record's
+ *     `fileName` is rewritten to the file's path in the archive, so an import
+ *     (#1472) can find every entry and keep every link.
+ *   - **Nothing decrypted is written to the server's disk.** Everything here
+ *     returns bytes in memory for the caller to stream.
+ *
+ * Reading goes through `storeFileIO`, which hands back plain or sealed I/O and
+ * REFUSES an encrypted store whose key this context does not hold. A locked
+ * store therefore throws rather than quietly producing an archive of
+ * ciphertext or of nothing at all — a takeout that looks like it worked and
+ * cannot be read is worse than an error.
+ */
+import { type PrivateStoreLayout } from './privateStorePath.js';
+import type { ActorContext } from '../context/ActorContext.js';
+/** One file of the takeout, ready for a packer. */
+export type TakeoutFile = {
+    /** Path inside the archive, `/`-separated. */
+    path: string;
+    bytes: Buffer;
+    mtime: Date;
+};
+export type TakeoutOptions = {
+    pagesDirectory: string;
+    owner: string;
+    store: string;
+    /** Leave the attachments out — someone who wants their writing, not gigabytes of photos. */
+    pagesOnly?: boolean;
+    layout: PrivateStoreLayout;
+};
+/**
+ * Name of the file index inside a takeout, beside the pages.
+ *
+ * Fixed rather than read from the store layout: a takeout is carried to other
+ * instances, whose layout may name the on-disk index differently.
+ */
+export declare const TAKEOUT_FILE_INDEX = "files-index.json";
+export type Takeout = {
+    owner: string;
+    store: string;
+    files: TakeoutFile[];
+    pageCount: number;
+    attachmentCount: number;
+    totalBytes: number;
+};
+/**
+ * Build a takeout of one store.
+ *
+ * Throws when the store is encrypted and `ctx` does not hold its key — the
+ * caller turns that into "unlock your store first", never into an empty
+ * archive.
+ */
+export declare function buildStoreTakeout(ctx: ActorContext, options: TakeoutOptions): Promise<Takeout>;