Files
outline/server/models/Collection.ts
T
b4cbb39f17 feat: request document access (#10825)
* feat: Request document access

Allow users without permission to a document to request access. Notifies
document managers via in-app notification and email; managers can grant
or dismiss the request.

- Adds AccessRequest model, migration, policy, presenter
- Adds accessRequests.create/info/approve/dismiss endpoints
- Adds DocumentAccessRequestNotificationsTask + email
- Adds Error403 request flow with loading state and pending indicator
- Auto-opens notifications popover via ?notifications=true (used in email)
- Adds SplitButton primitive for permission selection in notifications
- Refactors useConsumeQueryParam hook

* refactor

* fix: Make approve/dismiss idempotent on access requests

Return success when the access request has already been dismissed, or
when the user already has document membership at approve time, instead
of throwing 400. Avoids racy double-clicks on notification actions
producing user-visible errors.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* Minor fixes

---------

Co-authored-by: Tom Moor <tom@getoutline.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-09 08:42:47 -04:00

1098 lines
28 KiB
TypeScript

/* oxlint-disable lines-between-class-members */
import fractionalIndex from "fractional-index";
import { find, findIndex, isNil, remove, uniq } from "es-toolkit/compat";
import type {
Identifier,
Transaction,
FindOptions,
NonNullFindOptions,
InferAttributes,
InferCreationAttributes,
} from "sequelize";
import {
EmptyResultError,
type CreateOptions,
type UpdateOptions,
type ScopeOptions,
type SaveOptions,
Op,
} from "sequelize";
import {
Sequelize,
Table,
Column,
Unique,
IsIn,
Default,
BeforeValidate,
BeforeSave,
AfterCreate,
HasMany,
BelongsToMany,
BelongsTo,
ForeignKey,
Scopes,
DataType,
Length as SimpleLength,
BeforeDestroy,
IsDate,
AllowNull,
BeforeCreate,
BeforeUpdate,
DefaultScope,
AfterSave,
} from "sequelize-typescript";
import isUUID from "validator/lib/isUUID";
import type {
CollectionSort,
ImportableIntegrationService,
ProsemirrorData,
SourceMetadata,
NavigationNode,
} from "@shared/types";
import { CollectionPermission } from "@shared/types";
import { UrlHelper } from "@shared/utils/UrlHelper";
import { sortNavigationNodes } from "@shared/utils/collections";
import slugify from "@shared/utils/slugify";
import { CollectionValidation } from "@shared/validations";
import { ValidationError } from "@server/errors";
import type { APIContext } from "@server/types";
import { CacheHelper } from "@server/utils/CacheHelper";
import { RedisPrefixHelper } from "@server/utils/RedisPrefixHelper";
import removeIndexCollision from "@server/utils/removeIndexCollision";
import { generateUrlId } from "@server/utils/url";
import { ValidateIndex } from "@server/validation";
import Document from "./Document";
import FileOperation from "./FileOperation";
import Group from "./Group";
import GroupMembership from "./GroupMembership";
import GroupUser from "./GroupUser";
import Import from "./Import";
import Team from "./Team";
import User from "./User";
import UserMembership from "./UserMembership";
import ParanoidModel from "./base/ParanoidModel";
import Fix from "./decorators/Fix";
import { DocumentHelper } from "./helpers/DocumentHelper";
import IsHexColor from "./validators/IsHexColor";
import Length from "./validators/Length";
import NotContainsUrl from "./validators/NotContainsUrl";
type AdditionalFindOptions = {
userId?: string;
includeDocumentStructure?: boolean;
includeOwner?: boolean;
includeArchivedBy?: boolean;
rejectOnEmpty?: boolean | Error;
};
@DefaultScope(() => ({
attributes: {
exclude: ["documentStructure"],
},
}))
@Scopes(() => ({
withAllMemberships: {
include: [
{
model: UserMembership,
as: "memberships",
required: false,
},
{
model: GroupMembership,
as: "groupMemberships",
required: false,
// use of "separate" property: sequelize breaks when there are
// nested "includes" with alternating values for "required"
// see https://github.com/sequelize/sequelize/issues/9869
separate: true,
// include for groups that are members of this collection,
// of which userId is a member of, resulting in:
// GroupMembership [inner join] Group [inner join] GroupUser [where] userId
include: [
{
model: Group,
as: "group",
required: true,
include: [
{
model: GroupUser,
as: "groupUsers",
required: true,
},
],
},
],
},
],
},
withUser: () => ({
include: [
{
model: User,
required: true,
as: "user",
},
],
}),
withArchivedBy: () => ({
include: [
{
association: "archivedBy",
},
],
}),
withDocumentStructure: () => ({
attributes: {
// resets to include the documentStructure column
exclude: [],
},
}),
withMembership: (userId: string) => {
if (!userId) {
return {};
}
return {
include: [
{
association: "memberships",
where: {
userId,
},
required: false,
},
{
model: GroupMembership,
as: "groupMemberships",
required: false,
// use of "separate" property: sequelize breaks when there are
// nested "includes" with alternating values for "required"
// see https://github.com/sequelize/sequelize/issues/9869
separate: true,
// include for groups that are members of this collection,
// of which userId is a member of, resulting in:
// CollectionGroup [inner join] Group [inner join] GroupUser [where] userId
include: [
{
model: Group,
as: "group",
required: true,
include: [
{
model: GroupUser,
as: "groupUsers",
required: true,
where: {
userId,
},
},
],
},
],
},
],
};
},
}))
@Table({ tableName: "collections", modelName: "collection" })
@Fix
class Collection extends ParanoidModel<
InferAttributes<Collection>,
Partial<InferCreationAttributes<Collection>>
> {
@SimpleLength({
min: 10,
max: 10,
msg: `urlId must be 10 characters`,
})
@Unique
@Column
urlId: string;
@NotContainsUrl
@Length({
max: CollectionValidation.maxNameLength,
msg: `name must be ${CollectionValidation.maxNameLength} characters or less`,
})
@Column
name: string;
/**
* The content of the collection as Markdown.
*
* @deprecated Use `content` instead, or `DocumentHelper.toMarkdown` if exporting lossy markdown.
* This column will be removed in a future migration.
*/
@Length({
max: CollectionValidation.maxDescriptionLength,
msg: `description must be ${CollectionValidation.maxDescriptionLength} characters or less`,
})
@Column
description: string | null;
/**
* The content of the collection as JSON, this is a snapshot at the last time the state was saved.
*/
@Column(DataType.JSONB)
content: ProsemirrorData | null;
/** An icon (or) emoji to use as the collection icon. */
@Column
icon: string | null;
/** The color of the icon. */
@IsHexColor
@Column
color: string | null;
@Length({
max: ValidateIndex.maxLength,
msg: `index must be ${ValidateIndex.maxLength} characters or less`,
})
@Column
index: string | null;
@IsIn([Object.values(CollectionPermission)])
@Column(DataType.STRING)
permission: CollectionPermission | null;
@Default(false)
@Column
maintainerApprovalRequired: boolean;
@Default(null)
@Column(DataType.JSONB)
documentStructure: NavigationNode[] | null;
@Default(true)
@Column
sharing: boolean;
@Default({ field: "title", direction: "asc" })
@Column({
type: DataType.JSONB,
validate: {
isSort(value: CollectionSort) {
if (
typeof value !== "object" ||
!value.direction ||
!value.field ||
Object.keys(value).length !== 2
) {
throw new Error("Sort must be an object with field,direction");
}
if (!["asc", "desc"].includes(value.direction)) {
throw new Error("Sort direction must be one of asc,desc");
}
if (!["title", "index"].includes(value.field)) {
throw new Error("Sort field must be one of title,index");
}
},
},
})
sort: CollectionSort;
/** Whether the collection is archived, and if so when. */
@IsDate
@Column
archivedAt: Date | null;
/** The minimum permission level required to manage templates in this collection. */
@IsIn([[CollectionPermission.Admin, CollectionPermission.ReadWrite]])
@Default(CollectionPermission.Admin)
@Column(DataType.STRING)
templateManagement: CollectionPermission;
/** Allows the configuration of commenting per collection. */
@AllowNull(true)
@Default(null)
@Column(DataType.BOOLEAN)
commenting: boolean | null;
@AllowNull
@Column(DataType.JSONB)
sourceMetadata: SourceMetadata | null;
// getters
/** The frontend path to this collection. */
get path(): string {
if (!this.name) {
return `/collection/untitled-${this.urlId}`;
}
return `/collection/${slugify(this.name)}-${this.urlId}`;
}
/**
* Whether this collection is considered active or not. A collection is active if
* it has not been archived or deleted.
*
* @returns boolean
*/
get isActive(): boolean {
return !this.archivedAt && !this.deletedAt;
}
// hooks
@BeforeValidate
static async onBeforeValidate(model: Collection) {
model.urlId = model.urlId || generateUrlId();
}
@BeforeSave
static async onBeforeSave(model: Collection) {
if (!model.content) {
model.content = await DocumentHelper.toJSON(model);
}
if (model.changed("documentStructure")) {
await CacheHelper.clearData(
RedisPrefixHelper.getCollectionDocumentsKey(model.id)
);
}
}
@AfterSave
static async cacheDocumentStructure(
model: Collection,
options: SaveOptions<Collection>
) {
if (model.changed("documentStructure")) {
const setData = () =>
CacheHelper.setData(
RedisPrefixHelper.getCollectionDocumentsKey(model.id),
model.documentStructure,
Collection.DOCUMENT_STRUCTURE_CACHE_TTL
);
if (options.transaction) {
return (options.transaction.parent || options.transaction).afterCommit(
setData
);
}
await setData();
}
}
@BeforeDestroy
static async checkLastCollection(model: Collection) {
const total = await this.count({
where: {
teamId: model.teamId,
},
});
if (total === 1) {
throw ValidationError("Cannot delete last collection");
}
}
@BeforeDestroy
static async deleteDocuments(model: Collection, ctx: APIContext["context"]) {
await Document.update(
{
lastModifiedById: ctx.auth.user.id,
deletedAt: new Date(),
},
{
transaction: ctx.transaction,
where: {
teamId: model.teamId,
collectionId: model.id,
archivedAt: {
[Op.is]: null,
},
},
}
);
}
@BeforeCreate
static async setIndex(model: Collection, options: CreateOptions<Collection>) {
if (model.index) {
model.index = await removeIndexCollision(model.teamId, model.index, {
transaction: options.transaction,
});
return;
}
const firstCollectionForTeam = await this.findOne({
where: {
teamId: model.teamId,
},
order: [
// using LC_COLLATE:"C" because we need byte order to drive the sorting
Sequelize.literal('"collection"."index" collate "C"'),
["updatedAt", "DESC"],
],
transaction: options.transaction,
});
model.index = fractionalIndex(null, firstCollectionForTeam?.index ?? null);
}
@AfterCreate
static async onAfterCreate(
model: Collection,
options: { transaction: Transaction }
) {
const existing = await UserMembership.findOne({
where: {
collectionId: model.id,
userId: model.createdById,
},
transaction: options.transaction,
});
if (!existing) {
return UserMembership.create(
{
collectionId: model.id,
userId: model.createdById,
permission: CollectionPermission.Admin,
createdById: model.createdById,
},
{
transaction: options.transaction,
hooks: false,
}
);
}
return existing;
}
@BeforeUpdate
static async checkIndex(
model: Collection,
options: UpdateOptions<Collection>
) {
if (
(model.index && model.changed("index")) ||
(!model.archivedAt && model.changed("archivedAt"))
) {
model.index = await removeIndexCollision(model.teamId, model.index!, {
transaction: options.transaction,
});
}
}
@BeforeUpdate
static async publishPermissionChangedEvent(
model: Collection,
ctx: APIContext["context"]
) {
const privacyChanged = model.previous("permission") !== model.permission;
const sharingChanged = model.previous("sharing") !== model.sharing;
if (privacyChanged || sharingChanged) {
await this.insertEvent("permission_changed", model, {
...ctx,
event: { publish: true },
});
}
}
// associations
@BelongsTo(() => FileOperation, "importId")
import: FileOperation | null;
@ForeignKey(() => FileOperation)
@Column(DataType.UUID)
importId: string | null;
@BelongsTo(() => Import, "apiImportId")
apiImport: Import<ImportableIntegrationService> | null;
@ForeignKey(() => Import)
@Column(DataType.UUID)
apiImportId: string | null;
@BelongsTo(() => User, "archivedById")
archivedBy?: User | null;
@AllowNull
@ForeignKey(() => User)
@Column(DataType.UUID)
archivedById?: string | null;
@HasMany(() => Document, "collectionId")
documents: Document[];
@HasMany(() => UserMembership, "collectionId")
memberships: UserMembership[];
@HasMany(() => GroupMembership, "collectionId")
groupMemberships: GroupMembership[];
@BelongsToMany(() => User, () => UserMembership)
users: User[];
@BelongsToMany(() => Group, () => GroupMembership)
groups: Group[];
@BelongsTo(() => User, "createdById")
user: User;
@ForeignKey(() => User)
@Column(DataType.UUID)
createdById: string;
@BelongsTo(() => Team, "teamId")
team: Team;
@ForeignKey(() => Team)
@Column(DataType.UUID)
teamId: string;
static DEFAULT_SORT: { field: "title" | "index"; direction: "asc" | "desc" } =
{
field: "index",
direction: "asc",
};
static DOCUMENT_STRUCTURE_CACHE_TTL = 60;
/**
* Returns an array of unique userIds that are members of a collection,
* either via group or direct membership.
*
* @param collectionId
* @param permission optional permission filter
*
* @returns userIds
*/
static async membershipUserIds(
collectionId: string,
permission?: CollectionPermission
) {
const collection = await this.scope("withAllMemberships").findOne({
where: { id: collectionId },
include: [
{
association: "memberships",
required: false,
...(permission ? { where: { permission } } : {}),
separate: true,
},
{
association: "groupMemberships",
required: false,
...(permission ? { where: { permission } } : {}),
separate: true,
},
],
});
if (!collection) {
return [];
}
const groupMemberships = collection.groupMemberships
.map((gm) => gm.group.groupUsers)
.flat();
const membershipUserIds = [
...groupMemberships,
...collection.memberships,
].map((membership) => membership.userId);
return uniq(membershipUserIds);
}
/**
* Overrides the standard findByPk behavior to allow also querying by urlId
* and loading memberships for a user passed in by `userId`
*
* @param id uuid or urlId
* @param options FindOptions
* @returns A promise resolving to a collection instance or null
*/
static async findByPk(
id: Identifier,
options?: NonNullFindOptions<Collection> & AdditionalFindOptions
): Promise<Collection>;
static async findByPk(
id: Identifier,
options?: FindOptions<Collection> & AdditionalFindOptions
): Promise<Collection | null>;
static async findByPk(
id: Identifier,
options: FindOptions<Collection> & AdditionalFindOptions = {}
): Promise<Collection | null> {
if (typeof id !== "string") {
return null;
}
const {
includeDocumentStructure,
includeOwner,
includeArchivedBy,
userId,
...rest
} = options;
const scopes: (string | ScopeOptions)[] = [
includeDocumentStructure ? "withDocumentStructure" : "defaultScope",
{
method: ["withMembership", userId],
},
];
if (includeOwner) {
scopes.push("withUser");
}
if (includeArchivedBy) {
scopes.push("withArchivedBy");
}
const scope = this.scope(scopes);
if (isUUID(id)) {
const collection = await scope.findOne({
where: {
id,
},
...rest,
rejectOnEmpty: false,
});
if (!collection && rest.rejectOnEmpty) {
throw new EmptyResultError(`Collection doesn't exist with id: ${id}`);
}
return collection;
}
const match = id.match(UrlHelper.SLUG_URL_REGEX);
if (match) {
const collection = await scope.findOne({
where: {
urlId: match[1],
},
...rest,
rejectOnEmpty: false,
});
if (!collection && rest.rejectOnEmpty) {
throw new EmptyResultError(`Collection doesn't exist with id: ${id}`);
}
return collection;
}
return null;
}
/**
* Find the first collection that the specified user has access to.
*
* @param user User to find the collection for
* @param options Additional options for the query
* @returns collection First collection in the sidebar order
*/
static async findFirstCollectionForUser(
user: User,
options: FindOptions = {}
) {
const id = await user.collectionIds({ transaction: options.transaction });
return this.findOne({
where: {
teamId: user.teamId,
id,
},
order: [
// using LC_COLLATE:"C" because we need byte order to drive the sorting
Sequelize.literal('"collection"."index" collate "C"'),
["updatedAt", "DESC"],
],
...options,
});
}
/**
* Convenience method to return if a collection is considered private.
* This means that a membership is required to view it rather than just being
* a workspace member.
*
* @returns boolean
*/
get isPrivate() {
return !this.permission;
}
/**
* Returns the collection's documentStructure via cache, populating it on
* miss. The cache is kept fresh by this model's save hooks, so callers
* should prefer this over re-fetching the column directly.
*
* @returns the cached documentStructure, or null when the collection has none.
*/
getCachedDocumentStructure = async (): Promise<NavigationNode[] | null> => {
const result = await CacheHelper.getDataOrSet<NavigationNode[] | null>(
RedisPrefixHelper.getCollectionDocumentsKey(this.id),
async () =>
(
await (this.constructor as typeof Collection).findByPk(this.id, {
attributes: ["documentStructure"],
includeDocumentStructure: true,
rejectOnEmpty: true,
})
).documentStructure,
Collection.DOCUMENT_STRUCTURE_CACHE_TTL
);
return result ?? null;
};
getDocumentTree = (documentId: string): NavigationNode | null => {
if (!this.documentStructure) {
return null;
}
let result!: NavigationNode | undefined;
const loopChildren = (documents: NavigationNode[]) => {
if (result) {
return;
}
documents.forEach((document) => {
if (result) {
return;
}
if (document.id === documentId) {
result = document;
} else {
loopChildren(document.children);
}
});
};
// Technically, sorting the children is presenter-layer work...
// but the only place it's used passes straight into an API response
// so the extra indirection is not worthwhile
loopChildren(this.documentStructure);
// if the document is a draft loopChildren will not find it in the structure
if (!result) {
return null;
}
return {
...result,
children: sortNavigationNodes(result.children, this.sort),
};
};
/**
* Archives the collection and all of its non-archived documents. The
* collection's `archivedAt` and `archivedBy` are set to now and the acting
* user respectively, and child documents inherit the same `archivedAt`.
*
* @param ctx - the API context, including the acting user and optional transaction.
* @returns the updated collection.
*/
archiveWithCtx = async (ctx: APIContext) => {
const { transaction } = ctx.state;
const { user } = ctx.state.auth;
this.archivedAt = new Date();
this.archivedById = user.id;
this.archivedBy = user;
await this.saveWithCtx(ctx, undefined, { name: "archive" });
await Document.update(
{
lastModifiedById: user.id,
archivedAt: this.archivedAt,
},
{
where: {
teamId: this.teamId,
collectionId: this.id,
archivedAt: { [Op.is]: null },
},
transaction,
}
);
return this;
};
deleteDocument = async function (document: Document, options?: FindOptions) {
await this.removeDocumentInStructure(document, options);
// Helper to destroy all child documents for a document
const loopChildren = async (
documentId: string,
opts?: FindOptions<Document>
) => {
const childDocuments = await Document.findAll({
where: {
parentDocumentId: documentId,
},
});
for (const child of childDocuments) {
await loopChildren(child.id, opts);
await child.destroy(opts);
}
};
await loopChildren(document.id, options);
await document.destroy(options);
};
removeDocumentInStructure = async function (
document: Document,
options?: FindOptions & {
save?: boolean;
}
) {
if (!this.documentStructure) {
return;
}
let result: [NavigationNode, number] | undefined;
const removeFromChildren = async (
children: NavigationNode[],
id: string
) => {
children = await Promise.all(
children.map(async (childDocument) => ({
...childDocument,
children: await removeFromChildren(childDocument.children, id),
}))
);
const match = find(children, {
id,
});
if (match) {
if (!result) {
result = [
match,
findIndex(children, {
id,
}),
];
}
remove(children, {
id,
});
}
return children;
};
this.documentStructure = await removeFromChildren(
this.documentStructure,
document.id
);
// Sequelize doesn't seem to set the value with splice on JSONB field
// https://github.com/sequelize/sequelize/blob/e1446837196c07b8ff0c23359b958d68af40fd6d/src/model.js#L3937
this.changed("documentStructure", true);
if (options?.save !== false) {
await this.save({
...options,
fields: ["documentStructure"],
});
}
return result;
};
getDocumentParents = function (documentId: string): string[] | void {
let result!: string[];
const loopChildren = (documents: NavigationNode[], path: string[] = []) => {
if (result) {
return;
}
documents.forEach((document) => {
if (document.id === documentId) {
result = path;
} else {
loopChildren(document.children, [...path, document.id]);
}
});
};
if (this.documentStructure) {
loopChildren(this.documentStructure);
}
return result;
};
/**
* Update document's title and url in the documentStructure
*/
updateDocument = async function (
updatedDocument: Document,
options?: { transaction?: Transaction | null | undefined }
) {
if (!this.documentStructure) {
return;
}
const { id } = updatedDocument;
const updateChildren = (documents: NavigationNode[]) =>
Promise.all(
documents.map(async (document) => {
if (document.id === id) {
document = {
...(await updatedDocument.toNavigationNode(options)),
children: document.children,
};
} else {
document.children = await updateChildren(document.children);
}
return document;
})
);
this.documentStructure = await updateChildren(this.documentStructure);
// Sequelize doesn't seem to set the value with splice on JSONB field
// https://github.com/sequelize/sequelize/blob/e1446837196c07b8ff0c23359b958d68af40fd6d/src/model.js#L3937
this.changed("documentStructure", true);
await this.save({
fields: ["documentStructure"],
...options,
});
return this;
};
addDocumentToStructure = async function (
document: Document,
index?: number,
options: FindOptions & {
save?: boolean;
silent?: boolean;
documentJson?: NavigationNode;
includeArchived?: boolean;
insertOrder?: "prepend" | "append";
} = {}
) {
if (!this.documentStructure) {
this.documentStructure = [];
}
if (this.getDocumentTree(document.id)) {
return this;
}
// If moving existing document with children, use existing structure
const documentJson = {
...(await document.toNavigationNode(options)),
...options.documentJson,
};
// Determine the insertion index based on order parameter or explicit index
let insertionIndex: number;
if (index !== undefined) {
// Explicit index takes precedence
insertionIndex = index;
} else if (options.insertOrder === "prepend") {
// Prepend to the beginning
insertionIndex = 0;
} else {
// Default behavior: append to the end (maintains backward compatibility)
insertionIndex = this.documentStructure.length;
}
if (!document.parentDocumentId) {
// Note: Index is supported on DB level but it's being ignored
// by the API presentation until we build product support for it.
this.documentStructure.splice(insertionIndex, 0, documentJson);
} else {
// Recursively place document
const placeDocument = (documentList: NavigationNode[]) =>
documentList.map((childDocument) => {
if (document.parentDocumentId === childDocument.id) {
const childInsertionIndex =
index !== undefined
? index
: options.insertOrder === "prepend"
? 0
: childDocument.children.length;
childDocument.children.splice(childInsertionIndex, 0, documentJson);
} else {
childDocument.children = placeDocument(childDocument.children);
}
return childDocument;
});
this.documentStructure = placeDocument(this.documentStructure);
}
// Sequelize doesn't seem to set the value with splice on JSONB field
// https://github.com/sequelize/sequelize/blob/e1446837196c07b8ff0c23359b958d68af40fd6d/src/model.js#L3937
this.changed("documentStructure", true);
if (options?.save !== false) {
await this.save({
...options,
fields: ["documentStructure"],
});
}
return this;
};
/**
* Get all of the document ids that are in this collection by
* recursively iterating through `documentStructure`.
*
* @returns list of document ids
*/
getAllDocumentIds = (): string[] => {
if (!this.documentStructure) {
return [];
}
const allDocumentIds: string[] = [];
const loopChildren = (node: NavigationNode) => {
allDocumentIds.push(node.id);
(node.children ?? []).forEach((childNode) => {
loopChildren(childNode);
});
};
this.documentStructure.forEach(loopChildren);
return allDocumentIds;
};
/**
* Returns a JSON representation of this collection suitable for use in the frontend navigation.
*
* @returns NavigationNode
*/
toNavigationNode = (): NavigationNode => ({
id: this.id,
title: this.name,
url: this.path,
icon: isNil(this.icon) ? undefined : this.icon,
color: isNil(this.color) ? undefined : this.color,
children: sortNavigationNodes(this.documentStructure ?? [], this.sort),
});
}
export default Collection;