handoff-app 2.0.0-2 → 2.0.0-4

package/src/app-builder/build.ts

@@ -8,7 +8,7 @@ import { buildPatterns } from '../pipeline/patterns';
 import processComponents from '../transformers/preview/component/builder';
 import { buildMainCss } from '../transformers/preview/component/css';
 import { buildMainJS } from '../transformers/preview/component/javascript';
-import { resolveApiTokenEnv, resolveDatabaseUrlEnv, resolveRegistryDriver } from '../registry/db/driver';
+import { resolveDatabaseUrlEnv, resolveRegistryDriver } from '../registry/db/driver';
 import { resolveAssetStorageFromConfig } from '../registry/asset-storage/resolve';
 import type { RuntimeMode } from '../types/config';
 import { Logger } from '../utils/logger';
@@ -258,7 +258,6 @@ const initializeProjectApp = async (handoff: Handoff, options: InitializeProject
   const escapedRuntimeMode = escapeForSingleQuotedJsString(runtimeMode);
   const escapedRegistryDriver = escapeForSingleQuotedJsString(resolveRegistryDriver(handoff.config));
   const escapedDatabaseUrlEnv = escapeForSingleQuotedJsString(resolveDatabaseUrlEnv(handoff.config));
-  const escapedApiTokenEnv = escapeForSingleQuotedJsString(resolveApiTokenEnv(handoff.config));
   // Asset storage selection baked (provider + module + env-var names + non-secret options JSON).
   const assetStorage = resolveAssetStorageFromConfig(handoff.config);
   const escapedAssetStorageAdapter = escapeForSingleQuotedJsString(assetStorage.adapterKind);
@@ -276,7 +275,6 @@ const initializeProjectApp = async (handoff: Handoff, options: InitializeProject
     '%HANDOFF_RUNTIME_MODE%': escapedRuntimeMode,
     '%HANDOFF_REGISTRY_DRIVER%': escapedRegistryDriver,
     '%HANDOFF_REGISTRY_DATABASE_URL_ENV%': escapedDatabaseUrlEnv,
-    '%HANDOFF_REGISTRY_API_TOKEN_ENV%': escapedApiTokenEnv,
     '%HANDOFF_ASSET_STORAGE_ADAPTER%': escapedAssetStorageAdapter,
     '%HANDOFF_ASSET_STORAGE_MODULE%': escapedAssetStorageModule,
     '%HANDOFF_ASSET_STORAGE_TOKEN_ENV%': escapedAssetStorageTokenEnv,
@@ -418,7 +416,11 @@ and \`.next/static/\` already copied alongside so the server serves them.
 ## Required environment variables (supplied at deploy time, never baked in)
 
 - \`${databaseUrlEnv}\` — PostgreSQL/Neon connection string, read at request time.
-- \`HANDOFF_REGISTRY_API_TOKEN\` — bearer token for registry management mutations (if used).
+- \`AUTH_SECRET\` — a long, random secret used to sign browser sessions.
+- \`AUTH_URL\` — the canonical public registry URL, including the configured base path.
+
+Optional email delivery uses \`RESEND_API_KEY\` and \`AUTH_FROM_EMAIL\`. Without them, invitation
+links are shown once to an administrator for manual delivery.
 
 ## Database migrations
 
@@ -433,6 +435,21 @@ ${databaseUrlEnv}="postgres://…" handoff-app db:migrate
 built with, and applies the package-owned migration set. It runs independently of \`build\` and of
 starting the server, so run it as a release/one-shot job.
 
+## Complete the one-time installation
+
+After migrations and deployment, open \`/install\` immediately and create the initial administrator.
+The installer verifies the deployment but never changes the schema. An exposed, uninstalled registry
+can be claimed by its first visitor, so do not leave this step unattended.
+
+Once installation completes, sign in and authorize a workspace:
+
+\`\`\`bash
+handoff-app login --url https://registry.example.com
+\`\`\`
+
+The browser approval issues a revocable, user-owned credential. The former
+\`HANDOFF_REGISTRY_API_TOKEN\` fixed server secret is no longer accepted.
+
 ## Run it (self-hosting)
 
 Standalone is the documented artifact for self-hosting on a Node.js server, VPS, Docker, or
@@ -481,7 +498,7 @@ containers, custom Node servers, and other non-Vercel hosts.
  * package is driver-specific (the Neon serverless driver also needs `ws` for its Node WebSocket transport).
  */
 const getRequiredRegistryRuntimeModules = (handoff: Handoff): string[] => {
-  const base = ['next', 'react', 'react-dom', 'drizzle-orm'];
+  const base = ['next', 'next-auth', 'react', 'react-dom', 'drizzle-orm'];
   const driver = resolveRegistryDriver(handoff.config);
   const driverModules = driver === 'neon' ? ['@neondatabase/serverless', 'ws'] : ['pg'];
   // Asset-storage SDKs the deployed registry must be able to load at request time. The pre-packaged

package/src/app-builder/client-config.ts

@@ -3,7 +3,8 @@ import path from 'path';
 import Handoff from '..';
 import { getClientConfig } from '../config';
 import { resolveAssetStorageFromConfig } from '../registry/asset-storage/resolve';
-import { resolveApiTokenEnv, resolveDatabaseUrlEnv, resolveRegistryDriver } from '../registry/db/driver';
+import { resolveAuthenticatedRegistryConnection } from '../registry/connection';
+import { resolveDatabaseUrlEnv, resolveRegistryDriver } from '../registry/db/driver';
 import type { Config, RuntimeMode } from '../types/config';
 import { getAppPath } from './paths';
 
@@ -59,7 +60,6 @@ const buildServerRuntimeConfig = (config: Config, modeOverride?: RuntimeMode) =>
     registry: {
       driver: resolveRegistryDriver(config),
       databaseUrlEnv: resolveDatabaseUrlEnv(config),
-      apiTokenEnv: resolveApiTokenEnv(config),
     },
     assetStorage: {
       adapter: assetStorage.adapterKind,
@@ -93,13 +93,14 @@ export const persistClientConfig = async (handoff: Handoff, options: PersistClie
   await fs.ensureDir(appPath);
 
   const clientConfig = getClientConfig(handoff.config);
-  if (options.runtimeModeOverride) {
-    // A forced registry mode (the registry build target) is never a connected workspace, so the
-    // baked client config must report `connected: false` even when packaged from a connected
-    // workspace project.
-    const connected = options.runtimeModeOverride === 'registry' ? false : clientConfig.runtime.connected;
-    clientConfig.runtime = { ...clientConfig.runtime, mode: options.runtimeModeOverride, connected };
-  }
+  const mode = options.runtimeModeOverride ?? clientConfig.runtime.mode;
+  // A registry build target is never a connected workspace, so it must bake `connected: false`
+  // even when packaged from a connected project. Otherwise a workspace is connected whenever a
+  // registry URL resolves — from config/env or a saved device login — so `login` alone surfaces
+  // the publish/checkout UI without also requiring HANDOFF_REGISTRY_URL.
+  const connected =
+    mode === 'registry' ? false : Boolean((await resolveAuthenticatedRegistryConnection(handoff.config, handoff.workingPath)).url);
+  clientConfig.runtime = { ...clientConfig.runtime, mode, connected };
 
   await fs.writeJson(path.resolve(appPath, 'client.config.json'), { config: clientConfig }, { spaces: 2 });
   await fs.writeJson(

package/src/cli/auth/browser.ts

@@ -0,0 +1,29 @@
+import { spawn } from 'child_process';
+
+/** Fire-and-forget opening of a URL in the system browser. The printed URL remains the fallback. */
+export const tryOpenBrowser = (url: string): void => {
+  try {
+    const { protocol } = new URL(url);
+    if (protocol !== 'http:' && protocol !== 'https:') return;
+  } catch {
+    return;
+  }
+
+  const platform = process.platform;
+  // rundll32 is a plain executable rather than a shell, so spawn hands it the URL as one
+  // untouched argument. `cmd /c start` would re-parse shell metacharacters in it.
+  const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'rundll32.exe' : 'xdg-open';
+  const args = platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+
+  try {
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: platform === 'win32',
+    });
+    child.on('error', () => undefined);
+    child.unref();
+  } catch {
+    // Headless and SSH environments can use the URL printed by the login flow.
+  }
+};

package/src/cli/auth/device.ts

@@ -0,0 +1,181 @@
+import { Logger } from '../../utils/logger';
+import { tryOpenBrowser } from './browser';
+import { assertRegistryOriginUrl, type CliAuth, normalizeRegistryUrl, writeCliAuth } from './store';
+
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+const DEFAULT_DEVICE_EXPIRES_IN_SECONDS = 15 * 60;
+const DEFAULT_TOKEN_EXPIRES_IN_SECONDS = 365 * 24 * 60 * 60;
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+
+interface DeviceAuthorizationResponse {
+  device_code?: string;
+  user_code?: string;
+  verification_uri?: string;
+  verification_uri_complete?: string;
+  expires_in?: number;
+  interval?: number;
+}
+
+interface TokenResponse {
+  access_token?: string;
+  token_type?: string;
+  expires_in?: number;
+  error?: string | { code?: string; message?: string };
+  error_description?: string;
+}
+
+interface Envelope<T> {
+  data?: T;
+  error?: string | { code?: string; message?: string };
+}
+
+export interface LoginOptions {
+  openBrowser?: boolean;
+}
+
+const sleep = (milliseconds: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+const responsePayload = <T>(value: T | Envelope<T>): T => {
+  const envelope = value as Envelope<T>;
+  return envelope && typeof envelope === 'object' && envelope.data ? envelope.data : (value as T);
+};
+
+const responseError = (value: unknown): { code?: string; message?: string } => {
+  if (!value || typeof value !== 'object') return {};
+  const body = value as TokenResponse;
+  if (typeof body.error === 'string') {
+    return { code: body.error, message: body.error_description || body.error };
+  }
+  if (body.error && typeof body.error === 'object') {
+    return { code: body.error.code, message: body.error.message };
+  }
+  return {};
+};
+
+const readJson = async (response: Response): Promise<unknown> => {
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return {};
+  }
+};
+
+const shouldOpenBrowser = (options: LoginOptions): boolean => {
+  if (options.openBrowser === false) return false;
+  if (process.env.CI === '1' || process.env.CI === 'true') return false;
+  return process.env.HANDOFF_LOGIN_NO_BROWSER !== '1' && process.env.HANDOFF_LOGIN_NO_BROWSER !== 'true';
+};
+
+const positiveNumberOr = (value: unknown, fallback: number): number =>
+  typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+
+/** Complete the device grant and persist the one-time plaintext access token for this workspace. */
+export const loginWithDevice = async (workingPath: string, remoteUrl: string, options: LoginOptions = {}): Promise<CliAuth> => {
+  const baseUrl = normalizeRegistryUrl(remoteUrl);
+  let deviceResponse: Response;
+  try {
+    deviceResponse = await fetch(`${baseUrl}/api/oauth/device`, {
+      method: 'POST',
+      headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+      body: '{}',
+    });
+  } catch (error) {
+    throw new Error(`Could not reach the registry at ${baseUrl}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const rawDevice = await readJson(deviceResponse);
+  const device = responsePayload(rawDevice as DeviceAuthorizationResponse | Envelope<DeviceAuthorizationResponse>);
+  if (!deviceResponse.ok) {
+    const failure = responseError(rawDevice);
+    throw new Error(`Device authorization failed (${deviceResponse.status}): ${failure.message || deviceResponse.statusText}`);
+  }
+  if (!device.device_code || !device.user_code || !device.verification_uri) {
+    throw new Error('The registry returned an invalid device authorization response.');
+  }
+
+  const verificationUrl = assertRegistryOriginUrl(
+    baseUrl,
+    device.verification_uri_complete ||
+      `${device.verification_uri}${device.verification_uri.includes('?') ? '&' : '?'}user_code=${encodeURIComponent(device.user_code)}`,
+  );
+
+  Logger.log('');
+  Logger.log('Approve this device in your browser:');
+  Logger.log(verificationUrl);
+  Logger.log('');
+  Logger.log(`Device code: ${device.user_code}`);
+  Logger.log('');
+
+  if (shouldOpenBrowser(options)) {
+    tryOpenBrowser(verificationUrl);
+    Logger.info('Attempted to open your default browser.');
+  }
+
+  const deadline = Date.now() + positiveNumberOr(device.expires_in, DEFAULT_DEVICE_EXPIRES_IN_SECONDS) * 1000;
+  let intervalMs = positiveNumberOr(device.interval, DEFAULT_POLL_INTERVAL_SECONDS) * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(Math.min(intervalMs, Math.max(0, deadline - Date.now())));
+
+    let tokenResponse: Response;
+    try {
+      tokenResponse = await fetch(`${baseUrl}/api/oauth/token`, {
+        method: 'POST',
+        headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          grant_type: DEVICE_GRANT,
+          device_code: device.device_code,
+        }),
+      });
+    } catch (error) {
+      throw new Error(`Could not reach the registry at ${baseUrl}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    const rawToken = await readJson(tokenResponse);
+    const token = responsePayload(rawToken as TokenResponse | Envelope<TokenResponse>);
+    if (tokenResponse.ok && token.access_token) {
+      const expiresIn = positiveNumberOr(token.expires_in, DEFAULT_TOKEN_EXPIRES_IN_SECONDS);
+      const auth: CliAuth = {
+        remoteUrl: baseUrl,
+        accessToken: token.access_token,
+        expiresAtMs: Date.now() + expiresIn * 1000,
+      };
+      await writeCliAuth(workingPath, auth);
+      return auth;
+    }
+
+    const failure = responseError(token);
+    if (failure.code === 'authorization_pending') continue;
+    if (failure.code === 'slow_down') {
+      intervalMs = Math.min(intervalMs + 5_000, 60_000);
+      continue;
+    }
+    if (failure.code === 'expired_token') break;
+    throw new Error(`Token request failed: ${failure.message || tokenResponse.statusText || 'unknown error'}`);
+  }
+
+  throw new Error('Device authorization expired. Run `handoff-app login` again.');
+};
+
+/**
+ * Best-effort remote revocation. The caller must clear the local credential regardless of failure.
+ * The bearer header identifies the current token while the body supports RFC 7009-style handlers.
+ */
+export const revokeAccessToken = async (auth: CliAuth): Promise<void> => {
+  const response = await fetch(`${normalizeRegistryUrl(auth.remoteUrl)}/api/oauth/revoke`, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/json',
+      Authorization: `Bearer ${auth.accessToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ token: auth.accessToken }),
+  });
+  if (!response.ok) {
+    const body = await readJson(response);
+    const failure = responseError(body);
+    throw new Error(failure.message || `${response.status} ${response.statusText}`);
+  }
+};

