@book.dev/sdk 1.60.0 → 1.64.0

package/dist/account.d.ts

@@ -52,6 +52,17 @@ export declare class AccountClient {
     putSettings(token: string, settings: Record<string, unknown>): Promise<{
         updatedAt: string;
     }>;
+    /**
+     * Mint a verifiable identity assertion (JWS) for the OpenBook data server
+     * (OB-165). The data server verifies it against the account's JWKS and
+     * attributes the user's changes to `iss#sub`. Returns `{identity, expiresAt}`,
+     * or `null` when the account doesn't issue identities (501) — the app then
+     * acts as a named guest. Throws `AccountError(401)` on an invalid/revoked token.
+     */
+    getIdentityToken(token: string, aud?: string): Promise<{
+        identity: string;
+        expiresAt: string;
+    } | null>;
     /** Cheap token check (a settings GET): true if accepted, false on 401. */
     validate(token: string): Promise<boolean>;
 }

package/dist/account.js

@@ -88,6 +88,33 @@ export class AccountClient {
         const body = (await res.json());
         return { updatedAt: body.updatedAt };
     }
+    /**
+     * Mint a verifiable identity assertion (JWS) for the OpenBook data server
+     * (OB-165). The data server verifies it against the account's JWKS and
+     * attributes the user's changes to `iss#sub`. Returns `{identity, expiresAt}`,
+     * or `null` when the account doesn't issue identities (501) — the app then
+     * acts as a named guest. Throws `AccountError(401)` on an invalid/revoked token.
+     */
+    async getIdentityToken(token, aud) {
+        // `aud` scopes the assertion to one data server (OB-177), so it can't be
+        // replayed to another. Required by the issuer only when it runs an audience
+        // allowlist; harmless (and unscoped) otherwise.
+        const url = new URL('/api/identity/token', this.baseUrl + '/');
+        if (aud)
+            url.searchParams.set('aud', aud);
+        const res = await fetch(url, {
+            headers: { authorization: `Bearer ${token}` },
+            cache: 'no-store',
+        });
+        if (res.status === 501)
+            return null; // issuance not configured on this account
+        if (!res.ok)
+            throw new AccountError(res.status, `account identity token failed (${res.status})`);
+        const body = (await res.json());
+        if (!body.identity || !body.expiresAt)
+            return null;
+        return { identity: body.identity, expiresAt: body.expiresAt };
+    }
     /** Cheap token check (a settings GET): true if accepted, false on 401. */
     async validate(token) {
         try {

package/dist/account.js.map

@@ -1 +1 @@
-{"version":3,"file":"account.js","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"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"}

package/dist/ai.d.ts

@@ -63,6 +63,16 @@ export interface AiConfig {
  * and both UIs read settings through this, so old configs keep working.
  */
 export declare function providerSettings(config: AiConfig, provider: AiProvider): AiProviderSettings;
+/**
+ * Whether a provider is a **paid / hosted** engine — `openai` (an OpenAI-style
+ * endpoint that may be `api.openai.com`) or `claude` (Anthropic's hosted API).
+ * Both can bill per token and send content off the machine, so paid inference is
+ * fenced behind sign-in on a claimed multi-user instance (a guest must not be
+ * able to rack up inference cost). The rest — `off`/`mock`/`llama`/`mlx` — run
+ * locally and free, and stay open. The single source of truth for "is this
+ * inference paid"; routes and UI both classify the configured provider through it.
+ */
+export declare function isPaidProvider(provider: AiProvider): boolean;
 export interface AiStatus {
     config: AiConfig;
     /** The engine can generate text right now. */

package/dist/ai.js

@@ -33,4 +33,16 @@ export function providerSettings(config, provider) {
     }
     return {};
 }
+/**
+ * Whether a provider is a **paid / hosted** engine — `openai` (an OpenAI-style
+ * endpoint that may be `api.openai.com`) or `claude` (Anthropic's hosted API).
+ * Both can bill per token and send content off the machine, so paid inference is
+ * fenced behind sign-in on a claimed multi-user instance (a guest must not be
+ * able to rack up inference cost). The rest — `off`/`mock`/`llama`/`mlx` — run
+ * locally and free, and stay open. The single source of truth for "is this
+ * inference paid"; routes and UI both classify the configured provider through it.
+ */
+export function isPaidProvider(provider) {
+    return provider === 'openai' || provider === 'claude';
+}
 //# sourceMappingURL=ai.js.map

package/dist/ai.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai.js","sourceRoot":"","sources":["../src/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgDH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAgB,EAAE,QAAoB;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACxB,IAAI,QAAQ,KAAK,MAAM,CAAC,QAAQ,EAAE,CAAC;QACjC,OAAO,EAAC,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAC,CAAC;IAC5G,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}
+{"version":3,"file":"ai.js","sourceRoot":"","sources":["../src/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAgDH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAgB,EAAE,QAAoB;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC;IACxB,IAAI,QAAQ,KAAK,MAAM,CAAC,QAAQ,EAAE,CAAC;QACjC,OAAO,EAAC,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAC,CAAC;IAC5G,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,QAAoB;IACjD,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,QAAQ,CAAC;AACxD,CAAC"}

package/dist/authorize.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The one authorization function (OB-189; contract
+ * `docs/sharing-access-contract-spike-OB-182.md` §1).
+ *
+ * `authorize(principal, page, ctx)` is the single, **pure, isomorphic** access
+ * decision for the whole product. The origin calls it on every content
+ * request/event; the client reuses it to grey out UI. It has **no I/O**: the
+ * roster role, the resolved (post-`inherit`) visibility, and the email-authority
+ * gate are all computed by the caller (the store) and handed in via {@link
+ * AccessCtx}. This module only composes them through the §1.2 precedence ladder.
+ *
+ * Wiring it into routes, streams and the request → {@link AccessCtx} build is
+ * OB-190 (enforcement) and is intentionally NOT here.
+ */
+import type { Principal } from './identity';
+import type { InstanceConfig } from './provenance';
+import type { AclLevel, MemberRole, PageVisibility } from './types';
+/**
+ * Roster role, in the authorize layer (contract §1.1 calls this union `Role`).
+ * An ALIAS of {@link MemberRole} — there is exactly one role union in the SDK.
+ */
+export type Role = MemberRole;
+/** A resolved (never `inherit`) page visibility scope. */
+export type EffectiveVisibility = Exclude<PageVisibility, 'inherit'>;
+/**
+ * One per-page ACL grant, as seen by {@link authorize} (the in-memory shape of a
+ * `page_acl` row, §2.3). Exactly one grantee key is set: `subject` (a grantee
+ * already bound to any trusted issuer) XOR `email` (a grantee by persona email,
+ * lowercased). An `email` entry MUST carry the pinned `issuer` — the
+ * email-authority — or it can never match (B1).
+ */
+export interface AclEntry {
+    /** Grantee already bound to a member/handle (any trusted issuer). */
+    subject?: string;
+    /** Grantee by persona email (lowercased). */
+    email?: string;
+    /** REQUIRED for an email entry — the pinned email-authority (B1). */
+    issuer?: string;
+    level: AclLevel;
+}
+/** The per-page inputs to a decision: the page's scope + its ACL grants. */
+export interface AccessPage {
+    visibility: PageVisibility;
+    acl: AclEntry[];
+}
+/**
+ * The non-page, caller-resolved inputs to a decision (contract §1.1). Everything
+ * here is computed by the store before the call: the active-persona role, the
+ * effective visibility after resolving `inherit`, and whether the principal's
+ * email may be trusted.
+ */
+export interface AccessCtx {
+    config: Pick<InstanceConfig, 'guestAccess' | 'ownerSubject' | 'defaultVisibility' | 'emailAuthority'>;
+    /**
+     * Role of the principal's ACTIVE persona, resolved by the store: a roster row
+     * with `status='active'` whose BOUND `subject === principal.subject` (and, for
+     * an email persona, whose email === principal.email under the pinned authority).
+     * `invited`/`suspended` rows resolve to `null` — a dormant row grants nothing
+     * (S3). `null` ⇒ the principal is not an active member.
+     */
+    role: Role | null;
+    /**
+     * Effective visibility after resolving `inherit` (up the PARENT chain for an
+     * ordinary page, or via the DATABASE HOST PAGE for a database row — N9), down to
+     * `config.defaultVisibility` at the root. Never `inherit`.
+     */
+    effectiveVisibility: EffectiveVisibility;
+    /**
+     * True iff the principal's email may be trusted for persona / email-ACL
+     * matching: `verifiedVia==='jws'` AND `principal.issuer === config.emailAuthority`
+     * (B1). Only then does email matching fire. See {@link isEmailAuthoritative}.
+     */
+    emailIsAuthoritative: boolean;
+}
+/** The decision: independent read/write grants plus the deciding rung's reason. */
+export interface Decision {
+    canRead: boolean;
+    canWrite: boolean;
+    reason: string;
+}
+/**
+ * The `emailIsAuthoritative` predicate (contract §1.1, B1) as a reusable pure
+ * helper the store uses to build {@link AccessCtx.emailIsAuthoritative}. An email
+ * is trustworthy ONLY on a fresh JWS from the one pinned email-authority — a
+ * federated self-issuer asserting arbitrary emails can never satisfy it.
+ */
+export declare function isEmailAuthoritative(principal: Principal, config: Pick<InstanceConfig, 'emailAuthority'>): boolean;
+/**
+ * Decide read+write for a principal on a page (contract §1.2 precedence ladder).
+ *
+ * Ladder, highest authority first; the first rule that grants a *field* wins, and
+ * write is only ever granted by rules 0/1/2/3/4:
+ *
+ *  0. Unclaimed instance (`ownerSubject` unset) → legacy guest-gate short-circuit
+ *     (loopback-only by the §2.6 exposure invariant).
+ *  1. Loopback owner (`verifiedVia==='local'`) → read+write.
+ *  2. Owner (`jws` && `subject===ownerSubject`) → read+write.
+ *  3. Per-page ACL: `write` → read+write; `read` → read (write falls through).
+ *  4. Roster role: `admin` → read+write; `viewer` → read per scope, write denied.
+ *  5. Visibility scope vs principal class → governs read for everyone else.
+ *  6. Guest-gate floor (`guestAccess='off'` denies the guest class even `public`).
+ *  7. Default deny.
+ */
+export declare function authorize(principal: Principal, page: AccessPage, ctx: AccessCtx): Decision;

package/dist/authorize.js

@@ -0,0 +1,151 @@
+/**
+ * The one authorization function (OB-189; contract
+ * `docs/sharing-access-contract-spike-OB-182.md` §1).
+ *
+ * `authorize(principal, page, ctx)` is the single, **pure, isomorphic** access
+ * decision for the whole product. The origin calls it on every content
+ * request/event; the client reuses it to grey out UI. It has **no I/O**: the
+ * roster role, the resolved (post-`inherit`) visibility, and the email-authority
+ * gate are all computed by the caller (the store) and handed in via {@link
+ * AccessCtx}. This module only composes them through the §1.2 precedence ladder.
+ *
+ * Wiring it into routes, streams and the request → {@link AccessCtx} build is
+ * OB-190 (enforcement) and is intentionally NOT here.
+ */
+/**
+ * The `emailIsAuthoritative` predicate (contract §1.1, B1) as a reusable pure
+ * helper the store uses to build {@link AccessCtx.emailIsAuthoritative}. An email
+ * is trustworthy ONLY on a fresh JWS from the one pinned email-authority — a
+ * federated self-issuer asserting arbitrary emails can never satisfy it.
+ */
+export function isEmailAuthoritative(principal, config) {
+    return (principal.verifiedVia === 'jws' &&
+        !!config.emailAuthority &&
+        principal.issuer === config.emailAuthority);
+}
+/**
+ * The highest ACL grant a principal matches on this page (§1.2 rule 3), or `null`.
+ * `'write'` outranks `'read'`. A **subject** entry matches only a `jws` principal
+ * with the same subject (any trusted issuer); an **email** entry matches only when
+ * the email is authoritative AND the lowercased emails are equal AND the entry's
+ * `issuer` is the pinned email-authority (B1) — so a federated issuer can never
+ * satisfy an `account.book.pub`-scoped email grant.
+ */
+function matchAcl(principal, acl, ctx) {
+    const isJws = principal.verifiedVia === 'jws';
+    let best = null;
+    for (const entry of acl) {
+        let matches = false;
+        if (entry.subject) {
+            matches = isJws && entry.subject === principal.subject;
+        }
+        else if (entry.email) {
+            matches =
+                ctx.emailIsAuthoritative &&
+                    !!principal.email &&
+                    entry.email.toLowerCase() === principal.email.toLowerCase() &&
+                    entry.issuer === ctx.config.emailAuthority;
+        }
+        if (matches) {
+            if (entry.level === 'write')
+                return 'write';
+            best = 'read';
+        }
+    }
+    return best;
+}
+/** Does the principal get READ purely from the visibility scope (§1.2 rule 5)? */
+function scopeAllowsRead(principal, ctx, guestBlocked) {
+    switch (ctx.effectiveVisibility) {
+        case 'public':
+            // Read for ALL — incl. anonymous — overriding the guest gate, EXCEPT a
+            // guest when `guestAccess='off'` (rule 6 / footnote ¹).
+            return !guestBlocked;
+        case 'authenticated':
+            // Any signed-in (jws) user; guests denied (N8).
+            return principal.verifiedVia === 'jws';
+        case 'members':
+            // Only active roster members — an active row resolves to a non-null role.
+            // A signed-in non-member or invited/suspended persona (role null) gets
+            // nothing here; it may still read via an ACL above.
+            return ctx.role !== null;
+        case 'restricted':
+            // Only owner/admin/ACL, all handled above; everyone else: no.
+            return false;
+    }
+}
+/**
+ * Decide read+write for a principal on a page (contract §1.2 precedence ladder).
+ *
+ * Ladder, highest authority first; the first rule that grants a *field* wins, and
+ * write is only ever granted by rules 0/1/2/3/4:
+ *
+ *  0. Unclaimed instance (`ownerSubject` unset) → legacy guest-gate short-circuit
+ *     (loopback-only by the §2.6 exposure invariant).
+ *  1. Loopback owner (`verifiedVia==='local'`) → read+write.
+ *  2. Owner (`jws` && `subject===ownerSubject`) → read+write.
+ *  3. Per-page ACL: `write` → read+write; `read` → read (write falls through).
+ *  4. Roster role: `admin` → read+write; `viewer` → read per scope, write denied.
+ *  5. Visibility scope vs principal class → governs read for everyone else.
+ *  6. Guest-gate floor (`guestAccess='off'` denies the guest class even `public`).
+ *  7. Default deny.
+ */
+export function authorize(principal, page, ctx) {
+    const { config } = ctx;
+    const isLocal = principal.verifiedVia === 'local';
+    const isJws = principal.verifiedVia === 'jws';
+    // Rule 0 — unclaimed instance: legacy short-circuit, preserving today's
+    // loopback behaviour exactly. Roster/scope/ACL don't exist until claimed; the
+    // in-process (`local`) and any `jws` caller always read+write (truth-table
+    // footer), everyone else is judged by the guest gate. Reachable only on
+    // loopback (the §2.6 exposure invariant — a claim is required before exposure).
+    if (config.ownerSubject === undefined) {
+        const privileged = isJws || isLocal;
+        return {
+            canRead: config.guestAccess !== 'off' || privileged,
+            canWrite: config.guestAccess === 'write' || privileged,
+            reason: 'legacy-guest-gate',
+        };
+    }
+    // ── Claimed instance ──────────────────────────────────────────────────────
+    const isOwner = isJws && principal.subject === config.ownerSubject; // rule 2
+    const aclMatch = matchAcl(principal, page.acl, ctx); // rule 3
+    const isAdmin = ctx.role === 'admin'; // rule 4
+    const isViewer = ctx.role === 'viewer'; // rule 4
+    // Rule 6 floor: the guest class is denied even `public` when guests are
+    // disabled. Hardened (OB-190, OB-189 security review #1) to the WHOLE
+    // unauthenticated class — any principal that is neither an authenticated `jws`
+    // user nor the loopback owner. `kind==='guest'` is the common case, but a
+    // non-request-assertable `unverified`/`synced` `user` principal must never slip
+    // past the `guestAccess='off'` floor onto a `public` page either (defence in
+    // depth behind the middleware, which already rejects such principals at the gate
+    // on an identity-enabled instance).
+    const guestBlocked = !isJws && !isLocal && config.guestAccess === 'off';
+    const scopeRead = scopeAllowsRead(principal, ctx, guestBlocked); // rule 5
+    // WRITE — only rules 1/2/3(write)/4(admin) ever grant it. `viewer` is locked,
+    // jws-non-members and guests are read-only on a claimed instance.
+    const canWrite = isLocal || isOwner || aclMatch === 'write' || isAdmin;
+    // READ — granted by the first rung that allows it.
+    const canRead = isLocal || isOwner || aclMatch !== null || isAdmin || scopeRead;
+    let reason;
+    if (isLocal)
+        reason = 'local-owner';
+    else if (isOwner)
+        reason = 'owner';
+    else if (aclMatch === 'write')
+        reason = 'acl-write';
+    else if (isAdmin)
+        reason = 'admin';
+    else if (aclMatch === 'read')
+        reason = 'acl-read';
+    else if (isViewer)
+        reason = canRead ? 'viewer-readonly' : 'no-grant';
+    else if (canRead)
+        reason = 'visibility-scope';
+    else if (guestBlocked)
+        reason = 'guest-disabled';
+    else
+        reason = 'no-grant';
+    return { canRead, canWrite, reason };
+}
+//# sourceMappingURL=authorize.js.map

package/dist/authorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":"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"}

package/dist/authors.d.ts

@@ -0,0 +1,26 @@
+import type { PageSnapshot } from './types';
+/**
+ * Compute the `[blockId, subject]` authorship for `next`. Unchanged blocks keep
+ * their prior author; changed/new blocks get `authorSubject` when it is a
+ * verified identity (a non-empty subject), and are otherwise left unattributed
+ * (an anonymous/guest edit honestly clears a block's verified author rather than
+ * falsely keeping the previous one). Returns a sparse map — only blocks with a
+ * known author — or `null` when none are attributed (so the field stays absent
+ * on single-user / unverified documents).
+ */
+export declare function computeBlockAuthors(prev: PageSnapshot | null | undefined, next: PageSnapshot, authorSubject: string): Array<[string, string]> | null;
+/**
+ * Return `next` with its `authors` stamped relative to `prev`. `authorSubject` is
+ * the request's *verified* principal subject (`iss#sub`), or `''` for an
+ * unverified/guest/local write (which carries no new attribution). Idempotent
+ * when the document is unchanged. Omits the `authors` key entirely when nothing
+ * is attributed, so it never appears on single-user/unverified snapshots.
+ */
+export declare function stampSnapshotAuthors(prev: PageSnapshot | null | undefined, next: PageSnapshot, authorSubject: string): PageSnapshot;
+/**
+ * The verified author of a snapshot's most-recently-changed attributed block —
+ * the snapshot's "last verified editor", read on the receiving instance to
+ * attribute a synced edit. Uses `mtimes` to find the newest block, falling back
+ * to any attributed block. Returns `null` when nothing is attributed.
+ */
+export declare function latestSnapshotAuthor(data: PageSnapshot | null | undefined): string | null;

package/dist/authors.js

@@ -0,0 +1,81 @@
+/**
+ * Per-block authorship that travels WITH a page snapshot (OB-170), so an edit
+ * made on one instance is correctly attributed when the snapshot reaches another
+ * (the sync/merge path). Parallel to `mtimes` (which records *when* each block
+ * changed): `authors` records *who* — but only for **verified** identities, so
+ * guest/local/unverified edits never pollute the carried attribution.
+ *
+ * A snapshot's `authors` is a sparse `[blockId, subject]` map (only blocks with
+ * a known verified author). The server stamps it on write from the request's
+ * verified principal, carrying forward each unchanged block's prior author and
+ * setting the current author on changed/new blocks. Pure + isomorphic, mirroring
+ * `mtime.ts` so it runs on the server write path and in tests alike.
+ */
+import { snapshotBlocks } from './mtime';
+/**
+ * Compute the `[blockId, subject]` authorship for `next`. Unchanged blocks keep
+ * their prior author; changed/new blocks get `authorSubject` when it is a
+ * verified identity (a non-empty subject), and are otherwise left unattributed
+ * (an anonymous/guest edit honestly clears a block's verified author rather than
+ * falsely keeping the previous one). Returns a sparse map — only blocks with a
+ * known author — or `null` when none are attributed (so the field stays absent
+ * on single-user / unverified documents).
+ */
+export function computeBlockAuthors(prev, next, authorSubject) {
+    const prevBlocks = snapshotBlocks(prev);
+    const prevHash = new Map();
+    for (const b of prevBlocks)
+        prevHash.set(b.id, b.hash);
+    const prevAuthor = new Map(prev?.authors ?? []);
+    const verified = authorSubject.length > 0;
+    const out = [];
+    for (const b of snapshotBlocks(next)) {
+        const unchanged = prevHash.get(b.id) === b.hash;
+        const author = unchanged ? prevAuthor.get(b.id) ?? '' : verified ? authorSubject : '';
+        if (author)
+            out.push([b.id, author]);
+    }
+    return out.length > 0 ? out : null;
+}
+/**
+ * Return `next` with its `authors` stamped relative to `prev`. `authorSubject` is
+ * the request's *verified* principal subject (`iss#sub`), or `''` for an
+ * unverified/guest/local write (which carries no new attribution). Idempotent
+ * when the document is unchanged. Omits the `authors` key entirely when nothing
+ * is attributed, so it never appears on single-user/unverified snapshots.
+ */
+export function stampSnapshotAuthors(prev, next, authorSubject) {
+    const authors = computeBlockAuthors(prev, next, authorSubject);
+    if (!authors) {
+        // Nothing attributed: drop any stale `authors` rather than carry an empty map.
+        if (next.authors === undefined)
+            return next;
+        const rest = { ...next };
+        delete rest.authors;
+        return rest;
+    }
+    return { ...next, authors };
+}
+/**
+ * The verified author of a snapshot's most-recently-changed attributed block —
+ * the snapshot's "last verified editor", read on the receiving instance to
+ * attribute a synced edit. Uses `mtimes` to find the newest block, falling back
+ * to any attributed block. Returns `null` when nothing is attributed.
+ */
+export function latestSnapshotAuthor(data) {
+    const authors = new Map(data?.authors ?? []);
+    if (authors.size === 0)
+        return null;
+    let latestIso = null;
+    let latestSubject = null;
+    for (const [blockId, iso] of data?.mtimes ?? []) {
+        const subject = authors.get(blockId);
+        if (subject && (latestIso === null || iso > latestIso)) {
+            latestIso = iso;
+            latestSubject = subject;
+        }
+    }
+    // No mtimes overlap (e.g. a snapshot without mtimes) → any attributed author.
+    return latestSubject ?? authors.values().next().value ?? null;
+}
+//# sourceMappingURL=authors.js.map

package/dist/authors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authors.js","sourceRoot":"","sources":["../src/authors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAC,cAAc,EAAC,MAAM,SAAS,CAAC;AAGvC;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAqC,EACrC,IAAkB,EAClB,aAAqB;IAErB,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,UAAU;QAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAiB,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;IAE1C,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC;QAChD,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;QACtF,IAAI,MAAM;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAqC,EACrC,IAAkB,EAClB,aAAqB;IAErB,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;IAC/D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,+EAA+E;QAC/E,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QAC5C,MAAM,IAAI,GAAG,EAAC,GAAG,IAAI,EAAC,CAAC;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAC,GAAG,IAAI,EAAE,OAAO,EAAC,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAqC;IACxE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAiB,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;IAC7D,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,IAAI,aAAa,GAAkB,IAAI,CAAC;IACxC,KAAK,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,IAAI,EAAE,MAAM,IAAI,EAAE,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,GAAG,GAAG,SAAS,CAAC,EAAE,CAAC;YACvD,SAAS,GAAG,GAAG,CAAC;YAChB,aAAa,GAAG,OAAO,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,8EAA8E;IAC9E,OAAO,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC;AAChE,CAAC"}

package/dist/backup.d.ts

@@ -37,6 +37,45 @@ export interface ImportResult {
     /** old page id → new page id (copy mode; identity in overwrite). */
     idMap: Record<string, string>;
 }
+/**
+ * Backup cadences, in increasing interval. The server keeps a rolling set per
+ * cadence (grandfather-father-son rotation), so short cadences churn fast and
+ * long ones are retained sparsely — automatic, tiered data safety on top of the
+ * ad-hoc export.
+ */
+export type BackupCadence = 'daily' | 'weekly' | 'monthly' | 'yearly';
+export declare const BACKUP_CADENCES: readonly BackupCadence[];
+/** Interval of each cadence, in milliseconds. */
+export declare const BACKUP_CADENCE_MS: Record<BackupCadence, number>;
+/** Scheduled-backup policy, persisted server-side in the `settings` table. */
+export interface BackupConfig {
+    /** Master switch — when false the scheduler is idle (the default). */
+    enabled: boolean;
+    /** Where backups are written; `null` = the server default (`<dataDir>/backups`). */
+    dir: string | null;
+    /** Which cadences are active. */
+    cadences: Record<BackupCadence, boolean>;
+    /** How many snapshots to retain per cadence before pruning the oldest. */
+    keep: Record<BackupCadence, number>;
+    /** Last successful run per cadence (ISO), so a reboot catches up overdue ones. */
+    lastRun: Partial<Record<BackupCadence, string>>;
+}
+export declare const DEFAULT_BACKUP_CONFIG: BackupConfig;
+/** A derived, per-cadence view for the UI (last/next run + how many are on disk). */
+export interface BackupCadenceStatus {
+    cadence: BackupCadence;
+    enabled: boolean;
+    lastRun: string | null;
+    nextDue: string | null;
+    count: number;
+}
+/** What `GET /api/backups` returns: the policy + resolved dir + derived status. */
+export interface BackupStatus {
+    config: BackupConfig;
+    /** The resolved output directory (config.dir, or the server default). */
+    resolvedDir: string | null;
+    cadences: BackupCadenceStatus[];
+}
 /**
  * Pure: re-key a bundle for copy-mode import. Mints a fresh id for every page and
  * database, remaps every internal reference (`parentId`, `databaseId`,

package/dist/backup.js

@@ -1,4 +1,19 @@
 export const BACKUP_VERSION = 1;
+export const BACKUP_CADENCES = ['daily', 'weekly', 'monthly', 'yearly'];
+/** Interval of each cadence, in milliseconds. */
+export const BACKUP_CADENCE_MS = {
+    daily: 24 * 60 * 60 * 1000,
+    weekly: 7 * 24 * 60 * 60 * 1000,
+    monthly: 30 * 24 * 60 * 60 * 1000,
+    yearly: 365 * 24 * 60 * 60 * 1000,
+};
+export const DEFAULT_BACKUP_CONFIG = {
+    enabled: false,
+    dir: null,
+    cadences: { daily: true, weekly: true, monthly: true, yearly: true },
+    keep: { daily: 7, weekly: 5, monthly: 12, yearly: 3 },
+    lastRun: {},
+};
 /**
  * Pure: re-key a bundle for copy-mode import. Mints a fresh id for every page and
  * database, remaps every internal reference (`parentId`, `databaseId`,

package/dist/backup.js.map

@@ -1 +1 @@
-{"version":3,"file":"backup.js","sourceRoot":"","sources":["../src/backup.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AA+BhC;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,KAAmB,EACnB,SAA2B,EAC3B,KAAmB;IAEnB,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC;IAC7C,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,SAAS;QAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC;IAEjD,MAAM,aAAa,GAAG,CAAC,IAAwB,EAAsB,EAAE;QACrE,IAAI,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAChC,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,mBAAmB,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,mBAAmB,GAAG,KAAK,CAAC,CAAC;QACrF,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;IAChD,CAAC,CAAC;IAEF,MAAM,aAAa,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtC,GAAG,CAAC;QACJ,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACf,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;QACpE,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI;QAC5E,gBAAgB,EAAE,CAAC,CAAC,gBAAgB,IAAI,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,IAAI;QACpG,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC;KAC5B,CAAC,CAAC,CAAC;IACJ,MAAM,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAC,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAC,CAAC,CAAC,CAAC;IACzG,OAAO,EAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"backup.js","sourceRoot":"","sources":["../src/backup.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAyChC,MAAM,CAAC,MAAM,eAAe,GAA6B,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAE3G,iDAAiD;AACjD,MAAM,CAAC,MAAM,iBAAiB,GAAkC;IAC9D,KAAK,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;IAC1B,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;IAC/B,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;IACjC,MAAM,EAAE,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;CAClC,CAAC;AAgBF,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,OAAO,EAAE,KAAK;IACd,GAAG,EAAE,IAAI;IACT,QAAQ,EAAE,EAAC,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAC;IAClE,IAAI,EAAE,EAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,EAAC;IACnD,OAAO,EAAE,EAAE;CACZ,CAAC;AAmBF;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,KAAmB,EACnB,SAA2B,EAC3B,KAAmB;IAEnB,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC;IAC7C,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,SAAS;QAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC;IAEjD,MAAM,aAAa,GAAG,CAAC,IAAwB,EAAsB,EAAE;QACrE,IAAI,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAChC,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,mBAAmB,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,mBAAmB,GAAG,KAAK,CAAC,CAAC;QACrF,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;IAChD,CAAC,CAAC;IAEF,MAAM,aAAa,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtC,GAAG,CAAC;QACJ,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACf,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;QACpE,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI;QAC5E,gBAAgB,EAAE,CAAC,CAAC,gBAAgB,IAAI,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,IAAI;QACpG,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC;KAC5B,CAAC,CAAC,CAAC;IACJ,MAAM,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAC,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAC,CAAC,CAAC,CAAC;IACzG,OAAO,EAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAC,CAAC;AAC/D,CAAC"}