Files
outline/server/utils/oauth/ClientMetadataHelper.ts

459 lines
14 KiB
TypeScript

import { clamp } from "es-toolkit";
import { UniqueConstraintError } from "sequelize";
import { z } from "zod";
import { TeamPreference } from "@shared/types";
import { parseDomain } from "@shared/utils/domains";
import { errToString } from "@shared/utils/error";
import { Day, Minute, Second } from "@shared/utils/time";
import { getHostname } from "@shared/utils/urls";
import { OAuthClientValidation } from "@shared/validations";
import env from "@server/env";
import { AuthorizationError, InvalidClientMetadataError } from "@server/errors";
import Logger from "@server/logging/Logger";
import { OAuthClient, Share, Team } from "@server/models";
import UploadOAuthClientLogoTask from "@server/queues/tasks/UploadOAuthClientLogoTask";
import type { Response } from "@server/utils/fetch";
import fetch from "@server/utils/fetch";
import { OAuthHelper } from "./OAuthHelper";
/** JWK members that hold private or symmetric key material (RFC 7518 §6). */
const privateKeyMembers = ["d", "p", "q", "dp", "dq", "qi", "oth", "k"];
const MetadataDocumentSchema = z
.object({
client_id: z.string(),
client_name: z.string().min(1).max(OAuthClientValidation.maxNameLength),
redirect_uris: z
.array(
z
.string()
.max(OAuthClientValidation.maxRedirectUriLength)
.refine(
(uri) => OAuthHelper.isValidRedirectUri(uri),
"Invalid redirect URI"
)
)
.min(1)
.max(OAuthClientValidation.maxRedirectUris),
client_uri: z
.url({ protocol: /^https$/ })
.max(OAuthClientValidation.maxDeveloperUrlLength)
.optional(),
logo_uri: z
.url({ protocol: /^https$/ })
.max(OAuthClientValidation.maxAvatarUrlLength)
.optional(),
// Clients can list several methods, with the singular field as their
// preference. Only public clients are supported, so "none" must be one of
// them.
token_endpoint_auth_method: z.string().optional(),
token_endpoint_auth_methods_supported: z.array(z.string()).optional(),
client_secret: z.never().optional(),
// Public keys are ignored, but a document with private key material is
// invalid and must not be cached (draft section 4.1).
jwks: z
.object({
keys: z.array(
z
.record(z.string(), z.unknown())
.refine(
(key) => !privateKeyMembers.some((member) => member in key),
"jwks must not contain private key material"
)
),
})
.optional(),
client_secret_expires_at: z.never().optional(),
})
.refine(
(document) =>
(
document.token_endpoint_auth_methods_supported ?? [
document.token_endpoint_auth_method ?? "none",
]
).includes("none"),
{
message: "must allow the none method",
path: ["token_endpoint_auth_method"],
}
);
type MetadataDocument = z.infer<typeof MetadataDocumentSchema>;
/**
* Helpers for OAuth clients that are identified by a client ID metadata
* document (CIMD). The client sends an https URL as its `client_id`, and the
* document at that URL describes the client.
*
* https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/
*/
export class ClientMetadataHelper {
/** The maximum time to wait for the metadata document. */
public static fetchTimeout = 5000;
/** The maximum size of the metadata document, in bytes. */
public static maxDocumentSize = 5 * 1024;
/** The minimum time to cache a metadata document. */
public static minCacheDuration = 5 * Minute.ms;
/** The maximum time to cache a metadata document. */
public static maxCacheDuration = Day.ms;
/**
* Find an OAuth client by its public `clientId`. When the identifier is a
* metadata document URL, the document is fetched if there is no cached
* client or the cached copy has expired.
*
* @param clientId The public client identifier.
* @param team The team of the user that requests the client.
* @returns The OAuth client, or null if it is not found, the client_id is
* not a valid metadata document URL, or metadata documents are disabled.
* @throws AuthorizationError if the client is a metadata document and the
* team has turned MCP off.
* @throws InvalidClientMetadataError if the metadata document cannot be
* fetched or is not valid.
*/
public static async findOrFetchByClientId(
clientId: string,
team: Team
): Promise<OAuthClient | null> {
if (!OAuthClient.isMetadataDocumentClientId(clientId)) {
return OAuthClient.findByClientId(clientId);
}
if (env.OAUTH_DISABLE_CIMD) {
return null;
}
// Metadata documents only serve MCP, so do not fetch one for a team that
// has turned it off.
if (!team.getPreference(TeamPreference.MCP)) {
throw AuthorizationError();
}
if (!ClientMetadataHelper.isValidClientIdUrl(clientId)) {
return null;
}
const existing = await OAuthClient.findByClientId(clientId);
if (
existing?.metadataExpiresAt &&
existing.metadataExpiresAt > new Date()
) {
return existing;
}
// Users can upload content to this installation, so a document hosted
// here could impersonate a client.
const hostname = getHostname(clientId);
if (
!hostname ||
(await ClientMetadataHelper.isInstallationHost(hostname))
) {
return null;
}
// An existing client is kept when the fetch fails, so that issued tokens
// continue to work, but it cannot be authorized again until a fetch
// succeeds.
const { document, expiresAt } =
await ClientMetadataHelper.fetchMetadataDocument(clientId);
const client = await ClientMetadataHelper.saveClient(
clientId,
existing,
document,
expiresAt
);
const logoUrl = document.logo_uri;
if (client && logoUrl) {
await new UploadOAuthClientLogoTask().scheduleOptional({
oauthClientId: client.id,
logoUrl,
});
}
return client;
}
/**
* Whether a client identifier is a valid metadata document URL. The URL
* must use https, have a path (a root path is allowed), and must not have a
* fragment, userinfo, or dot path segments.
*
* @param clientId The client identifier to validate.
* @returns true if the identifier is a valid metadata document URL.
*/
public static isValidClientIdUrl(clientId: string): boolean {
if (clientId.length > OAuthClientValidation.maxClientIdLength) {
return false;
}
// The URL parser treats backslashes as separators and removes tabs and
// newlines, which would hide dot segments from the raw path check below.
// oxlint-disable-next-line no-control-regex
if (/[\\\s\x00-\x1f\x7f]/.test(clientId)) {
return false;
}
let url: URL;
try {
url = new URL(clientId);
} catch {
return false;
}
if (!OAuthClient.isMetadataDocumentClientId(clientId)) {
return false;
}
if (clientId.includes("#")) {
return false;
}
// The parsed URL drops empty userinfo, as in "https://@host", so look for
// the delimiter in the raw authority instead.
const authority = clientId
.slice(OAuthClientValidation.metadataDocumentClientIdPrefix.length)
.split(/[/?]/)[0];
if (authority.includes("@")) {
return false;
}
// A trailing dot names the same host, so it could bypass host checks.
if (url.hostname.endsWith(".")) {
return false;
}
// The parsed URL resolves dot segments, so inspect the raw path instead.
const rawPath = clientId.replace(/^https:\/\/[^/?]*/, "").split("?")[0];
if (!rawPath) {
return false;
}
return !rawPath
.split("/")
.some((segment) => [".", ".."].includes(segment.replace(/%2e/gi, ".")));
}
/**
* Whether a hostname serves this installation or its file storage. This
* includes workspace subdomains, custom workspace domains, and custom share
* domains.
*
* @param hostname The hostname to check.
* @returns true if the hostname belongs to this installation.
*/
public static async isInstallationHost(hostname: string): Promise<boolean> {
const { host, custom } = parseDomain(hostname);
if (!custom) {
return true;
}
const storageHosts = [
env.URL,
env.CDN_URL,
env.AWS_S3_UPLOAD_BUCKET_URL,
env.AWS_S3_ACCELERATE_URL,
].flatMap((url) => getHostname(url) ?? []);
if (storageHosts.includes(host)) {
return true;
}
const [team, share] = await Promise.all([
Team.findByDomain(host),
Share.unscoped().findOne({
attributes: ["id"],
where: { domain: host },
}),
]);
return !!team || !!share;
}
/**
* Fetch and validate the metadata document for a client. Redirects are not
* followed, and only a 200 response with a valid document is accepted.
*
* @param clientId The metadata document URL.
* @returns The validated document and the time the cached copy expires.
* @throws InvalidClientMetadataError if the document cannot be fetched or
* is not valid.
*/
public static async fetchMetadataDocument(clientId: string): Promise<{
document: MetadataDocument;
expiresAt: Date;
}> {
let res: Response;
let text: string;
try {
res = await fetch(clientId, {
method: "GET",
redirect: "manual",
// Special-use addresses are never allowed, even when the installation
// allows them for other integrations (draft section 8.6).
allowIPAddressList: [],
size: ClientMetadataHelper.maxDocumentSize,
signal: AbortSignal.timeout(ClientMetadataHelper.fetchTimeout),
headers: { Accept: "application/json" },
});
text = await res.text();
} catch (err) {
// Network errors can describe internal hosts, so they are only logged.
Logger.warn("Failed to fetch OAuth client metadata document", {
clientId,
error: errToString(err),
});
throw InvalidClientMetadataError(
"The client metadata document could not be fetched"
);
}
if (res.status !== 200) {
throw InvalidClientMetadataError(
`The client metadata document responded with status ${res.status}`
);
}
const contentType = res.headers.get("content-type")?.split(";")[0].trim();
if (
!contentType ||
!/^application\/(?:[\w.-]+\+)?json$/i.test(contentType)
) {
throw InvalidClientMetadataError(
`The client metadata document must be JSON, not ${contentType ?? "an unknown type"}`
);
}
let json: unknown;
try {
json = JSON.parse(text);
} catch {
throw InvalidClientMetadataError(
"The client metadata document is not valid JSON"
);
}
const result = MetadataDocumentSchema.safeParse(json);
if (!result.success) {
const issue = result.error.issues[0];
throw InvalidClientMetadataError(
`The client metadata document is invalid: ${issue.path.join(".") || "document"} ${issue.message}`
);
}
const document = result.data;
if (document.client_id !== clientId) {
throw InvalidClientMetadataError(
"The client_id in the client metadata document does not match its URL"
);
}
return {
document,
expiresAt: ClientMetadataHelper.cacheExpiry(res.headers),
};
}
/**
* Returns when a cached metadata document expires, using HTTP caching
* semantics. `no-store` and `no-cache` expire the document at once.
* Otherwise the freshness lifetime comes from `max-age` or `Expires`, less
* the current age of the response, and is clamped between the minimum and maximum
* cache durations.
*
* @param headers The response headers.
* @param now The current time.
* @returns The time the cached document expires.
*/
public static cacheExpiry(
headers: { get(name: string): string | null },
now = new Date()
): Date {
const directives = (headers.get("cache-control") ?? "")
.toLowerCase()
.split(",")
.map((directive) => directive.trim());
if (
directives.some(
(directive) =>
directive === "no-store" || directive.startsWith("no-cache")
)
) {
return now;
}
const maxAge = directives
.map((directive) => directive.match(/^max-age\s*=\s*"?(\d+)"?$/))
.find(Boolean);
const expires = headers.get("expires");
const date = new Date(headers.get("date") ?? "").getTime();
const responseTime = Number.isNaN(date) ? now.getTime() : date;
// The current age is the larger of the Age header and the time since the
// Date header (RFC 9111 section 4.2.3).
const age = Math.max(
(parseInt(headers.get("age") ?? "", 10) || 0) * Second.ms,
now.getTime() - responseTime
);
let duration = 0;
if (maxAge) {
duration = parseInt(maxAge[1], 10) * Second.ms;
} else if (expires) {
const expiresAt = new Date(expires).getTime();
duration = Number.isNaN(expiresAt) ? 0 : expiresAt - responseTime;
}
duration -= age;
const clamped = clamp(
duration,
ClientMetadataHelper.minCacheDuration,
ClientMetadataHelper.maxCacheDuration
);
return new Date(now.getTime() + clamped);
}
/**
* Create or update the cached client for a metadata document. The logo is
* not stored here, it is copied to file storage by a background task.
*
* @param clientId The metadata document URL.
* @param existing The cached client, if there is one.
* @param document The validated metadata document.
* @param expiresAt When the cached document expires.
* @returns The saved client.
*/
private static async saveClient(
clientId: string,
existing: OAuthClient | null,
document: MetadataDocument,
expiresAt: Date
): Promise<OAuthClient | null> {
const attributes = {
name: document.client_name,
redirectUris: document.redirect_uris,
developerUrl: document.client_uri ?? null,
clientType: "public" as const,
published: false,
metadataExpiresAt: expiresAt,
...(!document.logo_uri && { avatarUrl: null }),
};
if (existing) {
return existing.update(attributes);
}
try {
return await OAuthClient.create({
...attributes,
clientId,
teamId: null,
createdById: null,
});
} catch (err) {
// A concurrent request for the same URL created the row first.
if (err instanceof UniqueConstraintError) {
return OAuthClient.findByClientId(clientId);
}
throw err;
}
}
}