@k2b/cloud 0.39.0 → 0.40.0

package/src/services/service-account-credentials.ts

@@ -11,6 +11,7 @@ import {
   type StandaloneServiceAccountKind,
   serviceAccounts,
 } from "./service-accounts";
+import { ConfirmedBrowserSignInError, requireConfirmedBrowserSignIn } from "./session/recent";
 
 export type ServiceAccountCredentialStatus = "active" | "revoked";
 export type ServiceAccountCredentialKind = "api_token";
@@ -388,10 +389,27 @@ export const createApiToken = async (params: {
 
 export const createUserApiToken = async (params: {
   user: User;
+  browserSignIn: { userId: string; sid: string };
   access?: "full" | "models";
   name: string;
   expiresAt?: string | null;
 }): Promise<Result<{ credential: ServiceAccountCredential; token: string }>> => {
+  const confirmSignIn = async (db: SQL): Promise<ReturnType<typeof fail> | null> => {
+    if (params.browserSignIn.userId !== params.user.id) return fail(err.forbidden("The browser sign-in belongs to another account."));
+    try {
+      await requireConfirmedBrowserSignIn(db, params.browserSignIn, (code) => {
+        throw new ConfirmedBrowserSignInError(code);
+      });
+      return null;
+    } catch (error) {
+      if (error instanceof ConfirmedBrowserSignInError) return fail({ code: error.code, status: 403, message: error.message });
+      throw error;
+    }
+  };
+
+  // Checked before the key holder is created and again where the key is written.
+  const early = await confirmSignIn(sql);
+  if (early) return early;
   const serviceAccountResult = await getOrCreateUserDelegatedServiceAccount({
     userId: params.user.id,
     createdBy: params.user.id,
@@ -399,6 +417,9 @@ export const createUserApiToken = async (params: {
   if (!serviceAccountResult.ok) return fail(serviceAccountResult.error);
 
   return sql.begin(async (tx) => {
+    const rejected = await confirmSignIn(tx);
+    if (rejected) return rejected;
+
     const result = await insertApiToken(tx, {
       serviceAccountId: serviceAccountResult.data.id,
       name: params.name,

package/src/services/session/index.ts

@@ -5,6 +5,8 @@ import { HTTPException } from "hono/http-exception";
 import { env } from "../../config/env";
 import { PWA_AUTH_PATH, PWA_COOKIES } from "../../contracts/pwa";
 import type { User } from "../../contracts/shared";
+import { getLocale } from "../../server/locale";
+import { describeRequest } from "../../server/request-context";
 import { isAccountCategoryAllowed } from "../account-category-policy";
 import { isAccountExpired } from "../account-model";
 import { audit } from "../audit";
@@ -12,6 +14,17 @@ import { IDENTITY_CLOCK_TOLERANCE_SECONDS, IDENTITY_ROLLOUT_MARGIN_MS } from "..
 import { invalidateIdentitySignerCache, type PreparedIdentitySigner, prepareIdentitySigner } from "../identity/key-ring";
 import { getIdentityRuntimeConfig } from "../identity/runtime-config";
 import { type CloudSessionClaims, isSessionJwtCandidate, signSessionToken, verifySessionToken } from "../identity/session-token";
+import {
+  announceNewBrowser,
+  type NewBrowserSignInNotice,
+  type NewBrowserSignInNotifier,
+  newBrowserCookie,
+  noticeFirstName,
+  readBrowserCookie,
+  rememberSignIn,
+  type SignInMethod,
+  setBrowserCookie,
+} from "../known-browsers";
 import * as settings from "../settings";
 import { loadJwtSession, loadJwtSessionIdentity } from "./user";
 
@@ -144,12 +157,24 @@ const revokeToken = async (token: string, requestId?: string | null): Promise<vo
   }
 };
 
+export class SessionEpochChangedError extends Error {}
+/** The Cloud Login device that approved a sign-in was removed before the session was issued. */
+export class SessionAppDeviceInactiveError extends Error {}
+
 export type SessionIssueOptions = {
+  authEpoch?: number;
   ttlSeconds: number;
+  /** Only web session.create supplies browser persistence, never mobile issuance. */
+  knownBrowser?: Pick<
+    Parameters<typeof rememberSignIn>[1],
+    "cookie" | "browser" | "os" | "country" | "city" | "method" | "device" | "locale" | "announce"
+  >;
   /** Pre-chosen family id, for callers that record it in the same transaction. */
   sid?: string;
   /** Binds the family to a paired phone of the mobile app; the device must be active. */
   pwaDeviceId?: string | null;
+  /** The active Cloud Login device that approved this web sign-in. */
+  appDeviceId?: string;
   /** Web sign-ins update `last_login_local`; app renewals track use per device instead. */
   recordLogin?: boolean;
 };
@@ -162,12 +187,14 @@ type PreparedFamily = {
   expiresAt: Date;
   signer: PreparedIdentitySigner;
   options: SessionIssueOptions;
+  notice: NewBrowserSignInNotice | null;
 };
 
 const SIGNER_INACTIVE = "Prepared Cloud session signer is no longer active";
 const isSignerInactive = (error: unknown) => error instanceof Error && error.message === SIGNER_INACTIVE;
 
-/** Inserts one family in `tx`. Locks the user row first, like every caller that locks more rows. */
+/** Inserts one family in `tx`. Locks the user row first, like every caller that locks more rows; `NO KEY UPDATE`
+ * serializes with every other account lock but lets foreign-key checks of concurrent writes pass. */
 const insertFamily = async (
   tx: SQL,
   c: Context,
@@ -175,19 +202,22 @@ const insertFamily = async (
   signer: PreparedIdentitySigner,
   options: SessionIssueOptions,
 ): Promise<PreparedFamily> => {
-  const issuedAt = new Date();
-  const expiresAt = new Date(issuedAt.getTime() + options.ttlSeconds * 1_000);
   const sid = options.sid ?? crypto.randomUUID();
   const requestId = c.req.header("x-request-id")?.slice(0, 64) ?? null;
   const userAgent = c.req.header("user-agent")?.slice(0, 256) ?? null;
-  const [user] = await tx<Array<{ auth_epoch: string | number | bigint; provider: "local" | "ipa"; profile: "guest" | "user" }>>`
-    SELECT auth_epoch, provider, profile FROM auth.users WHERE id = ${userId}::uuid FOR UPDATE
+  const [user] = await tx<
+    Array<{ given_name: string | null; auth_epoch: string | number | bigint; provider: "local" | "ipa"; profile: "guest" | "user" }>
+  >`
+    SELECT given_name, auth_epoch, provider, profile FROM auth.users WHERE id = ${userId}::uuid FOR NO KEY UPDATE
   `;
   if (!user) throw new Error("Cannot create a session for an unknown user");
+  const issuedAt = new Date();
+  const expiresAt = new Date(issuedAt.getTime() + options.ttlSeconds * 1_000);
   if (!(await isAccountCategoryAllowed(user, tx)))
     throw new HTTPException(403, { message: "This account category is disabled. Contact an administrator." });
   const epoch = Number(user.auth_epoch);
   if (!Number.isSafeInteger(epoch) || epoch < 0) throw new Error("User auth_epoch is invalid");
+  if (options.authEpoch !== undefined && epoch !== options.authEpoch) throw new SessionEpochChangedError();
   if (options.pwaDeviceId) {
     // Device revocation locks the same user row first, so a revoked device never gets a new family.
     const [device] = await tx`
@@ -195,6 +225,14 @@ const insertFamily = async (
     `;
     if (!device) throw new Error("Cannot create an app session for an inactive device");
   }
+  if (options.appDeviceId) {
+    // A device that decides a terminal sign-in holds its row and then takes a key-share lock on this user row, so the
+    // user row above is held without blocking key-share locks. Removals that end the device's sign-ins hold the user
+    // row too, so they wait for this family.
+    const [device] = await tx`SELECT id FROM auth.app_devices
+      WHERE id=${options.appDeviceId}::uuid AND user_id=${userId}::uuid AND revoked_at IS NULL`;
+    if (!device) throw new SessionAppDeviceInactiveError("Cannot create a session for an inactive sign-in device");
+  }
   const [activeKey] = await tx<Array<{ kid: string }>>`
     UPDATE auth.signing_keys
     SET verify_until = GREATEST(verify_until, ${new Date(expiresAt.getTime() + IDENTITY_CLOCK_TOLERANCE_SECONDS * 1_000 + IDENTITY_ROLLOUT_MARGIN_MS)})
@@ -204,12 +242,15 @@ const insertFamily = async (
   if (!activeKey) throw new Error(SIGNER_INACTIVE);
   await tx`
     INSERT INTO auth.session_families (
-      sid, user_id, auth_epoch, signing_kid, issued_at, expires_at, created_request_id, created_user_agent, legal_pending, pwa_device_id
+      sid, user_id, auth_epoch, signing_kid, issued_at, expires_at, created_request_id, created_user_agent, legal_pending, pwa_device_id, app_device_id
     ) VALUES (${sid}, ${userId}, ${epoch}, ${signer.kid}, ${issuedAt}, ${expiresAt}, ${requestId}, ${userAgent},
-      NOT EXISTS (SELECT 1 FROM auth.legal_acceptances WHERE user_id = ${userId}::uuid), ${options.pwaDeviceId ?? null})
+      NOT EXISTS (SELECT 1 FROM auth.legal_acceptances WHERE user_id = ${userId}::uuid), ${options.pwaDeviceId ?? null}, ${options.appDeviceId ?? null})
   `;
+  const notice = options.knownBrowser
+    ? await rememberSignIn(tx, { ...options.knownBrowser, userId, firstName: noticeFirstName(user.given_name), now: issuedAt })
+    : null;
   if (options.recordLogin !== false) await tx`UPDATE auth.users SET last_login_local = ${issuedAt} WHERE id = ${userId}::uuid`;
-  return { userId, sid, authEpoch: epoch, issuedAt, expiresAt, signer, options };
+  return { userId, sid, authEpoch: epoch, issuedAt, expiresAt, signer, options, notice };
 };
 
 /** Signs a committed family. Null when the signer was revoked meanwhile; the family is revoked then. */
@@ -244,7 +285,13 @@ const signFamily = async (family: PreparedFamily): Promise<string | null> => {
 };
 
 /** One issuance attempt is retried once when the signing key changes underneath it. */
-const issueJwtSession = async (c: Context, userId: string, options: SessionIssueOptions, attempt = 0): Promise<string> => {
+const issueJwtSession = async (
+  c: Context,
+  userId: string,
+  options: SessionIssueOptions,
+  attempt = 0,
+  committedNotice: NewBrowserSignInNotice | null = null,
+): Promise<{ token: string; notice: NewBrowserSignInNotice | null }> => {
   const signer = await prepareIdentitySigner("session");
   let family: PreparedFamily;
   try {
@@ -252,13 +299,14 @@ const issueJwtSession = async (c: Context, userId: string, options: SessionIssue
   } catch (error) {
     if (attempt === 0 && isSignerInactive(error)) {
       invalidateIdentitySignerCache("session", signer.kid);
-      return issueJwtSession(c, userId, options, 1);
+      return issueJwtSession(c, userId, options, 1, committedNotice);
     }
     throw error;
   }
   const token = await signFamily(family);
-  if (token) return token;
-  if (attempt === 0) return issueJwtSession(c, userId, { ...options, sid: undefined }, 1);
+  const notice = committedNotice ?? family.notice;
+  if (token) return { token, notice };
+  if (attempt === 0) return issueJwtSession(c, userId, { ...options, sid: undefined }, 1, notice);
   throw new Error("Cloud session signer changed repeatedly during issuance");
 };
 
@@ -281,7 +329,7 @@ const issueInTransaction = async <T>(
       value = await sql.begin((tx) =>
         work(tx, async (userId, options) => {
           if (family) throw new Error("Only one session family per transaction");
-          family = await insertFamily(tx, c, userId, signer, options);
+          family = await insertFamily(tx, c, userId, signer, { ...options, knownBrowser: undefined });
           return family.sid;
         }),
       );
@@ -294,7 +342,7 @@ const issueInTransaction = async <T>(
     }
     if (!family) return { value, token: null };
     const token = await signFamily(family);
-    return { value, token: token ?? (await issueJwtSession(c, family.userId, { ...family.options, sid: undefined }, 1)) };
+    return { value, token: token ?? (await issueJwtSession(c, family.userId, { ...family.options, sid: undefined }, 1)).token };
   }
 };
 
@@ -349,11 +397,43 @@ export const session = {
 
   getBearerToken: (c: Context): string | null => parseBearer(c.req.header("Authorization")),
 
-  create: async (c: Context, userId: string): Promise<string> => {
+  create: async (
+    c: Context,
+    userId: string,
+    signIn: {
+      method: SignInMethod;
+      device?: string | null;
+      /** Null means this sign-in announces nothing, including during maintenance. */
+      notify: NewBrowserSignInNotifier | null;
+      /** Account epoch an earlier approval was bound to; issuance fails when sign-out everywhere moved it. */
+      authEpoch?: number;
+      /** The Cloud Login device that approved this sign-in; removing the device can end the session. */
+      appDeviceId?: string;
+    },
+  ): Promise<string> => {
     const expiryHours = await settings.get<number>("user.session.expiry_hours");
     if (!Number.isFinite(expiryHours) || expiryHours < 1) throw new Error("user.session.expiry_hours must be a positive number");
     const ttlSeconds = Math.floor(expiryHours * 60 * 60);
-    const clientToken = await issueJwtSession(c, userId, { ttlSeconds });
+    const cookie = readBrowserCookie(c) ?? newBrowserCookie();
+    const { browser, os, country, city } = describeRequest(c);
+    const { token: clientToken, notice } = await issueJwtSession(c, userId, {
+      ttlSeconds,
+      authEpoch: signIn.authEpoch,
+      appDeviceId: signIn.appDeviceId,
+      knownBrowser: {
+        cookie,
+        browser,
+        os,
+        country,
+        city,
+        method: signIn.method,
+        device: signIn.device ?? null,
+        locale: getLocale(c),
+        announce: signIn.notify !== null,
+      },
+    });
+    // Handoff precedes the response so the person signing in cannot turn the notice off first.
+    if (signIn.notify !== null && notice) await announceNewBrowser(signIn.notify, notice);
 
     setCookie(c, "session_token", clientToken, {
       httpOnly: true,
@@ -362,6 +442,7 @@ export const session = {
       maxAge: ttlSeconds,
       path: "/",
     });
+    setBrowserCookie(c, cookie);
     return clientToken;
   },
 

package/src/services/session/recent.ts

@@ -11,6 +11,15 @@ export type EligibleAccount = {
   account_expires: Date | null;
 };
 
+/** New personal access requires a browser sign-in from the last ten minutes. */
+export const LASTING_ACCESS_SIGN_IN_SECONDS = 600;
+
+export class ConfirmedBrowserSignInError extends Error {
+  constructor(readonly code: "REAUTHENTICATE" | "FORBIDDEN") {
+    super(code === "REAUTHENTICATE" ? "Sign in again to confirm it is you." : "This account cannot create new access.");
+  }
+}
+
 type Reject = (code: "REAUTHENTICATE" | "FORBIDDEN") => never;
 
 /** The account exists, has not expired and its category is enabled. */
@@ -40,3 +49,7 @@ export const requireRecentWebSession = async (
   if (!row) return reject("REAUTHENTICATE");
   return requireEligibleAccount(tx, actor.userId, reject);
 };
+
+/** Checks the browser session inside the transaction that creates personal access. */
+export const requireConfirmedBrowserSignIn = (tx: SQL, signIn: { userId: string; sid: string }, reject: Reject): Promise<EligibleAccount> =>
+  requireRecentWebSession(tx, signIn, LASTING_ACCESS_SIGN_IN_SECONDS, reject);

package/src/services/webauthn.ts

@@ -16,6 +16,7 @@ import { accounts } from "./accounts";
 import { audit } from "./audit";
 import { logger } from "./logging";
 import { isUniqueViolation, toPgTextArray } from "./postgres";
+import { ConfirmedBrowserSignInError, requireConfirmedBrowserSignIn } from "./session/recent";
 import { coreSettings } from "./settings/api";
 
 const CHALLENGE_TTL_SECONDS = 300;
@@ -185,6 +186,7 @@ export const beginRegistration = async (params: { user: User }): Promise<Result<
 
 export const finishRegistration = async (params: {
   user: User;
+  browserSignIn: { userId: string; sid: string };
   name: string;
   response: RegistrationResponseJSON;
 }): Promise<Result<WebAuthnPasskey>> => {
@@ -221,6 +223,16 @@ export const finishRegistration = async (params: {
 
   try {
     return sql.begin(async (tx) => {
+      if (params.browserSignIn.userId !== params.user.id) return fail(err.forbidden("The browser sign-in belongs to another account."));
+      try {
+        await requireConfirmedBrowserSignIn(tx, params.browserSignIn, (code) => {
+          throw new ConfirmedBrowserSignInError(code);
+        });
+      } catch (error) {
+        if (error instanceof ConfirmedBrowserSignInError) return fail({ code: error.code, status: 403, message: error.message });
+        throw error;
+      }
+
       const [row] = await tx<DbPasskeyRow[]>`
         INSERT INTO auth.webauthn_credentials (
           user_id,

package/src/shared/email-html.ts

@@ -10,6 +10,7 @@ export const EMAIL_HTML_TAGS = [
   "h1",
   "h2",
   "h3",
+  "hr",
   "li",
   "ol",
   "p",
@@ -33,6 +34,7 @@ export const EMAIL_HTML_ALLOWED_ATTRIBUTES: Record<string, string[]> = {
   h1: ["style"],
   h2: ["style"],
   h3: ["style"],
+  hr: ["style"],
   li: ["style"],
   ol: ["style"],
   p: ["style"],

package/src/shared/help.ts

@@ -1,5 +1,8 @@
 import { localeFallbackChain } from "./locale";
 
+/** Maximum number of page-specific Help articles shared with the panel. */
+export const HELP_VIEW_LIMIT = 3;
+
 export const HELP_KINDS = ["start", "task", "reference", "troubleshoot"] as const;
 export type HelpKind = (typeof HELP_KINDS)[number];
 /** The glossary's access levels; Help names only these, never app-specific permissions. */

package/src/shared-text/cursor.ts

@@ -0,0 +1,22 @@
+const STREAM_CURSOR_REGEX = /^s6t\.[A-Za-z0-9_-]+\.\d+$/;
+
+export const parseStreamCursor = (cursor: string | null | undefined): { resource: string; seq: number } | null => {
+  if (!cursor || !STREAM_CURSOR_REGEX.test(cursor)) return null;
+  const [, resource, sequence] = cursor.split(".");
+  const seq = Number(sequence);
+  if (!resource || !Number.isSafeInteger(seq) || seq < 0) return null;
+  return { resource, seq };
+};
+
+export const compareStreamCursor = (left: string, right: string): number => {
+  const l = parseStreamCursor(left);
+  const r = parseStreamCursor(right);
+  if (!l || !r || l.resource !== r.resource) throw new Error(`Invalid stream cursor comparison: "${left}" vs "${right}"`);
+  return l.seq - r.seq;
+};
+
+export const maxStreamCursor = (a: string | null, b: string | null): string | null => {
+  if (!a) return b;
+  if (!b) return a;
+  return compareStreamCursor(a, b) >= 0 ? a : b;
+};

package/src/shared-text/documents.ts

@@ -0,0 +1,142 @@
+import type { Topic } from "@k2b/sync";
+import * as Y from "yjs";
+import { compareStreamCursor } from "./cursor";
+import { SHARED_TEXT_NAME, sharedTextNodeId, toBase64 } from "./events";
+import { minimalTextDiff } from "./text-diff";
+import type {
+  SharedTextActor,
+  SharedTextContributor,
+  SharedTextEditResult,
+  SharedTextSnapshot,
+  SharedTextStore,
+  SharedTextStoredState,
+  SharedTextSyncEvent,
+} from "./types";
+
+type DocumentLog = {
+  topic(): Pick<Topic<SharedTextSyncEvent>, "latestCursor" | "publish">;
+  replay(config: {
+    docId: string;
+    after: string | null;
+    until: string;
+    doc: Y.Doc;
+    signal?: AbortSignal;
+  }): Promise<SharedTextContributor[]>;
+};
+
+/**
+ * Fallback text becomes the same Yjs items in every copy: an update published
+ * against one copy then applies to the next one, which a random client ID
+ * would leave pending and silently drop from the saved state.
+ */
+const FALLBACK_CLIENT_ID = 0;
+
+const createDoc = (stored: SharedTextStoredState): Y.Doc => {
+  const doc = new Y.Doc({ gc: true });
+  try {
+    if (stored.state) Y.applyUpdate(doc, stored.state, "snapshot");
+    else if (stored.text) {
+      const clientID = doc.clientID;
+      doc.clientID = FALLBACK_CLIENT_ID;
+      doc.getText(SHARED_TEXT_NAME).insert(0, stored.text);
+      doc.clientID = clientID;
+    }
+    return doc;
+  } catch (error) {
+    doc.destroy();
+    throw error;
+  }
+};
+
+export const bindDocuments = <Saved, Context>({ topic, replay }: DocumentLog, store: SharedTextStore<Saved, Context>) => {
+  return {
+    async read(docId: string, options: { signal?: AbortSignal } = {}): Promise<SharedTextSnapshot | null> {
+      const stored = await store.load(docId, options);
+      if (!stored) return null;
+      const latest = await topic().latestCursor({ tenantId: docId });
+      if (!latest || (stored.cursor && compareStreamCursor(latest, stored.cursor) <= 0))
+        return { state: stored.state, text: stored.text, cursor: stored.cursor };
+      const doc = createDoc(stored);
+      try {
+        await replay({ docId, after: stored.cursor, until: latest, doc, signal: options.signal });
+        return { state: Y.encodeStateAsUpdate(doc), text: doc.getText(SHARED_TEXT_NAME).toString(), cursor: latest };
+      } finally {
+        doc.destroy();
+      }
+    },
+    async edit(
+      docId: string,
+      options: { actor: SharedTextActor | null; context?: Context; signal?: AbortSignal },
+      update: (current: { text: string; contributors: SharedTextContributor[]; state(): Uint8Array }) => string | Promise<string>,
+    ): Promise<SharedTextEditResult<Saved>> {
+      const requestedAt = Date.now();
+      const stored = await store.load(docId, { signal: options.signal });
+      if (!stored) return { status: "notFound" };
+      const handle = topic();
+      const target = await handle.latestCursor({ tenantId: docId });
+      const doc = createDoc(stored);
+      try {
+        let contributors: SharedTextContributor[] = [];
+        try {
+          if (target) contributors = await replay({ docId, after: stored.cursor, until: target, doc, signal: options.signal });
+        } catch (error) {
+          // A cancelled request is not a sync failure: it throws like every other abort before publication.
+          options.signal?.throwIfAborted();
+          return { status: "syncFailed", error };
+        }
+        options.signal?.throwIfAborted();
+        const ytext = doc.getText(SHARED_TEXT_NAME);
+        const text = ytext.toString();
+        const next = await update({ text, contributors, state: () => Y.encodeStateAsUpdate(doc) });
+        if (next === text) return { status: "unchanged", text };
+        // A request cancelled while the callback ran must not publish a write.
+        options.signal?.throwIfAborted();
+        const diff = minimalTextDiff(text, next);
+        const beforeEditState = Y.encodeStateVector(doc);
+        doc.transact(() => {
+          if (diff.deleteCount > 0) ytext.delete(diff.index, diff.deleteCount);
+          if (diff.insert.length > 0) ytext.insert(diff.index, diff.insert);
+        }, "cli-edit");
+        const actor = options.actor;
+        const published = await handle.publish({
+          tenantId: docId,
+          data: {
+            kind: "sync",
+            payload: toBase64(Y.encodeStateAsUpdate(doc, beforeEditState)),
+            originNodeId: sharedTextNodeId,
+            originPeerId: null,
+            ...(actor ? { actor } : {}),
+          },
+        });
+        let persistedDoc: Y.Doc | undefined;
+        try {
+          persistedDoc = createDoc(stored);
+          await replay({ docId, after: stored.cursor, until: published.cursor, doc: persistedDoc, signal: options.signal });
+          const persistedText = persistedDoc.getText(SHARED_TEXT_NAME).toString();
+          const credited = new Map(contributors.map((contributor) => [`${contributor.kind}:${contributor.id}`, contributor]));
+          if (actor) credited.set(`${actor.kind}:${actor.id}`, { ...actor, lastContributedAt: new Date(requestedAt) });
+          const saved = await store.save(
+            docId,
+            {
+              state: Y.encodeStateAsUpdate(persistedDoc),
+              text: persistedText,
+              cursor: published.cursor,
+              restoreRevision: stored.restoreRevision,
+              requestedAt,
+              actor,
+              contributors: [...credited.values()],
+            },
+            options.context,
+          );
+          return { status: "edited", text: persistedText, cursor: published.cursor, saved };
+        } catch (error) {
+          return { status: "persistFailed", cursor: published.cursor, error };
+        } finally {
+          persistedDoc?.destroy();
+        }
+      } finally {
+        doc.destroy();
+      }
+    },
+  };
+};

package/src/shared-text/events.ts

@@ -0,0 +1,43 @@
+import { fromBase64Strict } from "@k2b/stdlib";
+import * as Y from "yjs";
+import type { SharedTextEvent } from "./types";
+
+export const SHARED_TEXT_NAME = "codemirror";
+export const sharedTextNodeId = crypto.randomUUID();
+export const toBase64 = (data: Uint8Array): string => Buffer.from(data).toString("base64");
+export const fromBase64 = fromBase64Strict;
+
+/** A retained event cannot be decoded as a Yjs update: retrying never helps, no replay can pass it. */
+export class MalformedSharedTextEventError extends Error {
+  constructor(
+    readonly docId: string,
+    readonly cursor: string,
+    cause: unknown,
+  ) {
+    super(`Malformed sync event for document ${docId} at cursor ${cursor}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    this.name = "MalformedSharedTextEventError";
+  }
+}
+
+/** Ingress check: a publish is accepted only when it is base64 of a decodable Yjs update. */
+export const isValidSharedTextUpdate = (payload: string): boolean => {
+  try {
+    Y.decodeUpdate(fromBase64(payload));
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const applySharedTextEvent = (doc: Y.Doc, event: { cursor: string; data: SharedTextEvent }, docId: string): void => {
+  if (event.data.kind !== "sync") return;
+  try {
+    const update = fromBase64(event.data.payload);
+    // Decode completely before mutating the document: malformed bytes must not
+    // partially integrate state before recovery skips the invalid event.
+    Y.decodeUpdate(update);
+    Y.applyUpdate(doc, update, `replay:${event.cursor}`);
+  } catch (error) {
+    throw new MalformedSharedTextEventError(docId, event.cursor, error);
+  }
+};

package/src/shared-text/index.ts

@@ -0,0 +1,12 @@
+export { compareStreamCursor, maxStreamCursor, parseStreamCursor } from "./cursor";
+export {
+  applySharedTextEvent,
+  fromBase64,
+  isValidSharedTextUpdate,
+  MalformedSharedTextEventError,
+  SHARED_TEXT_NAME,
+  sharedTextNodeId,
+  toBase64,
+} from "./events";
+export { sharedText } from "./log";
+export * from "./types";

package/src/shared-text/log.ts

@@ -0,0 +1,48 @@
+import type { TopicConfig } from "@k2b/sync";
+import type * as Y from "yjs";
+import { getProcessSync } from "../_internal/process-sync";
+import { compareStreamCursor } from "./cursor";
+import { bindDocuments } from "./documents";
+import { applySharedTextEvent } from "./events";
+import type { SharedTextContributor, SharedTextStore, SharedTextSyncEvent } from "./types";
+
+const define = (topicConfig: Readonly<Pick<TopicConfig, "id" | "retention" | "deadLetterRetention" | "maxPayloadBytes">>) => {
+  const topic = () => getProcessSync().topic<SharedTextSyncEvent>(topicConfig);
+  const replay = async (config: {
+    docId: string;
+    after: string | null;
+    until: string;
+    doc: Y.Doc;
+    signal?: AbortSignal;
+  }): Promise<SharedTextContributor[]> => {
+    const contributors = new Map<string, SharedTextContributor>();
+    const handle = topic();
+    const after = config.after ?? handle.cursorAt(0);
+    if (compareStreamCursor(after, config.until) >= 0) return [];
+    let reachedTarget = false;
+    for await (const event of handle.replay({ tenantId: config.docId, after, until: config.until, signal: config.signal })) {
+      applySharedTextEvent(config.doc, event, config.docId);
+      if (event.data.actor)
+        contributors.set(`${event.data.actor.kind}:${event.data.actor.id}`, {
+          ...event.data.actor,
+          lastContributedAt: event.publishedAt,
+        });
+      reachedTarget = event.cursor === config.until;
+    }
+    if (!reachedTarget) throw new Error(`Target cursor "${config.until}" was not reached during replay`);
+    return [...contributors.values()];
+  };
+
+  return {
+    id: topicConfig.id,
+    topicConfig,
+    topic,
+    replay,
+    withStore<Saved, Context>(store: SharedTextStore<Saved, Context>) {
+      return bindDocuments({ topic, replay }, store);
+    },
+  };
+};
+
+/** Server-only document logs. Applications authorize callers before read/edit. */
+export const sharedText = { define };

package/src/shared-text/text-diff.ts

@@ -0,0 +1,23 @@
+const splitsSurrogatePair = (text: string, index: number): boolean => {
+  const before = text.charCodeAt(index - 1);
+  const after = text.charCodeAt(index);
+  return before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff;
+};
+
+/** One replacement retaining the shared prefix and suffix at Unicode boundaries. */
+export const minimalTextDiff = (before: string, after: string): { index: number; deleteCount: number; insert: string } => {
+  let index = 0;
+  while (index < before.length && index < after.length && before[index] === after[index]) index++;
+  if (splitsSurrogatePair(before, index) || splitsSurrogatePair(after, index)) index--;
+
+  let suffix = 0;
+  while (
+    suffix < before.length - index &&
+    suffix < after.length - index &&
+    before[before.length - suffix - 1] === after[after.length - suffix - 1]
+  )
+    suffix++;
+  if (splitsSurrogatePair(before, before.length - suffix) || splitsSurrogatePair(after, after.length - suffix)) suffix--;
+
+  return { index, deleteCount: before.length - index - suffix, insert: after.slice(index, after.length - suffix) };
+};