User Authentication (login, whoami, config)

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/commands/login.ts
• packages/cli/src/commands/whoami.ts
• packages/cli/src/commands/config.ts
• packages/cli/src/core/user-config.ts
• packages/cli/src/commands/logout.ts
• packages/cli/src/core/auth.ts

The prpm CLI provides a set of commands to manage user authentication and configuration. This system allows users to log in to the PRPM registry, verify their identity, log out, and manage local configuration settings like the registry URL and authentication token. The core of this functionality revolves around a local JSON configuration file stored in the user's home directory.

Authentication is handled via a web-based OAuth flow, where the CLI temporarily runs a local server to capture the authentication token. This token is then stored locally for subsequent API requests. The config command provides a direct interface to view and modify the underlying configuration file, giving users control over their CLI environment.

Core Components

The authentication and configuration system is composed of several CLI commands and core modules that work together.

This diagram shows the dependency flow: CLI commands use the auth.ts module for authentication actions, which in turn relies on the user-config.ts module for storing and retrieving data from the file system. The config command interacts directly with user-config.ts.

Sources: packages/cli/src/commands/login.ts, packages/cli/src/commands/logout.ts, packages/cli/src/commands/whoami.ts, packages/cli/src/commands/config.ts, packages/cli/src/core/auth.ts, packages/cli/src/core/user-config.ts

User Configuration (user-config.ts)

The UserConfig class is the foundation for persistence. It manages a JSON file located at ~/.prpm/config.json.

• UserConfig.get(key): Retrieves a value for a specific key.
• UserConfig.set(key, value): Sets a value for a specific key.
• User-Config.getAll(): Returns all configuration data.
• UserConfig.delete(key): Removes a key from the configuration.
• UserConfig.clear(): Clears all configuration data.

Sources: packages/cli/src/core/user-config.ts:20-88

Auth Module (auth.ts)

This module provides a focused API for authentication data, abstracting the UserConfig class.

• getAuthConfig(): Retrieves the authToken from the user config.
• saveAuthConfig({ token }): Saves the authToken to the user config.
• clearAuthConfig(): Deletes the authToken from the user config.

Sources: packages/cli/src/core/auth.ts:9-25

Commands

prpm login

This command initiates a web-based OAuth 2.0 authentication flow to log the user into the PRPM registry.

Authentication Flow

The login process involves the CLI, the user's web browser, and the PRPM authentication server. The CLI starts a temporary local web server to receive the token via a callback.

This sequence diagram illustrates the prpm login process, from command execution to storing the token.

Sources: packages/cli/src/commands/login.ts:25-108

The implementation details include:

1. Creating a local HTTP server to listen on port 8999.
2. Opening the system's default browser to the registry's login page.
3. Waiting for the /callback request containing the JWT in a query parameter.
4. Calling saveAuthConfig to persist the token.
5. Sending a success HTML page to the browser and shutting down the server.

Sources: packages/cli/src/commands/login.ts:38-41, packages/cli/src/commands/login.ts:51, packages/cli/src/commands/login.ts:64-74, packages/cli/src/commands/login.ts:80-86

prpm whoami

This command allows a user to check their current login status and view their user information.

Process Flow

This flowchart shows how prpm whoami checks for and decodes the locally stored token to display user information.

The command performs the following steps:

1. Calls getAuthConfig() to retrieve the token from ~/.prpm/config.json.
2. If no token is found, it informs the user they are not logged in.
3. If a token is found, it decodes the JWT payload locally to extract user details like username and email.
4. It then displays this information to the user. The command does not appear to make a network request to validate the token's authenticity against the server; it only decodes it.

Sources: packages/cli/src/commands/whoami.ts:15-39

prpm logout

This command logs the user out by deleting their stored authentication token. It's a straightforward process that calls clearAuthConfig(), which in turn removes the authToken key from the ~/.prpm/config.json file.

Sources: packages/cli/src/commands/logout.ts:15-20, packages/cli/src/core/auth.ts:22-25, packages/cli/src/core/user-config.ts:77-82

prpm config

This command provides a direct interface to manage the ~/.prpm/config.json file. It supports getting, setting, and listing configuration values.

Subcommands

Subcommand	Description	Example
get <key>	Retrieves the value for a given configuration key.	prpm config get registryUrl
set <key> <value>	Sets a value for a given configuration key.	prpm config set registryUrl https://my.registry.dev
list	Displays all key-value pairs in the configuration file.	prpm config list
delete <key>	Deletes a key from the configuration file.	prpm config delete registryUrl

Sources: packages/cli/src/commands/config.ts:19-78

Configuration Keys

The primary keys managed by the configuration system are:

Key	Description	Managed By
authToken	The JWT used to authenticate with the PRPM registry.	login, logout, config
registryUrl	The URL of the PRPM registry.	config

Sources: packages/cli/src/core/user-config.ts:10, packages/cli/src/core/auth.ts:11

Summary

The user authentication and configuration system in prpm is a well-defined set of commands and modules that provide a secure and user-friendly way to manage sessions and settings. The login command uses a standard OAuth flow with a local server for a smooth user experience, while whoami and logout provide simple session management. The underlying UserConfig class offers a robust mechanism for persisting settings, which is exposed to the user through the versatile config command. This separation of concerns between commands, the auth module, and the user config module makes the system maintainable and easy to understand.