feat: support implicit OAuth in VS Code remote environments (#285)

* docs: remove developer preview banner and disclaimer

Remove the "Developer Preview" note and disclaimer from the CLI README,
the preview banner from the docs site theme, and all associated CSS.

* feat: support implicit OAuth in VS Code remote environments (Codespaces)

Add openBrowser and redirectUri options to ImplicitOAuthConfig,
AuthCredentials, and CreateOAuthOptions so callers can customize the
browser opener and redirect URI for implicit auth flows.

The VS Code extension now uses vscode.env.openExternal (opens browser
on the client) and vscode.env.asExternalUri (resolves localhost to the
Codespaces forwarded port URL) so implicit OAuth works in remote
environments where the `open` package cannot reach the user's browser.

* fix: thread openBrowser/redirectUri through B2CInstance path

The content tree, webdav tree, and log tailing features use
configProvider.getInstance() which creates a B2CInstance with its own
internal auth resolution. Thread redirectUri and openBrowser through
OAuthAuthConfig, AuthConfig, createInstanceFromConfig, and
createB2CInstance so these features also use vscode.env.openExternal
in remote environments.

Author: clavery

.changeset/implicit-auth-vscode-browser.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-tooling-sdk': minor
+'b2c-vs-extension': patch
+---
+
+Add `openBrowser` and `redirectUri` options to OAuth strategy creation, allowing callers to customize how the browser is opened and which redirect URI is used during implicit auth. The VS Code extension now uses `vscode.env.openExternal` and `vscode.env.asExternalUri` so implicit OAuth works in Codespaces and other remote environments.

packages/b2c-tooling-sdk/src/auth/oauth-implicit.ts

@@ -41,6 +41,12 @@ export interface ImplicitOAuthConfig {
    * The local server still listens on localPort regardless of this setting.
    */
   redirectUri?: string;
+  /**
+   * Custom browser opener. Receives the authorization URL and should open it
+   * in the user's browser. Useful in environments where the default `open` package
+   * doesn't work (e.g., VS Code remote/Codespaces where `vscode.env.openExternal` is needed).
+   */
+  openBrowser?: (url: string) => Promise<void>;
 }
 
 /**
@@ -70,7 +76,7 @@ function getOauth2RedirectHTML(redirectUri: string): string {
  * Opens the system default browser to the specified URL.
  * Dynamically imports 'open' package to handle the browser opening.
  */
-async function openBrowser(url: string): Promise<void> {
+async function openBrowserDefault(url: string): Promise<void> {
   try {
     // Dynamic import of 'open' package
     const open = await import('open');
@@ -325,9 +331,13 @@ export class ImplicitOAuthStrategy implements AuthStrategy {
     logger.info({url: authorizeUrl}, `Login URL: ${authorizeUrl}`);
     logger.info('If the URL does not open automatically, copy/paste it into a browser on this machine.');
 
-    // Attempt to open the browser
+    // Attempt to open the browser (prefer injected opener, fall back to `open` package)
     logger.debug('[Auth] Attempting to open browser');
-    await openBrowser(authorizeUrl);
+    if (this.config.openBrowser) {
+      await this.config.openBrowser(authorizeUrl);
+    } else {
+      await openBrowserDefault(authorizeUrl);
+    }
 
     return new Promise<AccessTokenResponse>((resolve, reject) => {
       const sockets: Set<Socket> = new Set();

packages/b2c-tooling-sdk/src/auth/resolve.ts

@@ -182,6 +182,8 @@ export function resolveAuthStrategy(
             clientId: credentials.clientId,
             scopes: credentials.scopes,
             accountManagerHost: credentials.accountManagerHost,
+            redirectUri: credentials.redirectUri,
+            openBrowser: credentials.openBrowser,
           });
         }
         break;

packages/b2c-tooling-sdk/src/auth/types.ts

@@ -51,6 +51,10 @@ export interface OAuthAuthConfig {
   clientSecret?: string;
   scopes?: string[];
   accountManagerHost?: string;
+  /** Override redirect URI for implicit OAuth flow (e.g., for port forwarding in remote environments) */
+  redirectUri?: string;
+  /** Custom browser opener for implicit OAuth flow. Receives the authorization URL. */
+  openBrowser?: (url: string) => Promise<void>;
 }
 
 /**
@@ -133,4 +137,8 @@ export interface AuthCredentials {
   apiKey?: string;
   /** Header name for API key (defaults to Authorization with Bearer prefix) */
   apiKeyHeaderName?: string;
+  /** Override redirect URI for implicit OAuth flow (e.g., for port forwarding in remote environments) */
+  redirectUri?: string;
+  /** Custom browser opener for implicit OAuth flow. Receives the authorization URL. */
+  openBrowser?: (url: string) => Promise<void>;
 }

packages/b2c-tooling-sdk/src/config/mapping.ts

@@ -478,7 +478,10 @@ export function buildAuthConfigFromNormalized(config: NormalizedConfig): AuthCon
  * await instance.webdav.mkcol('Cartridges/v1');
  * ```
  */
-export function createInstanceFromConfig(config: NormalizedConfig): B2CInstance {
+export function createInstanceFromConfig(
+  config: NormalizedConfig,
+  options?: {redirectUri?: string; openBrowser?: (url: string) => Promise<void>},
+): B2CInstance {
   if (!config.hostname) {
     throw new Error('Hostname is required. Set in dw.json or provide via overrides.');
   }
@@ -500,5 +503,14 @@ export function createInstanceFromConfig(config: NormalizedConfig): B2CInstance
 
   const authConfig = buildAuthConfigFromNormalized(config);
 
+  // Inject implicit auth options into OAuth config when present
+  if (authConfig.oauth && (options?.redirectUri || options?.openBrowser)) {
+    authConfig.oauth = {
+      ...authConfig.oauth,
+      redirectUri: options.redirectUri,
+      openBrowser: options.openBrowser,
+    };
+  }
+
   return new B2CInstance(instanceConfig, authConfig);
 }

packages/b2c-tooling-sdk/src/config/resolved-config.ts

@@ -55,11 +55,11 @@ export class ResolvedConfigImpl implements ResolvedB2CConfig {
 
   // Factory methods
 
-  createB2CInstance(): B2CInstance {
+  createB2CInstance(options?: Pick<CreateOAuthOptions, 'redirectUri' | 'openBrowser'>): B2CInstance {
     if (!this.hasB2CInstanceConfig()) {
       throw new Error('B2C instance requires hostname');
     }
-    return createInstanceFromConfig(this.values);
+    return createInstanceFromConfig(this.values, options);
   }
 
   createBasicAuth(): AuthStrategy {
@@ -82,6 +82,8 @@ export class ResolvedConfigImpl implements ResolvedB2CConfig {
       clientSecret: this.values.clientSecret,
       scopes: mergedScopes.length > 0 ? mergedScopes : undefined,
       accountManagerHost: this.values.accountManagerHost,
+      redirectUri: options?.redirectUri,
+      openBrowser: options?.openBrowser,
     };
     return resolveAuthStrategy(credentials, {allowedMethods: options?.allowedMethods});
   }

packages/b2c-tooling-sdk/src/config/types.ts

@@ -326,6 +326,10 @@ export interface CreateOAuthOptions {
   allowedMethods?: AuthMethod[];
   /** Additional OAuth scopes to request beyond those in config */
   scopes?: string[];
+  /** Override redirect URI for implicit OAuth flow (e.g., for port forwarding in remote environments) */
+  redirectUri?: string;
+  /** Custom browser opener for implicit OAuth flow. Receives the authorization URL. */
+  openBrowser?: (url: string) => Promise<void>;
 }
 
 /**
@@ -422,9 +426,10 @@ export interface ResolvedB2CConfig {
 
   /**
    * Creates a B2CInstance from the resolved configuration.
+   * @param options - Options for implicit OAuth (redirectUri, openBrowser)
    * @throws Error if hostname is not configured
    */
-  createB2CInstance(): B2CInstance;
+  createB2CInstance(options?: Pick<CreateOAuthOptions, 'redirectUri' | 'openBrowser'>): B2CInstance;
 
   /**
    * Creates a Basic auth strategy.

packages/b2c-tooling-sdk/src/instance/index.ts

@@ -184,6 +184,8 @@ export class B2CInstance {
       clientSecret: this.auth.oauth.clientSecret,
       scopes: this.auth.oauth.scopes,
       accountManagerHost: this.auth.oauth.accountManagerHost,
+      redirectUri: this.auth.oauth.redirectUri,
+      openBrowser: this.auth.oauth.openBrowser,
     };
 
     // Filter to only OAuth methods (client-credentials, implicit)

packages/b2c-vs-extension/src/api-browser/api-browser-tree-provider.ts

@@ -127,7 +127,8 @@ export class ApiBrowserTreeDataProvider implements vscode.TreeDataProvider<ApiBr
       const schemas = await vscode.window.withProgress(
         {location: {viewId: 'b2cApiBrowser'}, title: 'Loading SCAPI schemas...'},
         async () => {
-          const oauthStrategy = config.createOAuth();
+          const oauthOptions = await this.configProvider.getImplicitAuthOptions();
+          const oauthStrategy = config.createOAuth(oauthOptions);
           const schemasClient = createScapiSchemasClient({shortCode, tenantId}, oauthStrategy);
           const orgId = toOrganizationId(tenantId);
           const {data, error, response} = await schemasClient.GET('/organizations/{organizationId}/schemas', {

packages/b2c-vs-extension/src/api-browser/swagger-webview.ts

@@ -218,7 +218,8 @@ export class SwaggerWebviewManager implements vscode.Disposable {
 
     // Resolve external $refs server-side so the webview doesn't have to fetch them
     if (config.hasOAuthConfig()) {
-      const oauthStrategy = config.createOAuth();
+      const oauthOptions = await this.configProvider.getImplicitAuthOptions();
+      const oauthStrategy = config.createOAuth(oauthOptions);
       const authHeader = await oauthStrategy.getAuthorizationHeader?.();
       await resolveExternalRefs(spec, authHeader, this.log);
     }
@@ -308,7 +309,8 @@ export class SwaggerWebviewManager implements vscode.Disposable {
           const tenantId = deriveTenantId(config.values.hostname);
           if (!tenantId) throw new Error('Could not derive tenant ID from hostname.');
 
-          const oauthStrategy = config.createOAuth();
+          const oauthOptions = await this.configProvider.getImplicitAuthOptions();
+          const oauthStrategy = config.createOAuth(oauthOptions);
           const schemasClient = createScapiSchemasClient({shortCode, tenantId}, oauthStrategy);
           const orgId = toOrganizationId(tenantId);
           const {data, error, response} = await schemasClient.GET(
@@ -452,7 +454,8 @@ export class SwaggerWebviewManager implements vscode.Disposable {
       if (!config.hasOAuthConfig()) return null;
       // Request the specific scopes required by this API spec so the token
       // includes them (the cache will re-authenticate if scopes are missing)
-      const oauthStrategy = config.createOAuth({scopes});
+      const oauthOptions = await this.configProvider.getImplicitAuthOptions();
+      const oauthStrategy = config.createOAuth({...oauthOptions, scopes});
       const header = await oauthStrategy.getAuthorizationHeader?.();
       if (!header) return null;
       // Header is "Bearer <token>" — extract the token
@@ -510,7 +513,8 @@ export class SwaggerWebviewManager implements vscode.Disposable {
 
     try {
       this.log.appendLine(`[API Browser] Auto-discovering SLAS client for tenant ${tenantId}...`);
-      const oauthStrategy = config.createOAuth();
+      const oauthOptions = await this.configProvider.getImplicitAuthOptions();
+      const oauthStrategy = config.createOAuth(oauthOptions);
       const slasClient = createSlasClient({shortCode}, oauthStrategy);
 
       const {data, error} = await slasClient.GET('/tenants/{tenantId}/clients', {