@tldraw/sync-collaboration 5.3.0-next.2fa9c61a8de6 → 5.3.0-next.7654e7ac2a02

package/dist-esm/index.d.mts

@@ -10,9 +10,9 @@ import type { TLRecordAuthorizers } from '@tldraw/sync-core';
  */
 export declare interface CommentAuthorizerOptions<SessionMeta> {
     /**
-     * Resolve the authenticated user id for a session from its host-provided `meta`. Return
-     * `null` for anonymous sessions — they can't create comments or threads, and can't perform
-     * any owner-only action. Called exactly once per authorized write.
+     * Resolve the authenticated user id for a session from its host-provided `meta`. Return `null`
+     * for anonymous sessions — they can't create records, and own none, so the default
+     * {@link CommentAuthorizerOptions.canModifyComment} grants them no edits or deletes either.
      */
     getUserId(session: {
         isReadonly: boolean;
@@ -20,39 +20,114 @@ export declare interface CommentAuthorizerOptions<SessionMeta> {
         sessionId: string;
     }): null | string;
     /**
-     * Whether a session may write comment records at all — checked before the per-type rules on
-     * every create, update, and delete. Defaults to `({ isReadonly }) => !isReadonly`: comment
-     * writes follow canvas access, so read-only viewers can read threads but not post, edit,
-     * resolve, or react. Override to decouple the lanes — `() => true` allows commenting on a
-     * read-only canvas (comment-only setups) — or to enforce custom criteria from the session.
+     * Whether a session may write comment records at all — checked before the per-type rules.
+     * Defaults to `({ isReadonly }) => !isReadonly`, so read-only viewers can read threads but not
+     * post. Override to decouple the lanes: `() => true` allows commenting on a read-only canvas.
      */
     canComment?(session: {
         isReadonly: boolean;
         meta: SessionMeta;
         sessionId: string;
     }): boolean;
+    /**
+     * Whether a session may make a particular write against a particular stored record: editing or
+     * deleting a comment, or deleting a thread. Defaults to
+     * `({ userId, ownerId }) => userId === ownerId` — the owner-only rule enforced up to now.
+     * Override to widen it (a workspace admin or moderator who may take down anyone's comment) or
+     * to narrow it (no edits after an hour).
+     *
+     * The counterpart to `canModifyComment` in `@tldraw/commenting`, which decides which
+     * affordances the UI offers. This one is the real rule, and the two want widening together: a
+     * delete the client offers and this rejects is applied locally, vetoed, and rebased away — the
+     * comment comes back with nothing to explain it.
+     *
+     * Asked after {@link CommentAuthorizerOptions.canComment} and after the structural rules, so it
+     * can only widen *who* may write, never *what* a write may contain. However permissive the
+     * callback, attribution is still stamped from the session and immutable, `isDeleted` is still
+     * write-once and never set at create, `threadId` and `createdAt` are still frozen, a
+     * resolution is still the resolver's own, and clients still can't hard-delete.
+     *
+     * A soft delete that changes anything besides the flag is asked about twice — once as the
+     * delete, once as an edit — so granting deletes alone can't be talked into an edit.
+     *
+     * Called at most once per authorized write, twice for that combined case.
+     *
+     * @example
+     * ```ts
+     * createCommentAuthorizers<SessionMeta>({
+     * 	getUserId: (session) => session.meta.userId,
+     * 	// Moderators may take anything down. Editing stays the author's, whoever you are.
+     * 	canModifyComment: (ctx) =>
+     * 		(ctx.action !== 'edit-comment' && isModerator(ctx.session.meta)) ||
+     * 		ctx.userId === ctx.ownerId,
+     * })
+     * ```
+     */
+    canModifyComment?(ctx: CommentModificationAuthContext<SessionMeta>): boolean;
 }
 
+/**
+ * A comment write that belongs to someone in particular, and the stored record it targets — the
+ * argument to {@link CommentAuthorizerOptions.canModifyComment}, and the server-side mirror of
+ * `CommentModification` in `@tldraw/commenting`.
+ *
+ * The record is the one the room holds, never the client's version of it: the incoming record is
+ * the thing being authorized, so a rule that read it would be asking the writer who owns what
+ * they're writing to.
+ *
+ * Resolving, reopening, and reacting aren't here, matching the client option: none of them is
+ * anyone's in particular, so {@link CommentAuthorizerOptions.canComment} is the only gate on them.
+ *
+ * @public
+ */
+export declare type CommentModification = {
+    readonly action: 'delete-comment';
+    readonly comment: TLComment;
+} | {
+    readonly action: 'delete-thread';
+    readonly thread: TLCommentThread;
+} | {
+    readonly action: 'edit-comment';
+    readonly comment: TLComment;
+};
+
+/**
+ * The argument to {@link CommentAuthorizerOptions.canModifyComment}: which write, against which
+ * stored record, by which session.
+ *
+ * `ownerId` is that record's owner — a comment's `authorId`, a thread's `createdBy` — so a callback
+ * widening the default doesn't have to know which field each record keeps it in.
+ *
+ * @public
+ */
+export declare type CommentModificationAuthContext<SessionMeta> = {
+    readonly ownerId: string;
+    readonly session: {
+        isReadonly: boolean;
+        meta: SessionMeta;
+        sessionId: string;
+    };
+    readonly userId: null | string;
+} & CommentModification;
+
 /**
  * Server-side write authorization for comment records, for use with a sync server's
- * `authorizeRecord` option (see `TLSocketRoom` in `@tldraw/sync-core`). Forces comment and
- * thread authorship from the session's identity so nothing can be posted, resolved, or deleted
- * in someone else's name:
+ * `authorizeRecord` option (see `TLSocketRoom` in `@tldraw/sync-core`). Forces authorship from the
+ * session's identity so nothing can be posted, resolved, or deleted in someone else's name:
  *
- * - `comment`: `authorId` is stamped from the session on create (anonymous creates are
- *   rejected) and immutable afterwards; only the author may update. `threadId` and `createdAt`
- *   are immutable too — a comment can't be re-parented or back-dated after the fact.
- * - `comment-thread`: `createdBy` and `createdAt` are stamped/fixed on create. Anyone with access
- *   may resolve/reopen, but a non-null `resolved.by` must be the session's own user.
- * - `comment-reaction`: `userId` is stamped on create and immutable; a create must land at the
- *   canonical id for its (comment, user, emoji) triple, everything identity-bearing is immutable
- *   on update, and only the reactor may delete their own reaction.
- * - Deletion is soft for comments and threads: a write-once `isDeleted` flag that only the
- *   record's owner may set, never cleared, never set at create. Client hard-deletes are always
- *   rejected — record removals are server-side only.
- * - `canComment` gates every create, update, and delete above, before the per-type rules run.
- *   By default it mirrors the session's canvas access (`!isReadonly`), so read-only viewers can
- *   read threads but not write to them; override it to decouple commenting from canvas access.
+ * - `comment`: `authorId` is stamped on create (anonymous creates rejected) and immutable after,
+ *   and who may update is `canModifyComment`'s call — the author's, unless widened. `threadId` and
+ *   `createdAt` are immutable too.
+ * - `comment-thread`: `createdBy` and `createdAt` are fixed on create. Anyone with access may
+ *   resolve/reopen, but a non-null `resolved.by` must be the session's own user.
+ * - `comment-reaction`: `userId` is stamped and immutable, a create must land at the canonical id
+ *   for its (comment, user, emoji) triple, and only the reactor may delete their own.
+ * - Deletion is soft for comments and threads: a write-once `isDeleted` flag, never set at create.
+ *   Client hard-deletes are always rejected — record removals are server-side only.
+ * - `canComment` gates every write before the per-type rules, defaulting to `!isReadonly`.
+ * - `canModifyComment` decides who may edit a comment, delete a comment, or delete a thread. It
+ *   defaults to the record's owner, and is asked after the structural rules above, so widening it
+ *   grants no more than those three writes on records the session doesn't own.
  *
  * Comment records ride alongside your document records, so widen the room's record union to
  * include them, then spread the result into the authorizer map alongside your own entries:

package/dist-esm/index.mjs

@@ -1,8 +1,10 @@
 import { registerTldrawLibraryVersion } from "@tldraw/utils";
-import { createCommentAuthorizers } from "./comment-authorizers.mjs";
+import {
+  createCommentAuthorizers
+} from "./comment-authorizers.mjs";
 registerTldrawLibraryVersion(
   "@tldraw/sync-collaboration",
-  "5.3.0-next.2fa9c61a8de6",
+  "5.3.0-next.7654e7ac2a02",
   "esm"
 );
 export {

package/dist-esm/index.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["import { registerTldrawLibraryVersion } from '@tldraw/utils'\n\n// Server-side logic for tldraw's collaboration features, safe to import from any sync\n// server \u2014 no react or client-editor dependencies.\nexport { type CommentAuthorizerOptions, createCommentAuthorizers } from './comment-authorizers'\n\nregisterTldrawLibraryVersion(\n\t(globalThis as any).TLDRAW_LIBRARY_NAME,\n\t(globalThis as any).TLDRAW_LIBRARY_VERSION,\n\t(globalThis as any).TLDRAW_LIBRARY_MODULES\n)\n"],
-  "mappings": "AAAA,SAAS,oCAAoC;AAI7C,SAAwC,gCAAgC;AAExE;AAAA,EACE;AAAA,EACA;AAAA,EACA;AACF;",
+  "sourcesContent": ["import { registerTldrawLibraryVersion } from '@tldraw/utils'\n\n// Server-side logic for tldraw's collaboration features, safe to import from any sync\n// server \u2014 no react or client-editor dependencies.\nexport {\n\ttype CommentAuthorizerOptions,\n\ttype CommentModification,\n\ttype CommentModificationAuthContext,\n\tcreateCommentAuthorizers,\n} from './comment-authorizers'\n\nregisterTldrawLibraryVersion(\n\t(globalThis as any).TLDRAW_LIBRARY_NAME,\n\t(globalThis as any).TLDRAW_LIBRARY_VERSION,\n\t(globalThis as any).TLDRAW_LIBRARY_MODULES\n)\n"],
+  "mappings": "AAAA,SAAS,oCAAoC;AAI7C;AAAA,EAIC;AAAA,OACM;AAEP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AACF;",
   "names": []
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tldraw/sync-collaboration",
   "description": "tldraw sync collaboration: server-side write authorization for collaboration features.",
-  "version": "5.3.0-next.2fa9c61a8de6",
+  "version": "5.3.0-next.7654e7ac2a02",
   "author": {
     "name": "tldraw Inc.",
     "email": "hello@tldraw.com"
@@ -31,10 +31,10 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "@tldraw/store": "5.3.0-next.2fa9c61a8de6",
-    "@tldraw/sync-core": "5.3.0-next.2fa9c61a8de6",
-    "@tldraw/tlschema": "5.3.0-next.2fa9c61a8de6",
-    "@tldraw/utils": "5.3.0-next.2fa9c61a8de6"
+    "@tldraw/store": "5.3.0-next.7654e7ac2a02",
+    "@tldraw/sync-core": "5.3.0-next.7654e7ac2a02",
+    "@tldraw/tlschema": "5.3.0-next.7654e7ac2a02",
+    "@tldraw/utils": "5.3.0-next.7654e7ac2a02"
   },
   "module": "dist-esm/index.mjs",
   "source": "src/index.ts",

package/src/comment-authorizers.test.ts

@@ -538,6 +538,28 @@ describe('createCommentAuthorizers', () => {
 			).toBeNull()
 		})
 
+		it('is asked before canModifyComment, so a blocked session is never asked about a record', () => {
+			let asked = 0
+			const blocked = createCommentAuthorizers<TestMeta>({
+				getUserId: (session) => session.meta.userId,
+				canComment: () => false,
+				canModifyComment: () => {
+					asked++
+					return true
+				},
+			})
+			const prev = comment('real-bob')
+			expect(
+				blocked.comment!({
+					session: session('real-bob'),
+					type: 'update',
+					prev,
+					next: { ...prev, isDeleted: true },
+				})
+			).toBeNull()
+			expect(asked).toBe(0)
+		})
+
 		it('lets a custom canComment block sessions on its own criteria', () => {
 			const bannable = createCommentAuthorizers<TestMeta>({
 				getUserId: (session) => session.meta.userId,
@@ -562,4 +584,342 @@ describe('createCommentAuthorizers', () => {
 			expect(result.authorId).toBe('real-bob')
 		})
 	})
+
+	// The default is the owner-only rule the per-type suites above already cover in full. These
+	// exercise the option itself: what a callback can widen, and what stays fixed underneath it.
+	describe('canModifyComment', () => {
+		const comment = (authorId: string) =>
+			createComment({ threadId: thread.id, pageId, authorId, body: toRichText('hi') })
+		const makeThread = (createdBy: string) =>
+			createCommentThread({ pageId, anchor: { type: 'page' }, createdBy })
+
+		// The motivating case: a moderator takes down someone else's comment, but takes over
+		// nobody's voice — editing stays the author's.
+		const moderated = createCommentAuthorizers<TestMeta>({
+			getUserId: (session) => session.meta.userId,
+			canModifyComment: (ctx) =>
+				(ctx.action !== 'edit-comment' && ctx.session.meta.userId === 'real-mod') ||
+				ctx.userId === ctx.ownerId,
+		})
+
+		it('lets a widened rule soft-delete another user’s comment', () => {
+			const prev = comment('real-bob')
+			const next = { ...prev, isDeleted: true }
+			expect(moderated.comment!({ session: session('real-mod'), type: 'update', prev, next })).toBe(
+				next
+			)
+		})
+
+		it('lets a widened rule soft-delete another user’s thread', () => {
+			const prev = makeThread('real-bob')
+			const next = { ...prev, isDeleted: true }
+			expect(
+				moderated['comment-thread']!({ session: session('real-mod'), type: 'update', prev, next })
+			).toBe(next)
+		})
+
+		it('keeps the edit and the delete separate: widening deletes grants no edits', () => {
+			const prev = comment('real-bob')
+			const next = { ...prev, body: toRichText('rewritten by the mod') }
+			expect(
+				moderated.comment!({ session: session('real-mod'), type: 'update', prev, next })
+			).toBeNull()
+		})
+
+		// The gap a delete-only permission would otherwise leave: flip the flag, rewrite the body,
+		// and the edit rides in on a write the delete gate allowed.
+		it('vetoes a delete that carries an edit past a delete-only permission', () => {
+			const prev = comment('real-bob')
+			const next = { ...prev, isDeleted: true, body: toRichText('rewritten on the way out') }
+			expect(
+				moderated.comment!({ session: session('real-mod'), type: 'update', prev, next })
+			).toBeNull()
+		})
+
+		it('still lets the owner delete and edit in one write', () => {
+			const prev = comment('real-bob')
+			const next = { ...prev, isDeleted: true, body: toRichText('last word') }
+			expect(moderated.comment!({ session: session('real-bob'), type: 'update', prev, next })).toBe(
+				next
+			)
+		})
+
+		it('leaves everyone else where the default left them', () => {
+			const prev = comment('real-bob')
+			expect(
+				moderated.comment!({
+					session: session('real-mallory'),
+					type: 'update',
+					prev,
+					next: { ...prev, isDeleted: true },
+				})
+			).toBeNull()
+			const threadPrev = makeThread('real-bob')
+			expect(
+				moderated['comment-thread']!({
+					session: session('real-mallory'),
+					type: 'update',
+					prev: threadPrev,
+					next: { ...threadPrev, isDeleted: true },
+				})
+			).toBeNull()
+		})
+
+		it('narrows as well as widens', () => {
+			const frozen = createCommentAuthorizers<TestMeta>({
+				getUserId: (session) => session.meta.userId,
+				canModifyComment: (ctx) => ctx.action !== 'edit-comment' && ctx.userId === ctx.ownerId,
+			})
+			const prev = comment('real-bob')
+			expect(
+				frozen.comment!({
+					session: session('real-bob'),
+					type: 'update',
+					prev,
+					next: { ...prev, body: toRichText('edited') },
+				})
+			).toBeNull()
+			// ...and the delete it didn't narrow still goes through
+			const deleted = { ...prev, isDeleted: true }
+			expect(
+				frozen.comment!({ session: session('real-bob'), type: 'update', prev, next: deleted })
+			).toBe(deleted)
+		})
+
+		it('is asked with the stored record, not the client’s version of it', () => {
+			const seen: unknown[] = []
+			const spying = createCommentAuthorizers<TestMeta>({
+				getUserId: (session) => session.meta.userId,
+				canModifyComment: (ctx) => {
+					seen.push(ctx)
+					return true
+				},
+			})
+			const prev = comment('real-bob')
+			// mallory's push claims the comment is hers and already deleted; the context must describe
+			// the record the room holds, or an ownership rule would be reading the attacker's claim
+			const next = { ...prev, authorId: 'real-mallory', body: toRichText('edited') }
+			spying.comment!({ session: session('real-mallory'), type: 'update', prev, next })
+			// the attribution guard rejects this one before the option is asked at all
+			expect(seen).toEqual([])
+
+			spying.comment!({
+				session: session('real-mallory'),
+				type: 'update',
+				prev,
+				next: { ...prev, body: toRichText('edited') },
+			})
+			expect(seen).toEqual([
+				{
+					session: session('real-mallory'),
+					userId: 'real-mallory',
+					ownerId: 'real-bob',
+					action: 'edit-comment',
+					comment: prev,
+				},
+			])
+		})
+
+		it('reports the thread’s creator as the owner of a thread delete', () => {
+			const seen: unknown[] = []
+			const spying = createCommentAuthorizers<TestMeta>({
+				getUserId: (session) => session.meta.userId,
+				canModifyComment: (ctx) => {
+					seen.push(ctx)
+					return true
+				},
+			})
+			const prev = makeThread('real-bob')
+			spying['comment-thread']!({
+				session: session('real-mallory'),
+				type: 'update',
+				prev,
+				next: { ...prev, isDeleted: true },
+			})
+			expect(seen).toEqual([
+				{
+					session: session('real-mallory'),
+					userId: 'real-mallory',
+					ownerId: 'real-bob',
+					action: 'delete-thread',
+					thread: prev,
+				},
+			])
+		})
+
+		// Resolving and reopening aren't anyone's in particular, matching the client option: they're
+		// `canComment`'s to gate, and the option is never asked about them.
+		it('is not asked about resolving or reopening a thread', () => {
+			let asked = 0
+			const counting = createCommentAuthorizers<TestMeta>({
+				getUserId: (session) => session.meta.userId,
+				canModifyComment: () => {
+					asked++
+					return true
+				},
+			})
+			const prev = makeThread('real-bob')
+			const resolved = { ...prev, resolved: { at: 1, by: 'real-mallory' } }
+			expect(
+				counting['comment-thread']!({
+					session: session('real-mallory'),
+					type: 'update',
+					prev,
+					next: resolved,
+				})
+			).toBe(resolved)
+			const reopened = { ...resolved, resolved: null }
+			expect(
+				counting['comment-thread']!({
+					session: session('real-mallory'),
+					type: 'update',
+					prev: resolved,
+					next: reopened,
+				})
+			).toBe(reopened)
+			expect(asked).toBe(0)
+		})
+
+		it('is not asked about reactions', () => {
+			let asked = 0
+			const counting = createCommentAuthorizers<TestMeta>({
+				getUserId: (session) => session.meta.userId,
+				canModifyComment: () => {
+					asked++
+					return true
+				},
+			})
+			const prev = createCommentReaction({
+				commentId: createCommentId('c1'),
+				threadId: thread.id,
+				pageId,
+				userId: 'real-bob',
+				emoji: '👍',
+			})
+			// a permissive callback doesn't hand mallory someone else's reaction
+			expect(
+				counting['comment-reaction']!({
+					session: session('real-mallory'),
+					type: 'delete',
+					prev,
+					next: null,
+				})
+			).toBeNull()
+			expect(
+				counting['comment-reaction']!({
+					session: session('real-bob'),
+					type: 'update',
+					prev,
+					next: { ...prev, createdAt: prev.createdAt + 1 },
+				})
+			).not.toBeNull()
+			expect(asked).toBe(0)
+		})
+
+		// The point of asking after the structural rules: a host can hand out these three writes
+		// without handing out the invariants underneath them.
+		describe('the structural rules hold however permissive the callback', () => {
+			const permissive = createCommentAuthorizers<TestMeta>({
+				getUserId: (session) => session.meta.userId,
+				canModifyComment: () => true,
+			})
+
+			it('still vetoes clearing a soft-delete', () => {
+				const prev = { ...comment('real-bob'), isDeleted: true }
+				expect(
+					permissive.comment!({
+						session: session('real-mod'),
+						type: 'update',
+						prev,
+						next: { ...prev, isDeleted: false },
+					})
+				).toBeNull()
+			})
+
+			it('still vetoes every client hard-delete', () => {
+				const prev = comment('real-bob')
+				expect(
+					permissive.comment!({ session: session('real-mod'), type: 'delete', prev, next: null })
+				).toBeNull()
+				const threadPrev = makeThread('real-bob')
+				expect(
+					permissive['comment-thread']!({
+						session: session('real-mod'),
+						type: 'delete',
+						prev: threadPrev,
+						next: null,
+					})
+				).toBeNull()
+			})
+
+			it('still vetoes changing a comment’s author', () => {
+				const prev = comment('real-bob')
+				expect(
+					permissive.comment!({
+						session: session('real-mod'),
+						type: 'update',
+						prev,
+						next: { ...prev, authorId: 'real-mod' },
+					})
+				).toBeNull()
+			})
+
+			it('still vetoes re-parenting and back-dating a comment', () => {
+				const prev = comment('real-bob')
+				expect(
+					permissive.comment!({
+						session: session('real-mod'),
+						type: 'update',
+						prev,
+						next: { ...prev, threadId: 'comment-thread:other' as TLCommentThread['id'] },
+					})
+				).toBeNull()
+				expect(
+					permissive.comment!({
+						session: session('real-mod'),
+						type: 'update',
+						prev,
+						next: { ...prev, createdAt: 1 },
+					})
+				).toBeNull()
+			})
+
+			it('still vetoes a create with the soft-delete flag already set', () => {
+				expect(
+					permissive.comment!({
+						session: session('real-mod'),
+						type: 'create',
+						prev: null,
+						next: { ...comment('real-mod'), isDeleted: true },
+					})
+				).toBeNull()
+			})
+
+			it('still vetoes a resolution attributed to someone else', () => {
+				const prev = makeThread('real-bob')
+				expect(
+					permissive['comment-thread']!({
+						session: session('real-mod'),
+						type: 'update',
+						prev,
+						next: { ...prev, resolved: { at: 1, by: 'real-alice' } },
+					})
+				).toBeNull()
+			})
+
+			// An anonymous session has no identity to check a record against, so the default withholds
+			// all three writes from it. A callback that returns true regardless is taken at its word —
+			// worth knowing before writing one that ignores `userId`.
+			it('takes a callback at its word about an anonymous session', () => {
+				const prev = comment('real-bob')
+				const next = { ...prev, isDeleted: true }
+				expect(permissive.comment!({ session: session(null), type: 'update', prev, next })).toBe(
+					next
+				)
+				expect(
+					authorizers.comment!({ session: session(null), type: 'update', prev, next })
+				).toBeNull()
+			})
+		})
+	})
 })