chore(backend): Add helper type for auth helpers without request parameters#6910

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wobsoriano merged 7 commits into from
Oct 7, 2025
Merged

chore(backend): Add helper type for auth helpers without request parameters #6910

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
acac59d
chore: Consolidate auth function helper types
wobsoriano Oct 3, 2025
a99c68c
chore: add changeset
wobsoriano Oct 3, 2025
5fb3d59
chore: update types
wobsoriano Oct 3, 2025
347fd83
chore: fix generic type
wobsoriano Oct 3, 2025
ea84310
chore: fix typedoc tests
wobsoriano Oct 3, 2025
5d93a54
chore: fix mimic next auth type
wobsoriano Oct 3, 2025
6471cc3
chore: update changeset
wobsoriano Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .changeset/real-trainers-knock.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
---
"@clerk/astro": patch
"@clerk/backend": patch
"@clerk/express": patch
"@clerk/fastify": patch
"@clerk/nextjs": patch
"@clerk/nuxt": patch
"@clerk/tanstack-react-start": patch
---

Added internal helper type for `auth` and `getAuth()` functions that don't require a request or context parameter
2 changes: 2 additions & 0 deletions .typedoc/__tests__/__snapshots__/file-structure.test.ts.snap
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -208,6 +208,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
"nextjs/create-sync-get-auth.mdx",
"nextjs/current-user.mdx",
"nextjs/get-auth.mdx",
"nextjs/session-auth-with-redirect.mdx",
"clerk-react/api-keys.mdx",
"clerk-react/checkout-button-props.mdx",
"clerk-react/checkout-button.mdx",
Expand DownExpand Up@@ -247,6 +248,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
"backend/email-address.mdx",
"backend/external-account.mdx",
"backend/feature.mdx",
"backend/get-auth-fn-no-request.mdx",
"backend/get-auth-fn.mdx",
"backend/identification-link.mdx",
"backend/infer-auth-object-from-token-array.mdx",
Expand Down
11 changes: 3 additions & 8 deletions packages/astro/src/server/clerk-middleware.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
import type { AuthObject, ClerkClient } from '@clerk/backend';
import type {
AuthenticateRequestOptions,
AuthOptions,
ClerkRequest,
RedirectFun,
RequestState,
SignedInAuthObject,
SignedOutAuthObject,
} from '@clerk/backend/internal';
import {
AuthStatus,
Expand DownExpand Up@@ -36,18 +35,14 @@ import type {
AstroMiddlewareNextParam,
AstroMiddlewareReturn,
AuthFn,
AuthOptions,
SessionAuthObjectWithRedirect,
} from './types';
import { isRedirect, setHeader } from './utils';

const CONTROL_FLOW_ERROR = {
REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
};

type ClerkMiddlewareAuthObject = (SignedInAuthObject | SignedOutAuthObject) & {
redirectToSignIn: (opts?: { returnBackUrl?: URL | string | null }) => Response;
};

type ClerkAstroMiddlewareHandler = (
auth: AuthFn,
context: AstroMiddlewareContextParam,
Expand DownExpand Up@@ -396,7 +391,7 @@ const redirectAdapter = (url: string | URL) => {

const createMiddlewareRedirectToSignIn = (
clerkRequest: ClerkRequest,
): ClerkMiddlewareAuthObject['redirectToSignIn'] => {
): SessionAuthObjectWithRedirect['redirectToSignIn'] => {
return (opts = {}) => {
const err = new Error(CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_IN) as any;
err.returnBackUrl = opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkRequest.clerkUrl.toString();
Expand Down
52 changes: 4 additions & 48 deletions packages/astro/src/server/types.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,5 @@
import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
import type {
AuthenticateRequestOptions,
InferAuthObjectFromToken,
InferAuthObjectFromTokenArray,
RedirectFun,
SessionTokenType,
TokenType,
} from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { SessionAuthObject } from '@clerk/backend';
import type { GetAuthFnNoRequest, RedirectFun } from '@clerk/backend/internal';
import type { APIContext } from 'astro';

/**
Expand All@@ -26,44 +18,8 @@ export type AstroMiddlewareContextParam = APIContext;
export type AstroMiddlewareNextParam = MiddlewareNext;
export type AstroMiddlewareReturn = Response | Promise<Response>;

export type AuthOptions = PendingSessionOptions & Pick<AuthenticateRequestOptions, 'acceptsToken'>;

type SessionAuthObjectWithRedirect = SessionAuthObject & {
export type SessionAuthObjectWithRedirect = SessionAuthObject & {
redirectToSignIn: RedirectFun<Response>;
};

export interface AuthFn {
/**
* @example
* const auth = context.locals.auth({ acceptsToken: ['session_token', 'api_key'] })
*/
<T extends TokenType[]>(
options: AuthOptions & { acceptsToken: T },
):
| InferAuthObjectFromTokenArray<
T,
SessionAuthObjectWithRedirect,
MachineAuthObject<Exclude<T[number], SessionTokenType>>
>
| InvalidTokenAuthObject;

/**
* @example
* const auth = context.locals.auth({ acceptsToken: 'session_token' })
*/
<T extends TokenType>(
options: AuthOptions & { acceptsToken: T },
): InferAuthObjectFromToken<T, SessionAuthObjectWithRedirect, MachineAuthObject<Exclude<T, SessionTokenType>>>;

/**
* @example
* const auth = context.locals.auth({ acceptsToken: 'any' })
*/
(options: AuthOptions & { acceptsToken: 'any' }): AuthObject;

/**
* @example
* const auth = context.locals.auth()
*/
(options?: PendingSessionOptions): SessionAuthObjectWithRedirect;
}
export type AuthFn = GetAuthFnNoRequest<SessionAuthObjectWithRedirect>;
2 changes: 2 additions & 0 deletions packages/backend/src/internal.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,8 @@ export type {
InferAuthObjectFromToken,
InferAuthObjectFromTokenArray,
GetAuthFn,
AuthOptions,
GetAuthFnNoRequest,
} from './tokens/types';

export { TokenType } from './tokens/tokenTypes';
Expand Down
132 changes: 91 additions & 41 deletions packages/backend/src/tokens/__tests__/getAuth.test-d.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,99 @@
import { expectTypeOf, test } from 'vitest';

import type { RedirectFun } from '../../createRedirect';
import type { AuthObject, InvalidTokenAuthObject } from '../authObjects';
import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';

// Across our SDKs, we have a getAuth() function
const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
return {} as any;
};

test('infers the correct AuthObject type for each accepted token type', () => {
const request = new Request('https://example.com');

// Session token by default
expectTypeOf(getAuth(request)).toMatchTypeOf<SessionAuthObject>();

// Individual token types
expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();

// Array of token types
expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toMatchTypeOf<
SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
>();
expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toMatchTypeOf<
MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
>();

// Any token type
expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
import type { GetAuthFn, GetAuthFnNoRequest, MachineAuthObject, SessionAuthObject } from '../types';

describe('getAuth() or auth() with request parameter', () => {
const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
return {} as any;
};

test('infers the correct AuthObject type for each accepted token type', () => {
const request = new Request('https://example.com');

// Session token by default
expectTypeOf(getAuth(request)).toExtend<SessionAuthObject>();

// Individual token types
expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toExtend<SessionAuthObject>();
expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

// Array of token types
expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
>();
expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
>();

// Any token type
expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toExtend<AuthObject>();
});

test('verifies discriminated union works correctly with acceptsToken: any', () => {
const request = new Request('https://example.com');

const auth = getAuth(request, { acceptsToken: 'any' });

if (auth.tokenType === 'session_token') {
expectTypeOf(auth).toExtend<SessionAuthObject>();
} else if (auth.tokenType === 'api_key') {
expectTypeOf(auth).toExtend<MachineAuthObject<'api_key'>>();
} else if (auth.tokenType === 'm2m_token') {
expectTypeOf(auth).toExtend<MachineAuthObject<'m2m_token'>>();
} else if (auth.tokenType === 'oauth_token') {
expectTypeOf(auth).toExtend<MachineAuthObject<'oauth_token'>>();
}
});
});

test('verifies discriminated union works correctly with acceptsToken: any', () => {
const request = new Request('https://example.com');
describe('getAuth() or auth() without request parameter', () => {
type SessionAuthWithRedirect = SessionAuthObject & {
redirectToSignIn: RedirectFun<Response>;
redirectToSignUp: RedirectFun<Response>;
};

// Mimic Next.js auth() helper
const auth: GetAuthFnNoRequest<SessionAuthWithRedirect, true> = (_options: any) => {
return {} as any;
};

test('infers the correct AuthObject type for each accepted token type', async () => {
// Session token by default
expectTypeOf(await auth()).toExtend<SessionAuthWithRedirect>();

// Individual token types
expectTypeOf(await auth({ acceptsToken: 'session_token' })).toExtend<SessionAuthWithRedirect>();
expectTypeOf(await auth({ acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
expectTypeOf(await auth({ acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
expectTypeOf(await auth({ acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

// Array of token types
expectTypeOf(await auth({ acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
SessionAuthWithRedirect | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
>();
expectTypeOf(await auth({ acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
>();

// Any token type
expectTypeOf(await auth({ acceptsToken: 'any' })).toExtend<AuthObject>();
});

const auth = getAuth(request, { acceptsToken: 'any' });
test('verifies discriminated union works correctly with acceptsToken: any', async () => {
const authObject = await auth({ acceptsToken: 'any' });

if (auth.tokenType === 'session_token') {
expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
} else if (auth.tokenType === 'api_key') {
expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
} else if (auth.tokenType === 'm2m_token') {
expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
} else if (auth.tokenType === 'oauth_token') {
expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
}
if (authObject.tokenType === 'session_token') {
expectTypeOf(authObject).toExtend<SessionAuthWithRedirect>();
} else if (authObject.tokenType === 'api_key') {
expectTypeOf(authObject).toExtend<MachineAuthObject<'api_key'>>();
} else if (authObject.tokenType === 'm2m_token') {
expectTypeOf(authObject).toExtend<MachineAuthObject<'m2m_token'>>();
} else if (authObject.tokenType === 'oauth_token') {
expectTypeOf(authObject).toExtend<MachineAuthObject<'oauth_token'>>();
}
});
});
51 changes: 49 additions & 2 deletions packages/backend/src/tokens/types.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -187,14 +187,13 @@ export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> =
? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
: never;

type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
export type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

type MaybePromise<T, IsPromise extends boolean> = IsPromise extends true ? Promise<T> : T;

/**
* Shared generic overload type for getAuth() helpers across SDKs.
*
* - Parameterized by the request type (RequestType).
* - Handles different accepted token types and their corresponding return types.
*/
export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false> {
Expand DownExpand Up@@ -235,3 +234,51 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
*/
(req: RequestType, options?: PendingSessionOptions): MaybePromise<SessionAuthObject, ReturnsPromise>;
}

/**
* Shared generic overload type for auth() or getAuth() helpers that don't require a request parameter.
*
* - Handles different accepted token types and their corresponding return types.
* - The SessionAuthType parameter allows frameworks to extend the base SessionAuthObject with additional properties like redirect methods.
*/
export interface GetAuthFnNoRequest<
SessionAuthType extends SessionAuthObject = SessionAuthObject,
ReturnsPromise extends boolean = false,
> {
/**
* @example
* const authObject = await auth({ acceptsToken: ['session_token', 'api_key'] })
*/
<T extends TokenType[]>(
options: AuthOptions & { acceptsToken: T },
): MaybePromise<
| InferAuthObjectFromTokenArray<T, SessionAuthType, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
| InvalidTokenAuthObject,
ReturnsPromise
>;

/**
* @example
* const authObject = await auth({ acceptsToken: 'session_token' })
*/
<T extends TokenType>(
options: AuthOptions & { acceptsToken: T },
): MaybePromise<
InferAuthObjectFromToken<T, SessionAuthType, MachineAuthObject<Exclude<T, SessionTokenType>>>,
ReturnsPromise
>;

/**
* @example
* const authObject = await auth({ acceptsToken: 'any' })
*/
(
options: AuthOptions & { acceptsToken: 'any' },
): MaybePromise<Exclude<AuthObject, SessionAuthObject> | SessionAuthType, ReturnsPromise>;

/**
* @example
* const authObject = await auth()
*/
(options?: PendingSessionOptions): MaybePromise<SessionAuthType, ReturnsPromise>;
}
7 changes: 2 additions & 5 deletions packages/express/src/getAuth.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
import type { AuthenticateRequestOptions, GetAuthFn } from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { Request as ExpressRequest } from 'express';

import { middlewareRequired } from './errors';
import { requestHasAuthObject } from './utils';

type GetAuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

/**
* Retrieves the Clerk AuthObject using the current request object.
*
* @param {GetAuthOptions} options - Optional configuration for retriving auth object.
* @returns {AuthObject} Object with information about the request state and claims.
* @throws {Error} `clerkMiddleware` or `requireAuth` is required to be set in the middleware chain before this util is used.
*/
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: AuthOptions) => {
if (!requestHasAuthObject(req)) {
throw new Error(middlewareRequired('getAuth'));
}
Expand Down
11 changes: 2 additions & 9 deletions packages/fastify/src/getAuth.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,10 @@
import type {
AuthenticateRequestOptions,
GetAuthFn,
SignedInAuthObject,
SignedOutAuthObject,
} from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn, SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { FastifyRequest } from 'fastify';

import { pluginRegistrationRequired } from './errors';

type GetAuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: AuthOptions) => {
const authReq = req as FastifyRequest & { auth: SignedInAuthObject | SignedOutAuthObject };

if (!authReq.auth) {
Expand Down
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
chore(backend): Add helper type for auth helpers without request parameters#6910

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

wobsoriano
merged 7 commits into

from

Oct 7, 2025
 Merged


chore(backend): Add helper type for auth helpers without request parameters
#6910
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
acac59d

chore: Consolidate auth function helper types


wobsoriano Oct 3, 2025
a99c68c

chore: add changeset


wobsoriano Oct 3, 2025
5fb3d59

chore: update types


wobsoriano Oct 3, 2025
347fd83

chore: fix generic type


wobsoriano Oct 3, 2025
ea84310

chore: fix typedoc tests


wobsoriano Oct 3, 2025
5d93a54

chore: fix mimic next auth type


wobsoriano Oct 3, 2025
6471cc3

chore: update changeset


wobsoriano Oct 7, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


11 changes: 11 additions & 0 deletions
.changeset/real-trainers-knock.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
---
"@clerk/astro": patch
"@clerk/backend": patch
"@clerk/express": patch
"@clerk/fastify": patch
"@clerk/nextjs": patch
"@clerk/nuxt": patch
"@clerk/tanstack-react-start": patch
---

Added internal helper type for `auth` and `getAuth()` functions that don't require a request or context parameter

2 changes: 2 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -208,6 +208,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "nextjs/create-sync-get-auth.mdx",
 "nextjs/current-user.mdx",
 "nextjs/get-auth.mdx",
 "nextjs/session-auth-with-redirect.mdx",
 "clerk-react/api-keys.mdx",
 "clerk-react/checkout-button-props.mdx",
 "clerk-react/checkout-button.mdx",
Expand DownExpand Up@@ -247,6 +248,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/email-address.mdx",
 "backend/external-account.mdx",
 "backend/feature.mdx",
 "backend/get-auth-fn-no-request.mdx",
 "backend/get-auth-fn.mdx",
 "backend/identification-link.mdx",
 "backend/infer-auth-object-from-token-array.mdx",
Expand Down

11 changes: 3 additions & 8 deletions
packages/astro/src/server/clerk-middleware.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
import type { AuthObject, ClerkClient } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 AuthOptions,
 ClerkRequest,
 RedirectFun,
 RequestState,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import {
 AuthStatus,
Expand DownExpand Up@@ -36,18 +35,14 @@ import type {
 AstroMiddlewareNextParam,
 AstroMiddlewareReturn,
 AuthFn,
AuthOptions,
SessionAuthObjectWithRedirect,
} from './types';
import { isRedirect, setHeader } from './utils';

const CONTROL_FLOW_ERROR = {
 REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
};

type ClerkMiddlewareAuthObject = (SignedInAuthObject | SignedOutAuthObject) & {
 redirectToSignIn: (opts?: { returnBackUrl?: URL | string | null }) => Response;
};

type ClerkAstroMiddlewareHandler = (
 auth: AuthFn,
 context: AstroMiddlewareContextParam,
Expand DownExpand Up@@ -396,7 +391,7 @@ const redirectAdapter = (url: string | URL) => {

const createMiddlewareRedirectToSignIn = (
 clerkRequest: ClerkRequest,
): ClerkMiddlewareAuthObject['redirectToSignIn'] => {
): SessionAuthObjectWithRedirect['redirectToSignIn'] => {
 return (opts = {}) => {
 const err = new Error(CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_IN) as any;
 err.returnBackUrl = opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkRequest.clerkUrl.toString();
Expand Down

52 changes: 4 additions & 48 deletions
packages/astro/src/server/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,5 @@
import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 RedirectFun,
 SessionTokenType,
 TokenType,
} from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { SessionAuthObject } from '@clerk/backend';
import type { GetAuthFnNoRequest, RedirectFun } from '@clerk/backend/internal';
import type { APIContext } from 'astro';

/**
Expand All@@ -26,44 +18,8 @@ export type AstroMiddlewareContextParam = APIContext;
export type AstroMiddlewareNextParam = MiddlewareNext;
export type AstroMiddlewareReturn = Response | Promise<Response>;

export type AuthOptions = PendingSessionOptions & Pick<AuthenticateRequestOptions, 'acceptsToken'>;

type SessionAuthObjectWithRedirect = SessionAuthObject & {
export type SessionAuthObjectWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
};

export interface AuthFn {
 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ):
 | InferAuthObjectFromTokenArray<
 T,
 SessionAuthObjectWithRedirect,
 MachineAuthObject<Exclude<T[number], SessionTokenType>>
 >
 | InvalidTokenAuthObject;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): InferAuthObjectFromToken<T, SessionAuthObjectWithRedirect, MachineAuthObject<Exclude<T, SessionTokenType>>>;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'any' })
 */
 (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;

 /**
 * @example
 * const auth = context.locals.auth()
 */
 (options?: PendingSessionOptions): SessionAuthObjectWithRedirect;
}
export type AuthFn = GetAuthFnNoRequest<SessionAuthObjectWithRedirect>;

2 changes: 2 additions & 0 deletions
packages/backend/src/internal.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,8 @@ export type {
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 GetAuthFn,
 AuthOptions,
 GetAuthFnNoRequest,
} from './tokens/types';

export { TokenType } from './tokens/tokenTypes';
Expand Down

132 changes: 91 additions & 41 deletions
packages/backend/src/tokens/__tests__/getAuth.test-d.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,49 +1,99 @@
import { expectTypeOf, test } from 'vitest';

import type { RedirectFun } from '../../createRedirect';
import type { AuthObject, InvalidTokenAuthObject } from '../authObjects';
import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';

// Across our SDKs, we have a getAuth() function
const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
};

test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toMatchTypeOf<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toMatchTypeOf<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toMatchTypeOf<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
import type { GetAuthFn, GetAuthFnNoRequest, MachineAuthObject, SessionAuthObject } from '../types';

describe('getAuth() or auth() with request parameter', () => {
 const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toExtend<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toExtend<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');

 const auth = getAuth(request, { acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toExtend<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');
describe('getAuth() or auth() without request parameter', () => {
 type SessionAuthWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
 redirectToSignUp: RedirectFun<Response>;
 };

 // Mimic Next.js auth() helper
 const auth: GetAuthFnNoRequest<SessionAuthWithRedirect, true> = (_options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', async () => {
 // Session token by default
 expectTypeOf(await auth()).toExtend<SessionAuthWithRedirect>();

 // Individual token types
 expectTypeOf(await auth({ acceptsToken: 'session_token' })).toExtend<SessionAuthWithRedirect>();
 expectTypeOf(await auth({ acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(await auth({ acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(await auth({ acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(await auth({ acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthWithRedirect | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(await auth({ acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(await auth({ acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 const auth = getAuth(request, { acceptsToken: 'any' });
 test('verifies discriminated union works correctly with acceptsToken: any', async () => {
 const authObject = await auth({ acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
 }
 if (authObject.tokenType === 'session_token') {
 expectTypeOf(authObject).toExtend<SessionAuthWithRedirect>();
 } else if (authObject.tokenType === 'api_key') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'api_key'>>();
 } else if (authObject.tokenType === 'm2m_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (authObject.tokenType === 'oauth_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

51 changes: 49 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -187,14 +187,13 @@ export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> =
 ? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
 : never;

type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
export type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

type MaybePromise<T, IsPromise extends boolean> = IsPromise extends true ? Promise<T> : T;

/**
 * Shared generic overload type for getAuth() helpers across SDKs.
 *
 * - Parameterized by the request type (RequestType).
 * - Handles different accepted token types and their corresponding return types.
 */
export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false> {
Expand DownExpand Up@@ -235,3 +234,51 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
 */
 (req: RequestType, options?: PendingSessionOptions): MaybePromise<SessionAuthObject, ReturnsPromise>;
}

/**
 * Shared generic overload type for auth() or getAuth() helpers that don't require a request parameter.
 *
 * - Handles different accepted token types and their corresponding return types.
 * - The SessionAuthType parameter allows frameworks to extend the base SessionAuthObject with additional properties like redirect methods.
 */
export interface GetAuthFnNoRequest<
 SessionAuthType extends SessionAuthObject = SessionAuthObject,
 ReturnsPromise extends boolean = false,
> {
 /**
 * @example
 * const authObject = await auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 | InferAuthObjectFromTokenArray<T, SessionAuthType, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
 | InvalidTokenAuthObject,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 InferAuthObjectFromToken<T, SessionAuthType, MachineAuthObject<Exclude<T, SessionTokenType>>>,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'any' })
 */
 (
 options: AuthOptions & { acceptsToken: 'any' },
 ): MaybePromise<Exclude<AuthObject, SessionAuthObject> | SessionAuthType, ReturnsPromise>;

 /**
 * @example
 * const authObject = await auth()
 */
 (options?: PendingSessionOptions): MaybePromise<SessionAuthType, ReturnsPromise>;
}

7 changes: 2 additions & 5 deletions
packages/express/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
import type { AuthenticateRequestOptions, GetAuthFn } from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { Request as ExpressRequest } from 'express';

import { middlewareRequired } from './errors';
import { requestHasAuthObject } from './utils';

type GetAuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

/**
 * Retrieves the Clerk AuthObject using the current request object.
 *
 * @param {GetAuthOptions} options - Optional configuration for retriving auth object.
 * @returns {AuthObject} Object with information about the request state and claims.
 * @throws {Error} `clerkMiddleware` or `requireAuth` is required to be set in the middleware chain before this util is used.
 */
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: AuthOptions) => {
 if (!requestHasAuthObject(req)) {
 throw new Error(middlewareRequired('getAuth'));
 }
Expand Down

11 changes: 2 additions & 9 deletions
packages/fastify/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,17 +1,10 @@
import type {
 AuthenticateRequestOptions,
 GetAuthFn,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn, SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { FastifyRequest } from 'fastify';

import { pluginRegistrationRequired } from './errors';

type GetAuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: AuthOptions) => {
 const authReq = req as FastifyRequest & { auth: SignedInAuthObject | SignedOutAuthObject };

 if (!authReq.auth) {
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
chore(backend): Add helper type for auth helpers without request parameters#6910

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

wobsoriano
merged 7 commits into

from

Oct 7, 2025
 Merged


chore(backend): Add helper type for auth helpers without request parameters
#6910
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
acac59d

chore: Consolidate auth function helper types


wobsoriano Oct 3, 2025
a99c68c

chore: add changeset


wobsoriano Oct 3, 2025
5fb3d59

chore: update types


wobsoriano Oct 3, 2025
347fd83

chore: fix generic type


wobsoriano Oct 3, 2025
ea84310

chore: fix typedoc tests


wobsoriano Oct 3, 2025
5d93a54

chore: fix mimic next auth type


wobsoriano Oct 3, 2025
6471cc3

chore: update changeset


wobsoriano Oct 7, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


11 changes: 11 additions & 0 deletions
.changeset/real-trainers-knock.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
---
"@clerk/astro": patch
"@clerk/backend": patch
"@clerk/express": patch
"@clerk/fastify": patch
"@clerk/nextjs": patch
"@clerk/nuxt": patch
"@clerk/tanstack-react-start": patch
---

Added internal helper type for `auth` and `getAuth()` functions that don't require a request or context parameter

2 changes: 2 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -208,6 +208,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "nextjs/create-sync-get-auth.mdx",
 "nextjs/current-user.mdx",
 "nextjs/get-auth.mdx",
 "nextjs/session-auth-with-redirect.mdx",
 "clerk-react/api-keys.mdx",
 "clerk-react/checkout-button-props.mdx",
 "clerk-react/checkout-button.mdx",
Expand DownExpand Up@@ -247,6 +248,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/email-address.mdx",
 "backend/external-account.mdx",
 "backend/feature.mdx",
 "backend/get-auth-fn-no-request.mdx",
 "backend/get-auth-fn.mdx",
 "backend/identification-link.mdx",
 "backend/infer-auth-object-from-token-array.mdx",
Expand Down

11 changes: 3 additions & 8 deletions
packages/astro/src/server/clerk-middleware.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
import type { AuthObject, ClerkClient } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 AuthOptions,
 ClerkRequest,
 RedirectFun,
 RequestState,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import {
 AuthStatus,
Expand DownExpand Up@@ -36,18 +35,14 @@ import type {
 AstroMiddlewareNextParam,
 AstroMiddlewareReturn,
 AuthFn,
AuthOptions,
SessionAuthObjectWithRedirect,
} from './types';
import { isRedirect, setHeader } from './utils';

const CONTROL_FLOW_ERROR = {
 REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
};

type ClerkMiddlewareAuthObject = (SignedInAuthObject | SignedOutAuthObject) & {
 redirectToSignIn: (opts?: { returnBackUrl?: URL | string | null }) => Response;
};

type ClerkAstroMiddlewareHandler = (
 auth: AuthFn,
 context: AstroMiddlewareContextParam,
Expand DownExpand Up@@ -396,7 +391,7 @@ const redirectAdapter = (url: string | URL) => {

const createMiddlewareRedirectToSignIn = (
 clerkRequest: ClerkRequest,
): ClerkMiddlewareAuthObject['redirectToSignIn'] => {
): SessionAuthObjectWithRedirect['redirectToSignIn'] => {
 return (opts = {}) => {
 const err = new Error(CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_IN) as any;
 err.returnBackUrl = opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkRequest.clerkUrl.toString();
Expand Down

52 changes: 4 additions & 48 deletions
packages/astro/src/server/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,5 @@
import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 RedirectFun,
 SessionTokenType,
 TokenType,
} from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { SessionAuthObject } from '@clerk/backend';
import type { GetAuthFnNoRequest, RedirectFun } from '@clerk/backend/internal';
import type { APIContext } from 'astro';

/**
Expand All@@ -26,44 +18,8 @@ export type AstroMiddlewareContextParam = APIContext;
export type AstroMiddlewareNextParam = MiddlewareNext;
export type AstroMiddlewareReturn = Response | Promise<Response>;

export type AuthOptions = PendingSessionOptions & Pick<AuthenticateRequestOptions, 'acceptsToken'>;

type SessionAuthObjectWithRedirect = SessionAuthObject & {
export type SessionAuthObjectWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
};

export interface AuthFn {
 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ):
 | InferAuthObjectFromTokenArray<
 T,
 SessionAuthObjectWithRedirect,
 MachineAuthObject<Exclude<T[number], SessionTokenType>>
 >
 | InvalidTokenAuthObject;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): InferAuthObjectFromToken<T, SessionAuthObjectWithRedirect, MachineAuthObject<Exclude<T, SessionTokenType>>>;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'any' })
 */
 (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;

 /**
 * @example
 * const auth = context.locals.auth()
 */
 (options?: PendingSessionOptions): SessionAuthObjectWithRedirect;
}
export type AuthFn = GetAuthFnNoRequest<SessionAuthObjectWithRedirect>;

2 changes: 2 additions & 0 deletions
packages/backend/src/internal.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,8 @@ export type {
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 GetAuthFn,
 AuthOptions,
 GetAuthFnNoRequest,
} from './tokens/types';

export { TokenType } from './tokens/tokenTypes';
Expand Down

132 changes: 91 additions & 41 deletions
packages/backend/src/tokens/__tests__/getAuth.test-d.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,49 +1,99 @@
import { expectTypeOf, test } from 'vitest';

import type { RedirectFun } from '../../createRedirect';
import type { AuthObject, InvalidTokenAuthObject } from '../authObjects';
import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';

// Across our SDKs, we have a getAuth() function
const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
};

test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toMatchTypeOf<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toMatchTypeOf<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toMatchTypeOf<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
import type { GetAuthFn, GetAuthFnNoRequest, MachineAuthObject, SessionAuthObject } from '../types';

describe('getAuth() or auth() with request parameter', () => {
 const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toExtend<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toExtend<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');

 const auth = getAuth(request, { acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toExtend<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');
describe('getAuth() or auth() without request parameter', () => {
 type SessionAuthWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
 redirectToSignUp: RedirectFun<Response>;
 };

 // Mimic Next.js auth() helper
 const auth: GetAuthFnNoRequest<SessionAuthWithRedirect, true> = (_options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', async () => {
 // Session token by default
 expectTypeOf(await auth()).toExtend<SessionAuthWithRedirect>();

 // Individual token types
 expectTypeOf(await auth({ acceptsToken: 'session_token' })).toExtend<SessionAuthWithRedirect>();
 expectTypeOf(await auth({ acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(await auth({ acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(await auth({ acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(await auth({ acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthWithRedirect | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(await auth({ acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(await auth({ acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 const auth = getAuth(request, { acceptsToken: 'any' });
 test('verifies discriminated union works correctly with acceptsToken: any', async () => {
 const authObject = await auth({ acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
 }
 if (authObject.tokenType === 'session_token') {
 expectTypeOf(authObject).toExtend<SessionAuthWithRedirect>();
 } else if (authObject.tokenType === 'api_key') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'api_key'>>();
 } else if (authObject.tokenType === 'm2m_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (authObject.tokenType === 'oauth_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

51 changes: 49 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -187,14 +187,13 @@ export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> =
 ? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
 : never;

type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
export type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

type MaybePromise<T, IsPromise extends boolean> = IsPromise extends true ? Promise<T> : T;

/**
 * Shared generic overload type for getAuth() helpers across SDKs.
 *
 * - Parameterized by the request type (RequestType).
 * - Handles different accepted token types and their corresponding return types.
 */
export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false> {
Expand DownExpand Up@@ -235,3 +234,51 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
 */
 (req: RequestType, options?: PendingSessionOptions): MaybePromise<SessionAuthObject, ReturnsPromise>;
}

/**
 * Shared generic overload type for auth() or getAuth() helpers that don't require a request parameter.
 *
 * - Handles different accepted token types and their corresponding return types.
 * - The SessionAuthType parameter allows frameworks to extend the base SessionAuthObject with additional properties like redirect methods.
 */
export interface GetAuthFnNoRequest<
 SessionAuthType extends SessionAuthObject = SessionAuthObject,
 ReturnsPromise extends boolean = false,
> {
 /**
 * @example
 * const authObject = await auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 | InferAuthObjectFromTokenArray<T, SessionAuthType, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
 | InvalidTokenAuthObject,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 InferAuthObjectFromToken<T, SessionAuthType, MachineAuthObject<Exclude<T, SessionTokenType>>>,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'any' })
 */
 (
 options: AuthOptions & { acceptsToken: 'any' },
 ): MaybePromise<Exclude<AuthObject, SessionAuthObject> | SessionAuthType, ReturnsPromise>;

 /**
 * @example
 * const authObject = await auth()
 */
 (options?: PendingSessionOptions): MaybePromise<SessionAuthType, ReturnsPromise>;
}

7 changes: 2 additions & 5 deletions
packages/express/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
import type { AuthenticateRequestOptions, GetAuthFn } from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { Request as ExpressRequest } from 'express';

import { middlewareRequired } from './errors';
import { requestHasAuthObject } from './utils';

type GetAuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

/**
 * Retrieves the Clerk AuthObject using the current request object.
 *
 * @param {GetAuthOptions} options - Optional configuration for retriving auth object.
 * @returns {AuthObject} Object with information about the request state and claims.
 * @throws {Error} `clerkMiddleware` or `requireAuth` is required to be set in the middleware chain before this util is used.
 */
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: AuthOptions) => {
 if (!requestHasAuthObject(req)) {
 throw new Error(middlewareRequired('getAuth'));
 }
Expand Down

11 changes: 2 additions & 9 deletions
packages/fastify/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,17 +1,10 @@
import type {
 AuthenticateRequestOptions,
 GetAuthFn,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn, SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { FastifyRequest } from 'fastify';

import { pluginRegistrationRequired } from './errors';

type GetAuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: AuthOptions) => {
 const authReq = req as FastifyRequest & { auth: SignedInAuthObject | SignedOutAuthObject };

 if (!authReq.auth) {
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
chore(backend): Add helper type for auth helpers without request parameters#6910

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

wobsoriano
merged 7 commits into

from

Oct 7, 2025
 Merged


chore(backend): Add helper type for auth helpers without request parameters
#6910
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
acac59d

chore: Consolidate auth function helper types


wobsoriano Oct 3, 2025
a99c68c

chore: add changeset


wobsoriano Oct 3, 2025
5fb3d59

chore: update types


wobsoriano Oct 3, 2025
347fd83

chore: fix generic type


wobsoriano Oct 3, 2025
ea84310

chore: fix typedoc tests


wobsoriano Oct 3, 2025
5d93a54

chore: fix mimic next auth type


wobsoriano Oct 3, 2025
6471cc3

chore: update changeset


wobsoriano Oct 7, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


11 changes: 11 additions & 0 deletions
.changeset/real-trainers-knock.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
---
"@clerk/astro": patch
"@clerk/backend": patch
"@clerk/express": patch
"@clerk/fastify": patch
"@clerk/nextjs": patch
"@clerk/nuxt": patch
"@clerk/tanstack-react-start": patch
---

Added internal helper type for `auth` and `getAuth()` functions that don't require a request or context parameter

2 changes: 2 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -208,6 +208,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "nextjs/create-sync-get-auth.mdx",
 "nextjs/current-user.mdx",
 "nextjs/get-auth.mdx",
 "nextjs/session-auth-with-redirect.mdx",
 "clerk-react/api-keys.mdx",
 "clerk-react/checkout-button-props.mdx",
 "clerk-react/checkout-button.mdx",
Expand DownExpand Up@@ -247,6 +248,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/email-address.mdx",
 "backend/external-account.mdx",
 "backend/feature.mdx",
 "backend/get-auth-fn-no-request.mdx",
 "backend/get-auth-fn.mdx",
 "backend/identification-link.mdx",
 "backend/infer-auth-object-from-token-array.mdx",
Expand Down

11 changes: 3 additions & 8 deletions
packages/astro/src/server/clerk-middleware.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
import type { AuthObject, ClerkClient } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 AuthOptions,
 ClerkRequest,
 RedirectFun,
 RequestState,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import {
 AuthStatus,
Expand DownExpand Up@@ -36,18 +35,14 @@ import type {
 AstroMiddlewareNextParam,
 AstroMiddlewareReturn,
 AuthFn,
AuthOptions,
SessionAuthObjectWithRedirect,
} from './types';
import { isRedirect, setHeader } from './utils';

const CONTROL_FLOW_ERROR = {
 REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
};

type ClerkMiddlewareAuthObject = (SignedInAuthObject | SignedOutAuthObject) & {
 redirectToSignIn: (opts?: { returnBackUrl?: URL | string | null }) => Response;
};

type ClerkAstroMiddlewareHandler = (
 auth: AuthFn,
 context: AstroMiddlewareContextParam,
Expand DownExpand Up@@ -396,7 +391,7 @@ const redirectAdapter = (url: string | URL) => {

const createMiddlewareRedirectToSignIn = (
 clerkRequest: ClerkRequest,
): ClerkMiddlewareAuthObject['redirectToSignIn'] => {
): SessionAuthObjectWithRedirect['redirectToSignIn'] => {
 return (opts = {}) => {
 const err = new Error(CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_IN) as any;
 err.returnBackUrl = opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkRequest.clerkUrl.toString();
Expand Down

52 changes: 4 additions & 48 deletions
packages/astro/src/server/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,5 @@
import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 RedirectFun,
 SessionTokenType,
 TokenType,
} from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { SessionAuthObject } from '@clerk/backend';
import type { GetAuthFnNoRequest, RedirectFun } from '@clerk/backend/internal';
import type { APIContext } from 'astro';

/**
Expand All@@ -26,44 +18,8 @@ export type AstroMiddlewareContextParam = APIContext;
export type AstroMiddlewareNextParam = MiddlewareNext;
export type AstroMiddlewareReturn = Response | Promise<Response>;

export type AuthOptions = PendingSessionOptions & Pick<AuthenticateRequestOptions, 'acceptsToken'>;

type SessionAuthObjectWithRedirect = SessionAuthObject & {
export type SessionAuthObjectWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
};

export interface AuthFn {
 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ):
 | InferAuthObjectFromTokenArray<
 T,
 SessionAuthObjectWithRedirect,
 MachineAuthObject<Exclude<T[number], SessionTokenType>>
 >
 | InvalidTokenAuthObject;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): InferAuthObjectFromToken<T, SessionAuthObjectWithRedirect, MachineAuthObject<Exclude<T, SessionTokenType>>>;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'any' })
 */
 (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;

 /**
 * @example
 * const auth = context.locals.auth()
 */
 (options?: PendingSessionOptions): SessionAuthObjectWithRedirect;
}
export type AuthFn = GetAuthFnNoRequest<SessionAuthObjectWithRedirect>;

2 changes: 2 additions & 0 deletions
packages/backend/src/internal.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,8 @@ export type {
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 GetAuthFn,
 AuthOptions,
 GetAuthFnNoRequest,
} from './tokens/types';

export { TokenType } from './tokens/tokenTypes';
Expand Down

132 changes: 91 additions & 41 deletions
packages/backend/src/tokens/__tests__/getAuth.test-d.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,49 +1,99 @@
import { expectTypeOf, test } from 'vitest';

import type { RedirectFun } from '../../createRedirect';
import type { AuthObject, InvalidTokenAuthObject } from '../authObjects';
import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';

// Across our SDKs, we have a getAuth() function
const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
};

test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toMatchTypeOf<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toMatchTypeOf<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toMatchTypeOf<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
import type { GetAuthFn, GetAuthFnNoRequest, MachineAuthObject, SessionAuthObject } from '../types';

describe('getAuth() or auth() with request parameter', () => {
 const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toExtend<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toExtend<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');

 const auth = getAuth(request, { acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toExtend<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');
describe('getAuth() or auth() without request parameter', () => {
 type SessionAuthWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
 redirectToSignUp: RedirectFun<Response>;
 };

 // Mimic Next.js auth() helper
 const auth: GetAuthFnNoRequest<SessionAuthWithRedirect, true> = (_options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', async () => {
 // Session token by default
 expectTypeOf(await auth()).toExtend<SessionAuthWithRedirect>();

 // Individual token types
 expectTypeOf(await auth({ acceptsToken: 'session_token' })).toExtend<SessionAuthWithRedirect>();
 expectTypeOf(await auth({ acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(await auth({ acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(await auth({ acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(await auth({ acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthWithRedirect | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(await auth({ acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(await auth({ acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 const auth = getAuth(request, { acceptsToken: 'any' });
 test('verifies discriminated union works correctly with acceptsToken: any', async () => {
 const authObject = await auth({ acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
 }
 if (authObject.tokenType === 'session_token') {
 expectTypeOf(authObject).toExtend<SessionAuthWithRedirect>();
 } else if (authObject.tokenType === 'api_key') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'api_key'>>();
 } else if (authObject.tokenType === 'm2m_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (authObject.tokenType === 'oauth_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

51 changes: 49 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -187,14 +187,13 @@ export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> =
 ? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
 : never;

type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
export type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

type MaybePromise<T, IsPromise extends boolean> = IsPromise extends true ? Promise<T> : T;

/**
 * Shared generic overload type for getAuth() helpers across SDKs.
 *
 * - Parameterized by the request type (RequestType).
 * - Handles different accepted token types and their corresponding return types.
 */
export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false> {
Expand DownExpand Up@@ -235,3 +234,51 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
 */
 (req: RequestType, options?: PendingSessionOptions): MaybePromise<SessionAuthObject, ReturnsPromise>;
}

/**
 * Shared generic overload type for auth() or getAuth() helpers that don't require a request parameter.
 *
 * - Handles different accepted token types and their corresponding return types.
 * - The SessionAuthType parameter allows frameworks to extend the base SessionAuthObject with additional properties like redirect methods.
 */
export interface GetAuthFnNoRequest<
 SessionAuthType extends SessionAuthObject = SessionAuthObject,
 ReturnsPromise extends boolean = false,
> {
 /**
 * @example
 * const authObject = await auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 | InferAuthObjectFromTokenArray<T, SessionAuthType, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
 | InvalidTokenAuthObject,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 InferAuthObjectFromToken<T, SessionAuthType, MachineAuthObject<Exclude<T, SessionTokenType>>>,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'any' })
 */
 (
 options: AuthOptions & { acceptsToken: 'any' },
 ): MaybePromise<Exclude<AuthObject, SessionAuthObject> | SessionAuthType, ReturnsPromise>;

 /**
 * @example
 * const authObject = await auth()
 */
 (options?: PendingSessionOptions): MaybePromise<SessionAuthType, ReturnsPromise>;
}

7 changes: 2 additions & 5 deletions
packages/express/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
import type { AuthenticateRequestOptions, GetAuthFn } from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { Request as ExpressRequest } from 'express';

import { middlewareRequired } from './errors';
import { requestHasAuthObject } from './utils';

type GetAuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

/**
 * Retrieves the Clerk AuthObject using the current request object.
 *
 * @param {GetAuthOptions} options - Optional configuration for retriving auth object.
 * @returns {AuthObject} Object with information about the request state and claims.
 * @throws {Error} `clerkMiddleware` or `requireAuth` is required to be set in the middleware chain before this util is used.
 */
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: AuthOptions) => {
 if (!requestHasAuthObject(req)) {
 throw new Error(middlewareRequired('getAuth'));
 }
Expand Down

11 changes: 2 additions & 9 deletions
packages/fastify/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,17 +1,10 @@
import type {
 AuthenticateRequestOptions,
 GetAuthFn,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn, SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { FastifyRequest } from 'fastify';

import { pluginRegistrationRequired } from './errors';

type GetAuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: AuthOptions) => {
 const authReq = req as FastifyRequest & { auth: SignedInAuthObject | SignedOutAuthObject };

 if (!authReq.auth) {
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
chore(backend): Add helper type for auth helpers without request parameters#6910

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

wobsoriano
merged 7 commits into

from

Oct 7, 2025
 Merged


chore(backend): Add helper type for auth helpers without request parameters
#6910
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
acac59d

chore: Consolidate auth function helper types


wobsoriano Oct 3, 2025
a99c68c

chore: add changeset


wobsoriano Oct 3, 2025
5fb3d59

chore: update types


wobsoriano Oct 3, 2025
347fd83

chore: fix generic type


wobsoriano Oct 3, 2025
ea84310

chore: fix typedoc tests


wobsoriano Oct 3, 2025
5d93a54

chore: fix mimic next auth type


wobsoriano Oct 3, 2025
6471cc3

chore: update changeset


wobsoriano Oct 7, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


11 changes: 11 additions & 0 deletions
.changeset/real-trainers-knock.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
---
"@clerk/astro": patch
"@clerk/backend": patch
"@clerk/express": patch
"@clerk/fastify": patch
"@clerk/nextjs": patch
"@clerk/nuxt": patch
"@clerk/tanstack-react-start": patch
---

Added internal helper type for `auth` and `getAuth()` functions that don't require a request or context parameter

2 changes: 2 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -208,6 +208,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "nextjs/create-sync-get-auth.mdx",
 "nextjs/current-user.mdx",
 "nextjs/get-auth.mdx",
 "nextjs/session-auth-with-redirect.mdx",
 "clerk-react/api-keys.mdx",
 "clerk-react/checkout-button-props.mdx",
 "clerk-react/checkout-button.mdx",
Expand DownExpand Up@@ -247,6 +248,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/email-address.mdx",
 "backend/external-account.mdx",
 "backend/feature.mdx",
 "backend/get-auth-fn-no-request.mdx",
 "backend/get-auth-fn.mdx",
 "backend/identification-link.mdx",
 "backend/infer-auth-object-from-token-array.mdx",
Expand Down

11 changes: 3 additions & 8 deletions
packages/astro/src/server/clerk-middleware.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
import type { AuthObject, ClerkClient } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 AuthOptions,
 ClerkRequest,
 RedirectFun,
 RequestState,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import {
 AuthStatus,
Expand DownExpand Up@@ -36,18 +35,14 @@ import type {
 AstroMiddlewareNextParam,
 AstroMiddlewareReturn,
 AuthFn,
AuthOptions,
SessionAuthObjectWithRedirect,
} from './types';
import { isRedirect, setHeader } from './utils';

const CONTROL_FLOW_ERROR = {
 REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
};

type ClerkMiddlewareAuthObject = (SignedInAuthObject | SignedOutAuthObject) & {
 redirectToSignIn: (opts?: { returnBackUrl?: URL | string | null }) => Response;
};

type ClerkAstroMiddlewareHandler = (
 auth: AuthFn,
 context: AstroMiddlewareContextParam,
Expand DownExpand Up@@ -396,7 +391,7 @@ const redirectAdapter = (url: string | URL) => {

const createMiddlewareRedirectToSignIn = (
 clerkRequest: ClerkRequest,
): ClerkMiddlewareAuthObject['redirectToSignIn'] => {
): SessionAuthObjectWithRedirect['redirectToSignIn'] => {
 return (opts = {}) => {
 const err = new Error(CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_IN) as any;
 err.returnBackUrl = opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkRequest.clerkUrl.toString();
Expand Down

52 changes: 4 additions & 48 deletions
packages/astro/src/server/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,5 @@
import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 RedirectFun,
 SessionTokenType,
 TokenType,
} from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { SessionAuthObject } from '@clerk/backend';
import type { GetAuthFnNoRequest, RedirectFun } from '@clerk/backend/internal';
import type { APIContext } from 'astro';

/**
Expand All@@ -26,44 +18,8 @@ export type AstroMiddlewareContextParam = APIContext;
export type AstroMiddlewareNextParam = MiddlewareNext;
export type AstroMiddlewareReturn = Response | Promise<Response>;

export type AuthOptions = PendingSessionOptions & Pick<AuthenticateRequestOptions, 'acceptsToken'>;

type SessionAuthObjectWithRedirect = SessionAuthObject & {
export type SessionAuthObjectWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
};

export interface AuthFn {
 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ):
 | InferAuthObjectFromTokenArray<
 T,
 SessionAuthObjectWithRedirect,
 MachineAuthObject<Exclude<T[number], SessionTokenType>>
 >
 | InvalidTokenAuthObject;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): InferAuthObjectFromToken<T, SessionAuthObjectWithRedirect, MachineAuthObject<Exclude<T, SessionTokenType>>>;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'any' })
 */
 (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;

 /**
 * @example
 * const auth = context.locals.auth()
 */
 (options?: PendingSessionOptions): SessionAuthObjectWithRedirect;
}
export type AuthFn = GetAuthFnNoRequest<SessionAuthObjectWithRedirect>;

2 changes: 2 additions & 0 deletions
packages/backend/src/internal.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,8 @@ export type {
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 GetAuthFn,
 AuthOptions,
 GetAuthFnNoRequest,
} from './tokens/types';

export { TokenType } from './tokens/tokenTypes';
Expand Down

132 changes: 91 additions & 41 deletions
packages/backend/src/tokens/__tests__/getAuth.test-d.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,49 +1,99 @@
import { expectTypeOf, test } from 'vitest';

import type { RedirectFun } from '../../createRedirect';
import type { AuthObject, InvalidTokenAuthObject } from '../authObjects';
import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';

// Across our SDKs, we have a getAuth() function
const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
};

test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toMatchTypeOf<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toMatchTypeOf<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toMatchTypeOf<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
import type { GetAuthFn, GetAuthFnNoRequest, MachineAuthObject, SessionAuthObject } from '../types';

describe('getAuth() or auth() with request parameter', () => {
 const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toExtend<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toExtend<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');

 const auth = getAuth(request, { acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toExtend<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');
describe('getAuth() or auth() without request parameter', () => {
 type SessionAuthWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
 redirectToSignUp: RedirectFun<Response>;
 };

 // Mimic Next.js auth() helper
 const auth: GetAuthFnNoRequest<SessionAuthWithRedirect, true> = (_options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', async () => {
 // Session token by default
 expectTypeOf(await auth()).toExtend<SessionAuthWithRedirect>();

 // Individual token types
 expectTypeOf(await auth({ acceptsToken: 'session_token' })).toExtend<SessionAuthWithRedirect>();
 expectTypeOf(await auth({ acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(await auth({ acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(await auth({ acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(await auth({ acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthWithRedirect | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(await auth({ acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(await auth({ acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 const auth = getAuth(request, { acceptsToken: 'any' });
 test('verifies discriminated union works correctly with acceptsToken: any', async () => {
 const authObject = await auth({ acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
 }
 if (authObject.tokenType === 'session_token') {
 expectTypeOf(authObject).toExtend<SessionAuthWithRedirect>();
 } else if (authObject.tokenType === 'api_key') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'api_key'>>();
 } else if (authObject.tokenType === 'm2m_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (authObject.tokenType === 'oauth_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

51 changes: 49 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -187,14 +187,13 @@ export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> =
 ? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
 : never;

type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
export type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

type MaybePromise<T, IsPromise extends boolean> = IsPromise extends true ? Promise<T> : T;

/**
 * Shared generic overload type for getAuth() helpers across SDKs.
 *
 * - Parameterized by the request type (RequestType).
 * - Handles different accepted token types and their corresponding return types.
 */
export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false> {
Expand DownExpand Up@@ -235,3 +234,51 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
 */
 (req: RequestType, options?: PendingSessionOptions): MaybePromise<SessionAuthObject, ReturnsPromise>;
}

/**
 * Shared generic overload type for auth() or getAuth() helpers that don't require a request parameter.
 *
 * - Handles different accepted token types and their corresponding return types.
 * - The SessionAuthType parameter allows frameworks to extend the base SessionAuthObject with additional properties like redirect methods.
 */
export interface GetAuthFnNoRequest<
 SessionAuthType extends SessionAuthObject = SessionAuthObject,
 ReturnsPromise extends boolean = false,
> {
 /**
 * @example
 * const authObject = await auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 | InferAuthObjectFromTokenArray<T, SessionAuthType, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
 | InvalidTokenAuthObject,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 InferAuthObjectFromToken<T, SessionAuthType, MachineAuthObject<Exclude<T, SessionTokenType>>>,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'any' })
 */
 (
 options: AuthOptions & { acceptsToken: 'any' },
 ): MaybePromise<Exclude<AuthObject, SessionAuthObject> | SessionAuthType, ReturnsPromise>;

 /**
 * @example
 * const authObject = await auth()
 */
 (options?: PendingSessionOptions): MaybePromise<SessionAuthType, ReturnsPromise>;
}

7 changes: 2 additions & 5 deletions
packages/express/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
import type { AuthenticateRequestOptions, GetAuthFn } from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { Request as ExpressRequest } from 'express';

import { middlewareRequired } from './errors';
import { requestHasAuthObject } from './utils';

type GetAuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

/**
 * Retrieves the Clerk AuthObject using the current request object.
 *
 * @param {GetAuthOptions} options - Optional configuration for retriving auth object.
 * @returns {AuthObject} Object with information about the request state and claims.
 * @throws {Error} `clerkMiddleware` or `requireAuth` is required to be set in the middleware chain before this util is used.
 */
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: AuthOptions) => {
 if (!requestHasAuthObject(req)) {
 throw new Error(middlewareRequired('getAuth'));
 }
Expand Down

11 changes: 2 additions & 9 deletions
packages/fastify/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,17 +1,10 @@
import type {
 AuthenticateRequestOptions,
 GetAuthFn,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn, SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { FastifyRequest } from 'fastify';

import { pluginRegistrationRequired } from './errors';

type GetAuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: AuthOptions) => {
 const authReq = req as FastifyRequest & { auth: SignedInAuthObject | SignedOutAuthObject };

 if (!authReq.auth) {
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
chore(backend): Add helper type for auth helpers without request parameters#6910

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

wobsoriano
merged 7 commits into

from

Oct 7, 2025
 Merged


chore(backend): Add helper type for auth helpers without request parameters
#6910
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
acac59d

chore: Consolidate auth function helper types


wobsoriano Oct 3, 2025
a99c68c

chore: add changeset


wobsoriano Oct 3, 2025
5fb3d59

chore: update types


wobsoriano Oct 3, 2025
347fd83

chore: fix generic type


wobsoriano Oct 3, 2025
ea84310

chore: fix typedoc tests


wobsoriano Oct 3, 2025
5d93a54

chore: fix mimic next auth type


wobsoriano Oct 3, 2025
6471cc3

chore: update changeset


wobsoriano Oct 7, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


11 changes: 11 additions & 0 deletions
.changeset/real-trainers-knock.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
---
"@clerk/astro": patch
"@clerk/backend": patch
"@clerk/express": patch
"@clerk/fastify": patch
"@clerk/nextjs": patch
"@clerk/nuxt": patch
"@clerk/tanstack-react-start": patch
---

Added internal helper type for `auth` and `getAuth()` functions that don't require a request or context parameter

2 changes: 2 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -208,6 +208,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "nextjs/create-sync-get-auth.mdx",
 "nextjs/current-user.mdx",
 "nextjs/get-auth.mdx",
 "nextjs/session-auth-with-redirect.mdx",
 "clerk-react/api-keys.mdx",
 "clerk-react/checkout-button-props.mdx",
 "clerk-react/checkout-button.mdx",
Expand DownExpand Up@@ -247,6 +248,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/email-address.mdx",
 "backend/external-account.mdx",
 "backend/feature.mdx",
 "backend/get-auth-fn-no-request.mdx",
 "backend/get-auth-fn.mdx",
 "backend/identification-link.mdx",
 "backend/infer-auth-object-from-token-array.mdx",
Expand Down

11 changes: 3 additions & 8 deletions
packages/astro/src/server/clerk-middleware.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
import type { AuthObject, ClerkClient } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 AuthOptions,
 ClerkRequest,
 RedirectFun,
 RequestState,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import {
 AuthStatus,
Expand DownExpand Up@@ -36,18 +35,14 @@ import type {
 AstroMiddlewareNextParam,
 AstroMiddlewareReturn,
 AuthFn,
AuthOptions,
SessionAuthObjectWithRedirect,
} from './types';
import { isRedirect, setHeader } from './utils';

const CONTROL_FLOW_ERROR = {
 REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
};

type ClerkMiddlewareAuthObject = (SignedInAuthObject | SignedOutAuthObject) & {
 redirectToSignIn: (opts?: { returnBackUrl?: URL | string | null }) => Response;
};

type ClerkAstroMiddlewareHandler = (
 auth: AuthFn,
 context: AstroMiddlewareContextParam,
Expand DownExpand Up@@ -396,7 +391,7 @@ const redirectAdapter = (url: string | URL) => {

const createMiddlewareRedirectToSignIn = (
 clerkRequest: ClerkRequest,
): ClerkMiddlewareAuthObject['redirectToSignIn'] => {
): SessionAuthObjectWithRedirect['redirectToSignIn'] => {
 return (opts = {}) => {
 const err = new Error(CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_IN) as any;
 err.returnBackUrl = opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkRequest.clerkUrl.toString();
Expand Down

52 changes: 4 additions & 48 deletions
packages/astro/src/server/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,5 @@
import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 RedirectFun,
 SessionTokenType,
 TokenType,
} from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { SessionAuthObject } from '@clerk/backend';
import type { GetAuthFnNoRequest, RedirectFun } from '@clerk/backend/internal';
import type { APIContext } from 'astro';

/**
Expand All@@ -26,44 +18,8 @@ export type AstroMiddlewareContextParam = APIContext;
export type AstroMiddlewareNextParam = MiddlewareNext;
export type AstroMiddlewareReturn = Response | Promise<Response>;

export type AuthOptions = PendingSessionOptions & Pick<AuthenticateRequestOptions, 'acceptsToken'>;

type SessionAuthObjectWithRedirect = SessionAuthObject & {
export type SessionAuthObjectWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
};

export interface AuthFn {
 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ):
 | InferAuthObjectFromTokenArray<
 T,
 SessionAuthObjectWithRedirect,
 MachineAuthObject<Exclude<T[number], SessionTokenType>>
 >
 | InvalidTokenAuthObject;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): InferAuthObjectFromToken<T, SessionAuthObjectWithRedirect, MachineAuthObject<Exclude<T, SessionTokenType>>>;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'any' })
 */
 (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;

 /**
 * @example
 * const auth = context.locals.auth()
 */
 (options?: PendingSessionOptions): SessionAuthObjectWithRedirect;
}
export type AuthFn = GetAuthFnNoRequest<SessionAuthObjectWithRedirect>;

2 changes: 2 additions & 0 deletions
packages/backend/src/internal.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,8 @@ export type {
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 GetAuthFn,
 AuthOptions,
 GetAuthFnNoRequest,
} from './tokens/types';

export { TokenType } from './tokens/tokenTypes';
Expand Down

132 changes: 91 additions & 41 deletions
packages/backend/src/tokens/__tests__/getAuth.test-d.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,49 +1,99 @@
import { expectTypeOf, test } from 'vitest';

import type { RedirectFun } from '../../createRedirect';
import type { AuthObject, InvalidTokenAuthObject } from '../authObjects';
import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';

// Across our SDKs, we have a getAuth() function
const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
};

test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toMatchTypeOf<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toMatchTypeOf<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toMatchTypeOf<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
import type { GetAuthFn, GetAuthFnNoRequest, MachineAuthObject, SessionAuthObject } from '../types';

describe('getAuth() or auth() with request parameter', () => {
 const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toExtend<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toExtend<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');

 const auth = getAuth(request, { acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toExtend<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');
describe('getAuth() or auth() without request parameter', () => {
 type SessionAuthWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
 redirectToSignUp: RedirectFun<Response>;
 };

 // Mimic Next.js auth() helper
 const auth: GetAuthFnNoRequest<SessionAuthWithRedirect, true> = (_options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', async () => {
 // Session token by default
 expectTypeOf(await auth()).toExtend<SessionAuthWithRedirect>();

 // Individual token types
 expectTypeOf(await auth({ acceptsToken: 'session_token' })).toExtend<SessionAuthWithRedirect>();
 expectTypeOf(await auth({ acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(await auth({ acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(await auth({ acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(await auth({ acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthWithRedirect | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(await auth({ acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(await auth({ acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 const auth = getAuth(request, { acceptsToken: 'any' });
 test('verifies discriminated union works correctly with acceptsToken: any', async () => {
 const authObject = await auth({ acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
 }
 if (authObject.tokenType === 'session_token') {
 expectTypeOf(authObject).toExtend<SessionAuthWithRedirect>();
 } else if (authObject.tokenType === 'api_key') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'api_key'>>();
 } else if (authObject.tokenType === 'm2m_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (authObject.tokenType === 'oauth_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

51 changes: 49 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -187,14 +187,13 @@ export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> =
 ? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
 : never;

type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
export type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

type MaybePromise<T, IsPromise extends boolean> = IsPromise extends true ? Promise<T> : T;

/**
 * Shared generic overload type for getAuth() helpers across SDKs.
 *
 * - Parameterized by the request type (RequestType).
 * - Handles different accepted token types and their corresponding return types.
 */
export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false> {
Expand DownExpand Up@@ -235,3 +234,51 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
 */
 (req: RequestType, options?: PendingSessionOptions): MaybePromise<SessionAuthObject, ReturnsPromise>;
}

/**
 * Shared generic overload type for auth() or getAuth() helpers that don't require a request parameter.
 *
 * - Handles different accepted token types and their corresponding return types.
 * - The SessionAuthType parameter allows frameworks to extend the base SessionAuthObject with additional properties like redirect methods.
 */
export interface GetAuthFnNoRequest<
 SessionAuthType extends SessionAuthObject = SessionAuthObject,
 ReturnsPromise extends boolean = false,
> {
 /**
 * @example
 * const authObject = await auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 | InferAuthObjectFromTokenArray<T, SessionAuthType, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
 | InvalidTokenAuthObject,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 InferAuthObjectFromToken<T, SessionAuthType, MachineAuthObject<Exclude<T, SessionTokenType>>>,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'any' })
 */
 (
 options: AuthOptions & { acceptsToken: 'any' },
 ): MaybePromise<Exclude<AuthObject, SessionAuthObject> | SessionAuthType, ReturnsPromise>;

 /**
 * @example
 * const authObject = await auth()
 */
 (options?: PendingSessionOptions): MaybePromise<SessionAuthType, ReturnsPromise>;
}

7 changes: 2 additions & 5 deletions
packages/express/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
import type { AuthenticateRequestOptions, GetAuthFn } from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { Request as ExpressRequest } from 'express';

import { middlewareRequired } from './errors';
import { requestHasAuthObject } from './utils';

type GetAuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

/**
 * Retrieves the Clerk AuthObject using the current request object.
 *
 * @param {GetAuthOptions} options - Optional configuration for retriving auth object.
 * @returns {AuthObject} Object with information about the request state and claims.
 * @throws {Error} `clerkMiddleware` or `requireAuth` is required to be set in the middleware chain before this util is used.
 */
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: AuthOptions) => {
 if (!requestHasAuthObject(req)) {
 throw new Error(middlewareRequired('getAuth'));
 }
Expand Down

11 changes: 2 additions & 9 deletions
packages/fastify/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,17 +1,10 @@
import type {
 AuthenticateRequestOptions,
 GetAuthFn,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn, SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { FastifyRequest } from 'fastify';

import { pluginRegistrationRequired } from './errors';

type GetAuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: AuthOptions) => {
 const authReq = req as FastifyRequest & { auth: SignedInAuthObject | SignedOutAuthObject };

 if (!authReq.auth) {
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
chore(backend): Add helper type for auth helpers without request parameters#6910

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

wobsoriano
merged 7 commits into

from

Oct 7, 2025
 Merged


chore(backend): Add helper type for auth helpers without request parameters
#6910
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
acac59d

chore: Consolidate auth function helper types


wobsoriano Oct 3, 2025
a99c68c

chore: add changeset


wobsoriano Oct 3, 2025
5fb3d59

chore: update types


wobsoriano Oct 3, 2025
347fd83

chore: fix generic type


wobsoriano Oct 3, 2025
ea84310

chore: fix typedoc tests


wobsoriano Oct 3, 2025
5d93a54

chore: fix mimic next auth type


wobsoriano Oct 3, 2025
6471cc3

chore: update changeset


wobsoriano Oct 7, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


11 changes: 11 additions & 0 deletions
.changeset/real-trainers-knock.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
---
"@clerk/astro": patch
"@clerk/backend": patch
"@clerk/express": patch
"@clerk/fastify": patch
"@clerk/nextjs": patch
"@clerk/nuxt": patch
"@clerk/tanstack-react-start": patch
---

Added internal helper type for `auth` and `getAuth()` functions that don't require a request or context parameter

2 changes: 2 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -208,6 +208,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "nextjs/create-sync-get-auth.mdx",
 "nextjs/current-user.mdx",
 "nextjs/get-auth.mdx",
 "nextjs/session-auth-with-redirect.mdx",
 "clerk-react/api-keys.mdx",
 "clerk-react/checkout-button-props.mdx",
 "clerk-react/checkout-button.mdx",
Expand DownExpand Up@@ -247,6 +248,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/email-address.mdx",
 "backend/external-account.mdx",
 "backend/feature.mdx",
 "backend/get-auth-fn-no-request.mdx",
 "backend/get-auth-fn.mdx",
 "backend/identification-link.mdx",
 "backend/infer-auth-object-from-token-array.mdx",
Expand Down

11 changes: 3 additions & 8 deletions
packages/astro/src/server/clerk-middleware.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
import type { AuthObject, ClerkClient } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 AuthOptions,
 ClerkRequest,
 RedirectFun,
 RequestState,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import {
 AuthStatus,
Expand DownExpand Up@@ -36,18 +35,14 @@ import type {
 AstroMiddlewareNextParam,
 AstroMiddlewareReturn,
 AuthFn,
AuthOptions,
SessionAuthObjectWithRedirect,
} from './types';
import { isRedirect, setHeader } from './utils';

const CONTROL_FLOW_ERROR = {
 REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
};

type ClerkMiddlewareAuthObject = (SignedInAuthObject | SignedOutAuthObject) & {
 redirectToSignIn: (opts?: { returnBackUrl?: URL | string | null }) => Response;
};

type ClerkAstroMiddlewareHandler = (
 auth: AuthFn,
 context: AstroMiddlewareContextParam,
Expand DownExpand Up@@ -396,7 +391,7 @@ const redirectAdapter = (url: string | URL) => {

const createMiddlewareRedirectToSignIn = (
 clerkRequest: ClerkRequest,
): ClerkMiddlewareAuthObject['redirectToSignIn'] => {
): SessionAuthObjectWithRedirect['redirectToSignIn'] => {
 return (opts = {}) => {
 const err = new Error(CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_IN) as any;
 err.returnBackUrl = opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkRequest.clerkUrl.toString();
Expand Down

52 changes: 4 additions & 48 deletions
packages/astro/src/server/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,5 @@
import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 RedirectFun,
 SessionTokenType,
 TokenType,
} from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { SessionAuthObject } from '@clerk/backend';
import type { GetAuthFnNoRequest, RedirectFun } from '@clerk/backend/internal';
import type { APIContext } from 'astro';

/**
Expand All@@ -26,44 +18,8 @@ export type AstroMiddlewareContextParam = APIContext;
export type AstroMiddlewareNextParam = MiddlewareNext;
export type AstroMiddlewareReturn = Response | Promise<Response>;

export type AuthOptions = PendingSessionOptions & Pick<AuthenticateRequestOptions, 'acceptsToken'>;

type SessionAuthObjectWithRedirect = SessionAuthObject & {
export type SessionAuthObjectWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
};

export interface AuthFn {
 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ):
 | InferAuthObjectFromTokenArray<
 T,
 SessionAuthObjectWithRedirect,
 MachineAuthObject<Exclude<T[number], SessionTokenType>>
 >
 | InvalidTokenAuthObject;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): InferAuthObjectFromToken<T, SessionAuthObjectWithRedirect, MachineAuthObject<Exclude<T, SessionTokenType>>>;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'any' })
 */
 (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;

 /**
 * @example
 * const auth = context.locals.auth()
 */
 (options?: PendingSessionOptions): SessionAuthObjectWithRedirect;
}
export type AuthFn = GetAuthFnNoRequest<SessionAuthObjectWithRedirect>;

2 changes: 2 additions & 0 deletions
packages/backend/src/internal.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,8 @@ export type {
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 GetAuthFn,
 AuthOptions,
 GetAuthFnNoRequest,
} from './tokens/types';

export { TokenType } from './tokens/tokenTypes';
Expand Down

132 changes: 91 additions & 41 deletions
packages/backend/src/tokens/__tests__/getAuth.test-d.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,49 +1,99 @@
import { expectTypeOf, test } from 'vitest';

import type { RedirectFun } from '../../createRedirect';
import type { AuthObject, InvalidTokenAuthObject } from '../authObjects';
import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';

// Across our SDKs, we have a getAuth() function
const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
};

test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toMatchTypeOf<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toMatchTypeOf<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toMatchTypeOf<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
import type { GetAuthFn, GetAuthFnNoRequest, MachineAuthObject, SessionAuthObject } from '../types';

describe('getAuth() or auth() with request parameter', () => {
 const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toExtend<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toExtend<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');

 const auth = getAuth(request, { acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toExtend<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');
describe('getAuth() or auth() without request parameter', () => {
 type SessionAuthWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
 redirectToSignUp: RedirectFun<Response>;
 };

 // Mimic Next.js auth() helper
 const auth: GetAuthFnNoRequest<SessionAuthWithRedirect, true> = (_options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', async () => {
 // Session token by default
 expectTypeOf(await auth()).toExtend<SessionAuthWithRedirect>();

 // Individual token types
 expectTypeOf(await auth({ acceptsToken: 'session_token' })).toExtend<SessionAuthWithRedirect>();
 expectTypeOf(await auth({ acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(await auth({ acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(await auth({ acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(await auth({ acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthWithRedirect | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(await auth({ acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(await auth({ acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 const auth = getAuth(request, { acceptsToken: 'any' });
 test('verifies discriminated union works correctly with acceptsToken: any', async () => {
 const authObject = await auth({ acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
 }
 if (authObject.tokenType === 'session_token') {
 expectTypeOf(authObject).toExtend<SessionAuthWithRedirect>();
 } else if (authObject.tokenType === 'api_key') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'api_key'>>();
 } else if (authObject.tokenType === 'm2m_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (authObject.tokenType === 'oauth_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

51 changes: 49 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -187,14 +187,13 @@ export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> =
 ? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
 : never;

type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
export type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

type MaybePromise<T, IsPromise extends boolean> = IsPromise extends true ? Promise<T> : T;

/**
 * Shared generic overload type for getAuth() helpers across SDKs.
 *
 * - Parameterized by the request type (RequestType).
 * - Handles different accepted token types and their corresponding return types.
 */
export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false> {
Expand DownExpand Up@@ -235,3 +234,51 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
 */
 (req: RequestType, options?: PendingSessionOptions): MaybePromise<SessionAuthObject, ReturnsPromise>;
}

/**
 * Shared generic overload type for auth() or getAuth() helpers that don't require a request parameter.
 *
 * - Handles different accepted token types and their corresponding return types.
 * - The SessionAuthType parameter allows frameworks to extend the base SessionAuthObject with additional properties like redirect methods.
 */
export interface GetAuthFnNoRequest<
 SessionAuthType extends SessionAuthObject = SessionAuthObject,
 ReturnsPromise extends boolean = false,
> {
 /**
 * @example
 * const authObject = await auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 | InferAuthObjectFromTokenArray<T, SessionAuthType, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
 | InvalidTokenAuthObject,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 InferAuthObjectFromToken<T, SessionAuthType, MachineAuthObject<Exclude<T, SessionTokenType>>>,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'any' })
 */
 (
 options: AuthOptions & { acceptsToken: 'any' },
 ): MaybePromise<Exclude<AuthObject, SessionAuthObject> | SessionAuthType, ReturnsPromise>;

 /**
 * @example
 * const authObject = await auth()
 */
 (options?: PendingSessionOptions): MaybePromise<SessionAuthType, ReturnsPromise>;
}

7 changes: 2 additions & 5 deletions
packages/express/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
import type { AuthenticateRequestOptions, GetAuthFn } from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { Request as ExpressRequest } from 'express';

import { middlewareRequired } from './errors';
import { requestHasAuthObject } from './utils';

type GetAuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

/**
 * Retrieves the Clerk AuthObject using the current request object.
 *
 * @param {GetAuthOptions} options - Optional configuration for retriving auth object.
 * @returns {AuthObject} Object with information about the request state and claims.
 * @throws {Error} `clerkMiddleware` or `requireAuth` is required to be set in the middleware chain before this util is used.
 */
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: AuthOptions) => {
 if (!requestHasAuthObject(req)) {
 throw new Error(middlewareRequired('getAuth'));
 }
Expand Down

11 changes: 2 additions & 9 deletions
packages/fastify/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,17 +1,10 @@
import type {
 AuthenticateRequestOptions,
 GetAuthFn,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn, SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { FastifyRequest } from 'fastify';

import { pluginRegistrationRequired } from './errors';

type GetAuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: AuthOptions) => {
 const authReq = req as FastifyRequest & { auth: SignedInAuthObject | SignedOutAuthObject };

 if (!authReq.auth) {
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
chore(backend): Add helper type for auth helpers without request parameters#6910

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

wobsoriano
merged 7 commits into

from

Oct 7, 2025
 Merged


chore(backend): Add helper type for auth helpers without request parameters
#6910
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


7 commits


Select commit
Hold shift + click to select a range
acac59d

chore: Consolidate auth function helper types


wobsoriano Oct 3, 2025
a99c68c

chore: add changeset


wobsoriano Oct 3, 2025
5fb3d59

chore: update types


wobsoriano Oct 3, 2025
347fd83

chore: fix generic type


wobsoriano Oct 3, 2025
ea84310

chore: fix typedoc tests


wobsoriano Oct 3, 2025
5d93a54

chore: fix mimic next auth type


wobsoriano Oct 3, 2025
6471cc3

chore: update changeset


wobsoriano Oct 7, 2025

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


11 changes: 11 additions & 0 deletions
.changeset/real-trainers-knock.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
---
"@clerk/astro": patch
"@clerk/backend": patch
"@clerk/express": patch
"@clerk/fastify": patch
"@clerk/nextjs": patch
"@clerk/nuxt": patch
"@clerk/tanstack-react-start": patch
---

Added internal helper type for `auth` and `getAuth()` functions that don't require a request or context parameter

2 changes: 2 additions & 0 deletions
.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -208,6 +208,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "nextjs/create-sync-get-auth.mdx",
 "nextjs/current-user.mdx",
 "nextjs/get-auth.mdx",
 "nextjs/session-auth-with-redirect.mdx",
 "clerk-react/api-keys.mdx",
 "clerk-react/checkout-button-props.mdx",
 "clerk-react/checkout-button.mdx",
Expand DownExpand Up@@ -247,6 +248,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
 "backend/email-address.mdx",
 "backend/external-account.mdx",
 "backend/feature.mdx",
 "backend/get-auth-fn-no-request.mdx",
 "backend/get-auth-fn.mdx",
 "backend/identification-link.mdx",
 "backend/infer-auth-object-from-token-array.mdx",
Expand Down

11 changes: 3 additions & 8 deletions
packages/astro/src/server/clerk-middleware.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
import type { AuthObject, ClerkClient } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 AuthOptions,
 ClerkRequest,
 RedirectFun,
 RequestState,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import {
 AuthStatus,
Expand DownExpand Up@@ -36,18 +35,14 @@ import type {
 AstroMiddlewareNextParam,
 AstroMiddlewareReturn,
 AuthFn,
AuthOptions,
SessionAuthObjectWithRedirect,
} from './types';
import { isRedirect, setHeader } from './utils';

const CONTROL_FLOW_ERROR = {
 REDIRECT_TO_SIGN_IN: 'CLERK_PROTECT_REDIRECT_TO_SIGN_IN',
};

type ClerkMiddlewareAuthObject = (SignedInAuthObject | SignedOutAuthObject) & {
 redirectToSignIn: (opts?: { returnBackUrl?: URL | string | null }) => Response;
};

type ClerkAstroMiddlewareHandler = (
 auth: AuthFn,
 context: AstroMiddlewareContextParam,
Expand DownExpand Up@@ -396,7 +391,7 @@ const redirectAdapter = (url: string | URL) => {

const createMiddlewareRedirectToSignIn = (
 clerkRequest: ClerkRequest,
): ClerkMiddlewareAuthObject['redirectToSignIn'] => {
): SessionAuthObjectWithRedirect['redirectToSignIn'] => {
 return (opts = {}) => {
 const err = new Error(CONTROL_FLOW_ERROR.REDIRECT_TO_SIGN_IN) as any;
 err.returnBackUrl = opts.returnBackUrl === null ? '' : opts.returnBackUrl || clerkRequest.clerkUrl.toString();
Expand Down

52 changes: 4 additions & 48 deletions
packages/astro/src/server/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,13 +1,5 @@
import type { AuthObject, InvalidTokenAuthObject, MachineAuthObject, SessionAuthObject } from '@clerk/backend';
import type {
 AuthenticateRequestOptions,
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 RedirectFun,
 SessionTokenType,
 TokenType,
} from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { SessionAuthObject } from '@clerk/backend';
import type { GetAuthFnNoRequest, RedirectFun } from '@clerk/backend/internal';
import type { APIContext } from 'astro';

/**
Expand All@@ -26,44 +18,8 @@ export type AstroMiddlewareContextParam = APIContext;
export type AstroMiddlewareNextParam = MiddlewareNext;
export type AstroMiddlewareReturn = Response | Promise<Response>;

export type AuthOptions = PendingSessionOptions & Pick<AuthenticateRequestOptions, 'acceptsToken'>;

type SessionAuthObjectWithRedirect = SessionAuthObject & {
export type SessionAuthObjectWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
};

export interface AuthFn {
 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ):
 | InferAuthObjectFromTokenArray<
 T,
 SessionAuthObjectWithRedirect,
 MachineAuthObject<Exclude<T[number], SessionTokenType>>
 >
 | InvalidTokenAuthObject;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): InferAuthObjectFromToken<T, SessionAuthObjectWithRedirect, MachineAuthObject<Exclude<T, SessionTokenType>>>;

 /**
 * @example
 * const auth = context.locals.auth({ acceptsToken: 'any' })
 */
 (options: AuthOptions & { acceptsToken: 'any' }): AuthObject;

 /**
 * @example
 * const auth = context.locals.auth()
 */
 (options?: PendingSessionOptions): SessionAuthObjectWithRedirect;
}
export type AuthFn = GetAuthFnNoRequest<SessionAuthObjectWithRedirect>;

2 changes: 2 additions & 0 deletions
packages/backend/src/internal.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -13,6 +13,8 @@ export type {
 InferAuthObjectFromToken,
 InferAuthObjectFromTokenArray,
 GetAuthFn,
 AuthOptions,
 GetAuthFnNoRequest,
} from './tokens/types';

export { TokenType } from './tokens/tokenTypes';
Expand Down

132 changes: 91 additions & 41 deletions
packages/backend/src/tokens/__tests__/getAuth.test-d.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,49 +1,99 @@
import { expectTypeOf, test } from 'vitest';

import type { RedirectFun } from '../../createRedirect';
import type { AuthObject, InvalidTokenAuthObject } from '../authObjects';
import type { GetAuthFn, MachineAuthObject, SessionAuthObject } from '../types';

// Across our SDKs, we have a getAuth() function
const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
};

test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toMatchTypeOf<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toMatchTypeOf<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toMatchTypeOf<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toMatchTypeOf<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toMatchTypeOf<AuthObject>();
import type { GetAuthFn, GetAuthFnNoRequest, MachineAuthObject, SessionAuthObject } from '../types';

describe('getAuth() or auth() with request parameter', () => {
 const getAuth: GetAuthFn<Request> = (_request: any, _options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', () => {
 const request = new Request('https://example.com');

 // Session token by default
 expectTypeOf(getAuth(request)).toExtend<SessionAuthObject>();

 // Individual token types
 expectTypeOf(getAuth(request, { acceptsToken: 'session_token' })).toExtend<SessionAuthObject>();
 expectTypeOf(getAuth(request, { acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(getAuth(request, { acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(getAuth(request, { acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthObject | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(getAuth(request, { acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(getAuth(request, { acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');

 const auth = getAuth(request, { acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toExtend<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

test('verifies discriminated union works correctly with acceptsToken: any', () => {
 const request = new Request('https://example.com');
describe('getAuth() or auth() without request parameter', () => {
 type SessionAuthWithRedirect = SessionAuthObject & {
 redirectToSignIn: RedirectFun<Response>;
 redirectToSignUp: RedirectFun<Response>;
 };

 // Mimic Next.js auth() helper
 const auth: GetAuthFnNoRequest<SessionAuthWithRedirect, true> = (_options: any) => {
 return {} as any;
 };

 test('infers the correct AuthObject type for each accepted token type', async () => {
 // Session token by default
 expectTypeOf(await auth()).toExtend<SessionAuthWithRedirect>();

 // Individual token types
 expectTypeOf(await auth({ acceptsToken: 'session_token' })).toExtend<SessionAuthWithRedirect>();
 expectTypeOf(await auth({ acceptsToken: 'api_key' })).toExtend<MachineAuthObject<'api_key'>>();
 expectTypeOf(await auth({ acceptsToken: 'm2m_token' })).toExtend<MachineAuthObject<'m2m_token'>>();
 expectTypeOf(await auth({ acceptsToken: 'oauth_token' })).toExtend<MachineAuthObject<'oauth_token'>>();

 // Array of token types
 expectTypeOf(await auth({ acceptsToken: ['session_token', 'm2m_token'] })).toExtend<
 SessionAuthWithRedirect | MachineAuthObject<'m2m_token'> | InvalidTokenAuthObject
 >();
 expectTypeOf(await auth({ acceptsToken: ['m2m_token', 'oauth_token'] })).toExtend<
 MachineAuthObject<'m2m_token' | 'oauth_token'> | InvalidTokenAuthObject
 >();

 // Any token type
 expectTypeOf(await auth({ acceptsToken: 'any' })).toExtend<AuthObject>();
 });

 const auth = getAuth(request, { acceptsToken: 'any' });
 test('verifies discriminated union works correctly with acceptsToken: any', async () => {
 const authObject = await auth({ acceptsToken: 'any' });

 if (auth.tokenType === 'session_token') {
 expectTypeOf(auth).toMatchTypeOf<SessionAuthObject>();
 } else if (auth.tokenType === 'api_key') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'api_key'>>();
 } else if (auth.tokenType === 'm2m_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'m2m_token'>>();
 } else if (auth.tokenType === 'oauth_token') {
 expectTypeOf(auth).toMatchTypeOf<MachineAuthObject<'oauth_token'>>();
 }
 if (authObject.tokenType === 'session_token') {
 expectTypeOf(authObject).toExtend<SessionAuthWithRedirect>();
 } else if (authObject.tokenType === 'api_key') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'api_key'>>();
 } else if (authObject.tokenType === 'm2m_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'m2m_token'>>();
 } else if (authObject.tokenType === 'oauth_token') {
 expectTypeOf(authObject).toExtend<MachineAuthObject<'oauth_token'>>();
 }
 });
});

51 changes: 49 additions & 2 deletions
packages/backend/src/tokens/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -187,14 +187,13 @@ export type MachineAuthObject<T extends Exclude<TokenType, SessionTokenType>> =
 ? AuthenticatedMachineObject<T> | UnauthenticatedMachineObject<T>
 : never;

type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };
export type AuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

type MaybePromise<T, IsPromise extends boolean> = IsPromise extends true ? Promise<T> : T;

/**
 * Shared generic overload type for getAuth() helpers across SDKs.
 *
 * - Parameterized by the request type (RequestType).
 * - Handles different accepted token types and their corresponding return types.
 */
export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false> {
Expand DownExpand Up@@ -235,3 +234,51 @@ export interface GetAuthFn<RequestType, ReturnsPromise extends boolean = false>
 */
 (req: RequestType, options?: PendingSessionOptions): MaybePromise<SessionAuthObject, ReturnsPromise>;
}

/**
 * Shared generic overload type for auth() or getAuth() helpers that don't require a request parameter.
 *
 * - Handles different accepted token types and their corresponding return types.
 * - The SessionAuthType parameter allows frameworks to extend the base SessionAuthObject with additional properties like redirect methods.
 */
export interface GetAuthFnNoRequest<
 SessionAuthType extends SessionAuthObject = SessionAuthObject,
 ReturnsPromise extends boolean = false,
> {
 /**
 * @example
 * const authObject = await auth({ acceptsToken: ['session_token', 'api_key'] })
 */
 <T extends TokenType[]>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 | InferAuthObjectFromTokenArray<T, SessionAuthType, MachineAuthObject<Exclude<T[number], SessionTokenType>>>
 | InvalidTokenAuthObject,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'session_token' })
 */
 <T extends TokenType>(
 options: AuthOptions & { acceptsToken: T },
 ): MaybePromise<
 InferAuthObjectFromToken<T, SessionAuthType, MachineAuthObject<Exclude<T, SessionTokenType>>>,
 ReturnsPromise
 >;

 /**
 * @example
 * const authObject = await auth({ acceptsToken: 'any' })
 */
 (
 options: AuthOptions & { acceptsToken: 'any' },
 ): MaybePromise<Exclude<AuthObject, SessionAuthObject> | SessionAuthType, ReturnsPromise>;

 /**
 * @example
 * const authObject = await auth()
 */
 (options?: PendingSessionOptions): MaybePromise<SessionAuthType, ReturnsPromise>;
}

7 changes: 2 additions & 5 deletions
packages/express/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
import type { AuthenticateRequestOptions, GetAuthFn } from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { PendingSessionOptions } from '@clerk/types';
import type { Request as ExpressRequest } from 'express';

import { middlewareRequired } from './errors';
import { requestHasAuthObject } from './utils';

type GetAuthOptions = PendingSessionOptions & { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

/**
 * Retrieves the Clerk AuthObject using the current request object.
 *
 * @param {GetAuthOptions} options - Optional configuration for retriving auth object.
 * @returns {AuthObject} Object with information about the request state and claims.
 * @throws {Error} `clerkMiddleware` or `requireAuth` is required to be set in the middleware chain before this util is used.
 */
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<ExpressRequest> = ((req: ExpressRequest, options?: AuthOptions) => {
 if (!requestHasAuthObject(req)) {
 throw new Error(middlewareRequired('getAuth'));
 }
Expand Down

11 changes: 2 additions & 9 deletions
packages/fastify/src/getAuth.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,17 +1,10 @@
import type {
 AuthenticateRequestOptions,
 GetAuthFn,
 SignedInAuthObject,
 SignedOutAuthObject,
} from '@clerk/backend/internal';
import type { AuthOptions, GetAuthFn, SignedInAuthObject, SignedOutAuthObject } from '@clerk/backend/internal';
import { getAuthObjectForAcceptedToken } from '@clerk/backend/internal';
import type { FastifyRequest } from 'fastify';

import { pluginRegistrationRequired } from './errors';

type GetAuthOptions = { acceptsToken?: AuthenticateRequestOptions['acceptsToken'] };

export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: GetAuthOptions) => {
export const getAuth: GetAuthFn<FastifyRequest> = ((req: FastifyRequest, options?: AuthOptions) => {
 const authReq = req as FastifyRequest & { auth: SignedInAuthObject | SignedOutAuthObject };

 if (!authReq.auth) {
Expand Down
Loading
Loading