package/src/cli/auth/store.ts

@@ -0,0 +1,137 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+/** Credentials issued to this workspace by one registry. */
+export interface CliAuth {
+  remoteUrl: string;
+  accessToken: string;
+  /** Epoch milliseconds after which the token must not be used. */
+  expiresAtMs: number;
+}
+
+const AUTH_DIRECTORY = '.handoff';
+const AUTH_FILE = 'cli-auth.json';
+
+/**
+ * Canonicalize a registry URL for both HTTP requests and exact credential matching.
+ * Base paths are retained; query strings, fragments, credentials, and trailing slashes are not.
+ */
+export const normalizeRegistryUrl = (value: string): string => {
+  let parsed: URL;
+  try {
+    parsed = new URL(value.trim());
+  } catch {
+    throw new Error(`Invalid registry URL "${value}". Pass an absolute http:// or https:// URL.`);
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`Invalid registry URL protocol "${parsed.protocol}". Use http:// or https://.`);
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error('Registry URLs must not contain credentials.');
+  }
+
+  const pathname = parsed.pathname.replace(/\/+$/, '');
+  return `${parsed.origin}${pathname === '/' ? '' : pathname}`;
+};
+
+/**
+ * A verification URL is only trustworthy if it's a web URL on the same origin as the
+ * registry the CLI is authenticating against. This stops a tampered device-authorization
+ * response from sending the browser to (or injecting a command via) another origin.
+ */
+export const assertRegistryOriginUrl = (baseUrl: string, candidate: string): string => {
+  let url: URL;
+  try {
+    url = new URL(candidate);
+  } catch {
+    throw new Error('The registry returned an invalid verification URL.');
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error(`The registry returned a verification URL with an unsupported protocol "${url.protocol}".`);
+  }
+  if (url.origin !== new URL(baseUrl).origin) {
+    throw new Error('The registry returned a verification URL for a different origin than the registry.');
+  }
+  return url.toString();
+};
+
+export const cliAuthFilePath = (workingPath: string): string => path.resolve(workingPath, AUTH_DIRECTORY, AUTH_FILE);
+
+const isCliAuth = (value: unknown): value is CliAuth => {
+  if (!value || typeof value !== 'object') return false;
+  const auth = value as Partial<CliAuth>;
+  return (
+    typeof auth.remoteUrl === 'string' &&
+    typeof auth.accessToken === 'string' &&
+    auth.accessToken.length > 0 &&
+    typeof auth.expiresAtMs === 'number' &&
+    Number.isFinite(auth.expiresAtMs)
+  );
+};
+
+/** Invalid or partial credential files are treated as unauthenticated. */
+export const readCliAuth = async (workingPath: string): Promise<CliAuth | null> => {
+  try {
+    const value = (await fs.readJson(cliAuthFilePath(workingPath))) as unknown;
+    if (!isCliAuth(value)) return null;
+    return { ...value, remoteUrl: normalizeRegistryUrl(value.remoteUrl) };
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Atomically replace the credential file. Restrictive permissions are best-effort on platforms
+ * whose filesystems do not support POSIX modes.
+ */
+export const writeCliAuth = async (workingPath: string, auth: CliAuth): Promise<void> => {
+  const filePath = cliAuthFilePath(workingPath);
+  const directory = path.dirname(filePath);
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  const value: CliAuth = { ...auth, remoteUrl: normalizeRegistryUrl(auth.remoteUrl) };
+
+  await fs.ensureDir(directory, 0o700);
+  try {
+    await fs.chmod(directory, 0o700);
+  } catch {
+    // Windows and some mounted filesystems do not implement POSIX modes.
+  }
+
+  try {
+    await fs.writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    try {
+      await fs.chmod(temporaryPath, 0o600);
+    } catch {
+      // Best effort; see the directory chmod above.
+    }
+    await fs.rename(temporaryPath, filePath);
+    try {
+      await fs.chmod(filePath, 0o600);
+    } catch {
+      // Best effort.
+    }
+  } catch (error) {
+    await fs.remove(temporaryPath).catch(() => undefined);
+    throw error;
+  }
+};
+
+export const clearCliAuth = async (workingPath: string): Promise<void> => {
+  const filePath = cliAuthFilePath(workingPath);
+  if (await fs.pathExists(filePath)) {
+    await fs.remove(filePath);
+  }
+};
+
+export const cliAuthMatchesRegistry = (auth: CliAuth | null, remoteUrl: string): boolean => {
+  if (!auth) return false;
+  try {
+    return auth.remoteUrl === normalizeRegistryUrl(remoteUrl);
+  } catch {
+    return false;
+  }
+};
+
+export const cliAuthTokenIsValid = (auth: CliAuth | null, skewMs = 30_000): boolean =>
+  Boolean(auth?.accessToken && auth.expiresAtMs > Date.now() + skewMs);