@jant/core 0.6.16 → 0.7.0

package/src/services/auth.ts

@@ -21,8 +21,12 @@ import {
 import type { SettingsService } from "./settings.js";
 import type { StorageDriver } from "../lib/storage.js";
 import { SETTINGS_KEYS } from "../lib/constants.js";
-import { timingSafeEqualText } from "../lib/crypto.js";
-import { ValidationError, NotFoundError } from "../lib/errors.js";
+import { hmacHex, timingSafeEqualText } from "../lib/crypto.js";
+import {
+  ConfigurationError,
+  ValidationError,
+  NotFoundError,
+} from "../lib/errors.js";
 import { hashPassword } from "../lib/password.js";
 
 /** Dependencies for account deletion */
@@ -53,20 +57,27 @@ export interface AuthService {
   resetPassword(token: string, newPassword: string): Promise<void>;
 
   /**
-   * Generate a short-lived CSRF token for account deletion.
-   * Stores the hash + expiry in settings and returns the plaintext.
+   * Derive the account-deletion CSRF token for a session.
+   *
+   * Derived, not stored: rendering the delete page is a GET, and a GET that
+   * wrote a fresh token somewhere would invalidate every copy handed out
+   * before it — a second tab, a prefetch, or a browser extension re-fetching
+   * the page would silently break the button the author is looking at. Same
+   * session in, same token out, however many times it is asked for.
    *
-   * @returns The plaintext CSRF token to embed in the page
+   * @param sessionId - The signed-in session this token is bound to
+   * @returns The token to embed in the page
    */
-  generateDeleteCsrfToken(): Promise<string>;
+  generateDeleteCsrfToken(sessionId: string): Promise<string>;
 
   /**
-   * Validate a CSRF token for account deletion.
+   * Validate an account-deletion CSRF token against the requesting session.
    *
-   * @param token - The plaintext CSRF token from the form
-   * @returns true if valid and not expired
+   * @param token - The token submitted with the request
+   * @param sessionId - The session the request arrived on
+   * @returns `true` when the token belongs to this session
    */
-  validateDeleteCsrfToken(token: string): Promise<boolean>;
+  validateDeleteCsrfToken(token: string, sessionId: string): Promise<boolean>;
 
   /**
    * Delete all user data and reset the instance to a pristine state.
@@ -87,6 +98,8 @@ export function createAuthService(
   settings: SettingsService,
   config?: {
     databaseDialect?: DatabaseDialect;
+    /** Signing key for derived tokens. Absent only where no route needs one. */
+    authSecret?: string;
   },
   databaseSchema: DatabaseSchema = sqliteSchemaBundle,
 ): AuthService {
@@ -97,6 +110,7 @@ export function createAuthService(
     verification,
     media,
     collections,
+    smartCollections,
     threadCollections,
     pathRegistry,
     collectionDirectoryItems: directoryItemsTable,
@@ -108,6 +122,7 @@ export function createAuthService(
     apiTokens,
   } = databaseSchema;
   const databaseDialect = config?.databaseDialect ?? "sqlite";
+  const authSecret = config?.authSecret;
 
   async function deleteDataRows(targetDb: Database): Promise<void> {
     // Junction/dependent tables first
@@ -125,6 +140,12 @@ export function createAuthService(
     );
     await executeStatement(targetDb, sql`DELETE FROM post`);
 
+    // Both kinds of collection, and smart ones first — a smart collection holds
+    // a `collection_id`. There is no constraint forcing that order any more
+    // (see the note on the column in `db/schema.ts`), but a reset that walks
+    // every table by hand should not leave one of them to an implicit cascade
+    // from `site` at the very end.
+    await targetDb.delete(smartCollections);
     await targetDb.delete(collections);
     await targetDb.delete(apiTokens);
     await targetDb.delete(settingsTable);
@@ -174,14 +195,21 @@ export function createAuthService(
     return timingSafeEqualText(tokenHash, storedHash);
   }
 
-  async function hashToken(token: string): Promise<string> {
-    const hashBuffer = await crypto.subtle.digest(
-      "SHA-256",
-      new TextEncoder().encode(token),
-    );
-    return Array.from(new Uint8Array(hashBuffer))
-      .map((b) => b.toString(16).padStart(2, "0"))
-      .join("");
+  /**
+   * The delete-account token for a session — a pure function of the session and
+   * the server's signing key, so nothing has to be written down to check it
+   * later. It stops being valid when the session does, which is the only
+   * lifetime that means anything here: the token is a second factor on top of
+   * the session cookie, useless to anyone who does not already hold it.
+   */
+  async function deriveDeleteCsrfToken(sessionId: string): Promise<string> {
+    if (!authSecret) {
+      throw new ConfigurationError(
+        "AUTH_SECRET is required to protect account deletion.",
+      );
+    }
+
+    return hmacHex(authSecret, `delete-account:${sessionId}`);
   }
 
   return {
@@ -217,39 +245,13 @@ export function createAuthService(
       await settings.remove(SETTINGS_KEYS.PASSWORD_RESET_TOKEN);
     },
 
-    async generateDeleteCsrfToken() {
-      const bytes = new Uint8Array(32);
-      crypto.getRandomValues(bytes);
-      const plaintext = Array.from(bytes)
-        .map((b) => b.toString(16).padStart(2, "0"))
-        .join("");
-
-      const tokenHash = await hashToken(plaintext);
-      // Token valid for 15 minutes
-      const expiry = Math.floor(Date.now() / 1000) + 15 * 60;
-
-      await settings.set(
-        SETTINGS_KEYS.DELETE_CSRF_TOKEN,
-        `${tokenHash}:${expiry}`,
-      );
-
-      return plaintext;
+    async generateDeleteCsrfToken(sessionId) {
+      return deriveDeleteCsrfToken(sessionId);
     },
 
-    async validateDeleteCsrfToken(token) {
-      const stored = await settings.get(SETTINGS_KEYS.DELETE_CSRF_TOKEN);
-      if (!stored) return false;
-
-      const separatorIndex = stored.lastIndexOf(":");
-      const storedHash = stored.substring(0, separatorIndex);
-      const expiry = parseInt(stored.substring(separatorIndex + 1), 10);
-      const now = Math.floor(Date.now() / 1000);
-
-      if (now > expiry) return false;
-
-      const tokenHash = await hashToken(token);
-
-      return timingSafeEqualText(tokenHash, storedHash);
+    async validateDeleteCsrfToken(token, sessionId) {
+      const expected = await deriveDeleteCsrfToken(sessionId);
+      return timingSafeEqualText(token, expected);
     },
 
     async deleteAllData(deps) {

package/src/services/bootstrap.ts

@@ -1,83 +1,233 @@
 /**
  * Bootstrap Service
  *
- * Owns first-run site shell setup after account creation.
+ * Owns first-run setup, which runs in two acts on a self-hosted site: the
+ * account is created first, and everything about the site itself is settled
+ * afterwards. The two are separate methods because the site is left standing
+ * between them — `markSiteProvisioned` closes the first act, which is the same
+ * state a control plane leaves a hosted site in, so the second act is one code
+ * path for both install kinds.
+ *
+ * The first act belongs to self-hosted installs alone. A hosted site gets its
+ * owner through the control plane's handoff, so on a host-based install only
+ * the second act runs, against the site the request resolved — the same site
+ * the route's membership check reads. On a hosted install the database holds
+ * every tenant, so "the only site" is not a question with an answer there.
  */
 
+import type { DatabaseDialect } from "../db/dialect.js";
 import type { Database } from "../db/index.js";
 import {
   sqliteSchemaBundle,
   type DatabaseSchema,
 } from "../db/schema-bundle.js";
-import {
-  baseLocale,
-  isValidContentLanguage,
-  normalizeContentLanguage,
-  resolveCatalogLocale,
-} from "../i18n/locales.js";
 import { createNavItemService } from "./navigation.js";
 import { createSettingsService } from "./settings.js";
 import { createSiteMemberService } from "./site-member.js";
-import { createSiteService, type EnsureSingleSiteOptions } from "./site.js";
+import {
+  createSiteService,
+  TRANSIENT_SINGLE_SITE_ID,
+  type EnsureSingleSiteOptions,
+} from "./site.js";
 
-export interface CompleteInitialSetupData {
+export interface ProvisionOwnerAccountData {
+  /** The account the first setup screen just created. */
   ownerUserId: string;
-  siteName: string;
+}
+
+export interface CompleteSiteSetupData {
+  /**
+   * The site's name, on an install that does not have one yet.
+   *
+   * Omitted on a hosted site: the control plane named it at creation, so the
+   * second screen never asks and must not overwrite.
+   */
+  siteName?: string | null;
+  /** Language the site publishes in, chosen explicitly during setup. */
   siteLanguage?: string | null;
-  cjkSerifFont?: string | null;
+  /**
+   * The browser's own language, used only to pin the dashboard UI locale.
+   *
+   * Kept separate from `siteLanguage` because the two genuinely differ for the
+   * people this matters to most: someone running an English-language blog from
+   * a Chinese browser wants an English site and a Chinese dashboard.
+   */
+  browserLanguage?: string | null;
+  /**
+   * The browser's time zone, already mapped to a supported one by the caller.
+   *
+   * Omitted where the shell already carries one, so a second screen loaded in
+   * a different place cannot move a hosted site's clock.
+   */
   timeZone?: string | null;
 }
 
+export interface CompleteSiteSetupDeps {
+  /**
+   * Align the operator's better-auth account name with the site's display
+   * name, the way the general settings page does whenever the name changes.
+   *
+   * Injected rather than called here: the update needs the request's own
+   * headers to know whose account it is, and a service has none.
+   */
+  updateCurrentUserName?: ((displayName: string) => Promise<void>) | null;
+}
+
 export interface BootstrapService {
   /**
-   * Complete first-run setup for a newly created account.
-   * Materializes the versioned navigation profile and marks onboarding complete
-   * last so an interrupted setup can recover safely.
+   * Stand the site up around a newly created owner account.
+   *
+   * Everything here is what a site needs to exist at all — a row, an owner, a
+   * navigation profile. Nothing here is an answer the author gave, because at
+   * this point they have given none beyond their credentials.
+   *
+   * Ends by marking the site provisioned rather than complete. That is what
+   * makes the gap between the two screens survivable: at `provisioned` the
+   * onboarding middleware serves `/signin` normally, so an author who loses
+   * the session before finishing signs back in and lands on the second screen.
    *
-   * @param data - Initial site shell values captured during setup
+   * @param data - The account the first screen created
+   * @throws {Error} On a host-based install, where a site's owner arrives
+   *   through the control plane's handoff instead
    */
-  completeInitialSetup(data: CompleteInitialSetupData): Promise<void>;
+  provisionOwnerAccount(data: ProvisionOwnerAccountData): Promise<void>;
+
+  /**
+   * Close first-run setup by recording what the author said about their site.
+   *
+   * Shared by both install kinds: a self-hosted site arrives here from its
+   * second screen with a name to set, a hosted site from its only screen with
+   * the name already stored. Onboarding is marked complete last, so an
+   * interrupted run resumes rather than stranding a half-answered site.
+   *
+   * @param data - The answers the second screen collected
+   * @param opts - The language in effect before this answer
+   * @param deps - Cross-cutting work the route owns, such as the better-auth
+   *   account rename that needs the request's headers
+   */
+  completeSiteSetup(
+    data: CompleteSiteSetupData,
+    opts: { oldLanguage: string },
+    deps?: CompleteSiteSetupDeps,
+  ): Promise<void>;
 }
 
+/**
+ * Create the first-run setup service for one request.
+ *
+ * @param db - The database
+ * @param siteId - The site the request resolved. On a self-hosted install that
+ *   has not finished the account step this is the transient placeholder, since
+ *   no site row exists yet.
+ * @param options - The schema, dialect and resolution mode the runtime uses,
+ *   and where a self-hosted site's row and domain come from
+ * @returns The bootstrap service bound to that site
+ */
 export function createBootstrapService(
   db: Database,
+  siteId: string,
   options?: {
     schema?: DatabaseSchema;
+    databaseDialect?: DatabaseDialect;
     bootstrapSite?: EnsureSingleSiteOptions;
+    siteResolutionMode?: "single-site" | "host-based";
   },
 ): BootstrapService {
   const databaseSchema = options?.schema ?? sqliteSchemaBundle;
+  const dialect = options?.databaseDialect ?? "sqlite";
+  const siteResolutionMode = options?.siteResolutionMode ?? "single-site";
+
+  /**
+   * The request's site, which must be a real row by the time anything is
+   * written to it. The placeholder only stands in for a self-hosted site the
+   * account step has yet to create.
+   */
+  function existingSiteId(step: string): string {
+    if (siteId === TRANSIENT_SINGLE_SITE_ID) {
+      throw new Error(
+        `${step} needs an existing site, but the request resolved none.`,
+      );
+    }
+    return siteId;
+  }
+
+  /**
+   * The site the account step stands up. A self-hosted install has no row
+   * until now, so this is the step that creates it — along with its domain,
+   * when one is configured.
+   *
+   * A host-based install refuses before anything is written. The control
+   * plane creates each hosted site already provisioned, and its owner arrives
+   * through the hosted handoff, the only way anyone becomes a member of one.
+   * Attaching whoever just signed in to the site the host resolved would let
+   * any account in a database every tenant shares take a site that had lost
+   * its onboarding status.
+   */
+  async function siteToProvision(): Promise<string> {
+    if (siteResolutionMode === "host-based") {
+      throw new Error(
+        "provisionOwnerAccount runs on self-hosted installs only. A hosted site's owner arrives through the control plane's handoff.",
+      );
+    }
+    const { site } = await createSiteService(
+      db,
+      databaseSchema,
+    ).ensureSingleSite(options?.bootstrapSite);
+    return site.id;
+  }
 
   return {
-    async completeInitialSetup(data) {
-      const siteService = createSiteService(db, databaseSchema);
-      const { site } = await siteService.ensureSingleSite(
-        options?.bootstrapSite,
+    async provisionOwnerAccount(data) {
+      const provisionedSiteId = await siteToProvision();
+      const settings = createSettingsService(
+        db,
+        provisionedSiteId,
+        databaseSchema,
+        dialect,
+      );
+      const navItems = createNavItemService(
+        db,
+        provisionedSiteId,
+        databaseSchema,
       );
-      const settings = createSettingsService(db, site.id, databaseSchema);
-      const navItems = createNavItemService(db, site.id, databaseSchema);
       const siteMembers = createSiteMemberService(db, databaseSchema);
 
-      await siteMembers.ensure(site.id, data.ownerUserId, "owner");
+      await siteMembers.ensure(provisionedSiteId, data.ownerUserId, "owner");
       await navItems.materializeDefaultNavigation();
-      await settings.set("SITE_NAME", data.siteName.trim());
-      await settings.set("TIME_ZONE", data.timeZone ?? "UTC");
-      const siteLanguage =
-        data.siteLanguage && isValidContentLanguage(data.siteLanguage)
-          ? normalizeContentLanguage(data.siteLanguage)
-          : baseLocale;
-      await settings.set("SITE_LANGUAGE", siteLanguage);
-      // Pin the dashboard UI locale to the detected catalog language so it stays
-      // stable if the operator later changes the public content language.
-      await settings.set(
-        "DASHBOARD_LANGUAGE",
-        resolveCatalogLocale(siteLanguage),
+      await settings.markSiteProvisioned();
+    },
+
+    async completeSiteSetup(data, opts, deps) {
+      const settings = createSettingsService(
+        db,
+        existingSiteId("completeSiteSetup"),
+        databaseSchema,
+        dialect,
       );
-      if (data.cjkSerifFont && data.cjkSerifFont !== "off") {
-        await settings.set("CJK_SERIF_FONT", data.cjkSerifFont);
+
+      const siteName = data.siteName?.trim();
+      if (siteName) {
+        await settings.set("SITE_NAME", siteName);
+        // Before onboarding closes, deliberately: if the rename fails the site
+        // is still provisioned, and the author retries the screen they were
+        // already on rather than landing in a finished site under a stale name.
+        await deps?.updateCurrentUserName?.(siteName);
       }
 
-      await settings.completeOnboarding();
+      // `undefined` means the shell already has one. `null` is a browser that
+      // reported nothing, which is the same UTC default the site would fall
+      // back to anyway — written so a later reader sees a chosen value.
+      if (data.timeZone !== undefined) {
+        await settings.set("TIME_ZONE", data.timeZone ?? "UTC");
+      }
+
+      await settings.confirmFirstRunLanguage(
+        {
+          siteLanguage: data.siteLanguage ?? "",
+          browserLanguage: data.browserLanguage,
+        },
+        opts,
+      );
     },
   };
 }

package/src/services/collection-directory-position.ts

@@ -0,0 +1,76 @@
+/**
+ * Positions in the collections directory.
+ *
+ * The directory is one ordered list — manual collections, smart collections,
+ * dividers, and links share it — ordered by a fractional index, so a move
+ * rewrites a single row instead of renumbering the list.
+ *
+ * Two services write into that list: `collection` places manual collections
+ * along with the author's dividers and links, `smart-collection` places smart
+ * collections. The append rule lives here so the second writer cannot invent a
+ * different one.
+ */
+
+import { eq, sql } from "drizzle-orm";
+import { generateKeyBetween } from "fractional-indexing";
+import type { Database } from "../db/index.js";
+import type { DatabaseSchema } from "../db/schema-bundle.js";
+
+type DirectoryItemsTable = DatabaseSchema["collectionDirectoryItems"];
+
+/**
+ * How many times a writer retries after two rows land on the same position.
+ *
+ * `(site_id, position)` is unique, so a concurrent append can lose the race;
+ * the next attempt reads the new last position and appends after it.
+ */
+export const DIRECTORY_POSITION_RETRY_ATTEMPTS = 5;
+
+/**
+ * The position of the last row in a site's collections directory.
+ *
+ * @param db - Database handle
+ * @param table - The `collection_directory_item` table for this dialect
+ * @param siteId - Site the directory belongs to
+ * @returns The largest position, or `null` when the directory is empty
+ * @example
+ * ```ts
+ * const last = await getLastDirectoryPosition(db, directoryItems, siteId);
+ * ```
+ */
+export async function getLastDirectoryPosition(
+  db: Database,
+  table: DirectoryItemsTable,
+  siteId: string,
+): Promise<string | null> {
+  const rows = await db
+    .select({ position: table.position })
+    .from(table)
+    .where(eq(table.siteId, siteId))
+    .orderBy(sql`${table.position} DESC`)
+    .limit(1);
+  return rows[0]?.position ?? null;
+}
+
+/**
+ * A position that puts a new row at the end of the directory.
+ *
+ * @param db - Database handle
+ * @param table - The `collection_directory_item` table for this dialect
+ * @param siteId - Site the directory belongs to
+ * @returns A fractional index greater than every existing position
+ * @example
+ * ```ts
+ * const position = await getAppendDirectoryPosition(db, directoryItems, siteId);
+ * ```
+ */
+export async function getAppendDirectoryPosition(
+  db: Database,
+  table: DirectoryItemsTable,
+  siteId: string,
+): Promise<string> {
+  return generateKeyBetween(
+    await getLastDirectoryPosition(db, table, siteId),
+    null,
+  );
+}