@palantir/pack.auth 0.0.1-beta.1

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@palantir/pack.auth",
+  "version": "0.0.1-beta.1",
+  "description": "Authentication system for PACK applications",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/palantir/pack.git"
+  },
+  "exports": {
+    ".": {
+      "browser": "./build/browser/index.js",
+      "import": {
+        "types": "./build/types/index.d.ts",
+        "default": "./build/esm/index.js"
+      },
+      "require": "./build/cjs/index.js",
+      "default": "./build/browser/index.js"
+    },
+    "./*": {
+      "browser": "./build/browser/public/*.js",
+      "import": {
+        "types": "./build/types/public/*.d.ts",
+        "default": "./build/js/public/*.js"
+      },
+      "require": "./build/cjs/public/*.js",
+      "default": "./build/browser/public/*.js"
+    }
+  },
+  "dependencies": {
+    "tiny-invariant": "^1.3.3",
+    "@palantir/pack.core": "0.1.0-beta.2"
+  },
+  "peerDependencies": {
+    "@osdk/client": "~2.4.2"
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.1",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.2",
+    "vitest-mock-extended": "^3.1.0",
+    "@palantir/pack.monorepo.tsconfig": "~0.4.0-beta.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pack",
+    "auth"
+  ],
+  "main": "./build/cjs/index.js",
+  "module": "./build/esm/index.js",
+  "types": "./build/cjs/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "clean": "rimraf .turbo build dist lib test-output *.tgz tsconfig.tsbuildinfo",
+    "lint": "eslint ./src ; dprint check --config $(find-up dprint.json) --allow-no-files",
+    "lint:fix": "eslint ./src --fix ; dprint fmt --config $(find-up dprint.json) --allow-no-files",
+    "test": "vitest run --passWithNoTests -u",
+    "test:watch": "vitest --passWithNoTests",
+    "transpileBrowser": "monorepo-transpile -f esm -m bundle -t browser",
+    "transpileCjs": "monorepo-transpile -f cjs -m bundle -t node",
+    "transpileEsm": "monorepo-transpile -f esm -m bundle -t node",
+    "transpileTypes": "monorepo-transpile -f esm -m types -t node",
+    "typecheck": "tsc --noEmit --emitDeclarationOnly false"
+  }
+}

package/src/__tests__/AuthModuleImpl.test.ts

