Files
outline/server/collaboration/AuthenticationExtension.ts
Tom Moor 60095ed58a fix: Stricter document name handling in collaboration server (#14225)
* fix: Require canonical document names in collaboration connections

* Add null check before reading document id
2026-10-22 07:46:40 -04:00

301 lines
8.8 KiB
TypeScript

import type {
Connection,
Extension,
Hocuspocus,
onAuthenticatePayload,
onConfigurePayload,
onDestroyPayload,
} from "@hocuspocus/server";
import { uniq } from "es-toolkit";
import { AuthorizationChanged } from "@shared/collaboration/CloseEvents";
import { toError } from "@shared/utils/error";
import { Minute } from "@shared/utils/time";
import Logger from "@server/logging/Logger";
import { trace } from "@server/logging/tracing";
import Document from "@server/models/Document";
import GroupUser from "@server/models/GroupUser";
import type User from "@server/models/User";
import { can } from "@server/policies";
import RedisAdapter from "@server/storage/redis";
import { getUserForJWT } from "@server/utils/jwt";
import { AuthenticationError, InternalError } from "../errors";
/**
* Redis channel that carries access changes to collaboration servers.
*/
const CHANNEL = "collaboration:authorization";
/**
* Describes which connections are affected by an access change. A connection is
* closed only when it matches every property provided, so an empty scope
* matches all of them.
*/
export interface AuthorizationScope {
/** Restrict to connections belonging to one of these users. */
userIds?: string[];
/** Restrict to connections belonging to members of this group. */
groupId?: string;
/** Restrict to connections for documents in this collection. */
collectionId?: string;
/** Restrict to connections for these documents. */
documentIds?: string[];
}
/**
* Authorizes connections to a document when they are established, and closes
* them again whenever the access a user was granted may have changed or the
* token they authenticated with expires. Clients reconnect on their own, so
* authorization is only ever decided in one place.
*/
@trace()
export default class AuthenticationExtension implements Extension {
/**
* Publish an access change so that every collaboration server closes the
* connections it holds within the given scope. Access itself is not
* evaluated here, the scope only has to cover the connections that may be
* affected.
*
* @param scope The connections that may be affected by the change.
* @returns A promise that resolves once the change has been published.
* @throws {Error} If the scope is empty, which would match every connection.
*/
static async invalidate(scope: AuthorizationScope): Promise<void> {
// An absent property matches all connections, so a scope in which every
// property is absent would disconnect the entire cluster.
if (!Object.values(scope).some((value) => value !== undefined)) {
throw InternalError("An authorization scope must not be empty");
}
await RedisAdapter.collaborationClient.publish(
CHANNEL,
JSON.stringify(scope)
);
Logger.debug("multiplayer", "Published access change", scope);
}
async onAuthenticate({
connection,
token,
documentName,
}: onAuthenticatePayload) {
// allows for different entity types to use this multiplayer provider later
const [, documentId] = documentName.split(".");
if (!token) {
throw AuthenticationError("Authentication required");
}
const { user, expiresAt } = await getUserForJWT(token, [
"session",
"collaboration",
]);
const document = await Document.findByPk(documentId, {
userId: user.id,
});
if (!document || !can(user, "read", document)) {
throw AuthenticationError("Authorization required");
}
// Other spellings of the id would load a second copy of the document that
// access changes, which match on the canonical name, cannot reach.
if (documentName !== `document.${document.id}`) {
throw AuthenticationError("Invalid document name");
}
// set document to read only for the current user, thus changes will not be
// accepted and synced to other clients
if (!can(user, "update", document)) {
connection.readOnly = true;
}
return {
user,
expiresAt,
};
}
async onConfigure({ instance }: onConfigurePayload) {
this.instance = instance;
this.expiryInterval ??= setInterval(
this.handleExpiryInterval,
Minute.ms
).unref();
if (this.subscribed) {
return;
}
this.subscribed = true;
try {
const subscriber = RedisAdapter.collaborationSubscriber;
await subscriber.subscribe(CHANNEL);
subscriber.on("message", this.handleMessage);
Logger.debug("multiplayer", `Subscribed to ${CHANNEL}`);
} catch (error) {
Logger.error("Failed to subscribe to access changes", toError(error));
this.subscribed = false;
}
}
async onDestroy(_data: onDestroyPayload) {
clearInterval(this.expiryInterval);
this.expiryInterval = undefined;
if (this.subscribed) {
const subscriber = RedisAdapter.collaborationSubscriber;
subscriber.off("message", this.handleMessage);
await subscriber.unsubscribe(CHANNEL);
this.subscribed = false;
}
this.instance = undefined;
}
/**
* Close every locally held connection within the scope of an access change.
* A client that has kept its access reconnects with only a brief
* interruption, one that has not is refused by `onAuthenticate`.
*
* @param scope The connections that may be affected by the change.
* @returns A promise that resolves once the connections have been closed.
*/
async disconnect(scope: AuthorizationScope) {
if (!this.instance) {
return;
}
let affected: {
documentId: string;
userId: string;
connection: Connection;
}[] = [];
for (const [documentName, document] of this.instance.documents) {
const [, documentId] = documentName.split(".");
if (scope.documentIds && !scope.documentIds.includes(documentId)) {
continue;
}
for (const connection of document.getConnections()) {
const context: { user?: User } = connection.context;
const userId = context.user?.id;
if (!userId || (scope.userIds && !scope.userIds.includes(userId))) {
continue;
}
affected.push({ documentId, userId, connection });
}
}
if (scope.groupId && affected.length) {
const groupUsers = await GroupUser.findAll({
attributes: ["userId"],
where: {
groupId: scope.groupId,
userId: uniq(affected.map((item) => item.userId)),
},
});
const userIds = new Set(groupUsers.map((groupUser) => groupUser.userId));
affected = affected.filter((item) => userIds.has(item.userId));
}
if (scope.collectionId && affected.length) {
const documents = await Document.unscoped().findAll({
attributes: ["id"],
where: {
id: uniq(affected.map((item) => item.documentId)),
collectionId: scope.collectionId,
},
paranoid: false,
});
const documentIds = new Set(documents.map((document) => document.id));
affected = affected.filter((item) => documentIds.has(item.documentId));
}
if (!affected.length) {
return;
}
// Each closed connection is logged again by LoggerExtension, so record the
// reason once rather than per connection.
Logger.info(
"multiplayer",
`Closing ${affected.length} connections to authorize them again`,
scope
);
for (const { connection } of affected) {
connection.close(AuthorizationChanged);
}
}
/**
* Close every locally held connection that authenticated with a token which
* has since expired. The client reconnects and must present a token that is
* still valid.
*/
disconnectExpired() {
if (!this.instance) {
return;
}
const now = new Date();
const expired: Connection[] = [];
for (const document of this.instance.documents.values()) {
for (const connection of document.getConnections()) {
const context: { expiresAt?: Date } = connection.context;
if (context.expiresAt && context.expiresAt <= now) {
expired.push(connection);
}
}
}
if (!expired.length) {
return;
}
Logger.info(
"multiplayer",
`Closing ${expired.length} connections with an expired token`
);
for (const connection of expired) {
connection.close(AuthorizationChanged);
}
}
private instance?: Hocuspocus;
private subscribed = false;
private expiryInterval?: NodeJS.Timeout;
private handleExpiryInterval = () => {
try {
this.disconnectExpired();
} catch (error) {
Logger.error("Failed to close expired connections", toError(error));
}
};
private handleMessage = async (channel: string, message: string) => {
if (channel !== CHANNEL) {
return;
}
try {
const scope: AuthorizationScope = JSON.parse(message);
await this.disconnect(scope);
} catch (error) {
Logger.error("Failed to handle access change", toError(error));
}
};
}