@uipath/auth 1.203.0-preview.205 → 1.204.0-preview.206

package/README.md

@@ -2,52 +2,172 @@
 
 Authentication module for the UiPath CLI. Handles OIDC login, token management, and credential storage.
 
+This README covers the library API. For how the `uip` CLI uses it (login methods, named profiles, environment-variable auth, credential files), see the [Authentication Guide](https://github.com/UiPath/cli/blob/main/docs/guides/authentication.md) and the [Authentication Reference](https://github.com/UiPath/cli/blob/main/docs/reference/authentication.md).
+
 ## Installation
 
+The package is published to the GitHub Packages registry (`https://npm.pkg.github.com/@uipath`). With that registry configured for the `@uipath` scope:
+
 ```bash
 npm install @uipath/auth
 ```
 
 ## Usage
 
-### Interactive Login
+### Log in and save credentials
+
+`interactiveLogin` runs the whole login and writes the result to a credentials file. The flow is chosen by the options: the browser (authorization code + PKCE) by default, client credentials when a client secret is set, federated login when `clientAssertion` is set. The client secret can come from the `clientSecret` option or from a `clientSecret` pushed with `setAuthFileConfig` (the CLI pushes `auth.clientSecret` from `.uipath/config.json`), so with that set, a call with no `clientSecret` uses client credentials, not the browser.
 
 ```ts
 import { interactiveLogin } from "@uipath/auth";
 
-await interactiveLogin({ file: ".uipath" });
+function requireEnv(name: string): string {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`${name} is not set`);
+    }
+    return value;
+}
+
+// Browser login, saved to the default .uipath/.auth
+await interactiveLogin({ tenant: "DefaultTenant" });
+
+// Client credentials. Check the variables first: with no clientSecret,
+// interactiveLogin falls back to the browser flow instead of failing.
+await interactiveLogin({
+    clientId: requireEnv("UIPATH_CLIENT_ID"),
+    clientSecret: requireEnv("UIPATH_CLIENT_SECRET"),
+    tenant: "DefaultTenant",
+});
 ```
 
-### Client Credentials (CI/CD)
+`envFilePath` picks the file to write. An absolute path is used as is. A relative path (the default is `.uipath/.auth`) is looked for from the current directory upward, and a file found there is reused only if it already holds a `UIPATH_ACCESS_TOKEN`. A file without one, or one that cannot be read, is skipped. When nothing is reused, the credentials go under the home directory: `~/.uipath/.auth` for the default. The read functions below still pick a readable file that has no token, so an empty `.uipath/.auth` in the current directory or a parent hides the saved login from them.
+
+### Get tokens without saving them
 
 ```ts
-import { clientCredentialsLogin } from "@uipath/auth";
+import { clientCredentialsLogin, federatedCredentialsLogin } from "@uipath/auth";
 
+// requireEnv as in the example above: both calls take plain strings
 const tokens = await clientCredentialsLogin({
-    clientId: process.env.CLIENT_ID,
-    clientSecret: process.env.CLIENT_SECRET,
+    clientId: requireEnv("UIPATH_CLIENT_ID"),
+    clientSecret: requireEnv("UIPATH_CLIENT_SECRET"),
+});
+
+const federated = await federatedCredentialsLogin({
+    clientId: requireEnv("UIPATH_CLIENT_ID"),
+    clientAssertion: requireEnv("UIPATH_OIDC_TOKEN"),
 });
 ```
 
-### Check Login Status
+Both return the token response and write nothing to disk.
+
+### Read the current session
 
 ```ts
-import { getLoginStatusAsync } from "@uipath/auth";
+import { getAuthContext, getLoginStatusAsync } from "@uipath/auth";
+
+// Status report: Logged in / Not logged in / Expired / Refresh Failed
+const status = await getLoginStatusAsync();
+
+// What a command needs to call an API; throws when there is no usable session
+const { baseUrl, accessToken, tenantName } = await getAuthContext({
+    requireTenantName: true,
+});
+```
+
+Both pick credentials the same way as the CLI, using the first rule that applies:
+
+1. `UIPATH_CLI_ENFORCE_ROBOT_AUTH=true`: the local Robot only. No file is read.
+2. `UIPATH_CLI_ENABLE_ENV_AUTH=true`: the environment variables only.
+3. An active named profile: that profile's file only. If it is missing there is no session (`Not logged in`). There is no `.uipath/.auth` search and no Robot fallback.
+4. Otherwise the `.uipath/.auth` search. When it finds no file, a token is borrowed from the local Robot if one answers. This is skipped when `CI`, `GITHUB_ACTIONS` or `UIPATH_URL` is set.
+
+An expired token is renewed when the file holds a refresh token; pass `ensureTokenValidityMinutes` to renew earlier.
 
-const status = await getLoginStatusAsync({ file: ".uipath" });
+### Named profiles
+
+A named profile is a credentials file at `~/.uipath/profiles/<name>/.auth`. The CLI host calls `setActiveAuthProfile` once per invocation from `--profile`; after that, `getLoginStatusAsync`, `getAuthContext`, `getAuthEnv`, and `logout` read and write that profile's file.
+
+```ts
+import {
+    describeAuthProfilesAsync,
+    getLoginStatusAsync,
+    interactiveLogin,
+    resolveAuthProfileFilePath,
+    runWithAuthProfile,
+} from "@uipath/auth";
+
+// interactiveLogin does not follow the active profile: pass the path
+await interactiveLogin({ envFilePath: resolveAuthProfileFilePath("acme") });
+
+// Run code as a profile, isolated from other concurrent work in the process
+const status = await runWithAuthProfile("acme", () => getLoginStatusAsync());
+
+// Every profile with its status (never refreshes, never returns tokens)
+const profiles = await describeAuthProfilesAsync();
 ```
 
+`runWithAuthProfile` scopes the profile with `AsyncLocalStorage`, so in-process hosts such as the MCP server can serve several profiles at once. Profile names may contain only letters, numbers, `.`, `_`, and `-`; others throw `AuthProfileValidationError`.
+
 ## API
 
+### Login
+
+| Export | Description |
+| :--- | :--- |
+| `interactiveLogin(options)` | Full login (browser, client credentials, or federated) that saves credentials to `envFilePath` |
+| `authenticate(options)` | Browser authorization-code + PKCE step only; returns tokens without saving |
+| `clientCredentialsLogin(props)` | Client-credentials token request; returns tokens without saving |
+| `federatedCredentialsLogin(props)` | Client credentials with a JWT assertion (`jwt-bearer`); returns tokens without saving |
+| `logout(options)` | Delete the resolved credentials file (or `options.file`). Does not revoke tokens on the server |
+
+### Session
+
+| Export | Description |
+| :--- | :--- |
+| `getLoginStatusAsync(options)` | Current status, identity, and tokens; renews an expired token when it can |
+| `getAuthContext(options)` | Base URL, token, and org/tenant for an API call; throws when a required value is missing |
+| `getAuthEnv(options)` | The session as `UIPATH_*` key/value pairs, for handing to a child process |
+| `resolveSessionIdentity()`, `readTokenScopes()` | Who the token belongs to, and the scopes it carries |
+| `refreshAccessToken(params)` | Low-level refresh-token grant |
+
+### Environment and Robot auth
+
+| Export | Description |
+| :--- | :--- |
+| `isEnvAuthEnabled()`, `readAuthFromEnv()` | `UIPATH_CLI_ENABLE_ENV_AUTH` gate and the session it builds from `UIPATH_CLI_*` variables |
+| `ENV_AUTH_VARS`, `ENV_AUTH_ENABLE_VAR`, `EnvAuthConfigError` | Variable names and the error raised when one is missing |
+| `isRobotAuthEnforced()`, `ENFORCE_ROBOT_AUTH_VAR` | `UIPATH_CLI_ENFORCE_ROBOT_AUTH` gate |
+| `registerRobotClientLoader(loader)` | Host hook that lets the CLI borrow a token from the local Robot |
+
+### Named profiles
+
+| Export | Description |
+| :--- | :--- |
+| `setActiveAuthProfile(name)`, `getActiveAuthProfile()`, `clearActiveAuthProfile()` | Select the profile for the rest of the invocation |
+| `runWithAuthProfile(name, fn)` | Run `fn` with a profile in an isolated async scope |
+| `resolveAuthProfileFilePath(name)`, `getActiveAuthProfileFilePath()` | Path to a profile's `.auth` file |
+| `listAuthProfileNamesAsync()`, `describeAuthProfilesAsync()` | Profile names; profile names with org, tenant, and status |
+| `authProfileExistsAsync(name)`, `deleteAuthProfileAsync(name)` | Check for, or remove, a profile directory |
+| `normalizeAuthProfileName(name)`, `AuthProfileValidationError` | Name validation (`default` normalizes to `undefined`) |
+
+### Tenants
+
+| Export | Description |
+| :--- | :--- |
+| `fetchTenantsAndOrganizations()` | Tenants the token can use |
+| `selectTenantWithDeps()` | Tenant choice with a host-supplied prompt (`SelectFromList`) |
+| `TenantSelectionRequiredError`, `InvalidTenantError` | Several tenants and no choice; an unknown tenant name |
+
+### Credentials file and config
+
 | Export | Description |
 | :--- | :--- |
-| `interactiveLogin(options)` | Browser-based authorization code flow with PKCE |
-| `clientCredentialsLogin(props)` | Silent client credentials flow for service accounts |
-| `getLoginStatusAsync(options)` | Check current login status, auto-refreshes expired tokens |
-| `refreshAccessToken()` | Refresh an expired access token |
-| `selectTenant()` | Interactive tenant selection |
+| `resolveEnvFilePathAsync()`, `resolveEnvFileLocationAsync()` | Find the `.uipath/.auth` a path resolves to, and where it was found |
+| `loadEnvFileAsync()`, `saveEnvFileAsync()` | Read and write a credentials file (atomic writes) |
 | `setAuthFileConfig(cfg)` | Push the on-disk `auth.*` config slice into the auth singleton (called once by the CLI host at startup) |
-| `saveEnvFileAsync()` / `loadEnvFileAsync()` | Credential file I/O |
+| `InvalidBaseUrlError` | Raised for a malformed or non-HTTPS base URL (there is no host allowlist) |
 
 ## License
 

package/dist/authContext.d.ts

@@ -1,4 +1,5 @@
 import { type GetLoginStatusOptions, type LoginStatus } from "./loginStatus";
+import type { SessionIdentity } from "./sessionIdentity";
 export interface AuthContext {
     baseUrl: string;
     accessToken: string;
@@ -6,6 +7,14 @@ export interface AuthContext {
     organizationName?: string;
     tenantId?: string;
     tenantName?: string;
+    /**
+     * Who the session acts as, as the login status resolved it — from the
+     * token's claims *and* the auth flow this CLI persisted at login, which a
+     * bare token decode does not know. Absent when neither said anything.
+     * Read from unverified claims: for display and for predicting server
+     * behaviour, never for an authorization decision.
+     */
+    identity?: SessionIdentity;
 }
 export interface GetAuthContextOptions {
     tenant?: string;

package/dist/index.browser.d.ts

@@ -4,7 +4,7 @@ export * from "./clientCredentials";
 export { type AuthFileConfig, InvalidBaseUrlError, setAuthFileConfig, } from "./config";
 export * from "./loginStatus";
 export * from "./logout";
-export { type IdentityType, parseAuthFlow, resolveSessionIdentity, type SessionIdentity, } from "./sessionIdentity";
+export { type IdentityType, parseAuthFlow, readTokenScopes, resolveSessionIdentity, type SessionIdentity, } from "./sessionIdentity";
 export { fetchTenantsAndOrganizations, type Tenant, type TenantsAndOrganizations, } from "./tenantSelection";
 export * from "./tokenRefresh";
 export { AUTH_FLOW_ENV_VAR, type AuthFlow, type BaseCredentials, } from "./types";

package/dist/index.browser.js

@@ -18550,6 +18550,11 @@ var pickName = (claims) => {
   const username = asString(claims?.preferred_username);
   return asString(claims?.name) ?? (looksLikeEmail(username) ? undefined : username);
 };
+var pickScopes = (claims) => {
+  const raw = claims?.scope;
+  const scopes = Array.isArray(raw) ? raw.filter((entry) => asString(entry) !== undefined) : typeof raw === "string" ? raw.split(/\s+/).filter(Boolean) : [];
+  return scopes.length > 0 ? scopes : undefined;
+};
 var resolveSessionIdentity = (accessToken, authFlow) => {
   const claims = accessToken ? decodeClaims(accessToken) : undefined;
   const email = pickEmail(claims);
@@ -18575,6 +18580,7 @@ var resolveSessionIdentity = (accessToken, authFlow) => {
     identity.clientId = clientId;
   return identity;
 };
+var readTokenScopes = (accessToken) => accessToken ? pickScopes(decodeClaims(accessToken)) : undefined;
 
 // src/envAuth.ts
 var ENV_AUTH_ENABLE_VAR = "UIPATH_CLI_ENABLE_ENV_AUTH";
@@ -18647,6 +18653,7 @@ var readAuthFromEnv = () => {
   const expiration = getTokenExpiration(accessToken);
   const loginStatus = expiration && expiration <= new Date ? "Expired" : "Logged in";
   const identity = resolveSessionIdentity(accessToken);
+  const scopes = readTokenScopes(accessToken);
   return {
     loginStatus,
     accessToken,
@@ -18657,7 +18664,8 @@ var readAuthFromEnv = () => {
     tenantId,
     expiration,
     source: "env-vars" /* EnvironmentVariables */,
-    ...identity ? { identity } : {}
+    ...identity ? { identity } : {},
+    ...scopes ? { scopes } : {}
   };
 };
 
@@ -19305,10 +19313,15 @@ async function buildFileStatus(tokens, credentials, globalHint) {
 }
 function identityFields(accessToken, credentials) {
   const identity = resolveSessionIdentity(accessToken, parseAuthFlow(credentials[AUTH_FLOW_ENV_VAR]));
-  return identity ? { identity } : {};
+  const scopes = readTokenScopes(accessToken);
+  return {
+    ...identity ? { identity } : {},
+    ...scopes ? { scopes } : {}
+  };
 }
 function buildRobotStatus(robotCreds) {
   const identity = resolveSessionIdentity(robotCreds.accessToken);
+  const scopes = readTokenScopes(robotCreds.accessToken);
   return {
     loginStatus: "Logged in",
     accessToken: robotCreds.accessToken,
@@ -19320,7 +19333,8 @@ function buildRobotStatus(robotCreds) {
     issuer: robotCreds.issuer,
     expiration: getTokenExpiration(robotCreds.accessToken),
     source: "robot" /* Robot */,
-    ...identity ? { identity } : {}
+    ...identity ? { identity } : {},
+    ...scopes ? { scopes } : {}
   };
 }
 var isFileNotFoundError = (error) => {
@@ -19587,7 +19601,8 @@ var getAuthContext = async (options = {}) => {
     organizationId: status.organizationId,
     organizationName: status.organizationName,
     tenantId: status.tenantId,
-    tenantName
+    tenantName,
+    identity: status.identity
   };
 };
 var getAuthEnv = async (options = {}) => {
@@ -19829,6 +19844,7 @@ export {
   normalizeAuthProfileName,
   parseAuthFlow,
   parseJWT,
+  readTokenScopes,
   refreshAccessToken,
   resolveAuthProfileDirPath,
   resolveAuthProfileFilePath,
@@ -19841,4 +19857,4 @@ export {
   setAuthFileConfig
 };
 
-//# debugId=BA72FB3851B49E2164756E2164756E21
+//# debugId=444F587B7EE9CE7764756E2164756E21

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export * from "./logout";
 export { clearRefreshBreaker, loadRefreshBreaker, type RefreshBreakerState, refreshTokenFingerprint, saveRefreshBreaker, } from "./refreshCircuitBreaker";
 export { type RobotClientModuleLoader, registerRobotClientLoader, } from "./robotClientFallback";
 export { INVALID_TENANT_CODE, InvalidTenantError, isTenantSelectionError, type SelectFromList, selectTenantWithDeps, TENANT_SELECTION_REQUIRED_CODE, TenantSelectionError, TenantSelectionRequiredError, } from "./selectTenant";
-export { type IdentityType, parseAuthFlow, resolveSessionIdentity, type SessionIdentity, } from "./sessionIdentity";
+export { type IdentityType, parseAuthFlow, readTokenScopes, resolveSessionIdentity, type SessionIdentity, } from "./sessionIdentity";
 export { fetchTenantsAndOrganizations, type Tenant, type TenantsAndOrganizations, } from "./tenantSelection";
 export * from "./tokenRefresh";
 export { AUTH_FLOW_ENV_VAR, type AuthFlow, type BaseCredentials, } from "./types";

package/dist/index.js

@@ -2213,6 +2213,11 @@ var pickName = (claims) => {
   const username = asString(claims?.preferred_username);
   return asString(claims?.name) ?? (looksLikeEmail(username) ? undefined : username);
 };
+var pickScopes = (claims) => {
+  const raw = claims?.scope;
+  const scopes = Array.isArray(raw) ? raw.filter((entry) => asString(entry) !== undefined) : typeof raw === "string" ? raw.split(/\s+/).filter(Boolean) : [];
+  return scopes.length > 0 ? scopes : undefined;
+};
 var resolveSessionIdentity = (accessToken, authFlow) => {
   const claims = accessToken ? decodeClaims(accessToken) : undefined;
   const email = pickEmail(claims);
@@ -2238,6 +2243,7 @@ var resolveSessionIdentity = (accessToken, authFlow) => {
     identity.clientId = clientId;
   return identity;
 };
+var readTokenScopes = (accessToken) => accessToken ? pickScopes(decodeClaims(accessToken)) : undefined;
 
 // src/envAuth.ts
 var ENV_AUTH_ENABLE_VAR = "UIPATH_CLI_ENABLE_ENV_AUTH";
@@ -2310,6 +2316,7 @@ var readAuthFromEnv = () => {
   const expiration = getTokenExpiration(accessToken);
   const loginStatus = expiration && expiration <= new Date ? "Expired" : "Logged in";
   const identity = resolveSessionIdentity(accessToken);
+  const scopes = readTokenScopes(accessToken);
   return {
     loginStatus,
     accessToken,
@@ -2320,7 +2327,8 @@ var readAuthFromEnv = () => {
     tenantId,
     expiration,
     source: "env-vars" /* EnvironmentVariables */,
-    ...identity ? { identity } : {}
+    ...identity ? { identity } : {},
+    ...scopes ? { scopes } : {}
   };
 };
 
@@ -2972,10 +2980,15 @@ async function buildFileStatus(tokens, credentials, globalHint) {
 }
 function identityFields(accessToken, credentials) {
   const identity = resolveSessionIdentity(accessToken, parseAuthFlow(credentials[AUTH_FLOW_ENV_VAR]));
-  return identity ? { identity } : {};
+  const scopes = readTokenScopes(accessToken);
+  return {
+    ...identity ? { identity } : {},
+    ...scopes ? { scopes } : {}
+  };
 }
 function buildRobotStatus(robotCreds) {
   const identity = resolveSessionIdentity(robotCreds.accessToken);
+  const scopes = readTokenScopes(robotCreds.accessToken);
   return {
     loginStatus: "Logged in",
     accessToken: robotCreds.accessToken,
@@ -2987,7 +3000,8 @@ function buildRobotStatus(robotCreds) {
     issuer: robotCreds.issuer,
     expiration: getTokenExpiration(robotCreds.accessToken),
     source: "robot" /* Robot */,
-    ...identity ? { identity } : {}
+    ...identity ? { identity } : {},
+    ...scopes ? { scopes } : {}
   };
 }
 var isFileNotFoundError = (error) => {
@@ -3254,7 +3268,8 @@ var getAuthContext = async (options = {}) => {
     organizationId: status.organizationId,
     organizationName: status.organizationName,
     tenantId: status.tenantId,
-    tenantName
+    tenantName,
+    identity: status.identity
   };
 };
 var getAuthEnv = async (options = {}) => {
@@ -3989,6 +4004,7 @@ export {
   parseAuthFlow,
   parseJWT,
   readAuthFromEnv,
+  readTokenScopes,
   refreshAccessToken,
   refreshTokenFingerprint,
   registerRobotClientLoader,
@@ -4005,4 +4021,4 @@ export {
   setAuthFileConfig
 };
 
-//# debugId=07EEA08E9106212A64756E2164756E21
+//# debugId=4C387A5C17766AD564756E2164756E21

package/dist/loginStatus.d.ts

@@ -52,6 +52,13 @@ export interface LoginStatus {
      * not signature-verified.
      */
     identity?: SessionIdentity;
+    /**
+     * Scopes the access token carries. Kept beside `identity` rather than
+     * inside it because a token can carry the claim while saying too little
+     * to name who is acting, and dropping the scopes there would hide them
+     * from exactly the sessions that are hardest to diagnose.
+     */
+    scopes?: string[];
     /**
      * True when a refresh rotated successfully at the identity server but
      * persisting the new pair to disk failed. The returned `accessToken` is

package/dist/sessionIdentity.d.ts

@@ -33,3 +33,16 @@ export declare const parseAuthFlow: (value: string | undefined) => AuthFlow | un
  * omit the fields than to guess at who is acting.
  */
 export declare const resolveSessionIdentity: (accessToken: string | undefined, authFlow?: AuthFlow) => SessionIdentity | undefined;
+/**
+ * Scopes carried by an access token, in the order Identity returned them.
+ *
+ * Deliberately independent of {@link resolveSessionIdentity}: a token can
+ * carry a `scope` claim while saying too little to name who is acting — no
+ * `sub_type`, no user claims, no known flow — and those are exactly the
+ * sessions that are hardest to diagnose. Hanging the scopes off the identity
+ * dropped them for that shape.
+ *
+ * Read from an *unverified* claim (base64 decode, no signature check), for
+ * display only. Never branch on it for an authorization decision.
+ */
+export declare const readTokenScopes: (accessToken: string | undefined) => string[] | undefined;

package/package.json

@@ -2,7 +2,7 @@
     "name": "@uipath/auth",
     "author": "UiPath",
     "license": "SEE LICENSE IN LICENSE.txt",
-    "version": "1.203.0-preview.205",
+    "version": "1.204.0-preview.206",
     "repository": {
         "type": "git",
         "url": "https://github.com/UiPath/cli.git",
@@ -38,5 +38,5 @@
         "mihaigirleanu",
         "vlad-uipath"
     ],
-    "gitHead": "d8d19829030cc590c630bebfc60a9d9fc7fa8c31"
+    "gitHead": "ea7fd32a02acccf14e8e83522e69101430627b83"
 }