packages/backend/src/tokens/request.ts (1)

656-663: ⚠️ Potential issue

acceptsToken may be an array – leads to wrong tokenType in signed-out state

acceptsToken is cast to MachineTokenType, but when the caller supplied an array (e.g. ['api_key','machine_token']) this branch is still reached and signedOut() will receive an array instead of a string, violating the expected contract and potentially blowing up downstream logic that pattern-matches on tokenType.

-  return signedOut({
-    tokenType: acceptsToken as MachineTokenType,
+  const fallbackTokenType =
+    Array.isArray(acceptsToken) ? TokenType.MachineToken : (acceptsToken as MachineTokenType);
+  return signedOut({
+    tokenType: fallbackTokenType,

At minimum guard with Array.isArray, or refactor the control-flow earlier so that authenticateMachineRequestWithTokenInHeader is never called when acceptsToken is an array.

packages/nextjs/src/server/clerkMiddleware.ts (1)

286-297: Minor: make “Bearer ” stripping case-insensitive

replace('Bearer ', '') misses the common lowercase form (bearer ) and variants with extra spacing, which would cause isMachineTokenByPrefix to receive an untrimmed string and return false.

-const authHeader = getHeader(request, constants.Headers.Authorization)?.replace('Bearer ', '') ?? '';
+const authHeader =
+  getHeader(request, constants.Headers.Authorization)
+    // Strip the bearer scheme in a case-insensitive way and any leading spaces
+    ?.replace(/^Bearer\s+/i, '') ?? '';

packages/backend/src/tokens/request.ts (1)

691-709: (optional) avoid duplicate prefix scanning

isMachineTokenByPrefix is executed, and on the success path getMachineTokenType scans the prefixes again. Caching the mapping (prefix → type) removes the extra work and keeps the two helpers in sync.

packages/backend/src/tokens/machine.ts (2)

21-23: Unify prefix → type logic & avoid double iteration

Both isMachineTokenByPrefix and getMachineTokenType perform separate prefix scans.
Creating one canonical lookup avoids divergence and improves perf (especially if custom prefixes grow).

-const MACHINE_TOKEN_PREFIXES = [M2M_TOKEN_PREFIX, OAUTH_TOKEN_PREFIX, API_KEY_PREFIX] as const;
+const PREFIX_TO_TYPE: Record<string, MachineTokenType> = {
+  [M2M_TOKEN_PREFIX]: TokenType.MachineToken,
+  [OAUTH_TOKEN_PREFIX]: TokenType.OAuthToken,
+  [API_KEY_PREFIX]: TokenType.ApiKey,
+} as const;
+
+const MACHINE_TOKEN_PREFIXES = Object.keys(PREFIX_TO_TYPE);

 export function isMachineTokenByPrefix(token: string): boolean {
-  return MACHINE_TOKEN_PREFIXES.some(prefix => token.startsWith(prefix));
+  return MACHINE_TOKEN_PREFIXES.some(prefix => token.startsWith(prefix));
 }

 export function getMachineTokenType(token: string): MachineTokenType {
-  if (token.startsWith(M2M_TOKEN_PREFIX)) {
-    return TokenType.MachineToken;
-  }
-  ...
-  throw new Error('Unknown machine token type');
+  for (const [prefix, type] of Object.entries(PREFIX_TO_TYPE)) {
+    if (token.startsWith(prefix)) {
+      return type;
+    }
+  }
+  throw new Error('Unknown machine token type');
 }

Also applies to: 36-50, 71-79

---

77-79: Nit: rename parameter for clarity

Using the identifier type for the function parameter shadows its semantic meaning. tokenType is more explicit and avoids confusion.

-export function isMachineTokenType(type: string): type is MachineTokenType {
-  return type === TokenType.ApiKey || type === TokenType.MachineToken || type === TokenType.OAuthToken;
+export function isMachineTokenType(tokenType: string): tokenType is MachineTokenType {
+  return (
+    tokenType === TokenType.ApiKey ||
+    tokenType === TokenType.MachineToken ||
+    tokenType === TokenType.OAuthToken
+  );
 }

packages/backend/src/tokens/__tests__/machine.test.ts (2)

13-13: Rename describe block to match the renamed helper.

The suite is still titled isMachineToken, but the implementation under test is now isMachineTokenByPrefix.
Keeping the names in sync avoids confusion when reading test output.

-describe('isMachineToken', () => {
+describe('isMachineTokenByPrefix', () => {

---

82-93: Broaden negative-case coverage for isMachineTokenType.

Consider adding non-machine strings with similar shapes ('api_Key', 'API_KEY', etc.) to ensure the predicate remains case- and value-sensitive.

   it('returns false for non-machine token types', () => {
     expect(isMachineTokenType('session_token')).toBe(false);
+    expect(isMachineTokenType('api_Key')).toBe(false);   // mixed case
+    expect(isMachineTokenType('API_KEY')).toBe(false);   // upper case
   });

packages/nextjs/src/server/__tests__/getAuthDataFromRequest.test.ts (3)

45-47: Use the correct unauthenticated type in assertions.

auth is expected to be unauthenticated, but the cast uses AuthenticatedMachineObject.
Switching to UnauthenticatedMachineObject prevents accidental misuse of authenticated-only members in future edits.

-    expect((auth as AuthenticatedMachineObject<'machine_token'>).machineId).toBeNull();
+    expect(
+      (auth as UnauthenticatedMachineObject<'machine_token'>).machineId,
+    ).toBeNull();

---

50-63: Same casting nit – unauthenticated object.

Apply the same type-accurate cast here.

-    expect((auth as AuthenticatedMachineObject<'api_key'>).userId).toBeNull();
+    expect((auth as UnauthenticatedMachineObject<'api_key'>).userId).toBeNull();

---

65-71: Reset mocked verification between tests to avoid leakage.

verifyMachineAuthToken is globally mocked and mutated in multiple tests.
Add an afterEach(() => vi.resetAllMocks()) (or restoreAllMocks) to ensure each test starts with a clean slate.

32
 describe('getAuthDataFromRequestAsync', () => {
+  afterEach(() => {
+    vi.resetAllMocks();
+  });

packages/nextjs/src/server/data/getAuthDataFromRequest.ts (2)

171-173: Redundant null-check on tokenType.

handleMachineToken is only invoked when tokenType is already defined.
The early guard can be removed, simplifying the flow.

-  if (!tokenType) {
-    return signedOutAuthObject(options);
-  }

---

188-223: Nested conditional complexity ‑ consider flattening for readability.

handleIntentBased now has three levels of branching plus early returns.
A small refactor to guard-clauses / separate helpers would improve maintainability, especially as fallback rules evolve.

(No diff provided – structural suggestion.)

packages/backend/src/tokens/__tests__/authObjects.test.ts (3)

393-428: Consider table-driven tests to reduce duplication

All five scenarios are valuable, but the structure is repetitive and could be collapsed into a parameterised (table-driven) test:

const cases = [
  { acceptsToken: 'any',         auth: machineAuth, expectedType: 'api_key'          },
  { acceptsToken: 'api_key',     auth: machineAuth, expectedType: 'api_key'          },
  { acceptsToken: ['machine_token','oauth_token'],
                               auth: machineAuth, expectedType: 'api_key'          },
  { acceptsToken: ['api_key','oauth_token'],
                               auth: sessionAuth, expectedType: 'session_token'     },
  { acceptsToken: 'machine_token',
                               auth: machineAuth, expectedType: 'machine_token'     },
] as const;

cases.forEach(({acceptsToken, auth, expectedType}) =>
  it(`returns correct object for acceptsToken=${JSON.stringify(acceptsToken)}`, () => {
    const result = getAuthObjectForAcceptedToken({authObject: auth, acceptsToken});
    expect(result.tokenType).toBe(expectedType);
  }),
);

This eliminates boilerplate, makes future additions trivial, and keeps intent crystal-clear.

---

408-415: Broaden assertions for stronger guarantees

Only tokenType and id are asserted. If downstream logic relies on other properties (name, subject, scopes, etc.), they could silently regress without detection. Suggest asserting the entire object shape for the unauthenticated machine variant:

expect(result).toMatchObject({
  tokenType: 'api_key',
  id: null,
  subject: null,
  scopes: null,
  claims: null,
});

Strengthens the safety net with negligible overhead.

---

423-427: Minor semantic nit – variable naming

machineAuth actually represents an API-key auth object. Renaming to apiKeyAuth makes the mismatch between the provided token (api_key) and the requested one (machine_token) more explicit and self-documenting.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

.changeset/open-swans-count.md (1)

6-6: Clarify the changeset summary for future readers

A single-sentence summary is fine, but adding one more phrase about how the fallback now behaves (e.g., “returns an unauthenticated object of the accepted token type rather than the parsed token type”) would make the patch note self-contained and clearer in changelogs.

packages/fastify/src/__tests__/getAuth.test.ts (1)

37-43: Update the inline comment to match the new behaviour

The expectation is now api_key because it mirrors the accepted token type, not the actual token found.
Leaving the old wording is misleading for future maintainers.

-    expect(result.tokenType).toBe('api_key'); // reflects the actual token found
+    expect(result.tokenType).toBe('api_key'); // mirrors the *accepted* token type

packages/express/src/__tests__/getAuth.test.ts (1)

40-46: Fix the stale comment to avoid confusion

Same as in the Fastify test: the returned tokenType reflects the accepted token type, not the one on the incoming request. Adjust the comment accordingly.

-    expect(result.tokenType).toBe('api_key'); // reflects the actual token found
+    expect(result.tokenType).toBe('api_key'); // mirrors the *accepted* token type

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

packages/nextjs/src/server/protect.ts (1)

144-151: Consider folding the new null check into the existing guard for cleaner flow

Functionally this works, but we now have two adjacent early-return guards that both call handleUnauthorized().
Combining them (or moving the null check first) keeps the intent crystal-clear and avoids an unnecessary call to isTokenTypeAccepted when the token is already known to be invalid.

-  if (!isTokenTypeAccepted(authObject.tokenType, requestedToken)) {
-    return handleUnauthorized();
-  }
-
-  if (authObject.tokenType === null) {
-    return handleUnauthorized();
-  }
+  if (
+    authObject.tokenType === null ||
+    !isTokenTypeAccepted(authObject.tokenType, requestedToken)
+  ) {
+    return handleUnauthorized();
+  }

Same behaviour, fewer branches.
Use or ignore at your discretion.

packages/nextjs/src/app-router/server/auth.ts (1)

59-65: Document the new InvalidTokenAuthObject return path

The overload now rightfully includes InvalidTokenAuthObject, but the surrounding JSDoc (@example lines 52-56) still states “returns the auth object” without mentioning this extra unauthenticated variant. Adding a short note (or an extra example) will prevent consumers from overlooking the possibility of the invalid-token path and improves IntelliSense docs.

packages/backend/src/tokens/types.ts (1)

204-206: Synchronise docs & ‘any’ overload with the new invalid token union

The array overload now unions InvalidTokenAuthObject, but:

1. The earlier JSDoc (@example lines 197-200) doesn’t mention that an invalid object may be returned.
2. The 'any' overload (line 225) still returns plain AuthObject; verify that AuthObject already includes InvalidTokenAuthObject, otherwise callers using 'any' won’t see this variant in their type checking.

Updating the docs and, if needed, the 'any' overload will keep the public contract crystal-clear.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

packages/backend/src/tokens/authObjects.ts (1)

455-462: ⚠️ Potential issue

authObject.debug is still passed as data – identical issue flagged previously

unauthenticatedMachineObject/signedOutAuthObject expect raw debug data which they wrap with createDebug.
Passing the already-wrapped authObject.debug (a function) leads to createDebug spreading a function and silently discarding the original context.

Issue was highlighted in an earlier review and remains unfixed.

-      return unauthenticatedMachineObject(acceptsToken, authObject.debug);
+      return unauthenticatedMachineObject(acceptsToken, authObject.debug?.());

-    return signedOutAuthObject(authObject.debug);
+    return signedOutAuthObject(authObject.debug?.());

Please apply the same fix everywhere this pattern occurs.

packages/backend/src/tokens/authObjects.ts (2)

151-157: Consider surfacing minimal debug context in InvalidTokenAuthObject

debug currently returns an empty object, so consumers lose request-level hints (e.g. headers) that might aid investigation. Passing through sanitised context (like in other factory helpers) would keep parity across auth-object variants.

---

361-372: invalidTokenAuthObject() duplicates boilerplate – could reuse helpers

Implementation is hand-rolled; reusing unauthenticatedMachineObject & friends (or a shared base factory) would avoid future drift if common props change.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro