opaque claim

Author: thiskevinwang

packages/shared/src/types/jwtv2.ts

@@ -98,10 +98,9 @@ type JWTPayloadBase = {
   sts?: SessionStatusClaim;
 
   /**
-   * Reserved session claim. When present, the session is operating under
-   * a restricted scope and SDK consumers should treat affected
-   * functionality as unavailable. The claim shape is opaque and may
-   * change without notice.
+   * Reserved session claim. The claim shape is opaque and may change
+   * without notice. Do not depend on its presence or absence for
+   * authorization checks.
    */
   ams?: AmsClaim;
 
@@ -223,20 +222,9 @@ export type AgentActClaim = ActClaim & { type: 'agent' };
 export type SessionStatusClaim = Extract<SessionStatus, 'active' | 'pending'>;
 
 /**
- * Shape of the optional `ams` session claim. Carries an identifier and a
- * list of opaque scope strings that constrain what the session is
- * permitted to do. Both fields should be treated as opaque tokens; their
- * vocabulary is owned by the issuer and may change without notice.
+ * Opaque optional `ams` session claim. Consumers must not inspect its value
+ * or depend on its presence or absence for authorization checks.
  *
  * @inline
  */
-export interface AmsClaim {
-  /**
-   * Opaque identifier the session is scoped to.
-   */
-  app_id: string;
-  /**
-   * Opaque scope strings. Consumers should test for membership only.
-   */
-  scopes: string[];
-}
+export type AmsClaim = unknown;

packages/ui/src/hooks/__tests__/useAms.test.ts

@@ -0,0 +1,54 @@
+import type { JwtPayload } from '@clerk/shared/types';
+import { renderHook } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useAms } from '../useAms';
+
+const { mockUseSession } = vi.hoisted(() => ({
+  mockUseSession: vi.fn(),
+}));
+
+vi.mock('@clerk/shared/react', () => ({
+  useSession: mockUseSession,
+}));
+
+const mockClaims = (claims: JwtPayload | undefined) => {
+  mockUseSession.mockReturnValue({
+    session: claims
+      ? {
+          lastActiveToken: {
+            jwt: { claims },
+          },
+        }
+      : null,
+  });
+};
+
+describe('useAms', () => {
+  beforeEach(() => {
+    mockUseSession.mockReset();
+  });
+
+  it('returns inactive when the ams claim is absent', () => {
+    mockClaims({ __raw: 'token' } as JwtPayload);
+
+    const { result } = renderHook(() => useAms());
+
+    expect(result.current).toEqual({ isActive: false });
+  });
+
+  it('returns active when the ams claim is present without reading its value', () => {
+    const claims = { __raw: 'token' } as JwtPayload;
+    Object.defineProperty(claims, 'ams', {
+      enumerable: true,
+      get: () => {
+        throw new Error('ams should be opaque');
+      },
+    });
+    mockClaims(claims);
+
+    const { result } = renderHook(() => useAms());
+
+    expect(result.current).toEqual({ isActive: true });
+  });
+});

packages/ui/src/hooks/useAms.ts

@@ -1,55 +1,32 @@
 import { useSession } from '@clerk/shared/react';
-import type { AmsClaim } from '@clerk/shared/types';
 
 /**
- * Return shape for {@link useAms}. Splits the "claim absent" case from
- * the "claim present" case so callers can use `hasScope` unconditionally
- * — when the claim is absent `hasScope` always returns `true`, meaning
- * sites that read `if (!hasScope('foo')) hide()` keep working on
- * regular sessions.
+ * Return shape for {@link useAms}. The claim is opaque, so callers should
+ * only branch on whether it is present.
  */
-export type UseAmsReturn =
-  | {
-      isActive: false;
-      appId: undefined;
-      scopes: undefined;
-      hasScope: () => true;
-    }
-  | {
-      isActive: true;
-      appId: string;
-      scopes: string[];
-      hasScope: (scope: string) => boolean;
-    };
+export type UseAmsReturn = {
+  isActive: boolean;
+};
 
 const INACTIVE: UseAmsReturn = {
   isActive: false,
-  appId: undefined,
-  scopes: undefined,
-  hasScope: () => true,
 };
 
 /**
  * Returns information about the optional `ams` claim on the active
- * session. When the claim is present the session is operating under a
- * restricted scope; the returned `hasScope` helper can be used to gate
- * UI on individual scope strings.
+ * session. The claim shape is intentionally opaque.
  *
  * Reactive — re-renders when the session token rotates.
  */
 export const useAms = (): UseAmsReturn => {
   const { session } = useSession();
-  const ams = session?.lastActiveToken?.jwt?.claims.ams as AmsClaim | undefined;
+  const claims = session?.lastActiveToken?.jwt?.claims;
 
-  if (!ams || typeof ams.app_id !== 'string') {
+  if (!claims || !Object.prototype.hasOwnProperty.call(claims, 'ams')) {
     return INACTIVE;
   }
 
-  const scopes = Array.isArray(ams.scopes) ? ams.scopes : [];
   return {
     isActive: true,
-    appId: ams.app_id,
-    scopes,
-    hasScope: (scope: string) => scopes.includes(scope),
   };
 };