Remove OAuth authorization flows and use API key authentication for MCP

This commit is contained in:
Mike Cao committed 2026-09-09 15:22:15 -07:00
1 parent 16acac5530
commit b185837063
85 files changed
+383 -4631

No files matched your search

@@ -1,21 +0,0 @@
import { isOAuthEnabled } from '@/lib/oauth/config';
import {
buildAuthorizationServerMetadata,
corsPreflight,
metadataResponse,
} from '@/lib/oauth/metadata';
import { notFound } from '@/lib/response';
export const dynamic = 'force-dynamic';
export function OPTIONS() {
return corsPreflight();
}
export async function GET(request: Request) {
if (!isOAuthEnabled()) {
return notFound();
}
return metadataResponse(buildAuthorizationServerMetadata(request.headers));
}
@@ -1,22 +0,0 @@
import { isOAuthEnabled } from '@/lib/oauth/config';
import {
buildProtectedResourceMetadata,
corsPreflight,
metadataResponse,
} from '@/lib/oauth/metadata';
import { notFound } from '@/lib/response';
export const dynamic = 'force-dynamic';
export function OPTIONS() {
return corsPreflight();
}
/** Path-scoped protected resource metadata for the MCP endpoint (RFC 9728 §3.1). */
export async function GET(request: Request) {
if (!isOAuthEnabled()) {
return notFound();
}
return metadataResponse(buildProtectedResourceMetadata(request.headers));
}
@@ -1,21 +0,0 @@
import { isOAuthEnabled } from '@/lib/oauth/config';
import {
buildProtectedResourceMetadata,
corsPreflight,
metadataResponse,
} from '@/lib/oauth/metadata';
import { notFound } from '@/lib/response';
export const dynamic = 'force-dynamic';
export function OPTIONS() {
return corsPreflight();
}
export async function GET(request: Request) {
if (!isOAuthEnabled()) {
return notFound();
}
return metadataResponse(buildProtectedResourceMetadata(request.headers));
}
+17 -23
View File
@@ -10,9 +10,10 @@ const operation1 = defineOperation({
auth: 'bearer',
operation: {
operationId: 'getMe',
summary: 'Get me',
summary: 'Get my authentication details',
description:
'Returns the current authentication context, including the authenticated user or share credentials.',
tags: ['Account'],
'x-umami-oauth-scope': 'websites:read',
responses: {
'200': {
description: 'The operation completed successfully.',
@@ -26,30 +27,38 @@ const operation1 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
username: {
type: 'string',
description: 'Username of the account.',
},
role: {
type: 'string',
description: 'Permission role assigned to the user.',
},
isAdmin: {
type: 'boolean',
description: 'Whether the user has administrator privileges.',
},
},
required: ['id', 'username', 'role', 'isAdmin'],
description: 'User associated with the resource.',
},
apiKey: {
type: 'object',
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
name: {
type: 'string',
description: 'Display name of the resource.',
},
},
required: ['id', 'name'],
description: 'API key authentication details.',
},
authType: {
anyOf: [
@@ -62,37 +71,18 @@ const operation1 = defineOperation({
{
const: 'api-key',
},
{
const: 'oauth',
},
],
},
oauth: {
type: 'object',
properties: {
clientId: {
type: 'string',
},
scopes: {
type: 'array',
items: {
type: 'string',
},
},
tokenId: {
type: 'string',
},
},
required: ['clientId', 'scopes'],
},
shareToken: {
type: 'object',
properties: {
shareType: {
type: 'number',
description: 'Type of resource made available by the share.',
},
websiteId: {
type: 'string',
description: 'ID of the website.',
},
websiteIds: {
type: 'array',
@@ -102,9 +92,11 @@ const operation1 = defineOperation({
},
boardId: {
type: 'string',
description: 'ID of the board.',
},
pixelId: {
type: 'string',
description: 'ID of the tracking pixel.',
},
pixelIds: {
type: 'array',
@@ -114,6 +106,7 @@ const operation1 = defineOperation({
},
linkId: {
type: 'string',
description: 'ID of the tracked link.',
},
linkIds: {
type: 'array',
@@ -154,6 +147,7 @@ const operation1 = defineOperation({
},
],
},
description: 'Configuration parameters for the resource.',
},
},
},
-54
View File
@@ -1,54 +0,0 @@
import { defineOperation } from '@/openapi/operation';
import { badRequestResponse, jsonResponse, unauthorizedResponse } from '@/openapi/schemas';
import {
authorizationDecisionSchema,
authorizationDetailsSchema,
authorizationRedirectSchema,
authorizationRequestSchema,
oauthErrorSchema,
} from '../schema';
const describeAuthorizationOperation = defineOperation({
method: 'get',
path: '/api/oauth/authorize',
audience: 'internal',
auth: 'bearer',
operation: {
operationId: 'describeOAuthAuthorization',
summary: 'Describe a pending OAuth authorization request',
description:
'Validates an OAuth 2.1 authorization request and returns the client and scopes for the consent screen. Requires an interactive user session.',
tags: ['OAuth'],
requestParams: { query: authorizationRequestSchema },
responses: {
'200': jsonResponse(authorizationDetailsSchema, 'Authorization request details.'),
'400': jsonResponse(oauthErrorSchema, 'Invalid authorization request.'),
'401': unauthorizedResponse,
},
},
});
const decideAuthorizationOperation = defineOperation({
method: 'post',
path: '/api/oauth/authorize',
audience: 'internal',
auth: 'bearer',
operation: {
operationId: 'decideOAuthAuthorization',
summary: 'Approve or deny an OAuth authorization request',
description:
'Records the user decision. On approval an authorization code is issued and the redirect URL (with code, state and iss) is returned.',
tags: ['OAuth'],
requestBody: {
required: true,
content: { 'application/json': { schema: authorizationDecisionSchema } },
},
responses: {
'200': jsonResponse(authorizationRedirectSchema, 'Redirect URL for the browser.'),
'400': badRequestResponse,
'401': unauthorizedResponse,
},
},
});
export const operations = [describeAuthorizationOperation, decideAuthorizationOperation] as const;
-100
View File
@@ -1,100 +0,0 @@
import {
buildErrorRedirect,
buildSuccessRedirect,
issueAuthorizationCode,
validateAuthorizationRequest,
} from '@/lib/oauth/authorize';
import { getIssuer, isOAuthEnabled } from '@/lib/oauth/config';
import { OAuthError, oauthErrorResponse } from '@/lib/oauth/errors';
import { OAUTH_SCOPE_DESCRIPTIONS } from '@/lib/oauth/scopes';
import { parseRequest } from '@/lib/request';
import { json, notFound, unauthorized } from '@/lib/response';
import { authorizationDecisionSchema, authorizationRequestSchema } from '../schema';
function requireSession(auth: { user?: { id: string }; authType?: string } | null) {
// Only an interactive user session may grant consent: never an API key or another OAuth token.
return !!auth?.user?.id && (auth.authType === undefined || auth.authType === 'session');
}
/**
* Describes a pending authorization request for the consent screen. Validation errors are
* returned as JSON (the consent UI renders them) — no redirect happens until the user decides.
*/
export async function GET(request: Request) {
if (!isOAuthEnabled()) {
return notFound();
}
const { auth, query, error } = await parseRequest(request, authorizationRequestSchema);
if (error) {
return error();
}
if (!requireSession(auth)) {
return unauthorized();
}
try {
const validated = await validateAuthorizationRequest(query, getIssuer(request.headers));
return json({
client: {
id: validated.client.clientId,
name: validated.client.clientName,
uri: validated.client.clientUri,
logoUri: validated.client.logoUri,
source: validated.client.source,
},
scopes: validated.scopes.map(scope => ({
scope,
description: OAUTH_SCOPE_DESCRIPTIONS[scope],
})),
redirectUri: validated.redirectUri,
resource: validated.resource,
});
} catch (err) {
return oauthErrorResponse(err);
}
}
/** Records the user's decision and returns the redirect URL the browser should navigate to. */
export async function POST(request: Request) {
if (!isOAuthEnabled()) {
return notFound();
}
const { auth, body, error } = await parseRequest(request, authorizationDecisionSchema);
if (error) {
return error();
}
if (!requireSession(auth)) {
return unauthorized();
}
const issuer = getIssuer(request.headers);
const { decision, ...params } = body;
try {
const validated = await validateAuthorizationRequest(params, issuer);
if (decision !== 'approve') {
return json({
redirectUrl: buildErrorRedirect(
validated.redirectUri,
new OAuthError('access_denied', 'The user denied the request.'),
validated.state,
issuer,
),
});
}
const code = await issueAuthorizationCode(validated, auth.user.id);
return json({ redirectUrl: buildSuccessRedirect(validated, code, issuer) });
} catch (err) {
return oauthErrorResponse(err);
}
}
-31
View File
@@ -1,31 +0,0 @@
import { defineOperation } from '@/openapi/operation';
import { jsonResponse } from '@/openapi/schemas';
import {
clientRegistrationRequestSchema,
clientRegistrationResponseSchema,
oauthErrorSchema,
} from '../schema';
const registerOperation = defineOperation({
method: 'post',
path: '/api/oauth/register',
audience: 'internal',
auth: 'none',
operation: {
operationId: 'oauthRegisterClient',
summary: 'Register an OAuth client (dynamic client registration)',
description:
'RFC 7591 compatibility endpoint for MCP clients without Client ID Metadata Document support. Registers a public client. Prefer Client ID Metadata Documents (https URL client_id).',
tags: ['OAuth'],
requestBody: {
required: true,
content: { 'application/json': { schema: clientRegistrationRequestSchema } },
},
responses: {
'201': jsonResponse(clientRegistrationResponseSchema, 'Registered client.'),
'400': jsonResponse(oauthErrorSchema, 'Invalid client metadata.'),
},
},
});
export const operations = [registerOperation] as const;
-90
View File
@@ -1,90 +0,0 @@
import { uuid } from '@/lib/crypto';
import { isDynamicRegistrationEnabled } from '@/lib/oauth/config';
import { OAuthError, oauthErrorResponse, oauthJson } from '@/lib/oauth/errors';
import { corsPreflight } from '@/lib/oauth/metadata';
import { isAcceptableRedirectUri } from '@/lib/oauth/redirect';
import { parseRequest } from '@/lib/request';
import { notFound } from '@/lib/response';
import { createOauthClient } from '@/queries/prisma/oauth';
import { clientRegistrationRequestSchema } from '../schema';
export function OPTIONS() {
return corsPreflight();
}
/**
* Dynamic Client Registration (RFC 7591) compatibility endpoint for MCP clients that do not yet
* support Client ID Metadata Documents. Public clients only; disable with OAUTH_DISABLE_DCR=1.
*/
export async function POST(request: Request) {
if (!isDynamicRegistrationEnabled()) {
return notFound();
}
const { body, error } = await parseRequest(request, clientRegistrationRequestSchema, {
skipAuth: true,
});
if (error) {
return oauthJson(
{ error: 'invalid_client_metadata', error_description: 'Invalid registration request.' },
{ status: 400 },
);
}
try {
if (!body.redirect_uris.every(isAcceptableRedirectUri)) {
throw new OAuthError(
'invalid_redirect_uri',
'redirect_uris must be absolute https, loopback http or custom-scheme URLs without fragments.',
);
}
const grantTypes = body.grant_types ?? ['authorization_code', 'refresh_token'];
const responseTypes = body.response_types ?? ['code'];
if (grantTypes.some(type => !['authorization_code', 'refresh_token'].includes(type))) {
throw new OAuthError('invalid_client_metadata', 'Unsupported grant_types.');
}
if (responseTypes.some(type => type !== 'code')) {
throw new OAuthError('invalid_client_metadata', 'Unsupported response_types.');
}
const id = uuid();
const metadata = {
client_uri: body.client_uri,
logo_uri: body.logo_uri,
application_type: body.application_type,
software_id: body.software_id,
software_version: body.software_version,
scope: body.scope,
};
const client = await createOauthClient({
id,
name: body.client_name,
redirectUris: body.redirect_uris,
metadata,
});
return oauthJson(
{
client_id: client.id,
client_id_issued_at: Math.floor((client.createdAt ?? new Date()).getTime() / 1000),
client_name: client.name,
redirect_uris: body.redirect_uris,
token_endpoint_auth_method: 'none',
grant_types: grantTypes,
response_types: responseTypes,
...(body.client_uri ? { client_uri: body.client_uri } : {}),
...(body.logo_uri ? { logo_uri: body.logo_uri } : {}),
...(body.application_type ? { application_type: body.application_type } : {}),
...(body.scope ? { scope: body.scope } : {}),
},
{ status: 201 },
);
} catch (err) {
return oauthErrorResponse(err);
}
}
-31
View File
@@ -1,31 +0,0 @@
import { z } from 'zod';
import { defineOperation } from '@/openapi/operation';
import { jsonResponse } from '@/openapi/schemas';
import { oauthErrorSchema, revocationRequestSchema } from '../schema';
const revokeOperation = defineOperation({
method: 'post',
path: '/api/oauth/revoke',
audience: 'internal',
auth: 'none',
operation: {
operationId: 'oauthRevoke',
summary: 'Revoke an OAuth refresh token',
description:
'RFC 7009 revocation endpoint. Revokes the given refresh token; unknown tokens are accepted silently.',
tags: ['OAuth'],
requestBody: {
required: true,
content: {
'application/x-www-form-urlencoded': { schema: revocationRequestSchema },
'application/json': { schema: revocationRequestSchema },
},
},
responses: {
'200': jsonResponse(z.object({}), 'Token revoked (or already invalid).'),
'400': jsonResponse(oauthErrorSchema, 'Malformed request.'),
},
},
});
export const operations = [revokeOperation] as const;
-34
View File
@@ -1,34 +0,0 @@
import { isOAuthEnabled } from '@/lib/oauth/config';
import { oauthErrorResponse, oauthJson } from '@/lib/oauth/errors';
import { readOAuthBody } from '@/lib/oauth/form';
import { corsPreflight } from '@/lib/oauth/metadata';
import { handleRevocationRequest } from '@/lib/oauth/token';
import { notFound } from '@/lib/response';
export function OPTIONS() {
return corsPreflight();
}
/** RFC 7009 token revocation. Always returns 200 for well-formed requests. */
export async function POST(request: Request) {
if (!isOAuthEnabled()) {
return notFound();
}
try {
const params = await readOAuthBody(request);
if (typeof params.token !== 'string' || !params.token) {
return oauthJson(
{ error: 'invalid_request', error_description: 'token is required.' },
{ status: 400 },
);
}
await handleRevocationRequest(params);
return oauthJson({});
} catch (error) {
return oauthErrorResponse(error);
}
}
-102
View File
@@ -1,102 +0,0 @@
import { z } from 'zod';
export const authorizationRequestSchema = z
.object({
response_type: z.string().optional(),
client_id: z.string().max(2048),
redirect_uri: z.string().max(2048).optional(),
scope: z.string().max(500).optional(),
state: z.string().max(1024).optional(),
code_challenge: z.string().max(128).optional(),
code_challenge_method: z.string().max(10).optional(),
resource: z.string().max(2048).optional(),
})
.meta({ id: 'OAuthAuthorizationRequest' });
export const authorizationDecisionSchema = authorizationRequestSchema
.extend({
decision: z.enum(['approve', 'deny']),
})
.meta({ id: 'OAuthAuthorizationDecision' });
export const authorizationDetailsSchema = z
.object({
client: z.object({
id: z.string(),
name: z.string(),
uri: z.string().optional(),
logoUri: z.string().optional(),
source: z.enum(['metadata-document', 'registered']),
}),
scopes: z.array(z.object({ scope: z.string(), description: z.string() })),
redirectUri: z.string(),
resource: z.string(),
})
.meta({ id: 'OAuthAuthorizationDetails' });
export const authorizationRedirectSchema = z
.object({ redirectUrl: z.string() })
.meta({ id: 'OAuthAuthorizationRedirect' });
export const tokenRequestSchema = z
.object({
grant_type: z.enum(['authorization_code', 'refresh_token']),
code: z.string().optional(),
redirect_uri: z.string().optional(),
client_id: z.string().optional(),
code_verifier: z.string().optional(),
refresh_token: z.string().optional(),
scope: z.string().optional(),
resource: z.string().optional(),
})
.meta({ id: 'OAuthTokenRequest' });
export const tokenResponseSchema = z
.object({
access_token: z.string(),
token_type: z.literal('Bearer'),
expires_in: z.number().int(),
refresh_token: z.string(),
scope: z.string(),
})
.meta({ id: 'OAuthTokenResponse' });
export const oauthErrorSchema = z
.object({
error: z.string(),
error_description: z.string().optional(),
})
.meta({ id: 'OAuthErrorResponse' });
export const revocationRequestSchema = z
.object({
token: z.string(),
token_type_hint: z.string().optional(),
})
.meta({ id: 'OAuthRevocationRequest' });
export const clientRegistrationRequestSchema = z
.object({
redirect_uris: z.array(z.string().max(2048)).min(1).max(20),
client_name: z.string().trim().min(1).max(255),
client_uri: z.string().max(2048).optional(),
logo_uri: z.string().max(2048).optional(),
token_endpoint_auth_method: z.literal('none').optional(),
grant_types: z.array(z.string()).optional(),
response_types: z.array(z.string()).optional(),
application_type: z.enum(['web', 'native']).optional(),
scope: z.string().max(500).optional(),
software_id: z.string().max(255).optional(),
software_version: z.string().max(255).optional(),
})
.meta({ id: 'OAuthClientRegistrationRequest' });
export const clientRegistrationResponseSchema = clientRegistrationRequestSchema
.extend({
client_id: z.string(),
client_id_issued_at: z.number().int(),
token_endpoint_auth_method: z.literal('none'),
grant_types: z.array(z.string()),
response_types: z.array(z.string()),
})
.meta({ id: 'OAuthClientRegistrationResponse' });
-31
View File
@@ -1,31 +0,0 @@
import { defineOperation } from '@/openapi/operation';
import { jsonResponse } from '@/openapi/schemas';
import { oauthErrorSchema, tokenRequestSchema, tokenResponseSchema } from '../schema';
const tokenOperation = defineOperation({
method: 'post',
path: '/api/oauth/token',
audience: 'internal',
auth: 'none',
operation: {
operationId: 'oauthToken',
summary: 'OAuth 2.1 token endpoint',
description:
'Exchanges an authorization code (with PKCE code_verifier) or a refresh token for an access token. Accepts application/x-www-form-urlencoded or JSON. Refresh tokens are rotated on every use.',
tags: ['OAuth'],
requestBody: {
required: true,
content: {
'application/x-www-form-urlencoded': { schema: tokenRequestSchema },
'application/json': { schema: tokenRequestSchema },
},
},
responses: {
'200': jsonResponse(tokenResponseSchema, 'Access and refresh tokens.'),
'400': jsonResponse(oauthErrorSchema, 'Invalid grant or request.'),
'401': jsonResponse(oauthErrorSchema, 'Invalid client.'),
},
},
});
export const operations = [tokenOperation] as const;
-26
View File
@@ -1,26 +0,0 @@
import { getIssuer, isOAuthEnabled } from '@/lib/oauth/config';
import { oauthErrorResponse, oauthJson } from '@/lib/oauth/errors';
import { readOAuthBody } from '@/lib/oauth/form';
import { corsPreflight } from '@/lib/oauth/metadata';
import { handleTokenRequest } from '@/lib/oauth/token';
import { notFound } from '@/lib/response';
export function OPTIONS() {
return corsPreflight();
}
/** OAuth 2.1 token endpoint: authorization_code (PKCE) and refresh_token grants. */
export async function POST(request: Request) {
if (!isOAuthEnabled()) {
return notFound();
}
try {
const params = await readOAuthBody(request);
const tokens = await handleTokenRequest(params, getIssuer(request.headers));
return oauthJson(tokens);
} catch (error) {
return oauthErrorResponse(error);
}
}
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'getRealtime',
summary: 'Get realtime website id',
tags: ['Realtime'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'runAttributionReport',
summary: 'Create or update reports attribution',
tags: ['Reports'],
'x-umami-oauth-scope': 'analytics:read',
requestBody: {
required: true,
content: {
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'runBreakdownReport',
summary: 'Create or update reports breakdown',
tags: ['Reports'],
'x-umami-oauth-scope': 'analytics:read',
requestBody: {
required: true,
content: {
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'runFunnelReport',
summary: 'Create or update reports funnel',
tags: ['Reports'],
'x-umami-oauth-scope': 'analytics:read',
requestBody: {
required: true,
content: {
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'runJourneyReport',
summary: 'Create or update reports journey',
tags: ['Reports'],
'x-umami-oauth-scope': 'analytics:read',
requestBody: {
required: true,
content: {
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'runRetentionReport',
summary: 'Create or update reports retention',
tags: ['Reports'],
'x-umami-oauth-scope': 'analytics:read',
requestBody: {
required: true,
content: {
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'runRevenueReport',
summary: 'Create or update reports revenue',
tags: ['Reports'],
'x-umami-oauth-scope': 'analytics:read',
requestBody: {
required: true,
content: {
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'runUtmReport',
summary: 'Create or update reports utm',
tags: ['Reports'],
'x-umami-oauth-scope': 'analytics:read',
requestBody: {
required: true,
content: {
+123 -128
View File
@@ -10,7 +10,9 @@ const operation1 = defineOperation({
auth: 'bearer',
operation: {
operationId: 'deleteUser',
summary: 'Delete users user id',
summary: 'Delete a user',
description:
'Deletes the specified user account. The current user cannot delete their own account through this operation.',
tags: ['Users'],
parameters: [
{
@@ -20,6 +22,7 @@ const operation1 = defineOperation({
schema: {
type: 'string',
},
description: 'ID of the associated user.',
},
],
responses: {
@@ -32,6 +35,7 @@ const operation1 = defineOperation({
properties: {
ok: {
const: true,
description: 'Whether the operation succeeded.',
},
},
required: ['ok'],
@@ -84,7 +88,9 @@ const operation2 = defineOperation({
auth: 'bearer-or-share',
operation: {
operationId: 'getUser',
summary: 'Get users user id',
summary: 'Get a user',
description:
'Returns details for the specified user account when the caller has permission to view it.',
tags: ['Users'],
parameters: [
{
@@ -94,6 +100,7 @@ const operation2 = defineOperation({
schema: {
type: 'string',
},
description: 'ID of the associated user.',
},
],
responses: {
@@ -109,12 +116,15 @@ const operation2 = defineOperation({
properties: {
isEnabled: {
type: 'boolean',
description: 'Whether two-factor authentication is enabled.',
},
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
userId: {
type: 'string',
description: 'ID of the associated user.',
},
secret: {
type: 'string',
@@ -122,10 +132,12 @@ const operation2 = defineOperation({
createdAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was created.',
},
updatedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was last updated.',
},
},
required: ['isEnabled', 'id', 'userId', 'secret', 'createdAt', 'updatedAt'],
@@ -135,13 +147,16 @@ const operation2 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
userId: {
type: 'string',
description: 'ID of the associated user.',
},
updatedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was last updated.',
},
attempts: {
type: 'number',
@@ -149,28 +164,35 @@ const operation2 = defineOperation({
lockedUntil: {
type: 'string',
format: 'date-time',
description: 'Time until which further authentication attempts are blocked.',
},
},
required: ['id', 'userId', 'updatedAt', 'attempts', 'lockedUntil'],
},
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
createdAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was created.',
},
username: {
type: 'string',
description: 'Username of the account.',
},
password: {
type: 'string',
description: 'Password used to authenticate the account.',
},
role: {
type: 'string',
description: 'Permission role assigned to the user.',
},
twoFactorRequired: {
type: 'boolean',
description: 'Whether two-factor authentication is required.',
},
websites: {
type: 'array',
@@ -179,40 +201,51 @@ const operation2 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
userId: {
type: 'string',
description: 'ID of the associated user.',
},
createdAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was created.',
},
updatedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was last updated.',
},
deletedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was deleted, if applicable.',
},
createdBy: {
type: 'string',
description: 'ID of the user who created the resource.',
},
name: {
type: 'string',
description: 'Display name of the resource.',
},
domain: {
type: 'string',
description: 'Domain name associated with the resource.',
},
resetAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the website analytics were last reset.',
},
teamId: {
type: 'string',
description: 'ID of the associated team.',
},
recorderEnabled: {
type: 'boolean',
description: 'Whether recording is enabled for the website.',
},
replayConfig: {
anyOf: [
@@ -268,6 +301,7 @@ const operation2 = defineOperation({
required: ['length'],
},
],
description: 'Session replay and heatmap recording configuration.',
},
},
required: [
@@ -293,40 +327,51 @@ const operation2 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
userId: {
type: 'string',
description: 'ID of the associated user.',
},
createdAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was created.',
},
updatedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was last updated.',
},
deletedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was deleted, if applicable.',
},
createdBy: {
type: 'string',
description: 'ID of the user who created the resource.',
},
name: {
type: 'string',
description: 'Display name of the resource.',
},
domain: {
type: 'string',
description: 'Domain name associated with the resource.',
},
resetAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the website analytics were last reset.',
},
teamId: {
type: 'string',
description: 'ID of the associated team.',
},
recorderEnabled: {
type: 'boolean',
description: 'Whether recording is enabled for the website.',
},
replayConfig: {
anyOf: [
@@ -382,6 +427,7 @@ const operation2 = defineOperation({
required: ['length'],
},
],
description: 'Session replay and heatmap recording configuration.',
},
},
required: [
@@ -399,6 +445,7 @@ const operation2 = defineOperation({
'replayConfig',
],
},
description: 'ID of the user who created the resource.',
},
links: {
type: 'array',
@@ -407,33 +454,42 @@ const operation2 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
userId: {
type: 'string',
description: 'ID of the associated user.',
},
createdAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was created.',
},
updatedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was last updated.',
},
deletedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was deleted, if applicable.',
},
name: {
type: 'string',
description: 'Display name of the resource.',
},
teamId: {
type: 'string',
description: 'ID of the associated team.',
},
url: {
type: 'string',
description: 'URL associated with the resource.',
},
slug: {
type: 'string',
description: 'URL slug used to access the resource.',
},
},
required: [
@@ -448,6 +504,7 @@ const operation2 = defineOperation({
'slug',
],
},
description: 'Tracked links associated with the user.',
},
pixels: {
type: 'array',
@@ -456,30 +513,38 @@ const operation2 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
userId: {
type: 'string',
description: 'ID of the associated user.',
},
createdAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was created.',
},
updatedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was last updated.',
},
deletedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was deleted, if applicable.',
},
name: {
type: 'string',
description: 'Display name of the resource.',
},
teamId: {
type: 'string',
description: 'ID of the associated team.',
},
slug: {
type: 'string',
description: 'URL slug used to access the resource.',
},
},
required: [
@@ -493,6 +558,7 @@ const operation2 = defineOperation({
'slug',
],
},
description: 'Tracking pixels associated with the user.',
},
teams: {
type: 'array',
@@ -501,27 +567,34 @@ const operation2 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
userId: {
type: 'string',
description: 'ID of the associated user.',
},
createdAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was created.',
},
updatedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was last updated.',
},
role: {
type: 'string',
description: 'Permission role assigned to the user.',
},
teamId: {
type: 'string',
description: 'ID of the associated team.',
},
},
required: ['id', 'userId', 'createdAt', 'updatedAt', 'role', 'teamId'],
},
description: 'Teams associated with the user.',
},
reports: {
type: 'array',
@@ -530,26 +603,32 @@ const operation2 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
userId: {
type: 'string',
description: 'ID of the associated user.',
},
createdAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was created.',
},
updatedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was last updated.',
},
name: {
type: 'string',
description: 'Display name of the resource.',
},
type: {
type: 'string',
},
description: {
type: 'string',
description: 'Description of the resource.',
},
parameters: {
anyOf: [
@@ -605,9 +684,11 @@ const operation2 = defineOperation({
required: ['length'],
},
],
description: 'Configuration parameters for the resource.',
},
websiteId: {
type: 'string',
description: 'ID of the website.',
},
},
required: [
@@ -622,6 +703,7 @@ const operation2 = defineOperation({
'websiteId',
],
},
description: 'Saved reports associated with the user.',
},
boards: {
type: 'array',
@@ -630,29 +712,36 @@ const operation2 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
userId: {
type: 'string',
description: 'ID of the associated user.',
},
createdAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was created.',
},
updatedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was last updated.',
},
name: {
type: 'string',
description: 'Display name of the resource.',
},
teamId: {
type: 'string',
description: 'ID of the associated team.',
},
type: {
type: 'string',
},
description: {
type: 'string',
description: 'Description of the resource.',
},
parameters: {
anyOf: [
@@ -708,6 +797,7 @@ const operation2 = defineOperation({
required: ['length'],
},
],
description: 'Configuration parameters for the resource.',
},
},
required: [
@@ -722,6 +812,7 @@ const operation2 = defineOperation({
'parameters',
],
},
description: 'Boards associated with the user.',
},
twoFactorBackupCodes: {
type: 'array',
@@ -730,13 +821,16 @@ const operation2 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
userId: {
type: 'string',
description: 'ID of the associated user.',
},
createdAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was created.',
},
codeHash: {
type: 'string',
@@ -755,9 +849,11 @@ const operation2 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
userId: {
type: 'string',
description: 'ID of the associated user.',
},
otp: {
type: 'string',
@@ -765,6 +861,7 @@ const operation2 = defineOperation({
expiresAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the credential expires.',
},
},
required: ['id', 'userId', 'otp', 'expiresAt'],
@@ -777,26 +874,32 @@ const operation2 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
userId: {
type: 'string',
description: 'ID of the associated user.',
},
createdAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was created.',
},
name: {
type: 'string',
description: 'Display name of the resource.',
},
keyHash: {
type: 'string',
},
keyPrefix: {
type: 'string',
description: 'Visible prefix used to identify an API key.',
},
lastUsedAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the credential was last used.',
},
},
required: [
@@ -809,121 +912,7 @@ const operation2 = defineOperation({
'lastUsedAt',
],
},
},
oauthAuthorizationCodes: {
type: 'array',
items: {
type: 'object',
properties: {
id: {
type: 'string',
},
userId: {
type: 'string',
},
createdAt: {
type: 'string',
format: 'date-time',
},
codeHash: {
type: 'string',
},
expiresAt: {
type: 'string',
format: 'date-time',
},
clientId: {
type: 'string',
},
redirectUri: {
type: 'string',
},
scope: {
type: 'string',
},
resource: {
type: 'string',
},
codeChallenge: {
type: 'string',
},
codeChallengeMethod: {
type: 'string',
},
usedAt: {
type: 'string',
format: 'date-time',
},
},
required: [
'id',
'userId',
'createdAt',
'codeHash',
'expiresAt',
'clientId',
'redirectUri',
'scope',
'resource',
'codeChallenge',
'codeChallengeMethod',
'usedAt',
],
},
},
oauthRefreshTokens: {
type: 'array',
items: {
type: 'object',
properties: {
id: {
type: 'string',
},
userId: {
type: 'string',
},
createdAt: {
type: 'string',
format: 'date-time',
},
expiresAt: {
type: 'string',
format: 'date-time',
},
lastUsedAt: {
type: 'string',
format: 'date-time',
},
clientId: {
type: 'string',
},
scope: {
type: 'string',
},
resource: {
type: 'string',
},
tokenHash: {
type: 'string',
},
revokedAt: {
type: 'string',
format: 'date-time',
},
},
required: [
'id',
'userId',
'createdAt',
'expiresAt',
'lastUsedAt',
'clientId',
'scope',
'resource',
'tokenHash',
'revokedAt',
],
},
description: 'API keys associated with the user.',
},
_count: {
type: 'object',
@@ -933,21 +922,27 @@ const operation2 = defineOperation({
},
createdBy: {
type: 'number',
description: 'ID of the user who created the resource.',
},
links: {
type: 'number',
description: 'Tracked links associated with the user.',
},
pixels: {
type: 'number',
description: 'Tracking pixels associated with the user.',
},
teams: {
type: 'number',
description: 'Teams associated with the user.',
},
reports: {
type: 'number',
description: 'Saved reports associated with the user.',
},
boards: {
type: 'number',
description: 'Boards associated with the user.',
},
twoFactorAuth: {
type: 'number',
@@ -963,12 +958,7 @@ const operation2 = defineOperation({
},
apiKeys: {
type: 'number',
},
oauthAuthorizationCodes: {
type: 'number',
},
oauthRefreshTokens: {
type: 'number',
description: 'API keys associated with the user.',
},
},
required: [
@@ -984,8 +974,6 @@ const operation2 = defineOperation({
'twoFactorOtpUseds',
'twoFactorRateLimit',
'apiKeys',
'oauthAuthorizationCodes',
'oauthRefreshTokens',
],
},
},
@@ -1008,8 +996,6 @@ const operation2 = defineOperation({
'twoFactorBackupCodes',
'twoFactorOtpUseds',
'apiKeys',
'oauthAuthorizationCodes',
'oauthRefreshTokens',
'_count',
],
},
@@ -1044,7 +1030,8 @@ const operation3 = defineOperation({
auth: 'bearer',
operation: {
operationId: 'updateUser',
summary: 'Create or update users user id',
summary: 'Update a user',
description: "Updates a user's password. Administrators can also change the username and role.",
tags: ['Users'],
parameters: [
{
@@ -1054,6 +1041,7 @@ const operation3 = defineOperation({
schema: {
type: 'string',
},
description: 'ID of the associated user.',
},
],
requestBody: {
@@ -1066,15 +1054,18 @@ const operation3 = defineOperation({
username: {
type: 'string',
maxLength: 255,
description: 'Username of the account.',
},
password: {
type: 'string',
minLength: 8,
maxLength: 255,
description: 'Password used to authenticate the account.',
},
role: {
type: 'string',
enum: ['admin', 'user', 'view-only'],
description: 'Permission role assigned to the user.',
},
},
},
@@ -1091,16 +1082,20 @@ const operation3 = defineOperation({
properties: {
id: {
type: 'string',
description: 'Unique identifier of the resource.',
},
createdAt: {
type: 'string',
format: 'date-time',
description: 'Date and time the record was created.',
},
username: {
type: 'string',
description: 'Username of the account.',
},
role: {
type: 'string',
description: 'Permission role assigned to the user.',
},
},
required: ['id', 'createdAt', 'username', 'role'],
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'getWebsiteDateRange',
summary: 'Get websites website id daterange',
tags: ['Websites'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'getEventData',
summary: 'Get websites website id event data',
tags: ['Websites'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'getEventDataProperties',
summary: 'Get websites website id event data properties',
tags: ['Websites'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'getEventDataStats',
summary: 'Get websites website id event data stats',
tags: ['Websites'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'getEventDataValues',
summary: 'Get websites website id event data values',
tags: ['Websites'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'getWebsiteEventSeries',
summary: 'Get websites website id events series',
tags: ['Websites'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'getWebsiteEventStats',
summary: 'Get websites website id events stats',
tags: ['Websites'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'getWebsiteExpandedMetrics',
summary: 'Get websites website id metrics expanded',
tags: ['Websites'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'getWebsiteSessionActivity',
summary: 'Get websites website id sessions session id activity',
tags: ['Websites'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
@@ -111,7 +111,6 @@ const operation2 = defineOperation({
operationId: 'getWebsiteSession',
summary: 'Get websites website id sessions session id',
tags: ['Websites'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'getWebsiteSessionProperties',
summary: 'Get websites website id sessions session id properties',
tags: ['Websites'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
@@ -12,7 +12,6 @@ const operation1 = defineOperation({
operationId: 'getWebsiteSessionStats',
summary: 'Get websites website id sessions stats',
tags: ['Websites'],
'x-umami-oauth-scope': 'analytics:read',
parameters: [
{
name: 'websiteId',
+15 -7
View File
@@ -3,10 +3,9 @@ import type { McpLogger } from '@umami/mcp';
import { createUmamiMcpHttpHandler } from '@umami/mcp';
import debug from 'debug';
import { uuid } from '@/lib/crypto';
import { getBaseUrl } from '@/lib/get-base-url';
import { authenticateMcpRequest, mcpAuthErrorResponse } from '@/lib/mcp/auth';
import { createInProcessFetch } from '@/lib/mcp/dispatch';
import { getIssuer, isOAuthEnabled } from '@/lib/oauth/config';
import { corsPreflight } from '@/lib/oauth/metadata';
export const dynamic = 'force-dynamic';
@@ -27,10 +26,11 @@ const handler = createUmamiMcpHttpHandler({
logger,
onerror: error => log('handler error: %s', error?.message),
createClient: (authInfo, ctx) => {
const issuer = getIssuer(ctx.requestInfo?.headers);
const baseUrl = getBaseUrl(ctx.requestInfo?.headers).toString().replace(/\/+$/, '');
const basePath = (process.env.BASE_PATH ?? '').replace(/\/+$/, '');
return new UmamiClient({
baseUrl: `${issuer}/api`,
baseUrl: `${baseUrl}${basePath}/api`,
token: authInfo.token,
fetch: createInProcessFetch(),
});
@@ -38,14 +38,14 @@ const handler = createUmamiMcpHttpHandler({
});
async function handle(request: Request) {
if (!isOAuthEnabled() && process.env.MCP_DISABLED === '1') {
if (process.env.MCP_DISABLED === '1') {
return new Response(null, { status: 404 });
}
const auth = await authenticateMcpRequest(request);
if (!auth.ok) {
return mcpAuthErrorResponse(auth, request.headers);
return mcpAuthErrorResponse(auth);
}
const requestId = uuid();
@@ -55,7 +55,15 @@ async function handle(request: Request) {
}
export function OPTIONS() {
return corsPreflight();
return new Response(null, {
status: 204,
headers: {
'access-control-allow-origin': '*',
'access-control-allow-methods': 'GET, POST, DELETE, OPTIONS',
'access-control-allow-headers': '*',
'access-control-max-age': '86400',
},
});
}
export async function GET(request: Request) {
@@ -1,166 +0,0 @@
'use client';
import { Button, Column, Heading, Icon, Loading, Row, Text } from '@umami/react-zen';
import { usePathname, useSearchParams } from 'next/navigation';
import { useEffect, useMemo, useState } from 'react';
import { LoginForm } from '@/app/login/LoginForm';
import { useApi, useLoginQuery, useMessages } from '@/components/hooks';
import { Logo } from '@/components/svg';
import { setReturnUrl } from '@/lib/return-url';
interface AuthorizationDetails {
client: { id: string; name: string; uri?: string; logoUri?: string; source: string };
scopes: { scope: string; description: string }[];
redirectUri: string;
resource: string;
}
const SCOPE_MESSAGE_KEYS: Record<string, string> = {
'websites:read': 'oauthScopeWebsitesRead',
'analytics:read': 'oauthScopeAnalyticsRead',
};
function getOAuthErrorMessage(error: unknown) {
const record = error as { error_description?: string; message?: string; code?: string } | null;
return record?.error_description || record?.message || null;
}
function Frame({ children }: { children: React.ReactNode }) {
return (
<Column
alignItems="center"
justifyContent="flex-start"
height="100vh"
backgroundColor="surface-raised"
style={{ paddingTop: '10vh' }}
>
<Column alignItems="center" gap="6" style={{ width: '100%', maxWidth: 420 }}>
<Icon size="lg">
<Logo />
</Icon>
<Heading>umami</Heading>
{children}
</Column>
</Column>
);
}
export function OAuthAuthorizePage() {
const { t, labels, messages } = useMessages();
const pathname = usePathname();
const searchParams = useSearchParams();
const params = useMemo(() => Object.fromEntries(searchParams.entries()), [searchParams]);
const { user, isLoading } = useLoginQuery();
const { get, post, useQuery, useMutation } = useApi();
const [redirecting, setRedirecting] = useState(false);
useEffect(() => {
if (!isLoading && !user) {
setReturnUrl(`${pathname}?${searchParams.toString()}`);
}
}, [isLoading, user, pathname, searchParams]);
const details = useQuery<AuthorizationDetails>({
queryKey: ['oauth-authorize', params],
queryFn: () => get('/oauth/authorize', params),
enabled: !!user,
retry: false,
});
const decide = useMutation({
mutationFn: (decision: 'approve' | 'deny') =>
post('/oauth/authorize', { ...params, decision }) as Promise<{ redirectUrl: string }>,
onSuccess: ({ redirectUrl }) => {
setRedirecting(true);
window.location.assign(redirectUrl);
},
});
if (isLoading) {
return <Loading placement="absolute" />;
}
if (!user) {
return (
<Frame>
<Text>{t(messages.oauthLoginPrompt)}</Text>
<LoginForm />
</Frame>
);
}
if (details.isLoading) {
return <Loading placement="absolute" />;
}
if (details.error || !details.data) {
return (
<Frame>
<Text weight="bold">{t(messages.oauthInvalidRequest)}</Text>
{getOAuthErrorMessage(details.error) && (
<Text color="muted">{getOAuthErrorMessage(details.error)}</Text>
)}
</Frame>
);
}
const { client, scopes, redirectUri } = details.data;
const redirectHost = (() => {
try {
return new URL(redirectUri).host || redirectUri;
} catch {
return redirectUri;
}
})();
const decisionError = getOAuthErrorMessage(decide.error);
return (
<Frame>
<Column gap="4" style={{ width: '100%' }}>
<Text size="lg" weight="bold" align="center">
{t(messages.oauthConsent, { name: client.name })}
</Text>
{client.uri && (
<Text color="muted" align="center">
{client.uri}
</Text>
)}
<Text>{t(messages.oauthPermissions)}</Text>
<ul style={{ margin: 0, paddingInlineStart: 20 }}>
{scopes.map(({ scope, description }) => (
<li key={scope}>
<Text>
{SCOPE_MESSAGE_KEYS[scope] ? t(messages[SCOPE_MESSAGE_KEYS[scope]]) : description}
</Text>
</li>
))}
</ul>
<Text color="muted" size="sm">
{t(messages.oauthRedirectNotice, { url: redirectHost })}
</Text>
<Text color="muted" size="sm">
{t(messages.oauthSignedInAs, { username: user.username })}
</Text>
{decisionError && <Text style={{ color: 'var(--zen-status-error)' }}>{decisionError}</Text>}
<Row gap="3" justifyContent="flex-end">
<Button
data-test="button-oauth-deny"
onPress={() => decide.mutate('deny')}
isDisabled={decide.isPending || redirecting}
>
{t(labels.deny)}
</Button>
<Button
data-test="button-oauth-approve"
variant="primary"
onPress={() => decide.mutate('approve')}
isDisabled={decide.isPending || redirecting}
>
{t(labels.authorize)}
</Button>
</Row>
{redirecting && <Text color="muted">{t(messages.oauthRedirecting)}</Text>}
</Column>
</Frame>
);
}
-17
View File
@@ -1,17 +0,0 @@
import type { Metadata } from 'next';
import { isOAuthEnabled } from '@/lib/oauth/config';
import { OAuthAuthorizePage } from './OAuthAuthorizePage';
export const dynamic = 'force-dynamic';
export default async function () {
if (!isOAuthEnabled()) {
return null;
}
return <OAuthAuthorizePage />;
}
export const metadata: Metadata = {
title: 'Authorize application',
};
-9
View File
@@ -500,15 +500,6 @@ export const messages: Record<string, string> = {
twoFactorDisableDescription: 'message.two-factor-disable-description',
twoFactorRequiredMessage: 'message.two-factor-required-message',
twoFactorOverrideNote: 'message.two-factor-override-note',
oauthLoginPrompt: 'message.oauth-login-prompt',
oauthConsent: 'message.oauth-consent',
oauthPermissions: 'message.oauth-permissions',
oauthScopeWebsitesRead: 'message.oauth-scope-websites-read',
oauthScopeAnalyticsRead: 'message.oauth-scope-analytics-read',
oauthRedirectNotice: 'message.oauth-redirect-notice',
oauthSignedInAs: 'message.oauth-signed-in-as',
oauthInvalidRequest: 'message.oauth-invalid-request',
oauthRedirecting: 'message.oauth-redirecting',
twoFactorAdminGlobalDescription: 'message.two-factor-admin-global-description',
twoFactorRequireUserDescription: 'message.two-factor-require-user-description',
twoFactorRequireTeamDescription: 'message.two-factor-require-team-description',
-1
View File
@@ -15,7 +15,6 @@ export const API_KEY_BLOCKED_PATHS = [
'/api/auth',
'/api/users',
'/api/admin',
'/api/oauth',
];
export function generateApiKey() {
-14
View File
@@ -15,7 +15,6 @@ import {
} from '@/lib/constants';
import { createAuthKey, hash, secret } from '@/lib/crypto';
import { createSecureToken, parseSecureToken, parseToken } from '@/lib/jwt';
import { verifyOAuthRequest } from '@/lib/oauth/verify';
import redis from '@/lib/redis';
import { ensureArray } from '@/lib/utils';
import { getApiKeyByHash, updateApiKeyLastUsed } from '@/queries/prisma/apiKey';
@@ -75,19 +74,6 @@ export async function checkAuth(request: Request) {
return checkApiKeyAuth(request, token);
}
// OAuth access tokens are only honoured on routes that explicitly opted in (see
// src/lib/oauth/scopes.ts) and never fall through to session handling.
const oauth = await verifyOAuthRequest(token, request.method, new URL(request.url).pathname);
if (oauth.status === 'ok') {
return oauth.auth;
}
if (oauth.status !== 'not-oauth') {
log('OAuth token rejected', oauth);
return null;
}
const payload = parseSecureToken(token, secret());
const shareToken = await parseShareToken(request);
+46 -85
View File
@@ -1,7 +1,5 @@
import { beforeEach, describe, expect, test, vi } from 'vitest';
import { checkApiKeyAuth } from '@/lib/auth';
import { createAccessToken } from '@/lib/oauth/tokens';
import { getUser } from '@/queries/prisma/user';
import { authenticateMcpRequest, mcpAuthErrorResponse } from './auth';
vi.mock('@/lib/auth', () => ({
@@ -9,115 +7,78 @@ vi.mock('@/lib/auth', () => ({
checkApiKeyAuth: vi.fn(),
}));
vi.mock('@/queries/prisma/user', () => ({
getUser: vi.fn(),
}));
const checkApiKeyAuthMock = vi.mocked(checkApiKeyAuth);
const getUserMock = vi.mocked(getUser);
const ISSUER = 'https://analytics.example.com';
const USER = { id: 'user-1', username: 'admin', role: 'user', password: 'pw' };
function request(token?: string) {
return new Request(`${ISSUER}/mcp`, {
return new Request('https://analytics.example.com/mcp', {
method: 'POST',
headers: {
host: 'analytics.example.com',
'x-forwarded-proto': 'https',
...(token ? { authorization: `Bearer ${token}` } : {}),
},
headers: token ? { authorization: `Bearer ${token}` } : {},
});
}
function accessToken(overrides: Record<string, unknown> = {}) {
return createAccessToken({
userId: USER.id,
clientId: 'https://app.example.com/client.json',
scopes: ['websites:read', 'analytics:read'],
issuer: ISSUER,
resource: `${ISSUER}/mcp`,
passwordHash: USER.password,
...overrides,
}).token;
}
beforeEach(() => {
process.env.APP_SECRET = 'test';
delete process.env.OAUTH_ISSUER;
delete process.env.CLOUD_MODE;
vi.unstubAllEnvs();
vi.stubEnv('CLOUD_MODE', '');
checkApiKeyAuthMock.mockReset();
getUserMock.mockReset();
getUserMock.mockResolvedValue({ ...USER } as never);
});
describe('authenticateMcpRequest', () => {
test('rejects missing tokens with a resource metadata challenge', async () => {
test('rejects missing tokens with an API key challenge', async () => {
const result = await authenticateMcpRequest(request());
expect(result.ok).toBe(false);
const response = mcpAuthErrorResponse(result as never, request().headers);
const response = mcpAuthErrorResponse(result);
expect(response.status).toBe(401);
expect(response.headers.get('www-authenticate')).toContain(
`resource_metadata="${ISSUER}/.well-known/oauth-protected-resource/mcp"`,
);
expect(response.headers.get('www-authenticate')).toContain(
'scope="websites:read analytics:read"',
expect(response.headers.get('www-authenticate')).toBe(
'Bearer realm="Umami MCP", error="invalid_request"',
);
expect(response.headers.get('cache-control')).toBe('no-store');
});
test('accepts OAuth access tokens issued for this resource', async () => {
const result = await authenticateMcpRequest(request(accessToken()));
expect(result.ok).toBe(true);
if (result.ok) {
expect(result.userId).toBe(USER.id);
expect(result.authInfo).toMatchObject({
clientId: 'https://app.example.com/client.json',
scopes: ['analytics:read', 'websites:read'],
test.each(['not-a-token', 'eyJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoib2F1dGhfYWNjZXNzIn0.signature'])(
'rejects non-API-key credentials: %s',
async token => {
await expect(authenticateMcpRequest(request(token))).resolves.toMatchObject({
ok: false,
status: 401,
});
expect(result.authInfo.extra).toMatchObject({ userId: USER.id, authType: 'oauth' });
}
});
expect(checkApiKeyAuthMock).not.toHaveBeenCalled();
},
);
test('rejects tokens issued for another deployment', async () => {
const foreign = createAccessToken({
userId: USER.id,
clientId: 'c',
scopes: ['websites:read'],
issuer: 'https://other.example.com',
resource: 'https://other.example.com/mcp',
}).token;
const result = await authenticateMcpRequest(request(foreign));
expect(result).toMatchObject({ ok: false, status: 401, error: 'invalid_token' });
});
test('rejects session tokens and garbage', async () => {
await expect(authenticateMcpRequest(request('not-a-token'))).resolves.toMatchObject({
ok: false,
status: 401,
});
});
test('accepts self-hosted API keys', async () => {
test('accepts self-hosted API keys and preserves owner identity', async () => {
checkApiKeyAuthMock.mockResolvedValue({
token: 'umami_key',
user: { id: USER.id, username: 'admin', role: 'user', isAdmin: false },
authType: 'api-key',
user: { id: 'user-1' },
apiKey: { id: 'key-1', name: 'MCP' },
} as never);
const result = await authenticateMcpRequest(request('umami_key'));
await expect(authenticateMcpRequest(request('umami_key'))).resolves.toMatchObject({
ok: true,
userId: 'user-1',
authInfo: {
token: 'umami_key',
clientId: 'api-key:key-1',
scopes: [],
extra: { userId: 'user-1', authType: 'api-key' },
},
});
});
expect(result.ok).toBe(true);
test('rejects revoked or unknown keys', async () => {
checkApiKeyAuthMock.mockResolvedValue(null);
await expect(authenticateMcpRequest(request('umami_revoked'))).resolves.toMatchObject({
ok: false,
status: 401,
error: 'invalid_token',
});
});
if (result.ok) {
expect(result.authInfo.clientId).toBe('api-key:key-1');
expect(result.authInfo.scopes).toEqual(['websites:read', 'analytics:read']);
}
test('rejects self-hosted keys in Cloud mode', async () => {
vi.stubEnv('CLOUD_MODE', '1');
await expect(authenticateMcpRequest(request('umami_key'))).resolves.toMatchObject({
ok: false,
status: 401,
});
expect(checkApiKeyAuthMock).not.toHaveBeenCalled();
});
});
+13 -88
View File
@@ -1,24 +1,12 @@
import type { AuthInfo } from '@umami/mcp';
import { isApiKey, isApiKeyEnabled } from '@/lib/api-key';
import { checkApiKeyAuth, getBearerToken } from '@/lib/auth';
import { getIssuer, getOAuthEndpoints, isOAuthEnabled } from '@/lib/oauth/config';
import { OAUTH_SCOPES } from '@/lib/oauth/scopes';
import { looksLikeAccessToken, verifyAccessToken } from '@/lib/oauth/tokens';
import { buildOAuthAuth } from '@/lib/oauth/verify';
export type McpAuthResult =
| { ok: true; authInfo: AuthInfo; userId: string }
| { ok: false; status: 401 | 403; error: string; description: string; scope?: string };
| { ok: false; status: 401; error: string; description: string };
/**
* Authenticates a request to the embedded MCP endpoint.
*
* Accepted credentials:
* - OAuth access tokens issued by this deployment for the `/mcp` resource (primary).
* - Self-hosted API keys (`umami_…`), so a remote MCP client can be configured without OAuth.
*
* Browser session tokens are deliberately rejected.
*/
/** The embedded MCP endpoint accepts self-hosted API keys only. */
export async function authenticateMcpRequest(request: Request): Promise<McpAuthResult> {
const token = getBearerToken(request);
@@ -27,65 +15,18 @@ export async function authenticateMcpRequest(request: Request): Promise<McpAuthR
ok: false,
status: 401,
error: 'invalid_request',
description: 'Missing bearer token.',
description: 'Missing bearer API key.',
};
}
if (isApiKeyEnabled() && isApiKey(token)) {
const auth = await checkApiKeyAuth(request, token);
if (!auth?.user?.id) {
return { ok: false, status: 401, error: 'invalid_token', description: 'Invalid API key.' };
}
return {
ok: true,
userId: auth.user.id,
authInfo: {
token,
clientId: `api-key:${auth.apiKey.id}`,
scopes: [...OAUTH_SCOPES],
extra: { userId: auth.user.id, authType: 'api-key' },
},
};
if (!isApiKeyEnabled() || !isApiKey(token)) {
return { ok: false, status: 401, error: 'invalid_token', description: 'Invalid API key.' };
}
if (!looksLikeAccessToken(token) || !isOAuthEnabled()) {
return { ok: false, status: 401, error: 'invalid_token', description: 'Invalid bearer token.' };
}
const auth = await checkApiKeyAuth(request, token);
const verified = verifyAccessToken(token);
if (!verified) {
return {
ok: false,
status: 401,
error: 'invalid_token',
description: 'Access token is invalid or expired.',
};
}
// Audience binding: the token must have been issued for this deployment's MCP resource.
const endpoints = getOAuthEndpoints(request.headers);
if (verified.resource !== endpoints.resource || verified.issuer !== getIssuer(request.headers)) {
return {
ok: false,
status: 401,
error: 'invalid_token',
description: 'Access token was not issued for this resource.',
};
}
const auth = await buildOAuthAuth(token, verified);
if (!auth) {
return {
ok: false,
status: 401,
error: 'invalid_token',
description: 'Access token is no longer valid.',
};
if (!auth?.user?.id) {
return { ok: false, status: 401, error: 'invalid_token', description: 'Invalid API key.' };
}
return {
@@ -93,42 +34,26 @@ export async function authenticateMcpRequest(request: Request): Promise<McpAuthR
userId: auth.user.id,
authInfo: {
token,
clientId: verified.clientId,
scopes: verified.scopes,
expiresAt: Math.floor(verified.expiresAt / 1000),
resource: new URL(verified.resource),
extra: { userId: auth.user.id, authType: 'oauth', tokenId: verified.tokenId },
clientId: `api-key:${auth.apiKey.id}`,
scopes: [],
extra: { userId: auth.user.id, authType: 'api-key' },
},
};
}
export function mcpAuthErrorResponse(result: McpAuthResult, headers: Pick<Headers, 'get'>) {
export function mcpAuthErrorResponse(result: McpAuthResult) {
if (result.ok) {
throw new Error('mcpAuthErrorResponse called with a successful result.');
}
// Explicit narrowing: the project compiles without strictNullChecks, so the guard above does
// not narrow the union automatically.
const failure = result as Extract<McpAuthResult, { ok: false }>;
const endpoints = getOAuthEndpoints(headers);
const parts = [
`Bearer error="${failure.error}"`,
`error_description="${failure.description.replace(/"/g, "'")}"`,
`resource_metadata="${endpoints.protectedResourceMetadata}"`,
];
if (failure.scope) {
parts.push(`scope="${failure.scope}"`);
} else if (failure.status === 401) {
parts.push(`scope="${OAUTH_SCOPES.join(' ')}"`);
}
return Response.json(
{ error: failure.error, error_description: failure.description },
{
status: failure.status,
headers: {
'www-authenticate': parts.join(', '),
'www-authenticate': `Bearer realm="Umami MCP", error="${failure.error}"`,
'cache-control': 'no-store',
},
},
+1 -11
View File
@@ -1,17 +1,7 @@
import { describe, expect, test } from 'vitest';
import { OAUTH_ROUTE_SCOPES } from '@/lib/oauth/scopes';
import { MCP_DISPATCH_ROUTES, matchDispatchRoute } from './dispatch';
import { matchDispatchRoute } from './dispatch';
describe('MCP dispatch table', () => {
test('covers exactly the OAuth-allowlisted routes', () => {
const dispatch = MCP_DISPATCH_ROUTES.map(route => `${route.method} ${route.path}`).sort();
const allowlist = OAUTH_ROUTE_SCOPES.map(
route => `${route.method.toUpperCase()} ${route.path}`,
).sort();
expect(dispatch).toEqual(allowlist);
});
test('matches concrete paths and extracts parameters', () => {
const match = matchDispatchRoute('GET', '/api/websites/abc/sessions/def/activity');
+1 -2
View File
@@ -13,8 +13,7 @@ export interface DispatchRoute {
/**
* The API routes the embedded MCP server may call, dispatched in-process (no loopback HTTP).
* This list must stay identical to `OAUTH_ROUTE_SCOPES` in `src/lib/oauth/scopes.ts`;
* `dispatch.test.ts` enforces that. Anything not listed here is unreachable from MCP.
* Anything not listed here is unreachable from MCP.
*/
export const MCP_DISPATCH_ROUTES: readonly DispatchRoute[] = [
{ method: 'GET', path: '/api/me', load: () => import('@/app/api/me/route') },
-171
View File
@@ -1,171 +0,0 @@
import { beforeEach, describe, expect, test, vi } from 'vitest';
import { createAuthorizationCode } from '@/queries/prisma/oauth';
import {
buildErrorRedirect,
buildSuccessRedirect,
issueAuthorizationCode,
validateAuthorizationRequest,
} from './authorize';
import { resolveOAuthClient } from './client';
import { OAuthError } from './errors';
import { computeCodeChallenge } from './pkce';
vi.mock('./client', () => ({
resolveOAuthClient: vi.fn(),
}));
vi.mock('@/queries/prisma/oauth', () => ({
createAuthorizationCode: vi.fn(),
}));
const resolveOAuthClientMock = vi.mocked(resolveOAuthClient);
const createAuthorizationCodeMock = vi.mocked(createAuthorizationCode);
const ISSUER = 'https://analytics.example.com';
const CLIENT = {
clientId: 'https://app.example.com/client.json',
clientName: 'App',
redirectUris: ['https://app.example.com/cb', 'http://127.0.0.1:1/cb'],
source: 'metadata-document' as const,
};
const VERIFIER = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk';
function request(overrides: Record<string, unknown> = {}) {
return {
response_type: 'code',
client_id: CLIENT.clientId,
redirect_uri: 'https://app.example.com/cb',
scope: 'websites:read analytics:read',
state: 'xyz',
code_challenge: computeCodeChallenge(VERIFIER),
code_challenge_method: 'S256',
resource: `${ISSUER}/mcp`,
...overrides,
};
}
beforeEach(() => {
process.env.APP_SECRET = 'test';
resolveOAuthClientMock.mockReset();
resolveOAuthClientMock.mockResolvedValue(CLIENT);
createAuthorizationCodeMock.mockReset();
createAuthorizationCodeMock.mockResolvedValue({} as never);
});
describe('validateAuthorizationRequest', () => {
test('accepts a valid request', async () => {
await expect(validateAuthorizationRequest(request(), ISSUER)).resolves.toMatchObject({
client: CLIENT,
redirectUri: 'https://app.example.com/cb',
scopes: ['analytics:read', 'websites:read'],
state: 'xyz',
codeChallengeMethod: 'S256',
resource: `${ISSUER}/mcp`,
});
});
test('defaults to all scopes and the MCP resource when omitted', async () => {
const result = await validateAuthorizationRequest(
request({ scope: undefined, resource: undefined }),
ISSUER,
);
expect(result.scopes).toEqual(['analytics:read', 'websites:read']);
expect(result.resource).toBe(`${ISSUER}/mcp`);
});
test('allows loopback redirect ports to vary', async () => {
const result = await validateAuthorizationRequest(
request({ redirect_uri: 'http://127.0.0.1:54321/cb' }),
ISSUER,
);
expect(result.redirectUri).toBe('http://127.0.0.1:1/cb');
});
test('rejects unregistered redirect URIs before anything else (not redirectable)', async () => {
const error = await validateAuthorizationRequest(
request({ redirect_uri: 'https://evil.example/cb', response_type: 'token' }),
ISSUER,
).catch(e => e);
expect(error).toBeInstanceOf(OAuthError);
expect(error.code).toBe('invalid_redirect_uri');
expect(error.redirectable).toBe(false);
});
test('requires PKCE S256', async () => {
await expect(
validateAuthorizationRequest(request({ code_challenge: undefined }), ISSUER),
).rejects.toMatchObject({ code: 'invalid_request', redirectable: true });
await expect(
validateAuthorizationRequest(request({ code_challenge_method: 'plain' }), ISSUER),
).rejects.toMatchObject({ code: 'invalid_request' });
});
test('rejects unknown scopes, response types and resources', async () => {
await expect(
validateAuthorizationRequest(request({ scope: 'websites:write' }), ISSUER),
).rejects.toMatchObject({ code: 'invalid_scope' });
await expect(
validateAuthorizationRequest(request({ response_type: 'token' }), ISSUER),
).rejects.toMatchObject({ code: 'unsupported_response_type' });
await expect(
validateAuthorizationRequest(request({ resource: 'https://other.example/mcp' }), ISSUER),
).rejects.toMatchObject({ code: 'invalid_target' });
});
test('propagates client resolution errors', async () => {
resolveOAuthClientMock.mockRejectedValue(new OAuthError('invalid_client', 'Unknown'));
await expect(validateAuthorizationRequest(request(), ISSUER)).rejects.toMatchObject({
code: 'invalid_client',
});
});
});
describe('issueAuthorizationCode', () => {
test('stores a hashed, expiring, PKCE-bound code and builds the redirect', async () => {
const validated = await validateAuthorizationRequest(request(), ISSUER);
const code = await issueAuthorizationCode(validated, 'user-1');
expect(code.length).toBeGreaterThanOrEqual(43);
expect(createAuthorizationCodeMock).toHaveBeenCalledWith(
expect.objectContaining({
userId: 'user-1',
clientId: CLIENT.clientId,
redirectUri: 'https://app.example.com/cb',
scope: 'analytics:read websites:read',
codeChallenge: computeCodeChallenge(VERIFIER),
codeChallengeMethod: 'S256',
}),
);
const stored = createAuthorizationCodeMock.mock.calls[0][0];
expect(stored.codeHash).not.toContain(code);
expect(stored.expiresAt.getTime()).toBeLessThanOrEqual(Date.now() + 10 * 60 * 1000);
const redirect = new URL(buildSuccessRedirect(validated, code, ISSUER));
expect(redirect.origin + redirect.pathname).toBe('https://app.example.com/cb');
expect(redirect.searchParams.get('code')).toBe(code);
expect(redirect.searchParams.get('state')).toBe('xyz');
expect(redirect.searchParams.get('iss')).toBe(ISSUER);
});
test('builds error redirects with iss and state', () => {
const redirect = new URL(
buildErrorRedirect(
'https://app.example.com/cb',
new OAuthError('access_denied', 'Denied'),
'st',
ISSUER,
),
);
expect(redirect.searchParams.get('error')).toBe('access_denied');
expect(redirect.searchParams.get('state')).toBe('st');
expect(redirect.searchParams.get('iss')).toBe(ISSUER);
});
});
-183
View File
@@ -1,183 +0,0 @@
import { uuid } from '@/lib/crypto';
import {
type MetadataFetch,
type ResolvedOAuthClient,
resolveOAuthClient,
} from '@/lib/oauth/client';
import {
AUTHORIZATION_CODE_TTL_SECONDS,
getMcpResource,
normalizeResource,
} from '@/lib/oauth/config';
import { OAuthError } from '@/lib/oauth/errors';
import { isPkceMethod, isValidCodeChallenge } from '@/lib/oauth/pkce';
import { appendRedirectParams, findMatchingRedirectUri } from '@/lib/oauth/redirect';
import {
isOAuthScope,
normalizeScopes,
OAUTH_SCOPES,
type OAuthScope,
parseScopes,
} from '@/lib/oauth/scopes';
import { generateAuthorizationCode, hashToken } from '@/lib/oauth/tokens';
import { createAuthorizationCode } from '@/queries/prisma/oauth';
export interface AuthorizationRequestParams {
response_type?: unknown;
client_id?: unknown;
redirect_uri?: unknown;
scope?: unknown;
state?: unknown;
code_challenge?: unknown;
code_challenge_method?: unknown;
resource?: unknown;
}
export interface ValidatedAuthorizationRequest {
client: ResolvedOAuthClient;
redirectUri: string;
scopes: OAuthScope[];
state?: string;
codeChallenge: string;
codeChallengeMethod: 'S256';
resource: string;
}
function optionalString(value: unknown, name: string, max = 2048) {
if (value === undefined || value === null || value === '') {
return undefined;
}
if (typeof value !== 'string' || value.length > max) {
throw new OAuthError('invalid_request', `${name} is invalid.`);
}
return value;
}
/**
* Validates an authorization request per OAuth 2.1 + MCP requirements: PKCE S256 is mandatory,
* the redirect URI must be registered, scopes must be known, and the resource indicator must be
* this deployment's MCP server.
*
* Errors thrown before the redirect URI is validated must be shown to the user; errors thrown
* afterwards are marked `redirectable`.
*/
export async function validateAuthorizationRequest(
params: AuthorizationRequestParams,
issuer: string,
options: { fetch?: MetadataFetch } = {},
): Promise<ValidatedAuthorizationRequest> {
const client = await resolveOAuthClient(params.client_id, options);
const redirectUriParam = optionalString(params.redirect_uri, 'redirect_uri');
const redirectUri = redirectUriParam
? findMatchingRedirectUri(redirectUriParam, client.redirectUris)
: client.redirectUris.length === 1
? client.redirectUris[0]
: null;
if (!redirectUri) {
throw new OAuthError('invalid_redirect_uri', 'redirect_uri is not registered for this client.');
}
const redirectable = { redirectable: true };
if (params.response_type !== 'code') {
throw new OAuthError(
'unsupported_response_type',
'response_type must be "code".',
redirectable,
);
}
if (!isValidCodeChallenge(params.code_challenge)) {
throw new OAuthError(
'invalid_request',
'A PKCE code_challenge (S256) is required.',
redirectable,
);
}
if (!isPkceMethod(params.code_challenge_method)) {
throw new OAuthError('invalid_request', 'code_challenge_method must be "S256".', redirectable);
}
const requestedScopes = parseScopes(optionalString(params.scope, 'scope', 500));
const unknown = requestedScopes.filter(
scope => !isOAuthScope(scope) && scope !== 'offline_access',
);
if (unknown.length) {
throw new OAuthError('invalid_scope', `Unknown scope: ${unknown.join(', ')}.`, redirectable);
}
const scopes = requestedScopes.length
? normalizeScopes(requestedScopes)
: normalizeScopes([...OAUTH_SCOPES]);
if (!scopes.length) {
throw new OAuthError('invalid_scope', 'At least one scope is required.', redirectable);
}
const expectedResource = getMcpResource(issuer);
const resourceParam = optionalString(params.resource, 'resource');
const resource = resourceParam ? normalizeResource(resourceParam) : expectedResource;
if (!resource || resource !== expectedResource) {
throw new OAuthError('invalid_target', `resource must be ${expectedResource}.`, redirectable);
}
return {
client,
redirectUri,
scopes,
state: optionalString(params.state, 'state', 1024),
codeChallenge: params.code_challenge,
codeChallengeMethod: 'S256',
resource,
};
}
export async function issueAuthorizationCode(
request: ValidatedAuthorizationRequest,
userId: string,
) {
const code = generateAuthorizationCode();
await createAuthorizationCode({
id: uuid(),
codeHash: hashToken(code),
userId,
clientId: request.client.clientId,
redirectUri: request.redirectUri,
scope: request.scopes.join(' '),
resource: request.resource,
codeChallenge: request.codeChallenge,
codeChallengeMethod: request.codeChallengeMethod,
expiresAt: new Date(Date.now() + AUTHORIZATION_CODE_TTL_SECONDS * 1000),
});
return code;
}
export function buildSuccessRedirect(
request: Pick<ValidatedAuthorizationRequest, 'redirectUri' | 'state'>,
code: string,
issuer: string,
) {
return appendRedirectParams(request.redirectUri, { code, state: request.state, iss: issuer });
}
export function buildErrorRedirect(
redirectUri: string,
error: OAuthError,
state: string | undefined,
issuer: string,
) {
return appendRedirectParams(redirectUri, {
error: error.code,
error_description: error.message,
state,
iss: issuer,
});
}
-152
View File
@@ -1,152 +0,0 @@
import { beforeEach, describe, expect, test, vi } from 'vitest';
import { getOauthClient } from '@/queries/prisma/oauth';
import {
clearClientMetadataCache,
fetchClientMetadata,
isClientMetadataUrl,
resolveOAuthClient,
validateClientMetadata,
} from './client';
vi.mock('@/lib/redis', () => ({
default: { enabled: false, client: { get: vi.fn(), set: vi.fn() } },
}));
vi.mock('@/queries/prisma/oauth', () => ({
getOauthClient: vi.fn(),
}));
const getOauthClientMock = vi.mocked(getOauthClient);
const CLIENT_ID = 'https://app.example.com/oauth/client.json';
const validDocument = {
client_id: CLIENT_ID,
client_name: 'Example MCP Client',
client_uri: 'https://app.example.com',
redirect_uris: ['http://127.0.0.1:3000/callback', 'https://app.example.com/callback'],
token_endpoint_auth_method: 'none',
};
beforeEach(() => {
clearClientMetadataCache();
getOauthClientMock.mockReset();
});
describe('isClientMetadataUrl', () => {
test('requires https, a path and a public host', () => {
expect(isClientMetadataUrl(CLIENT_ID)).toBe(true);
expect(isClientMetadataUrl('https://app.example.com')).toBe(false);
expect(isClientMetadataUrl('https://app.example.com/')).toBe(false);
expect(isClientMetadataUrl('http://app.example.com/client.json')).toBe(false);
expect(isClientMetadataUrl('https://localhost/client.json')).toBe(false);
expect(isClientMetadataUrl('https://10.0.0.1/client.json')).toBe(false);
expect(isClientMetadataUrl('https://user:pw@app.example.com/client.json')).toBe(false);
expect(isClientMetadataUrl('not-a-url')).toBe(false);
});
});
describe('validateClientMetadata', () => {
test('accepts a valid document', () => {
expect(validateClientMetadata(CLIENT_ID, validDocument)).toMatchObject({
clientId: CLIENT_ID,
clientName: 'Example MCP Client',
redirectUris: validDocument.redirect_uris,
source: 'metadata-document',
});
});
test('rejects mismatched client_id', () => {
expect(() =>
validateClientMetadata(CLIENT_ID, { ...validDocument, client_id: 'https://other/x.json' }),
).toThrow(/does not match/);
});
test('rejects missing or invalid redirect URIs and names', () => {
expect(() =>
validateClientMetadata(CLIENT_ID, { ...validDocument, redirect_uris: [] }),
).toThrow(/redirect_uris/);
expect(() =>
validateClientMetadata(CLIENT_ID, {
...validDocument,
redirect_uris: ['http://app.example.com/cb'],
}),
).toThrow(/redirect_uris/);
expect(() =>
validateClientMetadata(CLIENT_ID, { ...validDocument, client_name: undefined }),
).toThrow(/client_name/);
});
test('rejects confidential clients', () => {
expect(() =>
validateClientMetadata(CLIENT_ID, {
...validDocument,
token_endpoint_auth_method: 'client_secret_basic',
}),
).toThrow(/public clients/);
});
});
describe('fetchClientMetadata', () => {
test('fetches and validates the document', async () => {
const fetchImpl = vi.fn(async () => Response.json(validDocument));
const client = await fetchClientMetadata(CLIENT_ID, fetchImpl);
expect(client.clientName).toBe('Example MCP Client');
expect(fetchImpl).toHaveBeenCalledWith(
CLIENT_ID,
expect.objectContaining({ method: 'GET', redirect: 'error' }),
);
});
test('maps fetch failures to invalid_client', async () => {
await expect(
fetchClientMetadata(CLIENT_ID, async () => new Response('nope', { status: 404 })),
).rejects.toMatchObject({ code: 'invalid_client' });
await expect(
fetchClientMetadata(CLIENT_ID, async () => new Response('{bad json')),
).rejects.toMatchObject({ code: 'invalid_client_metadata' });
await expect(
fetchClientMetadata(CLIENT_ID, async () => {
throw new TypeError('fetch failed');
}),
).rejects.toMatchObject({ code: 'invalid_client' });
});
});
describe('resolveOAuthClient', () => {
test('caches metadata documents', async () => {
const fetchImpl = vi.fn(async () => Response.json(validDocument));
await resolveOAuthClient(CLIENT_ID, { fetch: fetchImpl });
await resolveOAuthClient(CLIENT_ID, { fetch: fetchImpl });
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
test('resolves registered clients from the database', async () => {
getOauthClientMock.mockResolvedValue({
id: 'registered-1',
name: 'Registered',
redirectUris: ['https://a.example/cb'],
metadata: { client_uri: 'https://a.example' },
createdAt: new Date(),
} as never);
await expect(resolveOAuthClient('registered-1')).resolves.toMatchObject({
clientId: 'registered-1',
clientName: 'Registered',
clientUri: 'https://a.example',
source: 'registered',
});
});
test('rejects unknown and malformed client ids', async () => {
getOauthClientMock.mockResolvedValue(null);
await expect(resolveOAuthClient('missing')).rejects.toMatchObject({ code: 'invalid_client' });
await expect(resolveOAuthClient('http://insecure.example/x.json')).rejects.toMatchObject({
code: 'invalid_client',
});
await expect(resolveOAuthClient('')).rejects.toMatchObject({ code: 'invalid_client' });
});
});
-339
View File
@@ -1,339 +0,0 @@
import { lookup } from 'node:dns';
import { Agent } from 'node:https';
import debug from 'debug';
import ipaddr from 'ipaddr.js';
import nodeFetch from 'node-fetch';
import { CLIENT_METADATA_CACHE_SECONDS } from '@/lib/oauth/config';
import { OAuthError } from '@/lib/oauth/errors';
import { isAcceptableRedirectUri, parseUrl } from '@/lib/oauth/redirect';
import redis from '@/lib/redis';
import { getOauthClient } from '@/queries/prisma/oauth';
const log = debug('umami:oauth');
const METADATA_FETCH_TIMEOUT_MS = 5000;
const METADATA_MAX_BYTES = 64 * 1024;
const MAX_REDIRECT_URIS = 20;
const metadataAgent = new Agent({
keepAlive: false,
lookup(hostname, options, callback) {
// Validate the actual socket lookup, then connect only to those addresses. A separate
// preflight lookup would let a rebinding hostname return a private IP on the next lookup.
lookup(hostname, { all: true }, (error, addresses) => {
if (error) {
callback(error, '', 0);
return;
}
if (
!addresses.length ||
addresses.some(({ address }) => ipaddr.parse(address).range() !== 'unicast')
) {
callback(new Error('Client metadata must resolve only to public addresses.'), '', 0);
return;
}
const destinations = options.family
? addresses.filter(({ family }) => family === options.family)
: addresses;
if (!destinations.length) {
callback(new Error('No public address found for the requested address family.'), '', 0);
} else if (options.all) {
callback(null, destinations);
} else {
callback(null, destinations[0].address, destinations[0].family);
}
});
},
});
export interface ResolvedOAuthClient {
clientId: string;
clientName: string;
clientUri?: string;
logoUri?: string;
redirectUris: string[];
source: 'metadata-document' | 'registered';
}
interface ClientMetadataDocument {
client_id?: unknown;
client_name?: unknown;
client_uri?: unknown;
logo_uri?: unknown;
redirect_uris?: unknown;
token_endpoint_auth_method?: unknown;
}
const memoryCache = new Map<string, { value: ResolvedOAuthClient; expiresAt: number }>();
function isPrivateHostname(hostname: string) {
const host = hostname.toLowerCase();
if (host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local')) {
return true;
}
// IPv6 literal
if (host.startsWith('[')) {
return true;
}
// IPv4 literal: block entirely; metadata documents must be served from a DNS name.
if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) {
return true;
}
return false;
}
/**
* A Client ID Metadata Document identifier is an https URL with a non-root path.
* (draft-ietf-oauth-client-id-metadata-document)
*/
export function isClientMetadataUrl(clientId: string) {
const url = parseUrl(clientId);
return (
!!url &&
url.protocol === 'https:' &&
url.pathname !== '/' &&
url.pathname.length > 1 &&
!url.hash &&
!url.username &&
!url.password &&
!isPrivateHostname(url.hostname)
);
}
function parseRedirectUris(value: unknown) {
if (!Array.isArray(value) || !value.length || value.length > MAX_REDIRECT_URIS) {
return null;
}
const uris = value.filter((uri): uri is string => typeof uri === 'string');
if (uris.length !== value.length || !uris.every(isAcceptableRedirectUri)) {
return null;
}
return uris;
}
function asString(value: unknown, max = 255) {
return typeof value === 'string' && value.length <= max ? value : undefined;
}
export function validateClientMetadata(
clientId: string,
document: ClientMetadataDocument,
): ResolvedOAuthClient {
if (document.client_id !== clientId) {
throw new OAuthError(
'invalid_client_metadata',
'client_id in the metadata document does not match the document URL.',
);
}
const redirectUris = parseRedirectUris(document.redirect_uris);
if (!redirectUris) {
throw new OAuthError(
'invalid_client_metadata',
'redirect_uris must be a non-empty list of absolute https, loopback or custom-scheme URLs.',
);
}
const clientName = asString(document.client_name);
if (!clientName) {
throw new OAuthError('invalid_client_metadata', 'client_name is required.');
}
if (
document.token_endpoint_auth_method !== undefined &&
document.token_endpoint_auth_method !== 'none'
) {
throw new OAuthError(
'invalid_client_metadata',
'Only public clients (token_endpoint_auth_method "none") are supported.',
);
}
return {
clientId,
clientName,
clientUri: asString(document.client_uri, 2048),
logoUri: asString(document.logo_uri, 2048),
redirectUris,
source: 'metadata-document',
};
}
async function readCache(clientId: string): Promise<ResolvedOAuthClient | null> {
if (redis.enabled) {
return (await redis.client.get(`oauth:client:${clientId}`)) ?? null;
}
const entry = memoryCache.get(clientId);
if (entry && entry.expiresAt > Date.now()) {
return entry.value;
}
memoryCache.delete(clientId);
return null;
}
async function writeCache(clientId: string, value: ResolvedOAuthClient) {
if (redis.enabled) {
await redis.client.set(`oauth:client:${clientId}`, value, CLIENT_METADATA_CACHE_SECONDS);
return;
}
memoryCache.set(clientId, {
value,
expiresAt: Date.now() + CLIENT_METADATA_CACHE_SECONDS * 1000,
});
}
export type MetadataFetch = (
url: string,
init: RequestInit,
) => Promise<Pick<Response, 'ok' | 'status' | 'text'>>;
const fetchPublicMetadata: MetadataFetch = (url, init) =>
nodeFetch(url, {
method: 'GET',
headers: { accept: 'application/json' },
redirect: 'error',
signal: init.signal,
agent: metadataAgent,
size: METADATA_MAX_BYTES,
});
export async function fetchClientMetadata(
clientId: string,
fetchImpl: MetadataFetch = fetchPublicMetadata,
): Promise<ResolvedOAuthClient> {
if (!isClientMetadataUrl(clientId)) {
throw new OAuthError(
'invalid_client',
'Client metadata must use a public https URL with a path.',
);
}
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), METADATA_FETCH_TIMEOUT_MS);
try {
const response = await fetchImpl(clientId, {
method: 'GET',
headers: { accept: 'application/json' },
redirect: 'error',
signal: controller.signal,
});
if (!response.ok) {
throw new OAuthError(
'invalid_client',
`Could not fetch client metadata document (${response.status}).`,
);
}
const text = await response.text();
if (Buffer.byteLength(text, 'utf8') > METADATA_MAX_BYTES) {
throw new OAuthError('invalid_client_metadata', 'Client metadata document is too large.');
}
let document: ClientMetadataDocument;
try {
document = JSON.parse(text);
} catch {
throw new OAuthError('invalid_client_metadata', 'Client metadata document is not JSON.');
}
if (!document || typeof document !== 'object' || Array.isArray(document)) {
throw new OAuthError('invalid_client_metadata', 'Client metadata document is not an object.');
}
return validateClientMetadata(clientId, document);
} catch (error) {
if (error instanceof OAuthError) {
throw error;
}
log('client metadata fetch failed', error);
throw new OAuthError('invalid_client', 'Could not fetch client metadata document.');
} finally {
clearTimeout(timer);
controller.abort();
}
}
/**
* Resolves a client by ID. URL-shaped IDs are Client ID Metadata Documents (fetched and cached);
* anything else must be a client registered through dynamic registration.
*/
export async function resolveOAuthClient(
clientId: unknown,
options: { fetch?: MetadataFetch } = {},
): Promise<ResolvedOAuthClient> {
if (typeof clientId !== 'string' || !clientId || clientId.length > 2048) {
throw new OAuthError('invalid_client', 'client_id is required.');
}
if (isClientMetadataUrl(clientId)) {
const cached = await readCache(clientId);
if (cached) {
return cached;
}
const client = await fetchClientMetadata(clientId, options.fetch);
await writeCache(clientId, client);
return client;
}
if (clientId.startsWith('http://') || clientId.startsWith('https://')) {
throw new OAuthError(
'invalid_client',
'client_id URLs must use https, include a path and not point at a private host.',
);
}
const registered = await getOauthClient(clientId);
if (!registered) {
throw new OAuthError('invalid_client', 'Unknown client_id.');
}
const redirectUris = parseRedirectUris(registered.redirectUris);
if (!redirectUris) {
throw new OAuthError('invalid_client', 'Registered client has no valid redirect URIs.');
}
const metadata = (registered.metadata ?? {}) as Record<string, unknown>;
return {
clientId: registered.id,
clientName: registered.name,
clientUri: asString(metadata.client_uri, 2048),
logoUri: asString(metadata.logo_uri, 2048),
redirectUris,
source: 'registered',
};
}
export function clearClientMetadataCache() {
memoryCache.clear();
}
-96
View File
@@ -1,96 +0,0 @@
import { getBaseUrl } from '@/lib/get-base-url';
/** Authorization codes are single-use and short-lived (OAuth 2.1 recommends ≤ 10 minutes). */
export const AUTHORIZATION_CODE_TTL_SECONDS = 10 * 60;
/** Access tokens are short-lived JWTs; refresh tokens carry long-lived sessions. */
export const ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
export const REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
/** Cache lifetime for fetched Client ID Metadata Documents. */
export const CLIENT_METADATA_CACHE_SECONDS = 60 * 60;
export const OAUTH_ACCESS_TOKEN_TYPE = 'oauth_access';
export const REFRESH_TOKEN_PREFIX = 'umami_rt_';
export const MCP_RESOURCE_PATH = '/mcp';
export function isOAuthEnabled() {
return process.env.OAUTH_DISABLED !== '1' && !process.env.DISABLE_LOGIN;
}
export function isDynamicRegistrationEnabled() {
return isOAuthEnabled() && process.env.OAUTH_DISABLE_DCR !== '1';
}
function trimTrailingSlash(value: string) {
return value.replace(/\/+$/, '');
}
/**
* The OAuth issuer identifier: the public base URL of this Umami instance (including any
* BASE_PATH). Can be pinned with `OAUTH_ISSUER` for deployments behind proxies that do not
* forward host headers.
*/
export function getIssuer(headers?: Pick<Headers, 'get'>) {
const configured = process.env.OAUTH_ISSUER?.trim();
if (configured) {
return trimTrailingSlash(configured);
}
const base = trimTrailingSlash(getBaseUrl(headers).toString());
const basePath = trimTrailingSlash(process.env.BASE_PATH ?? '');
return `${base}${basePath}`;
}
/** Canonical resource identifier for the embedded MCP server (RFC 8707). */
export function getMcpResource(issuer: string) {
return `${trimTrailingSlash(issuer)}${MCP_RESOURCE_PATH}`;
}
export interface OAuthEndpoints {
issuer: string;
resource: string;
authorizationEndpoint: string;
tokenEndpoint: string;
revocationEndpoint: string;
registrationEndpoint?: string;
authorizationServerMetadata: string;
protectedResourceMetadata: string;
}
export function getOAuthEndpoints(headers?: Pick<Headers, 'get'>): OAuthEndpoints {
const issuer = getIssuer(headers);
return {
issuer,
resource: getMcpResource(issuer),
authorizationEndpoint: `${issuer}/oauth/authorize`,
tokenEndpoint: `${issuer}/api/oauth/token`,
revocationEndpoint: `${issuer}/api/oauth/revoke`,
registrationEndpoint: isDynamicRegistrationEnabled()
? `${issuer}/api/oauth/register`
: undefined,
authorizationServerMetadata: `${issuer}/.well-known/oauth-authorization-server`,
protectedResourceMetadata: `${issuer}/.well-known/oauth-protected-resource${MCP_RESOURCE_PATH}`,
};
}
/**
* Normalizes a resource indicator for comparison: lowercase scheme/host, no trailing slash,
* no fragment.
*/
export function normalizeResource(value: string) {
try {
const url = new URL(value);
if (url.hash) {
return null;
}
url.hash = '';
return trimTrailingSlash(url.toString());
} catch {
return null;
}
}
-88
View File
@@ -1,88 +0,0 @@
export type OAuthErrorCode =
| 'invalid_request'
| 'invalid_client'
| 'invalid_grant'
| 'unauthorized_client'
| 'unsupported_grant_type'
| 'unsupported_response_type'
| 'invalid_scope'
| 'invalid_target'
| 'access_denied'
| 'server_error'
| 'temporarily_unavailable'
| 'invalid_client_metadata'
| 'invalid_redirect_uri';
export class OAuthError extends Error {
readonly code: OAuthErrorCode;
readonly status: number;
/** When true the error may be delivered to the (validated) redirect URI. */
readonly redirectable: boolean;
constructor(
code: OAuthErrorCode,
description: string,
options: { status?: number; redirectable?: boolean } = {},
) {
super(description);
this.name = 'OAuthError';
this.code = code;
this.status = options.status ?? defaultStatus(code);
this.redirectable = options.redirectable ?? false;
}
toJSON() {
return { error: this.code, error_description: this.message };
}
}
function defaultStatus(code: OAuthErrorCode) {
switch (code) {
case 'invalid_client':
return 401;
case 'server_error':
return 500;
case 'temporarily_unavailable':
return 503;
default:
return 400;
}
}
export function isOAuthError(error: unknown): error is OAuthError {
return error instanceof OAuthError || (error as { name?: string })?.name === 'OAuthError';
}
const NO_STORE = { 'cache-control': 'no-store', pragma: 'no-cache' };
export function oauthJson(body: unknown, init: ResponseInit = {}) {
return Response.json(body, {
...init,
headers: { ...NO_STORE, ...(init.headers as Record<string, string>) },
});
}
export function oauthErrorResponse(error: unknown) {
if (isOAuthError(error)) {
const headers: Record<string, string> = {};
if (error.status === 401) {
headers['www-authenticate'] = `Bearer error="${error.code}"`;
}
return oauthJson(error.toJSON(), { status: error.status, headers });
}
return oauthJson(
{ error: 'server_error', error_description: 'Unexpected error.' },
{ status: 500 },
);
}
export function toOAuthError(error: unknown, fallback: OAuthErrorCode = 'server_error') {
if (isOAuthError(error)) {
return error;
}
return new OAuthError(fallback, 'Unexpected error.');
}
-29
View File
@@ -1,29 +0,0 @@
/**
* OAuth token/revocation/registration endpoints accept `application/x-www-form-urlencoded`
* (per RFC 6749) and, for convenience, JSON.
*/
export async function readOAuthBody(request: Request): Promise<Record<string, unknown>> {
const contentType = request.headers.get('content-type') ?? '';
try {
if (contentType.includes('application/json')) {
const body = await request.json();
return body && typeof body === 'object' && !Array.isArray(body) ? body : {};
}
const text = await request.text();
const params = new URLSearchParams(text);
const result: Record<string, unknown> = {};
for (const [key, value] of params) {
if (!(key in result)) {
result[key] = value;
}
}
return result;
} catch {
return {};
}
}
-12
View File
@@ -1,12 +0,0 @@
export * from './authorize';
export * from './client';
export * from './config';
export * from './errors';
export * from './form';
export * from './metadata';
export * from './pkce';
export * from './redirect';
export * from './scopes';
export * from './token';
export * from './tokens';
export * from './verify';
-64
View File
@@ -1,64 +0,0 @@
import { getOAuthEndpoints } from '@/lib/oauth/config';
import { OAUTH_SCOPES } from '@/lib/oauth/scopes';
/** RFC 8414 Authorization Server Metadata. */
export function buildAuthorizationServerMetadata(headers?: Pick<Headers, 'get'>) {
const endpoints = getOAuthEndpoints(headers);
return {
issuer: endpoints.issuer,
authorization_endpoint: endpoints.authorizationEndpoint,
token_endpoint: endpoints.tokenEndpoint,
revocation_endpoint: endpoints.revocationEndpoint,
...(endpoints.registrationEndpoint
? { registration_endpoint: endpoints.registrationEndpoint }
: {}),
response_types_supported: ['code'],
response_modes_supported: ['query'],
grant_types_supported: ['authorization_code', 'refresh_token'],
code_challenge_methods_supported: ['S256'],
token_endpoint_auth_methods_supported: ['none'],
revocation_endpoint_auth_methods_supported: ['none'],
scopes_supported: [...OAUTH_SCOPES],
authorization_response_iss_parameter_supported: true,
client_id_metadata_document_supported: true,
service_documentation: 'https://umami.is/docs/mcp',
};
}
/** RFC 9728 Protected Resource Metadata for the embedded MCP server. */
export function buildProtectedResourceMetadata(headers?: Pick<Headers, 'get'>) {
const endpoints = getOAuthEndpoints(headers);
return {
resource: endpoints.resource,
resource_name: 'Umami MCP',
authorization_servers: [endpoints.issuer],
scopes_supported: [...OAUTH_SCOPES],
bearer_methods_supported: ['header'],
resource_documentation: 'https://umami.is/docs/mcp',
};
}
export function metadataResponse(body: unknown) {
return Response.json(body, {
headers: {
'cache-control': 'public, max-age=300',
'access-control-allow-origin': '*',
'access-control-allow-methods': 'GET, OPTIONS',
'access-control-allow-headers': '*',
},
});
}
export function corsPreflight() {
return new Response(null, {
status: 204,
headers: {
'access-control-allow-origin': '*',
'access-control-allow-methods': 'GET, POST, OPTIONS',
'access-control-allow-headers': '*',
'access-control-max-age': '86400',
},
});
}
-40
View File
@@ -1,40 +0,0 @@
import { describe, expect, test } from 'vitest';
import {
computeCodeChallenge,
generateSecret,
isValidCodeChallenge,
isValidCodeVerifier,
verifyPkce,
} from './pkce';
// RFC 7636 Appendix B test vector.
const VERIFIER = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk';
const CHALLENGE = 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM';
describe('pkce', () => {
test('computes S256 challenges', () => {
expect(computeCodeChallenge(VERIFIER)).toBe(CHALLENGE);
});
test('verifies matching verifiers and rejects mismatches', () => {
expect(verifyPkce(VERIFIER, CHALLENGE, 'S256')).toBe(true);
expect(verifyPkce(`${VERIFIER.slice(0, -1)}x`, CHALLENGE, 'S256')).toBe(false);
expect(verifyPkce(VERIFIER, CHALLENGE, 'plain')).toBe(false);
expect(verifyPkce(undefined, CHALLENGE, 'S256')).toBe(false);
});
test('validates verifier and challenge formats', () => {
expect(isValidCodeVerifier(VERIFIER)).toBe(true);
expect(isValidCodeVerifier('short')).toBe(false);
expect(isValidCodeChallenge(CHALLENGE)).toBe(true);
expect(isValidCodeChallenge('not base64url!')).toBe(false);
});
test('generates URL-safe secrets', () => {
const secret = generateSecret();
expect(secret).toMatch(/^[A-Za-z0-9_-]+$/);
expect(secret.length).toBeGreaterThanOrEqual(43);
expect(generateSecret()).not.toBe(secret);
});
});
-39
View File
@@ -1,39 +0,0 @@
import crypto from 'node:crypto';
export const PKCE_METHODS = ['S256'] as const;
export type PkceMethod = (typeof PKCE_METHODS)[number];
const VERIFIER_PATTERN = /^[A-Za-z0-9\-._~]{43,128}$/;
const CHALLENGE_PATTERN = /^[A-Za-z0-9\-_]{43}$/;
export function isPkceMethod(value: unknown): value is PkceMethod {
return typeof value === 'string' && (PKCE_METHODS as readonly string[]).includes(value);
}
export function isValidCodeChallenge(value: unknown): value is string {
return typeof value === 'string' && CHALLENGE_PATTERN.test(value);
}
export function isValidCodeVerifier(value: unknown): value is string {
return typeof value === 'string' && VERIFIER_PATTERN.test(value);
}
export function computeCodeChallenge(verifier: string) {
return crypto.createHash('sha256').update(verifier, 'ascii').digest('base64url');
}
export function verifyPkce(verifier: unknown, challenge: string, method: string) {
if (method !== 'S256' || !isValidCodeVerifier(verifier)) {
return false;
}
const expected = Buffer.from(challenge);
const actual = Buffer.from(computeCodeChallenge(verifier));
return expected.length === actual.length && crypto.timingSafeEqual(expected, actual);
}
/** URL-safe random secret used for authorization codes and refresh tokens. */
export function generateSecret(bytes = 32) {
return crypto.randomBytes(bytes).toString('base64url');
}
-60
View File
@@ -1,60 +0,0 @@
import { describe, expect, test } from 'vitest';
import {
appendRedirectParams,
findMatchingRedirectUri,
isAcceptableRedirectUri,
redirectUriMatches,
} from './redirect';
describe('redirect URIs', () => {
test('accepts https, loopback http and custom schemes', () => {
expect(isAcceptableRedirectUri('https://app.example/callback')).toBe(true);
expect(isAcceptableRedirectUri('http://127.0.0.1:3000/callback')).toBe(true);
expect(isAcceptableRedirectUri('http://localhost/callback')).toBe(true);
expect(isAcceptableRedirectUri('myapp://callback')).toBe(true);
});
test('rejects non-loopback http, fragments and garbage', () => {
expect(isAcceptableRedirectUri('http://app.example/callback')).toBe(false);
expect(isAcceptableRedirectUri('https://app.example/callback#x')).toBe(false);
expect(isAcceptableRedirectUri('not a url')).toBe(false);
expect(isAcceptableRedirectUri(undefined)).toBe(false);
});
test('matches exactly, except loopback ports may vary', () => {
expect(redirectUriMatches('https://a.example/cb', 'https://a.example/cb')).toBe(true);
expect(redirectUriMatches('https://a.example/cb/', 'https://a.example/cb')).toBe(false);
expect(redirectUriMatches('https://a.example/cb?x=1', 'https://a.example/cb')).toBe(false);
expect(redirectUriMatches('http://127.0.0.1:51234/cb', 'http://127.0.0.1:3000/cb')).toBe(true);
expect(redirectUriMatches('http://localhost:51234/cb', 'http://localhost/cb')).toBe(true);
expect(redirectUriMatches('http://127.0.0.1:51234/other', 'http://127.0.0.1:3000/cb')).toBe(
false,
);
expect(redirectUriMatches('http://localhost:1/cb', 'http://127.0.0.1:1/cb')).toBe(false);
});
test('finds the registered match', () => {
expect(
findMatchingRedirectUri('http://127.0.0.1:9999/cb', [
'https://a.example/cb',
'http://127.0.0.1:1/cb',
]),
).toBe('http://127.0.0.1:1/cb');
expect(findMatchingRedirectUri('https://evil.example/cb', ['https://a.example/cb'])).toBeNull();
});
test('appends parameters without dropping existing ones', () => {
const url = new URL(
appendRedirectParams('https://a.example/cb?keep=1', {
code: 'c',
state: undefined,
iss: 'i',
}),
);
expect(url.searchParams.get('keep')).toBe('1');
expect(url.searchParams.get('code')).toBe('c');
expect(url.searchParams.get('iss')).toBe('i');
expect(url.searchParams.has('state')).toBe(false);
});
});
-77
View File
@@ -1,77 +0,0 @@
const LOOPBACK_HOSTS = new Set(['127.0.0.1', '[::1]', 'localhost']);
export function parseUrl(value: unknown): URL | null {
if (typeof value !== 'string' || !value) {
return null;
}
try {
return new URL(value);
} catch {
return null;
}
}
export function isLoopbackUrl(url: URL) {
return url.protocol === 'http:' && LOOPBACK_HOSTS.has(url.hostname);
}
/**
* Redirect URIs must be valid absolute URLs without fragments. Non-loopback `http` is rejected;
* custom schemes (native apps) and `https` are accepted.
*/
export function isAcceptableRedirectUri(value: unknown) {
const url = parseUrl(value);
if (!url || url.hash) {
return false;
}
if (url.protocol === 'http:') {
return isLoopbackUrl(url);
}
return true;
}
/**
* Exact string comparison, except that loopback redirect URIs may vary the port
* (RFC 8252 §7.3), since native clients bind an ephemeral port per authorization.
*/
export function redirectUriMatches(candidate: string, registered: string) {
if (candidate === registered) {
return true;
}
const left = parseUrl(candidate);
const right = parseUrl(registered);
if (!left || !right || !isLoopbackUrl(left) || !isLoopbackUrl(right)) {
return false;
}
return (
left.hostname === right.hostname &&
left.pathname === right.pathname &&
left.search === right.search
);
}
export function findMatchingRedirectUri(candidate: string, registered: readonly string[]) {
return registered.find(uri => redirectUriMatches(candidate, uri)) ?? null;
}
export function appendRedirectParams(
redirectUri: string,
params: Record<string, string | undefined>,
) {
const url = new URL(redirectUri);
for (const [key, value] of Object.entries(params)) {
if (value !== undefined) {
url.searchParams.set(key, value);
}
}
return url.toString();
}
-6
View File
@@ -1,6 +0,0 @@
/**
* Replay detection for authorization codes lives in `consumeAuthorizationCode`
* (`src/queries/prisma/oauth.ts`): a second redemption returns the original grant so that every
* refresh token issued from it can be revoked (OAuth 2.1 §4.1.2).
*/
export {};
-65
View File
@@ -1,65 +0,0 @@
import { describe, expect, test } from 'vitest';
import {
getContractOAuthScope,
getRouteOAuthScope,
hasRequiredScope,
normalizeScopes,
OAUTH_ROUTE_SCOPES,
parseScopes,
} from './scopes';
describe('getRouteOAuthScope', () => {
test('matches concrete paths against parameterized routes', () => {
expect(
getRouteOAuthScope('GET', '/api/websites/6f2a7e0e-2b0f-4b3f-9f0a-1234567890ab/stats'),
).toBe('analytics:read');
expect(getRouteOAuthScope('get', '/api/websites')).toBe('websites:read');
expect(getRouteOAuthScope('GET', '/api/websites/abc/sessions/def/activity')).toBe(
'analytics:read',
);
});
test('ignores a base path prefix', () => {
expect(getRouteOAuthScope('GET', '/umami/api/websites')).toBe('websites:read');
});
test('rejects routes that are not allowlisted', () => {
expect(getRouteOAuthScope('POST', '/api/websites')).toBeNull();
expect(getRouteOAuthScope('DELETE', '/api/websites/abc')).toBeNull();
expect(getRouteOAuthScope('GET', '/api/admin/users')).toBeNull();
expect(getRouteOAuthScope('GET', '/api/me/api-keys')).toBeNull();
expect(getRouteOAuthScope('POST', '/api/reports')).toBeNull();
});
test('does not match partial segments', () => {
expect(getRouteOAuthScope('GET', '/api/websites/abc/stats/extra')).toBeNull();
expect(getRouteOAuthScope('GET', '/api/websitesX')).toBeNull();
});
});
describe('getContractOAuthScope', () => {
test('looks up contract paths exactly', () => {
expect(getContractOAuthScope('get', '/api/websites/{websiteId}/stats')).toBe('analytics:read');
expect(getContractOAuthScope('post', '/api/websites/{websiteId}')).toBeNull();
});
});
describe('scope helpers', () => {
test('parses and normalizes scope strings', () => {
expect(parseScopes(' analytics:read websites:read ')).toEqual([
'analytics:read',
'websites:read',
]);
expect(normalizeScopes(['websites:read', 'bogus', 'analytics:read', 'websites:read'])).toEqual([
'analytics:read',
'websites:read',
]);
expect(hasRequiredScope(['analytics:read'], 'websites:read')).toBe(false);
});
test('every allowlisted route is unique', () => {
const keys = OAUTH_ROUTE_SCOPES.map(route => `${route.method} ${route.path}`);
expect(new Set(keys).size).toBe(keys.length);
});
});
-159
View File
@@ -1,159 +0,0 @@
/**
* OAuth scopes and the allowlist of API routes that accept OAuth access tokens.
*
* This module is the single source of truth for both:
* - the OpenAPI document (`src/openapi`), which advertises the scope per operation, and
* - runtime enforcement (`src/lib/auth.ts`), which rejects OAuth tokens on routes that
* have not explicitly opted in.
*
* It must remain free of environment-dependent side effects so that it can be imported
* from build scripts.
*/
export const OAUTH_SCOPES = ['websites:read', 'analytics:read'] as const;
export type OAuthScope = (typeof OAUTH_SCOPES)[number];
export const OAUTH_SCOPE_DESCRIPTIONS: Record<OAuthScope, string> = {
'websites:read': 'List and view websites you have access to.',
'analytics:read': 'Read analytics data (traffic, metrics, events, sessions, reports).',
};
export type OAuthHttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
export interface OAuthRouteScope {
method: OAuthHttpMethod;
path: `/api/${string}`;
scope: OAuthScope;
}
/**
* Routes that accept OAuth access tokens, and the scope each one requires.
* Paths use OpenAPI-style `{param}` placeholders and must match a discovered route exactly.
*
* Any route not listed here rejects OAuth authentication. Keep this list limited to what the
* MCP server needs; expanding it is an explicit product decision.
*/
export const OAUTH_ROUTE_SCOPES: readonly OAuthRouteScope[] = [
// Account
{ method: 'get', path: '/api/me', scope: 'websites:read' },
// Websites
{ method: 'get', path: '/api/websites', scope: 'websites:read' },
{ method: 'get', path: '/api/websites/{websiteId}', scope: 'websites:read' },
{ method: 'get', path: '/api/websites/{websiteId}/active', scope: 'analytics:read' },
{ method: 'get', path: '/api/websites/{websiteId}/daterange', scope: 'analytics:read' },
{ method: 'get', path: '/api/websites/{websiteId}/stats', scope: 'analytics:read' },
{ method: 'get', path: '/api/websites/{websiteId}/pageviews', scope: 'analytics:read' },
{ method: 'get', path: '/api/websites/{websiteId}/metrics', scope: 'analytics:read' },
{ method: 'get', path: '/api/websites/{websiteId}/metrics/expanded', scope: 'analytics:read' },
{ method: 'get', path: '/api/realtime/{websiteId}', scope: 'analytics:read' },
// Events
{ method: 'get', path: '/api/websites/{websiteId}/events', scope: 'analytics:read' },
{ method: 'get', path: '/api/websites/{websiteId}/events/stats', scope: 'analytics:read' },
{ method: 'get', path: '/api/websites/{websiteId}/events/series', scope: 'analytics:read' },
{ method: 'get', path: '/api/websites/{websiteId}/event-data', scope: 'analytics:read' },
{ method: 'get', path: '/api/websites/{websiteId}/event-data/stats', scope: 'analytics:read' },
{
method: 'get',
path: '/api/websites/{websiteId}/event-data/properties',
scope: 'analytics:read',
},
{ method: 'get', path: '/api/websites/{websiteId}/event-data/values', scope: 'analytics:read' },
// Sessions
{ method: 'get', path: '/api/websites/{websiteId}/sessions', scope: 'analytics:read' },
{ method: 'get', path: '/api/websites/{websiteId}/sessions/stats', scope: 'analytics:read' },
{
method: 'get',
path: '/api/websites/{websiteId}/sessions/{sessionId}',
scope: 'analytics:read',
},
{
method: 'get',
path: '/api/websites/{websiteId}/sessions/{sessionId}/activity',
scope: 'analytics:read',
},
{
method: 'get',
path: '/api/websites/{websiteId}/sessions/{sessionId}/properties',
scope: 'analytics:read',
},
// Reports (read/query only; saved-report CRUD is intentionally excluded)
{ method: 'post', path: '/api/reports/attribution', scope: 'analytics:read' },
{ method: 'post', path: '/api/reports/breakdown', scope: 'analytics:read' },
{ method: 'post', path: '/api/reports/funnel', scope: 'analytics:read' },
{ method: 'post', path: '/api/reports/journey', scope: 'analytics:read' },
{ method: 'post', path: '/api/reports/retention', scope: 'analytics:read' },
{ method: 'post', path: '/api/reports/revenue', scope: 'analytics:read' },
{ method: 'post', path: '/api/reports/utm', scope: 'analytics:read' },
];
export function isOAuthScope(value: unknown): value is OAuthScope {
return typeof value === 'string' && (OAUTH_SCOPES as readonly string[]).includes(value);
}
export function parseScopes(value?: string | null): string[] {
return (value ?? '')
.split(/[\s,]+/)
.map(scope => scope.trim())
.filter(Boolean);
}
export function normalizeScopes(scopes: string[]): OAuthScope[] {
return [...new Set(scopes.filter(isOAuthScope))].sort() as OAuthScope[];
}
function escapeRegExp(value: string) {
return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}
function toPattern(path: string) {
const source = path
.split('/')
.map(segment => (/^\{[^}]+}$/.test(segment) ? '[^/]+' : escapeRegExp(segment)))
.join('/');
return new RegExp(`^${source}/?$`);
}
const routePatterns = OAUTH_ROUTE_SCOPES.map(route => ({
...route,
pattern: toPattern(route.path),
}));
/**
* Returns the scope required to call the given route with an OAuth token, or `null` when the
* route does not accept OAuth authentication at all.
*
* `pathname` is a concrete request path (e.g. `/api/websites/1234/stats`). Any `BASE_PATH`
* or API URL prefix must be stripped by the caller.
*/
export function getRouteOAuthScope(method: string, pathname: string): OAuthScope | null {
const normalizedMethod = method.toLowerCase();
const apiIndex = pathname.indexOf('/api/');
const apiPath = apiIndex >= 0 ? pathname.slice(apiIndex) : pathname;
for (const route of routePatterns) {
if (route.method === normalizedMethod && route.pattern.test(apiPath)) {
return route.scope;
}
}
return null;
}
export function getContractOAuthScope(method: string, path: string): OAuthScope | null {
const normalizedMethod = method.toLowerCase();
return (
OAUTH_ROUTE_SCOPES.find(route => route.method === normalizedMethod && route.path === path)
?.scope ?? null
);
}
export function hasRequiredScope(granted: readonly string[], required: OAuthScope) {
return granted.includes(required);
}
-302
View File
@@ -1,302 +0,0 @@
import { beforeEach, describe, expect, test, vi } from 'vitest';
import {
consumeAuthorizationCode,
createRefreshToken,
getRefreshTokenByHash,
revokeRefreshToken,
revokeRefreshTokensForClient,
touchRefreshToken,
} from '@/queries/prisma/oauth';
import { getUser } from '@/queries/prisma/user';
import { computeCodeChallenge } from './pkce';
import { handleRevocationRequest, handleTokenRequest } from './token';
import { generateRefreshToken, hashToken, verifyAccessToken } from './tokens';
const { transactionClient } = vi.hoisted(() => ({ transactionClient: {} }));
vi.mock('@/lib/prisma', () => ({
default: {
transaction: vi.fn(async callback => callback(transactionClient)),
},
}));
vi.mock('@/queries/prisma/oauth', () => ({
consumeAuthorizationCode: vi.fn(),
createRefreshToken: vi.fn(),
getRefreshTokenByHash: vi.fn(),
revokeRefreshToken: vi.fn(),
revokeRefreshTokensForClient: vi.fn(),
touchRefreshToken: vi.fn(),
}));
vi.mock('@/queries/prisma/user', () => ({
getUser: vi.fn(),
}));
const consumeAuthorizationCodeMock = vi.mocked(consumeAuthorizationCode);
const createRefreshTokenMock = vi.mocked(createRefreshToken);
const getRefreshTokenByHashMock = vi.mocked(getRefreshTokenByHash);
const revokeRefreshTokenMock = vi.mocked(revokeRefreshToken);
const revokeRefreshTokensForClientMock = vi.mocked(revokeRefreshTokensForClient);
const touchRefreshTokenMock = vi.mocked(touchRefreshToken);
const getUserMock = vi.mocked(getUser);
const ISSUER = 'https://analytics.example.com';
const RESOURCE = `${ISSUER}/mcp`;
const CLIENT_ID = 'https://app.example.com/client.json';
const VERIFIER = 'dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk';
const USER = { id: 'user-1', username: 'admin', role: 'admin', password: 'hashed' };
function codeRecord(overrides: Record<string, unknown> = {}) {
return {
id: 'code-1',
codeHash: 'h',
userId: USER.id,
clientId: CLIENT_ID,
redirectUri: 'https://app.example.com/cb',
scope: 'analytics:read websites:read',
resource: RESOURCE,
codeChallenge: computeCodeChallenge(VERIFIER),
codeChallengeMethod: 'S256',
expiresAt: new Date(Date.now() + 60_000),
usedAt: new Date(),
createdAt: new Date(),
...overrides,
} as never;
}
function grant(overrides: Record<string, unknown> = {}) {
return {
grant_type: 'authorization_code',
code: 'the-code',
client_id: CLIENT_ID,
redirect_uri: 'https://app.example.com/cb',
code_verifier: VERIFIER,
resource: RESOURCE,
...overrides,
};
}
beforeEach(() => {
process.env.APP_SECRET = 'test';
vi.mocked(consumeAuthorizationCodeMock).mockReset();
createRefreshTokenMock.mockReset();
createRefreshTokenMock.mockResolvedValue({} as never);
getRefreshTokenByHashMock.mockReset();
revokeRefreshTokenMock.mockReset();
revokeRefreshTokenMock.mockResolvedValue(1);
revokeRefreshTokensForClientMock.mockReset();
touchRefreshTokenMock.mockReset();
touchRefreshTokenMock.mockResolvedValue({} as never);
getUserMock.mockReset();
getUserMock.mockResolvedValue(USER as never);
});
describe('authorization_code grant', () => {
test('issues access and refresh tokens', async () => {
consumeAuthorizationCodeMock.mockResolvedValue({ code: codeRecord(), replayed: null });
const tokens = await handleTokenRequest(grant(), ISSUER);
expect(tokens).toMatchObject({
token_type: 'Bearer',
expires_in: 3600,
scope: 'analytics:read websites:read',
});
expect(tokens.refresh_token).toMatch(/^umami_rt_/);
expect(verifyAccessToken(tokens.access_token)).toMatchObject({
userId: USER.id,
clientId: CLIENT_ID,
resource: RESOURCE,
});
expect(createRefreshTokenMock).toHaveBeenCalledWith(
expect.objectContaining({
userId: USER.id,
clientId: CLIENT_ID,
tokenHash: hashToken(tokens.refresh_token),
}),
transactionClient,
);
});
test('rejects an invalid PKCE verifier', async () => {
consumeAuthorizationCodeMock.mockResolvedValue({ code: codeRecord(), replayed: null });
await expect(
handleTokenRequest(grant({ code_verifier: `${VERIFIER.slice(0, -1)}x` }), ISSUER),
).rejects.toMatchObject({ code: 'invalid_grant', message: /PKCE/ });
expect(createRefreshTokenMock).not.toHaveBeenCalled();
});
test('rejects client and redirect_uri mismatches', async () => {
consumeAuthorizationCodeMock.mockResolvedValue({ code: codeRecord(), replayed: null });
await expect(
handleTokenRequest(grant({ client_id: 'https://other.example/c.json' }), ISSUER),
).rejects.toMatchObject({ code: 'invalid_grant', message: /client_id/ });
consumeAuthorizationCodeMock.mockResolvedValue({ code: codeRecord(), replayed: null });
await expect(
handleTokenRequest(grant({ redirect_uri: 'https://app.example.com/other' }), ISSUER),
).rejects.toMatchObject({ code: 'invalid_grant', message: /redirect_uri/ });
});
test('rejects expired or unknown codes', async () => {
consumeAuthorizationCodeMock.mockResolvedValue({ code: null, replayed: null });
await expect(handleTokenRequest(grant(), ISSUER)).rejects.toMatchObject({
code: 'invalid_grant',
});
expect(revokeRefreshTokensForClientMock).not.toHaveBeenCalled();
});
test('revokes the grant family when a code is replayed', async () => {
consumeAuthorizationCodeMock.mockResolvedValue({ code: null, replayed: codeRecord() });
await expect(handleTokenRequest(grant(), ISSUER)).rejects.toMatchObject({
code: 'invalid_grant',
});
expect(revokeRefreshTokensForClientMock).toHaveBeenCalledWith(
USER.id,
CLIENT_ID,
transactionClient,
);
});
test('rejects a mismatched resource indicator', async () => {
consumeAuthorizationCodeMock.mockResolvedValue({ code: codeRecord(), replayed: null });
await expect(
handleTokenRequest(grant({ resource: 'https://other.example/mcp' }), ISSUER),
).rejects.toMatchObject({ code: 'invalid_target' });
});
test('requires the required parameters', async () => {
await expect(
handleTokenRequest({ grant_type: 'authorization_code' }, ISSUER),
).rejects.toMatchObject({ code: 'invalid_request' });
await expect(handleTokenRequest({ grant_type: 'password' }, ISSUER)).rejects.toMatchObject({
code: 'unsupported_grant_type',
});
});
});
describe('refresh_token grant', () => {
function refreshRecord(overrides: Record<string, unknown> = {}) {
return {
id: 'rt-1',
tokenHash: 'h',
userId: USER.id,
clientId: CLIENT_ID,
scope: 'analytics:read websites:read',
resource: RESOURCE,
expiresAt: new Date(Date.now() + 60_000),
revokedAt: null,
lastUsedAt: null,
createdAt: new Date(),
...overrides,
} as never;
}
test('rotates the refresh token', async () => {
const presented = generateRefreshToken();
getRefreshTokenByHashMock.mockResolvedValue(refreshRecord());
const tokens = await handleTokenRequest(
{ grant_type: 'refresh_token', refresh_token: presented, client_id: CLIENT_ID },
ISSUER,
);
expect(getRefreshTokenByHashMock).toHaveBeenCalledWith(hashToken(presented));
expect(revokeRefreshTokenMock).toHaveBeenCalledWith('rt-1', transactionClient);
expect(tokens.refresh_token).not.toBe(presented);
expect(tokens.scope).toBe('analytics:read websites:read');
});
test('allows narrowing but not widening scope', async () => {
getRefreshTokenByHashMock.mockResolvedValue(refreshRecord({ scope: 'websites:read' }));
await expect(
handleTokenRequest(
{
grant_type: 'refresh_token',
refresh_token: generateRefreshToken(),
scope: 'analytics:read',
},
ISSUER,
),
).rejects.toMatchObject({ code: 'invalid_scope' });
getRefreshTokenByHashMock.mockResolvedValue(refreshRecord());
const narrowed = await handleTokenRequest(
{
grant_type: 'refresh_token',
refresh_token: generateRefreshToken(),
scope: 'websites:read',
},
ISSUER,
);
expect(narrowed.scope).toBe('websites:read');
});
test('rejects revoked, expired, unknown and concurrently-used tokens', async () => {
getRefreshTokenByHashMock.mockResolvedValue(refreshRecord({ revokedAt: new Date() }));
await expect(
handleTokenRequest(
{ grant_type: 'refresh_token', refresh_token: generateRefreshToken() },
ISSUER,
),
).rejects.toMatchObject({ code: 'invalid_grant' });
getRefreshTokenByHashMock.mockResolvedValue(
refreshRecord({ expiresAt: new Date(Date.now() - 1) }),
);
await expect(
handleTokenRequest(
{ grant_type: 'refresh_token', refresh_token: generateRefreshToken() },
ISSUER,
),
).rejects.toMatchObject({ code: 'invalid_grant' });
getRefreshTokenByHashMock.mockResolvedValue(null);
await expect(
handleTokenRequest(
{ grant_type: 'refresh_token', refresh_token: generateRefreshToken() },
ISSUER,
),
).rejects.toMatchObject({ code: 'invalid_grant' });
getRefreshTokenByHashMock.mockResolvedValue(refreshRecord());
revokeRefreshTokenMock.mockResolvedValue(0);
await expect(
handleTokenRequest(
{ grant_type: 'refresh_token', refresh_token: generateRefreshToken() },
ISSUER,
),
).rejects.toMatchObject({ code: 'invalid_grant', message: /already been used/ });
});
test('rejects a client mismatch', async () => {
getRefreshTokenByHashMock.mockResolvedValue(refreshRecord());
await expect(
handleTokenRequest(
{ grant_type: 'refresh_token', refresh_token: generateRefreshToken(), client_id: 'other' },
ISSUER,
),
).rejects.toMatchObject({ code: 'invalid_grant' });
});
});
describe('revocation', () => {
test('revokes known refresh tokens and ignores everything else', async () => {
getRefreshTokenByHashMock.mockResolvedValue({ id: 'rt-1', revokedAt: null } as never);
await handleRevocationRequest({ token: generateRefreshToken() });
expect(revokeRefreshTokenMock).toHaveBeenCalledWith('rt-1');
revokeRefreshTokenMock.mockClear();
await handleRevocationRequest({ token: 'not-a-refresh-token' });
await handleRevocationRequest({ token: undefined });
expect(revokeRefreshTokenMock).not.toHaveBeenCalled();
});
});
-272
View File
@@ -1,272 +0,0 @@
import type { Prisma } from '@/generated/prisma/client';
import { uuid } from '@/lib/crypto';
import { getMcpResource, normalizeResource, REFRESH_TOKEN_TTL_SECONDS } from '@/lib/oauth/config';
import { OAuthError } from '@/lib/oauth/errors';
import { verifyPkce } from '@/lib/oauth/pkce';
import { normalizeScopes, parseScopes } from '@/lib/oauth/scopes';
import {
createAccessToken,
generateRefreshToken,
hashToken,
isRefreshToken,
} from '@/lib/oauth/tokens';
import prisma from '@/lib/prisma';
import {
consumeAuthorizationCode,
createRefreshToken,
getRefreshTokenByHash,
revokeRefreshToken,
revokeRefreshTokensForClient,
touchRefreshToken,
} from '@/queries/prisma/oauth';
import { getUser } from '@/queries/prisma/user';
const transaction = prisma.transaction as <T>(
callback: (tx: Prisma.TransactionClient) => Promise<T>,
) => Promise<T>;
export interface TokenRequestParams {
grant_type?: unknown;
code?: unknown;
redirect_uri?: unknown;
client_id?: unknown;
code_verifier?: unknown;
refresh_token?: unknown;
scope?: unknown;
resource?: unknown;
}
export interface TokenResponse {
access_token: string;
token_type: 'Bearer';
expires_in: number;
refresh_token: string;
scope: string;
}
function requireString(value: unknown, name: string, max = 4096) {
if (typeof value !== 'string' || !value || value.length > max) {
throw new OAuthError('invalid_request', `${name} is required.`);
}
return value;
}
async function loadUser(userId: string) {
const user = (await getUser(userId, { includePassword: true })) as {
id: string;
password?: string;
deletedAt?: Date | null;
} | null;
if (!user?.id || user.deletedAt) {
throw new OAuthError('invalid_grant', 'The user account is no longer available.');
}
return user;
}
async function issueTokens(
options: {
userId: string;
clientId: string;
scopes: string[];
resource: string;
issuer: string;
passwordHash?: string;
},
tx: Prisma.TransactionClient,
): Promise<TokenResponse> {
const scopes = normalizeScopes(options.scopes);
const access = createAccessToken({
userId: options.userId,
clientId: options.clientId,
scopes,
issuer: options.issuer,
resource: options.resource,
passwordHash: options.passwordHash,
});
const refreshToken = generateRefreshToken();
await createRefreshToken(
{
id: uuid(),
tokenHash: hashToken(refreshToken),
userId: options.userId,
clientId: options.clientId,
scope: scopes.join(' '),
resource: options.resource,
expiresAt: new Date(Date.now() + REFRESH_TOKEN_TTL_SECONDS * 1000),
},
tx,
);
return {
access_token: access.token,
token_type: 'Bearer',
expires_in: access.expiresIn,
refresh_token: refreshToken,
scope: scopes.join(' '),
};
}
export async function handleAuthorizationCodeGrant(
params: TokenRequestParams,
issuer: string,
): Promise<TokenResponse> {
const code = requireString(params.code, 'code', 512);
const clientId = requireString(params.client_id, 'client_id', 2048);
const codeVerifier = requireString(params.code_verifier, 'code_verifier', 128);
const result = await transaction(async tx => {
const { code: record, replayed } = await consumeAuthorizationCode(hashToken(code), tx);
if (!record) {
if (replayed) {
// Replay of a redeemed code: revoke everything that code produced (OAuth 2.1 §4.1.2).
await revokeRefreshTokensForClient(replayed.userId, replayed.clientId, tx);
}
// Return the error so replay revocations commit before the request is rejected.
return new OAuthError(
'invalid_grant',
'Authorization code is invalid, expired or already used.',
);
}
if (record.clientId !== clientId) {
throw new OAuthError('invalid_grant', 'client_id does not match the authorization code.');
}
const redirectUri = typeof params.redirect_uri === 'string' ? params.redirect_uri : undefined;
if (redirectUri !== undefined && redirectUri !== record.redirectUri) {
throw new OAuthError(
'invalid_grant',
'redirect_uri does not match the authorization request.',
);
}
if (!verifyPkce(codeVerifier, record.codeChallenge, record.codeChallengeMethod)) {
throw new OAuthError('invalid_grant', 'PKCE verification failed.');
}
const expectedResource = record.resource ?? getMcpResource(issuer);
const resourceParam =
typeof params.resource === 'string' ? normalizeResource(params.resource) : null;
if (params.resource !== undefined && resourceParam !== expectedResource) {
throw new OAuthError('invalid_target', `resource must be ${expectedResource}.`);
}
const user = await loadUser(record.userId);
return issueTokens(
{
userId: user.id,
clientId: record.clientId,
scopes: parseScopes(record.scope),
resource: expectedResource,
issuer,
passwordHash: user.password,
},
tx,
);
});
if (result instanceof OAuthError) {
throw result;
}
return result;
}
export async function handleRefreshTokenGrant(
params: TokenRequestParams,
issuer: string,
): Promise<TokenResponse> {
const refreshToken = requireString(params.refresh_token, 'refresh_token', 512);
if (!isRefreshToken(refreshToken)) {
throw new OAuthError('invalid_grant', 'Refresh token is invalid.');
}
const record = await getRefreshTokenByHash(hashToken(refreshToken));
if (!record || record.revokedAt || record.expiresAt.getTime() <= Date.now()) {
throw new OAuthError('invalid_grant', 'Refresh token is invalid, expired or revoked.');
}
if (params.client_id !== undefined && params.client_id !== record.clientId) {
throw new OAuthError('invalid_grant', 'client_id does not match the refresh token.');
}
const grantedScopes = normalizeScopes(parseScopes(record.scope));
const requestedScopes = typeof params.scope === 'string' ? parseScopes(params.scope) : [];
const narrowed = requestedScopes.length ? normalizeScopes(requestedScopes) : grantedScopes;
if (narrowed.some(scope => !grantedScopes.includes(scope))) {
throw new OAuthError('invalid_scope', 'Requested scope exceeds the granted scope.');
}
const expectedResource = record.resource ?? getMcpResource(issuer);
if (params.resource !== undefined) {
const resourceParam =
typeof params.resource === 'string' ? normalizeResource(params.resource) : null;
if (resourceParam !== expectedResource) {
throw new OAuthError('invalid_target', `resource must be ${expectedResource}.`);
}
}
const user = await loadUser(record.userId);
// Rotate: the presented refresh token is retired and a new one issued (OAuth 2.1 §4.3.1).
return transaction(async tx => {
const revoked = await revokeRefreshToken(record.id, tx);
if (!revoked) {
throw new OAuthError('invalid_grant', 'Refresh token has already been used.');
}
await touchRefreshToken(record.id, tx);
return issueTokens(
{
userId: user.id,
clientId: record.clientId,
scopes: narrowed,
resource: expectedResource,
issuer,
passwordHash: user.password,
},
tx,
);
});
}
export async function handleTokenRequest(params: TokenRequestParams, issuer: string) {
switch (params.grant_type) {
case 'authorization_code':
return handleAuthorizationCodeGrant(params, issuer);
case 'refresh_token':
return handleRefreshTokenGrant(params, issuer);
default:
throw new OAuthError(
'unsupported_grant_type',
'grant_type must be "authorization_code" or "refresh_token".',
);
}
}
export async function handleRevocationRequest(params: { token?: unknown }) {
// RFC 7009: unknown tokens are silently accepted. Only refresh tokens are revocable;
// access tokens are short-lived and expire on their own.
if (isRefreshToken(params.token)) {
const record = await getRefreshTokenByHash(hashToken(params.token));
if (record && !record.revokedAt) {
await revokeRefreshToken(record.id);
}
}
}
-96
View File
@@ -1,96 +0,0 @@
import { beforeAll, describe, expect, test } from 'vitest';
import {
createAccessToken,
generateRefreshToken,
hashToken,
isRefreshToken,
looksLikeAccessToken,
verifyAccessToken,
} from './tokens';
const ISSUER = 'https://analytics.example.com';
const RESOURCE = `${ISSUER}/mcp`;
beforeAll(() => {
process.env.APP_SECRET = 'oauth-test-secret';
});
describe('access tokens', () => {
test('round-trips claims and binds the audience to the issuer', () => {
const { token, jti, expiresIn } = createAccessToken({
userId: 'user-1',
clientId: 'https://client.example/metadata.json',
scopes: ['websites:read', 'analytics:read', 'bogus'],
issuer: ISSUER,
resource: RESOURCE,
passwordHash: 'pw',
});
expect(expiresIn).toBe(3600);
expect(looksLikeAccessToken(token)).toBe(true);
const verified = verifyAccessToken(token);
expect(verified).toMatchObject({
userId: 'user-1',
clientId: 'https://client.example/metadata.json',
scopes: ['analytics:read', 'websites:read'],
issuer: ISSUER,
resource: RESOURCE,
tokenId: jti,
});
expect(verified?.passwordFingerprint).toBeDefined();
expect(verified?.expiresAt).toBeGreaterThan(Date.now());
});
test('rejects tokens whose audience is not the issuer MCP resource', () => {
const { token } = createAccessToken({
userId: 'user-1',
clientId: 'c',
scopes: ['websites:read'],
issuer: ISSUER,
resource: 'https://other.example/mcp',
});
expect(verifyAccessToken(token)).toBeNull();
});
test('rejects expired tokens', () => {
const { token } = createAccessToken({
userId: 'user-1',
clientId: 'c',
scopes: ['websites:read'],
issuer: ISSUER,
resource: RESOURCE,
expiresInSeconds: -10,
});
expect(verifyAccessToken(token)).toBeNull();
});
test('rejects tampered and foreign tokens', () => {
const { token } = createAccessToken({
userId: 'user-1',
clientId: 'c',
scopes: ['websites:read'],
issuer: ISSUER,
resource: RESOURCE,
});
const [header, payload] = token.split('.');
expect(verifyAccessToken(`${header}.${payload}.invalid`)).toBeNull();
expect(looksLikeAccessToken('umami_abc')).toBe(false);
expect(looksLikeAccessToken('a.b')).toBe(false);
});
});
describe('refresh tokens', () => {
test('generates prefixed tokens and stable hashes', () => {
const token = generateRefreshToken();
expect(isRefreshToken(token)).toBe(true);
expect(isRefreshToken('nope')).toBe(false);
expect(hashToken(token)).toBe(hashToken(token));
expect(hashToken(token)).not.toContain(token);
});
});
-138
View File
@@ -1,138 +0,0 @@
import { hash, secret, uuid } from '@/lib/crypto';
import { createToken, parseToken } from '@/lib/jwt';
import {
ACCESS_TOKEN_TTL_SECONDS,
getMcpResource,
OAUTH_ACCESS_TOKEN_TYPE,
REFRESH_TOKEN_PREFIX,
} from '@/lib/oauth/config';
import { generateSecret } from '@/lib/oauth/pkce';
import { normalizeScopes, type OAuthScope } from '@/lib/oauth/scopes';
export interface AccessTokenClaims {
/** User ID. */
sub: string;
iss: string;
aud: string;
client_id: string;
scope: string;
type: typeof OAUTH_ACCESS_TOKEN_TYPE;
jti: string;
/** Password fingerprint so that a password change invalidates outstanding tokens. */
pwd?: string;
iat: number;
exp: number;
}
export interface CreateAccessTokenOptions {
userId: string;
clientId: string;
scopes: readonly string[];
issuer: string;
resource: string;
passwordHash?: string;
expiresInSeconds?: number;
}
export function createAccessToken(options: CreateAccessTokenOptions) {
const expiresIn = options.expiresInSeconds ?? ACCESS_TOKEN_TTL_SECONDS;
const jti = uuid();
const token = createToken(
{
sub: options.userId,
iss: options.issuer,
aud: options.resource,
client_id: options.clientId,
scope: normalizeScopes([...options.scopes]).join(' '),
type: OAUTH_ACCESS_TOKEN_TYPE,
jti,
...(options.passwordHash ? { pwd: hash(options.passwordHash) } : {}),
},
secret(),
{ expiresIn },
) as string;
return { token, jti, expiresIn };
}
export interface VerifiedAccessToken {
userId: string;
clientId: string;
scopes: OAuthScope[];
issuer: string;
resource: string;
tokenId: string;
passwordFingerprint?: string;
expiresAt: number;
}
/**
* Cheap structural check so that ordinary session tokens (encrypted, not plain JWTs) and API
* keys can skip OAuth verification entirely.
*/
export function looksLikeAccessToken(token?: string | null): token is string {
if (!token || token.split('.').length !== 3) {
return false;
}
try {
const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8'));
return payload?.type === OAUTH_ACCESS_TOKEN_TYPE;
} catch {
return false;
}
}
/**
* Verifies signature, expiry, token type and audience binding. The audience must be the MCP
* resource of the issuer that minted the token, so a token can never be replayed against a
* different Umami deployment sharing the same secret.
*/
export function verifyAccessToken(token: string): VerifiedAccessToken | null {
const payload = parseToken(token, secret()) as Partial<AccessTokenClaims> | null;
if (
!payload ||
payload.type !== OAUTH_ACCESS_TOKEN_TYPE ||
typeof payload.sub !== 'string' ||
typeof payload.client_id !== 'string' ||
typeof payload.iss !== 'string' ||
typeof payload.aud !== 'string' ||
typeof payload.jti !== 'string' ||
typeof payload.exp !== 'number'
) {
return null;
}
if (payload.aud !== getMcpResource(payload.iss)) {
return null;
}
return {
userId: payload.sub,
clientId: payload.client_id,
scopes: normalizeScopes((payload.scope ?? '').split(' ')),
issuer: payload.iss,
resource: payload.aud,
tokenId: payload.jti,
passwordFingerprint: payload.pwd,
expiresAt: payload.exp * 1000,
};
}
export function generateRefreshToken() {
return `${REFRESH_TOKEN_PREFIX}${generateSecret(32)}`;
}
export function isRefreshToken(value: unknown): value is string {
return typeof value === 'string' && value.startsWith(REFRESH_TOKEN_PREFIX);
}
export function hashToken(value: string) {
return hash(value);
}
export function generateAuthorizationCode() {
return generateSecret(32);
}
-109
View File
@@ -1,109 +0,0 @@
import { beforeEach, describe, expect, test, vi } from 'vitest';
import { hash } from '@/lib/crypto';
import { getUser } from '@/queries/prisma/user';
import { createAccessToken } from './tokens';
import { verifyOAuthRequest } from './verify';
vi.mock('@/queries/prisma/user', () => ({
getUser: vi.fn(),
}));
const getUserMock = vi.mocked(getUser);
const ISSUER = 'https://analytics.example.com';
const USER = { id: 'user-1', username: 'admin', role: 'user', password: 'pw-hash' };
function token(scopes: string[], overrides: Record<string, unknown> = {}) {
return createAccessToken({
userId: USER.id,
clientId: 'https://app.example.com/client.json',
scopes,
issuer: ISSUER,
resource: `${ISSUER}/mcp`,
passwordHash: USER.password,
...overrides,
}).token;
}
beforeEach(() => {
process.env.APP_SECRET = 'test';
delete process.env.OAUTH_DISABLED;
getUserMock.mockReset();
getUserMock.mockResolvedValue({ ...USER } as never);
});
describe('verifyOAuthRequest', () => {
test('ignores non-OAuth tokens', async () => {
await expect(verifyOAuthRequest('umami_key', 'GET', '/api/websites')).resolves.toEqual({
status: 'not-oauth',
});
await expect(verifyOAuthRequest(undefined, 'GET', '/api/websites')).resolves.toEqual({
status: 'not-oauth',
});
});
test('builds an OAuth auth context on an allowlisted route', async () => {
const result = await verifyOAuthRequest(
token(['websites:read', 'analytics:read']),
'GET',
'/api/websites/abc/stats',
);
expect(result.status).toBe('ok');
if (result.status === 'ok') {
expect(result.auth.user).toMatchObject({ id: USER.id, isAdmin: false });
expect(result.auth.user).not.toHaveProperty('password');
expect(result.auth.authType).toBe('oauth');
expect(result.auth.oauth).toMatchObject({
clientId: 'https://app.example.com/client.json',
scopes: ['analytics:read', 'websites:read'],
});
}
});
test('rejects routes that did not opt in to OAuth', async () => {
await expect(
verifyOAuthRequest(token(['websites:read', 'analytics:read']), 'POST', '/api/websites'),
).resolves.toMatchObject({ status: 'forbidden', reason: 'route-not-allowed' });
await expect(
verifyOAuthRequest(token(['websites:read', 'analytics:read']), 'GET', '/api/me/api-keys'),
).resolves.toMatchObject({ status: 'forbidden', reason: 'route-not-allowed' });
await expect(
verifyOAuthRequest(token(['websites:read', 'analytics:read']), 'DELETE', '/api/websites/abc'),
).resolves.toMatchObject({ status: 'forbidden' });
});
test('rejects insufficient scope', async () => {
await expect(
verifyOAuthRequest(token(['websites:read']), 'GET', '/api/websites/abc/stats'),
).resolves.toMatchObject({
status: 'forbidden',
reason: 'insufficient-scope',
requiredScope: 'analytics:read',
});
});
test('rejects tokens after a password change or when the user is gone', async () => {
getUserMock.mockResolvedValue({ ...USER, password: 'changed' } as never);
await expect(
verifyOAuthRequest(token(['websites:read']), 'GET', '/api/websites'),
).resolves.toEqual({ status: 'invalid' });
getUserMock.mockResolvedValue(null as never);
await expect(
verifyOAuthRequest(token(['websites:read']), 'GET', '/api/websites'),
).resolves.toEqual({ status: 'invalid' });
});
test('rejects everything when OAuth is disabled', async () => {
process.env.OAUTH_DISABLED = '1';
await expect(
verifyOAuthRequest(token(['websites:read']), 'GET', '/api/websites'),
).resolves.toEqual({ status: 'invalid' });
});
test('password fingerprint uses the hashed password', () => {
expect(hash('pw-hash')).not.toBe('pw-hash');
});
});
-95
View File
@@ -1,95 +0,0 @@
import debug from 'debug';
import { ROLES } from '@/lib/constants';
import { hash } from '@/lib/crypto';
import { isOAuthEnabled } from '@/lib/oauth/config';
import { getRouteOAuthScope, hasRequiredScope } from '@/lib/oauth/scopes';
import {
looksLikeAccessToken,
type VerifiedAccessToken,
verifyAccessToken,
} from '@/lib/oauth/tokens';
import type { Auth } from '@/lib/types';
import { getUser } from '@/queries/prisma/user';
const log = debug('umami:oauth');
export type OAuthAuthResult =
| { status: 'not-oauth' }
| { status: 'invalid' }
| {
status: 'forbidden';
reason: 'route-not-allowed' | 'insufficient-scope';
requiredScope?: string;
}
| { status: 'ok'; auth: Auth & { token: string } };
/**
* Resolves an OAuth access token into an ordinary Umami `Auth` context.
*
* OAuth tokens are only accepted on routes listed in `OAUTH_ROUTE_SCOPES` and only when the
* token carries the scope that route requires. The resulting user context is subject to all
* normal Umami permission checks; scopes never widen access.
*/
export async function verifyOAuthRequest(
token: string | undefined,
method: string,
pathname: string,
): Promise<OAuthAuthResult> {
if (!looksLikeAccessToken(token)) {
return { status: 'not-oauth' };
}
if (!isOAuthEnabled()) {
return { status: 'invalid' };
}
const verified = verifyAccessToken(token);
if (!verified) {
log('invalid OAuth access token');
return { status: 'invalid' };
}
const requiredScope = getRouteOAuthScope(method, pathname);
if (!requiredScope) {
log('OAuth token used on non-allowlisted route', method, pathname);
return { status: 'forbidden', reason: 'route-not-allowed' };
}
if (!hasRequiredScope(verified.scopes, requiredScope)) {
return { status: 'forbidden', reason: 'insufficient-scope', requiredScope };
}
const auth = await buildOAuthAuth(token, verified);
return auth ? { status: 'ok', auth } : { status: 'invalid' };
}
export async function buildOAuthAuth(token: string, verified: VerifiedAccessToken) {
const user: any = await getUser(verified.userId, { includePassword: true });
if (!user?.id || user.deletedAt) {
log('OAuth token user not found');
return null;
}
if (verified.passwordFingerprint && hash(user.password) !== verified.passwordFingerprint) {
log('OAuth token issued before password change');
return null;
}
delete user.password;
user.isAdmin = user.role === ROLES.admin;
return {
token,
user,
authType: 'oauth' as const,
oauth: {
clientId: verified.clientId,
scopes: verified.scopes,
tokenId: verified.tokenId,
},
};
}
+1 -7
View File
@@ -12,7 +12,7 @@ export type Role = ObjectValues<typeof ROLES>;
export type DynamicDataType = ObjectValues<typeof DATA_TYPE>;
export type Operator = (typeof OPERATORS)[keyof typeof OPERATORS];
export type AuthType = 'session' | 'api-key' | 'oauth' | 'share';
export type AuthType = 'session' | 'api-key' | 'share';
export interface Auth {
user?: {
@@ -27,12 +27,6 @@ export interface Auth {
};
/** How the request was authenticated. Undefined for legacy callers that build Auth manually. */
authType?: AuthType;
/** OAuth details when `authType` is `oauth`. Scopes never expand Umami permissions. */
oauth?: {
clientId: string;
scopes: string[];
tokenId?: string;
};
shareToken?: {
shareType?: number;
websiteId?: string;
-8
View File
@@ -86,14 +86,6 @@ Operation IDs are public: they become method names in `@umami/api-client`. Route
overrides the mechanical path-based name (`getWebsitesWebsiteIdStats` -> `getWebsiteStats`).
Never rename an operation ID without a migration note for the client.
## OAuth scopes
`src/lib/oauth/scopes.ts` is the single allowlist of routes that accept OAuth access tokens and
the scope each requires. The document builder adds `x-umami-oauth-scope` and an `oauth2` security
requirement to those operations, and fails when an allowlist entry does not match a real route.
The same list is enforced at runtime by `checkAuth`, and mirrored by the in-process MCP dispatch
table (`src/lib/mcp/dispatch.ts`).
## Generated API client
`pnpm generate:api` regenerates the OpenAPI document and `packages/api-client/src/generated`.
+3 -23
View File
@@ -1,7 +1,6 @@
import { readFile } from 'node:fs/promises';
import path from 'node:path';
import { createDocument, type ZodOpenApiPathsObject } from 'zod-openapi';
import { getContractOAuthScope, OAUTH_ROUTE_SCOPES } from '@/lib/oauth/scopes';
import { loadApiContracts } from '@/openapi/contracts';
import {
analyzeContractCoverage,
@@ -11,7 +10,7 @@ import {
import { discoverApiOperations } from '@/openapi/discover';
import { applyFieldDescriptions } from '@/openapi/field-descriptions';
import { inferApiContracts } from '@/openapi/infer';
import { type ApiAudience, type ApiOperationContract, getOperationKey } from '@/openapi/operation';
import { type ApiAudience, getOperationKey } from '@/openapi/operation';
import { operationDescriptions } from '@/openapi/operation-descriptions';
import { errorResponseComponents } from '@/openapi/schemas';
import { getSecurityRequirements, securitySchemes } from '@/openapi/security';
@@ -31,19 +30,6 @@ async function getPackageVersion(projectRoot: string) {
return packageJson.version;
}
/**
* Every OAuth-allowlisted route must correspond to a real API route, otherwise the runtime
* allowlist and the published contract silently drift apart.
*/
function getOAuthRouteErrors(discovered: Pick<ApiOperationContract, 'method' | 'path'>[]) {
const discoveredKeys = new Set(discovered.map(getOperationKey));
return OAUTH_ROUTE_SCOPES.filter(route => !discoveredKeys.has(getOperationKey(route))).map(
route =>
`OAuth scope allowlist entry does not match a route: ${getOperationKey(route)} (src/lib/oauth/scopes.ts)`,
);
}
function getDocumentTags(paths: ZodOpenApiPathsObject) {
const names = new Set<string>();
@@ -79,11 +65,7 @@ export async function buildOpenApiDocument(
key =>
`Operation description does not match a route: ${key} (src/openapi/operation-descriptions.ts)`,
);
const errors = [
...getCoverageErrors(coverage),
...getOAuthRouteErrors(discovered),
...descriptionErrors,
];
const errors = [...getCoverageErrors(coverage), ...descriptionErrors];
if (errors.length) {
throw new Error(`Invalid OpenAPI contracts:\n${errors.map(error => `- ${error}`).join('\n')}`);
@@ -104,15 +86,13 @@ export async function buildOpenApiDocument(
paths[contract.path] = pathItem;
}
const scope = getContractOAuthScope(contract.method, contract.path);
const operation = {
...contract.operation,
...operationDescriptions[getOperationKey(contract)],
security: getSecurityRequirements(contract.auth, scope),
security: getSecurityRequirements(contract.auth),
'x-umami-audience': contract.audience,
'x-umami-contract': contract.origin,
'x-umami-source': contract.source,
...(scope ? { 'x-umami-oauth-scope': scope } : {}),
};
Object.assign(pathItem, { [contract.method]: operation });
-23
View File
@@ -167,29 +167,6 @@ const fieldDescriptions: Record<string, string> = {
error: 'Error details returned when the operation fails.',
message: 'Human-readable explanation of the result.',
ok: 'Whether the operation succeeded.',
client_id: 'OAuth client identifier.',
client_name: 'Human-readable name of the OAuth client.',
client_uri: 'URL of the OAuth client homepage.',
logo_uri: 'URL of the OAuth client logo.',
redirect_uri: 'Registered redirect URI to receive the authorization response.',
redirect_uris: 'Redirect URIs registered for the OAuth client.',
response_type: 'OAuth authorization response type; use code.',
response_types: 'Authorization response types supported by the client.',
code_challenge: 'PKCE challenge derived from the code verifier.',
code_challenge_method: 'Method used to derive the PKCE challenge; use S256.',
code_verifier: 'Original PKCE verifier used to obtain the authorization code.',
scope: 'Space-separated OAuth permissions.',
resource: 'Resource URI identifying the API targeted by the OAuth request.',
state: 'Client-provided value returned unchanged to correlate the authorization response.',
access_token: 'OAuth access token used to authorize API requests.',
refresh_token: 'OAuth refresh token used to obtain a new access token.',
token_type: 'Authorization scheme for the access token.',
expires_in: 'Access token lifetime in seconds.',
grant_type: 'OAuth grant used to obtain or refresh an access token.',
grant_types: 'OAuth grant types supported by the client.',
token_endpoint_auth_method: 'Client authentication method used at the token endpoint.',
token_type_hint: 'Hint indicating whether the revoked token is an access or refresh token.',
error_description: 'Human-readable explanation of the OAuth error.',
shareType: 'Type of resource made available by the share.',
};
-25
View File
@@ -232,31 +232,6 @@ export const operationDescriptions: Record<string, OperationDescription> = {
description:
"Returns a paginated list of the current user's websites, optionally including websites accessible through team membership.",
},
'GET /api/oauth/authorize': {
summary: 'Get OAuth authorization request details',
description:
'Validates an OAuth authorization request and returns the client and requested permissions for the consent screen. Requires an interactive user session.',
},
'POST /api/oauth/authorize': {
summary: 'Approve or deny OAuth access',
description:
"Records the user's consent decision and returns a redirect URL. Approval includes an authorization code, the request state, and the issuer.",
},
'POST /api/oauth/register': {
summary: 'Register an OAuth client',
description:
'Registers a public OAuth client for clients that do not support Client ID Metadata Documents. Clients that support them should use an HTTPS metadata URL as their client ID.',
},
'POST /api/oauth/revoke': {
summary: 'Revoke an OAuth refresh token',
description:
'Revokes the supplied refresh token. Unknown tokens are accepted without revealing whether they existed.',
},
'POST /api/oauth/token': {
summary: 'Get or refresh an OAuth access token',
description:
'Exchanges an authorization code and PKCE verifier, or a refresh token, for an access token. Accepts form-encoded or JSON requests and rotates refresh tokens on use.',
},
'GET /api/pixels': {
summary: 'List my tracking pixels',
description:
+1 -19
View File
@@ -1,4 +1,3 @@
import { OAUTH_SCOPE_DESCRIPTIONS, type OAuthScope } from '@/lib/oauth/scopes';
import type { ApiAuth } from '@/openapi/operation';
export const securitySchemes = {
@@ -9,19 +8,6 @@ export const securitySchemes = {
description:
'Token returned by POST /api/auth/login, or an API key (`umami_…`) created under Settings → API keys (self-hosted only).',
},
oauth2: {
type: 'oauth2' as const,
description:
'OAuth 2.1 access token (authorization code + PKCE). Only operations that declare an OAuth scope accept these tokens.',
flows: {
authorizationCode: {
authorizationUrl: '/oauth/authorize',
tokenUrl: '/api/oauth/token',
refreshUrl: '/api/oauth/token',
scopes: OAUTH_SCOPE_DESCRIPTIONS,
},
},
},
shareToken: {
type: 'apiKey' as const,
in: 'header' as const,
@@ -36,17 +22,13 @@ export const securitySchemes = {
},
};
export function getSecurityRequirements(auth: ApiAuth, scope?: OAuthScope | null) {
export function getSecurityRequirements(auth: ApiAuth) {
if (auth === 'none') {
return [];
}
const requirements: Record<string, string[]>[] = [{ bearerAuth: [] }];
if (scope) {
requirements.push({ oauth2: [scope] });
}
if (auth === 'bearer-or-share') {
requirements.push({ shareToken: [], shareContext: [] });
}
-127
View File
@@ -1,127 +0,0 @@
import type { Prisma } from '@/generated/prisma/client';
import prisma from '@/lib/prisma';
type OAuthDatabase = Pick<Prisma.TransactionClient, 'oauthAuthorizationCode' | 'oauthRefreshToken'>;
// The read-replica extension preserves these delegates, but changes their generic signatures.
const oauthDatabase = prisma.client as OAuthDatabase;
export async function createOauthClient(data: {
id: string;
name: string;
redirectUris: string[];
metadata?: Record<string, unknown>;
}) {
return prisma.client.oauthClient.create({
data: {
id: data.id,
name: data.name,
redirectUris: data.redirectUris,
metadata: data.metadata as any,
},
});
}
export async function getOauthClient(id: string) {
return prisma.client.oauthClient.findUnique({ where: { id } });
}
export async function createAuthorizationCode(data: {
id: string;
codeHash: string;
userId: string;
clientId: string;
redirectUri: string;
scope: string;
resource?: string | null;
codeChallenge: string;
codeChallengeMethod: string;
expiresAt: Date;
}) {
return prisma.client.oauthAuthorizationCode.create({ data });
}
/**
* Atomically marks a code as used and returns it, or `null` when the code is unknown, expired or
* has already been redeemed. Reuse of a code is a replay signal, handled by the caller.
*/
export async function consumeAuthorizationCode(
codeHash: string,
db: OAuthDatabase = oauthDatabase,
) {
const now = new Date();
const { count } = await db.oauthAuthorizationCode.updateMany({
where: { codeHash, usedAt: null, expiresAt: { gt: now } },
data: { usedAt: now },
});
const code = await db.oauthAuthorizationCode.findUnique({ where: { codeHash } });
if (!code) {
return { code: null, replayed: null };
}
if (count === 1) {
return { code, replayed: null };
}
// Code exists but was not consumable: either expired or already redeemed (replay).
return { code: null, replayed: code.usedAt && code.usedAt < new Date() ? code : null };
}
export async function createRefreshToken(
data: {
id: string;
tokenHash: string;
userId: string;
clientId: string;
scope: string;
resource?: string | null;
expiresAt: Date;
},
db: OAuthDatabase = oauthDatabase,
) {
return db.oauthRefreshToken.create({ data });
}
export async function getRefreshTokenByHash(tokenHash: string) {
return prisma.client.oauthRefreshToken.findUnique({ where: { tokenHash } });
}
export async function revokeRefreshToken(id: string, db: OAuthDatabase = oauthDatabase) {
const { count } = await db.oauthRefreshToken.updateMany({
where: { id, revokedAt: null },
data: { revokedAt: new Date() },
});
return count;
}
export async function revokeRefreshTokensForClient(
userId: string,
clientId: string,
db: OAuthDatabase = oauthDatabase,
) {
const { count } = await db.oauthRefreshToken.updateMany({
where: { userId, clientId, revokedAt: null },
data: { revokedAt: new Date() },
});
return count;
}
export async function touchRefreshToken(id: string, db: OAuthDatabase = oauthDatabase) {
return db.oauthRefreshToken.update({
where: { id },
data: { lastUsedAt: new Date() },
});
}
export async function deleteExpiredOauthRecords() {
const now = new Date();
const [codes, tokens] = await Promise.all([
prisma.client.oauthAuthorizationCode.deleteMany({ where: { expiresAt: { lt: now } } }),
prisma.client.oauthRefreshToken.deleteMany({ where: { expiresAt: { lt: now } } }),
]);
return { codes: codes.count, tokens: tokens.count };
}