@@ -0,0 +1,249 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { PackAppInternal } from "@palantir/pack.core";
+import type { MockedObject } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mockDeep } from "vitest-mock-extended";
+import { AuthModuleImpl, AuthState, type AuthStateCallback } from "../index.js";
+import type { BaseAuthService } from "../types/BaseAuthService.js";
+
+function createMockAuthService(
+  tokenValue = "mock-token",
+  overrides: Partial<BaseAuthService> = {},
+): MockedObject<BaseAuthService> {
+  const defaultService = {
+    dispose: vi.fn(),
+    getCurrentState: vi.fn().mockReturnValue(AuthState.Unauthenticated),
+    getCurrentUserId: vi.fn().mockReturnValue(undefined),
+    getToken: vi.fn().mockResolvedValue(tokenValue),
+    getTokenOrUndefined: vi.fn().mockReturnValue(undefined),
+    getUserData: vi.fn().mockResolvedValue({}),
+    isAuthenticated: vi.fn().mockReturnValue(false),
+    isValidated: vi.fn().mockReturnValue(false),
+    onAuthStateChange: vi.fn().mockReturnValue(vi.fn()),
+    refresh: vi.fn().mockResolvedValue(undefined),
+    signIn: vi.fn().mockResolvedValue(undefined),
+    signOut: vi.fn().mockResolvedValue(undefined),
+    validateToken: vi.fn().mockResolvedValue(true),
+    ...overrides,
+  };
+
+  return defaultService as MockedObject<BaseAuthService>;
+}
+
+describe("AuthModuleImpl", () => {
+  let authModule: AuthModuleImpl;
+
+  afterEach(() => {
+    authModule.dispose();
+  });
+
+  describe("with static token service", () => {
+    let authService: BaseAuthService;
+
+    beforeEach(() => {
+      // Create mock service that behaves like static token service
+      authService = createMockAuthService("static-token", {
+        isAuthenticated: vi.fn().mockReturnValue(true), // Static services start authenticated
+        signOut: vi.fn().mockRejectedValue(
+          new Error("Sign out not supported for static token providers"),
+        ),
+        refresh: undefined, // Static services don't support refresh
+      });
+
+      const mockApp = mockDeep<PackAppInternal>();
+
+      authModule = new AuthModuleImpl(mockApp, authService);
+    });
+
+    it("should be authenticated immediately", () => {
+      expect(authModule.isAuthenticated()).toBe(true);
+    });
+
+    it("should return token from provider", async () => {
+      const token = await authModule.getToken();
+      expect(token).toBe("static-token");
+      expect(authService.getToken).toHaveBeenCalled();
+    });
+
+    it("should return undefined for getTokenOrUndefined initially", () => {
+      expect(authModule.getTokenOrUndefined()).toBeUndefined();
+    });
+
+    it("should be no-op for signIn", async () => {
+      await expect(authModule.signIn()).resolves.toBeUndefined();
+    });
+
+    it("should reject signOut for static token providers", async () => {
+      await expect(authModule.signOut()).rejects.toThrow(
+        "Sign out not supported for static token providers",
+      );
+    });
+
+    it("should throw for refresh", async () => {
+      await expect(authModule.refresh()).rejects.toThrow("Refresh not supported");
+    });
+
+    it("should allow state change subscriptions", () => {
+      const callback = vi.fn();
+      const unsubscribe = authModule.onAuthStateChange(callback);
+
+      expect(typeof unsubscribe).toBe("function");
+      unsubscribe();
+    });
+
+    it("should resolve waitForAuth immediately when already authenticated", async () => {
+      await expect(authModule.waitForAuth()).resolves.toBeUndefined();
+    });
+  });
+
+  describe("with OAuth service", () => {
+    let mockApp: ReturnType<typeof mockDeep<PackAppInternal>>;
+    let mockAuthService: MockedObject<BaseAuthService>;
+
+    beforeEach(() => {
+      mockAuthService = createMockAuthService("oauth-token");
+      mockApp = mockDeep<PackAppInternal>();
+
+      authModule = new AuthModuleImpl(mockApp, mockAuthService);
+    });
+
+    it("should delegate isAuthenticated to service", () => {
+      expect(authModule.isAuthenticated()).toBe(false);
+      expect(mockAuthService.isAuthenticated).toHaveBeenCalled();
+    });
+
+    it("should delegate getToken to service", async () => {
+      const token = await authModule.getToken();
+      expect(token).toBe("oauth-token");
+      expect(mockAuthService.getToken).toHaveBeenCalled();
+    });
+
+    it("should delegate getTokenOrUndefined to service", () => {
+      const token = authModule.getTokenOrUndefined();
+      expect(token).toBeUndefined();
+      expect(mockAuthService.getTokenOrUndefined).toHaveBeenCalled();
+    });
+
+    it("should delegate signIn to service", async () => {
+      await authModule.signIn();
+      expect(mockAuthService.signIn).toHaveBeenCalled();
+    });
+
+    it("should delegate signOut to service", async () => {
+      await authModule.signOut();
+      expect(mockAuthService.signOut).toHaveBeenCalled();
+    });
+
+    it("should delegate refresh to service", async () => {
+      await authModule.refresh();
+      expect(mockAuthService.refresh).toHaveBeenCalled();
+    });
+
+    it("should delegate onAuthStateChange to service", () => {
+      const callback = vi.fn();
+      authModule.onAuthStateChange(callback);
+      expect(mockAuthService.onAuthStateChange).toHaveBeenCalledWith(callback);
+    });
+  });
+
+  describe("waitForAuth behavior", () => {
+    it("should resolve immediately when already authenticated", async () => {
+      const mockAuthService = createMockAuthService("test-token", {
+        isAuthenticated: vi.fn().mockReturnValue(true),
+      });
+
+      const mockApp = mockDeep<PackAppInternal>();
+
+      authModule = new AuthModuleImpl(mockApp, mockAuthService);
+
+      await expect(authModule.waitForAuth()).resolves.toBeUndefined();
+      expect(mockAuthService.onAuthStateChange).not.toHaveBeenCalled();
+    });
+
+    it("should wait for authentication event when not authenticated", async () => {
+      const mockUnsubscribe = vi.fn();
+      const mockAuthService = createMockAuthService("test-token", {
+        isAuthenticated: vi.fn().mockReturnValue(false),
+        onAuthStateChange: vi.fn().mockImplementation((callback: AuthStateCallback) => {
+          setTimeout(() => {
+            callback({
+              state: AuthState.Authenticated,
+              previousState: AuthState.Unauthenticated,
+            });
+          }, 10);
+          return mockUnsubscribe;
+        }),
+      });
+
+      const mockApp = mockDeep<PackAppInternal>();
+
+      authModule = new AuthModuleImpl(mockApp, mockAuthService);
+
+      await expect(authModule.waitForAuth()).resolves.toBeUndefined();
+      expect(mockAuthService.onAuthStateChange).toHaveBeenCalled();
+      expect(mockUnsubscribe).toHaveBeenCalled();
+    });
+
+    it("should reject on authentication error", async () => {
+      const mockUnsubscribe = vi.fn();
+      const error = new Error("Auth failed");
+      const mockAuthService = createMockAuthService("test-token", {
+        isAuthenticated: vi.fn().mockReturnValue(false),
+        onAuthStateChange: vi.fn().mockImplementation((callback: AuthStateCallback) => {
+          setTimeout(() => {
+            callback({
+              state: AuthState.Error,
+              previousState: AuthState.Authenticating,
+              error,
+            });
+          }, 10);
+          return mockUnsubscribe;
+        }),
+      });
+
+      const mockApp = mockDeep<PackAppInternal>();
+
+      authModule = new AuthModuleImpl(mockApp, mockAuthService);
+
+      await expect(authModule.waitForAuth()).rejects.toThrow("Authentication failed");
+      expect(mockUnsubscribe).toHaveBeenCalled();
+    });
+  });
+
+  describe("signIn deduplication", () => {
+    it("should deduplicate concurrent signIn calls", async () => {
+      const mockAuthService = createMockAuthService("test-token", {
+        signIn: vi.fn().mockImplementation(() => new Promise(resolve => setTimeout(resolve, 50))),
+      });
+
+      const mockApp = mockDeep<PackAppInternal>();
+
+      authModule = new AuthModuleImpl(mockApp, mockAuthService);
+
+      const promises = [
+        authModule.signIn(),
+        authModule.signIn(),
+        authModule.signIn(),
+      ];
+
+      await Promise.all(promises);
+
+      expect(mockAuthService.signIn).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/constants/AuthModuleKey.ts

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { ModuleKey, PackAppInternal } from "@palantir/pack.core";
+import type { AuthModule } from "../types/AuthModule.js";
+import type { AuthModuleConfig } from "../utils/AuthModuleConfig.js";
+import { AuthModuleImpl } from "../utils/AuthModuleImpl.js";
+
+export const AUTH_MODULE_KEY: ModuleKey<AuthModule, AuthModuleConfig> = {
+  appMemberName: "auth",
+  key: Symbol.for("pack.auth"),
+  initModule: (app: PackAppInternal, config?: AuthModuleConfig) => {
+    if (!config) {
+      throw new Error("AuthModuleConfig is required to initialize AuthModule");
+    }
+    return new AuthModuleImpl(app, config.authService);
+  },
+};

package/src/index.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { getAuthModule } from "./types/AuthModule.js";
+export type { AuthModule } from "./types/AuthModule.js";
+export { AuthState } from "./types/AuthState.js";
+export type { AuthStateCallback, AuthStateChangeEvent } from "./types/AuthState.js";
+export type { BaseAuthService } from "./types/BaseAuthService.js";
+export type { TokenChangeCallback } from "./types/TokenChange.js";
+export type { UnverifiedTokenInfo } from "./types/UnverifiedTokenInfo.js";
+export { createUserRef, invalidUserRef, isValidUserRef } from "./types/UserRef.js";
+export type { UserId, UserRef } from "./types/UserRef.js";
+export { type AuthModuleConfig, createAuthModuleConfig } from "./utils/AuthModuleConfig.js";
+export { AuthModuleImpl } from "./utils/AuthModuleImpl.js";

package/src/types/AuthModule.ts

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { PackAppInternal, Unsubscribe } from "@palantir/pack.core";
+import { assertIsAppInternal } from "@palantir/pack.core";
+import { AUTH_MODULE_KEY } from "../constants/AuthModuleKey.js";
+import type { AuthStateCallback } from "./AuthState.js";
+import type { TokenChangeCallback } from "./TokenChange.js";
+import type { UserRef } from "./UserRef.js";
+
+/**
+ * AuthModule provides unified authentication services for PACK applications.
+ *
+ * It wraps OSDK OAuth clients and provides a consistent interface for authentication
+ * state management, token access, and auth lifecycle events.
+ */
+// TODO: functions should be method style
+export interface AuthModule {
+  /**
+   * Get the current user information.
+   * Returns undefined if not authenticated or user data not available.
+   */
+  readonly getCurrentUser: () => UserRef | undefined;
+
+  /**
+   * Get an access token, automatically refreshing if needed.
+   * Throws if authentication fails or user is not signed in.
+   */
+  readonly getToken: () => Promise<string>;
+
+  /**
+   * Get the current access token without refresh, returns undefined if expired or unavailable.
+   */
+  readonly getTokenOrUndefined: () => string | undefined;
+
+  /**
+   * Get user data for a specific user ID.
+   * @param userId - The user ID to fetch data for
+   * @param force - Force refresh of cached data
+   * @returns Promise resolving to user data
+   */
+  readonly getUserData: (userId: string, force?: boolean) => Promise<unknown>;
+
+  /**
+   * Check if the user is currently authenticated with a valid token.
+   */
+  readonly isAuthenticated: () => boolean;
+
+  /**
+   * Subscribe to authentication state changes.
+   *
+   * @param callback Function called when auth state changes
+   * @returns Unsubscribe function
+   */
+  readonly onAuthStateChange: (callback: AuthStateCallback) => Unsubscribe;
+
+  /**
+   * Subscribe to token changes.
+   *
+   * @param callback Function called when token changes
+   * @returns Unsubscribe function
+   */
+  readonly onTokenChange: (callback: TokenChangeCallback) => Unsubscribe;
+
+  /**
+   * Manually refresh the access token using the refresh token.
+   * Only available for public OAuth clients.
+   */
+  readonly refresh?: () => Promise<void>;
+
+  /**
+   * Initiate sign-in flow. For public clients, this redirects to OAuth.
+   * For confidential clients, this performs client credentials flow.
+   */
+  readonly signIn: () => Promise<void>;
+
+  /**
+   * Sign out the current user and clear tokens.
+   */
+  readonly signOut: () => Promise<void>;
+
+  /**
+   * Validate the current token by checking with the platform API.
+   * Returns true if the token is valid, false otherwise.
+   */
+  readonly validateToken: () => Promise<boolean>;
+
+  /**
+   * Wait for authentication to complete. Resolves when authenticated,
+   * rejects if authentication fails or times out.
+   */
+  readonly waitForAuth: () => Promise<void>;
+}
+
+/**
+ * Get the auth module from an PACK app instance.
+ *
+ * @param app - PACK app instance
+ * @returns The auth module
+ */
+export function getAuthModule(app: PackAppInternal): AuthModule {
+  assertIsAppInternal(app);
+  return app.getModule(AUTH_MODULE_KEY);
+}

package/src/types/AuthState.ts

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const AuthState = {
+  Authenticated: "authenticated",
+  Authenticating: "authenticating",
+  Error: "error",
+  Initializing: "initializing",
+  Unauthenticated: "unauthenticated",
+} as const;
+
+export type AuthState = typeof AuthState[keyof typeof AuthState];
+
+export interface AuthStateChangeEvent {
+  readonly previousState?: AuthState;
+  readonly state: AuthState;
+  readonly error?: Error;
+}
+
+export type AuthStateCallback = (event: AuthStateChangeEvent) => void;

package/src/types/BaseAuthService.ts

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Unsubscribe } from "@palantir/pack.core";
+import type { AuthState, AuthStateCallback } from "./AuthState.js";
+import type { TokenChangeCallback } from "./TokenChange.js";
+
+/**
+ * Base interface for auth services that wrap different OAuth client implementations
+ */
+export interface BaseAuthService {
+  dispose(): void;
+  getCurrentState(): AuthState;
+  getCurrentUserId(): string | undefined;
+  getToken(): Promise<string>;
+  getTokenOrUndefined(): string | undefined;
+  getUserData(userId: string, force?: boolean): Promise<unknown>;
+  isAuthenticated(): boolean;
+  isValidated(): boolean;
+  onAuthStateChange(callback: AuthStateCallback): Unsubscribe;
+  onTokenChange(callback: TokenChangeCallback): Unsubscribe;
+  refresh?(): Promise<void>;
+  signIn(): Promise<void>;
+  signOut(): Promise<void>;
+  validateToken(): Promise<boolean>;
+}

package/src/types/TokenChange.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { UnverifiedTokenInfo } from "./UnverifiedTokenInfo.js";
+
+/**
+ * Callback function for token change events. A signout may fire a token change with undefined token.
+ */
+export type TokenChangeCallback = (
+  token: string | undefined,
+  info: UnverifiedTokenInfo,
+) => void;

package/src/types/UnverifiedTokenInfo.ts

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { UserId } from "./UserRef.js";
+
+/**
+ * Represents the parsed payload from a JWT token (unverified).
+ * The information provided should not be used for security-sensitive
+ * applications unless verified through some other process.
+ */
+export interface UnverifiedTokenInfo {
+  readonly expiryInstantUtc?: number;
+  readonly orgId?: string;
+  readonly sessionId?: string;
+  readonly tokenId?: string;
+  readonly userId?: UserId;
+}