Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

15.9 KB
Raw Blame
import fs from 'node:fs'
import os from 'node:os'
import path from 'node:path'
import pc from 'picocolors'
import { spreeTask } from './backend.js'
import { DEFAULT_SPREE_PORT } from './constants.js'
import { detectProject } from './context.js'
import { captureTask } from './docker.js'

/** Host a flag/env key defaults to when none is given — the local dev server. */
const LOCAL_DEV_URL = `http://localhost:${DEFAULT_SPREE_PORT}`

/**
 * Credential resolution for `spree api` / `spree auth`.
 *
 * The API key anchors a layer: host and key resolve together per source, so a
 * saved/minted secret key is never paired with a host from another source. An
 * explicit `--base-url` (or `--api-key`) flag overrides the resolved field —
 * the only sanctioned cross-source mix, since the user typed it deliberately.
 *
 *   1. flags            --base-url / --api-key (and --profile, which selects a
 *                       saved profile explicitly and then outranks env)
 *   2. env              SPREE_API_KEY (+ SPREE_BASE_URL, defaulting to the
 *                       local dev server); SPREE_BASE_URL alone never pairs
 *                       with a lower-layer key
 *   3. project          .spree/credentials.json next to docker-compose.yml,
 *                       auto-minted (read_all) on first use via the dev stack
 *   4. profile          ~/.config/spree/config.json, default profile
 */

export interface CredentialFlags {
  baseUrl?: string
  apiKey?: string
  profile?: string
}

export type CredentialSource = 'flags' | 'env' | 'project' | 'profile'

export interface ResolvedCredentials {
  baseUrl: string
  apiKey: string
  source: CredentialSource
  profileName?: string
  /** First 12 chars of the key — safe to display. */
  tokenPrefix: string
  /** Known only for project-minted keys (profiles store the key opaquely). */
  scopes?: string[]
}

export interface ProfileEntry {
  baseUrl: string
  token: string
}

export interface CliConfig {
  defaultProfile?: string
  profiles: Record<string, ProfileEntry>
}

export interface ProjectCredentials {
  baseUrl: string
  token: string
  scopes: string[]
  mintedAt: string
}

/** Thrown for resolution/usage problems — mapped to exit code 2. */
export class CredentialError extends Error {}

export function configDir(): string {
  return process.env.XDG_CONFIG_HOME
    ? path.join(process.env.XDG_CONFIG_HOME, 'spree')
    : path.join(os.homedir(), '.config', 'spree')
}

export function configPath(): string {
  return path.join(configDir(), 'config.json')
}

/** True when a thrown fs error is "no such file" (vs a permission/IO fault). */
export function isNotFound(error: unknown): boolean {
  return (error as NodeJS.ErrnoException)?.code === 'ENOENT'
}

export function readConfig(): CliConfig {
  let raw: string
  try {
    raw = fs.readFileSync(configPath(), 'utf-8')
  } catch (error) {
    if (isNotFound(error)) return { profiles: {} } // no config file yet — first run
    // A permission/IO fault is not "first run" — surface it rather than
    // silently starting fresh (which would later overwrite the unreadable file).
    throw error
  }

  try {
    const parsed = JSON.parse(raw) as Partial<CliConfig>
    return { ...parsed, profiles: parsed.profiles ?? {} }
  } catch {
    // The file exists but is corrupt. Back it up rather than silently
    // returning an empty config — otherwise the next `writeConfig` would
    // overwrite (and destroy) whatever profiles were in there.
    const backup = `${configPath()}.bak`
    try {
      fs.renameSync(configPath(), backup)
    } catch {
      // best effort
    }
    process.stderr.write(
      `${pc.yellow(`warning: ${configPath()} was not valid JSON; moved it to ${backup} and starting fresh.`)}\n`,
    )
    return { profiles: {} }
  }
}

export function writeConfig(config: CliConfig): void {
  fs.mkdirSync(configDir(), { recursive: true, mode: 0o700 })
  writeFilePrivate(configPath(), `${JSON.stringify(config, null, 2)}\n`)
}

/**
 * Writes a file readable only by the owner. `mode` on writeFileSync is
 * ignored when the file already exists, so chmod unconditionally afterward to
 * tighten any pre-existing (possibly world-readable) credential file.
 */
function writeFilePrivate(file: string, contents: string): void {
  fs.writeFileSync(file, contents, { mode: 0o600 })
  fs.chmodSync(file, 0o600)
}

export function projectCredentialsPath(projectDir: string): string {
  return path.join(projectDir, '.spree', 'credentials.json')
}

/**
 * Marker written when first-run setup completes on this machine. Kept
 * separate from credentials.json, which `spree auth logout` removes — losing
 * auth must not make `spree dev` mistake an initialized project for a fresh
 * one and re-run setup against its database. Lives in the fully gitignored
 * `.spree/`, so a teammate's clone correctly reads as not-set-up.
 */
export function projectSetupMarkerPath(projectDir: string): string {
  return path.join(projectDir, '.spree', 'setup-complete')
}

/** Records completed first-run setup — see {@link projectSetupMarkerPath}. */
export function writeProjectSetupMarker(projectDir: string): void {
  const file = projectSetupMarkerPath(projectDir)
  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
  ensureGitignoreCatchAll(path.join(path.dirname(file), '.gitignore'))
  fs.writeFileSync(file, `${new Date().toISOString()}\n`)
}

function adminEmailPath(projectDir: string): string {
  return path.join(projectDir, '.spree', 'admin-email')
}

/**
 * Remembers which admin email was seeded at init so `spree dev` can show it
 * on the summary card. The password is never persisted.
 */
export function writeAdminEmail(projectDir: string, email: string): void {
  const file = adminEmailPath(projectDir)
  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
  ensureGitignoreCatchAll(path.join(path.dirname(file), '.gitignore'))
  fs.writeFileSync(file, `${email}\n`)
}

export function readAdminEmail(projectDir: string): string | null {
  try {
    return fs.readFileSync(adminEmailPath(projectDir), 'utf-8').trim() || null
  } catch (error) {
    if (isNotFound(error)) return null
    throw error
  }
}

export function readProjectCredentials(projectDir: string): ProjectCredentials | null {
  let raw: string
  try {
    raw = fs.readFileSync(projectCredentialsPath(projectDir), 'utf-8')
  } catch (error) {
    if (isNotFound(error)) return null // not minted yet
    throw error // permission/IO fault — don't mask it as "mint a fresh key"
  }
  try {
    return JSON.parse(raw) as ProjectCredentials
  } catch {
    return null // corrupt file — fall back to re-mint
  }
}

export function writeProjectCredentials(projectDir: string, credentials: ProjectCredentials): void {
  const file = projectCredentialsPath(projectDir)
  const dir = path.dirname(file)
  fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
  // Make the directory self-ignoring so the minted key never gets committed,
  // independent of the project's own .gitignore vintage (the create-spree-app
  // entry only covers freshly scaffolded projects). Ensure a catch-all rule
  // even if a .gitignore already exists without one.
  ensureGitignoreCatchAll(path.join(dir, '.gitignore'))
  writeFilePrivate(file, `${JSON.stringify(credentials, null, 2)}\n`)
}

/** Ensures `.spree/.gitignore` ignores everything — creating it, or appending
 * a `*` rule if it exists without one — so credentials.json is never committed. */
function ensureGitignoreCatchAll(gitignorePath: string): void {
  let existing = ''
  try {
    existing = fs.readFileSync(gitignorePath, 'utf-8')
  } catch (error) {
    if (!isNotFound(error)) throw error
  }
  const hasCatchAll = existing.split('\n').some((line) => line.trim() === '*')
  if (hasCatchAll) return
  fs.writeFileSync(
    gitignorePath,
    existing && !existing.endsWith('\n') ? `${existing}\n*\n` : `${existing}*\n`,
  )
}

export function tokenPrefix(token: string): string {
  return token.slice(0, 12)
}

export interface MintKeyOptions {
  name: string
  keyType: 'secret' | 'publishable'
  scopes?: string[]
  /**
   * Revoke active keys of the same name first. For a key the CLI mints under
   * a fixed name on every run: names are unique among a store's active keys,
   * so without this an interrupted setup or a lost credentials.json makes the
   * next mint fail on "Name has already been taken". The task revokes and
   * creates in one transaction, so a failure never leaves neither.
   */
  replace?: boolean
}

/**
 * Mints an API key through the project's dev stack and returns its token.
 * The one place that knows the rake task's contract and the token shape.
 */
export async function mintApiKey(projectDir: string, options: MintKeyOptions): Promise<string> {
  let stdout: string
  try {
    stdout = await captureTask(spreeTask('cli:create_api_key'), projectDir, {
      NAME: options.name,
      KEY_TYPE: options.keyType,
      ...(options.scopes?.length ? { SCOPES: options.scopes.join(',') } : {}),
      ...(options.replace ? { REPLACE: 'true' } : {}),
    })
  } catch (error) {
    // Surface what the task actually said. Blaming a stopped stack for every
    // failure sends operators after a stack that is running fine while the
    // real cause (a validation error) scrolls past.
    const output = error instanceof Error ? error.message : String(error)
    const railsError = output.match(/^\w*(?:::\w+)*(?:Error|Invalid):.*$/m)?.[0]
    throw new CredentialError(
      railsError
        ? `Could not mint an API key.\n${pc.dim(railsError)}`
        : `Could not mint an API key via the dev stack. Is it running? Start it with \`spree dev\`.\n${pc.dim(output.split('\n')[0])}`,
    )
  }
  const prefix = options.keyType === 'publishable' ? 'pk_' : 'sk_'
  const token = stdout.match(new RegExp(`${prefix}[A-Za-z0-9_-]+`))?.[0]
  if (!token) {
    throw new CredentialError(
      'Could not mint an API key via the dev stack. Is it running? Start it with `spree dev`.',
    )
  }
  return token
}

/**
 * Auto-mints a read-only secret key through the project's dev stack and
 * persists it in `.spree/credentials.json` (gitignored). Write scopes are
 * never minted implicitly — `spree api-key create --scopes write_...` is the
 * explicit path. Shared by the lazy path (`resolveCredentials`) and the eager
 * path (`spree init`).
 *
 * @param quiet suppress the stderr progress chatter (the eager path owns its
 *   own spinner UI and prints the key in the setup summary).
 */
export async function mintProjectCredentials(
  projectDir: string,
  port: number,
  quiet = false,
): Promise<ProjectCredentials> {
  if (!quiet) {
    process.stderr.write(
      `${pc.dim('No credentials found — minting a read-only API key via the dev stack...')}\n`,
    )
  }

  const token = await mintApiKey(projectDir, {
    name: '@spree/cli (auto)',
    keyType: 'secret',
    scopes: ['read_all'],
    replace: true,
  })

  const credentials: ProjectCredentials = {
    baseUrl: `http://localhost:${port}`,
    token,
    scopes: ['read_all'],
    mintedAt: new Date().toISOString(),
  }
  writeProjectCredentials(projectDir, credentials)
  if (!quiet) {
    process.stderr.write(`${pc.dim(`Saved to .spree/credentials.json (scopes: read_all)`)}\n`)
  }
  return credentials
}

export interface ResolveOptions {
  /** Mint a project key when inside a project with no credentials (default true). */
  allowMint?: boolean
  /** Working directory for project detection (tests). */
  cwd?: string
}

export async function resolveCredentials(
  flags: CredentialFlags,
  options: ResolveOptions = {},
): Promise<ResolvedCredentials> {
  const { allowMint = true, cwd = process.cwd() } = options
  const config = readConfig()

  // The KEY anchors a layer: each layer (other than flags) contributes its
  // token together with its own base URL, so a saved/minted secret key is
  // never paired with a host from a different trust domain. The only
  // sanctioned cross-layer mix is an explicit `--base-url`/`--api-key` flag,
  // which the user typed on purpose; those override whatever a layer resolved.
  const flagBaseUrl = flags.baseUrl
  const flagApiKey = flags.apiKey

  let resolved:
    | {
        baseUrl?: string
        apiKey: string
        source: CredentialSource
        profileName?: string
        scopes?: string[]
      }
    | undefined

  // Layer 1 — explicit --api-key flag.
  if (flagApiKey) {
    resolved = { apiKey: flagApiKey, source: 'flags' }
  }

  // --profile is an explicit selection of a saved profile; it outranks env.
  if (!resolved && flags.profile) {
    const profile = config.profiles[flags.profile]
    if (!profile) {
      throw new CredentialError(
        `Unknown profile "${flags.profile}". Run \`spree auth login --profile ${flags.profile}\` to create it.`,
      )
    }
    resolved = {
      baseUrl: profile.baseUrl,
      apiKey: profile.token,
      source: 'profile',
      profileName: flags.profile,
    }
  }

  // Layer 2 — environment. The pair is anchored on SPREE_API_KEY; SPREE_BASE_URL
  // alone never pairs with a lower-layer key (that was the exfiltration path).
  if (!resolved && process.env.SPREE_API_KEY) {
    resolved = {
      baseUrl: process.env.SPREE_BASE_URL,
      apiKey: process.env.SPREE_API_KEY,
      source: 'env',
    }
  }

  // Layer 3 — project credentials (auto-minted on first use). Skipped when an
  // explicit --base-url points somewhere other than this project, so a remote
  // command never silently mints a local key.
  if (!resolved) {
    let projectDir: string | undefined
    let port = 0
    try {
      const ctx = detectProject(cwd)
      projectDir = ctx.projectDir
      port = ctx.port
    } catch {
      // not a Spree project directory — fall through
    }

    if (projectDir) {
      const projectUrl = `http://localhost:${port}`
      const targetsThisProject = !flagBaseUrl || flagBaseUrl.replace(/\/$/, '') === projectUrl
      let credentials = readProjectCredentials(projectDir)
      if (!credentials && allowMint && targetsThisProject) {
        credentials = await mintProjectCredentials(projectDir, port)
      }
      if (credentials) {
        resolved = {
          baseUrl: credentials.baseUrl,
          apiKey: credentials.token,
          source: 'project',
          scopes: credentials.scopes,
        }
      }
    }
  }

  // Layer 4 — default profile.
  if (!resolved && config.defaultProfile) {
    const profile = config.profiles[config.defaultProfile]
    if (profile) {
      resolved = {
        baseUrl: profile.baseUrl,
        apiKey: profile.token,
        source: 'profile',
        profileName: config.defaultProfile,
      }
    }
  }

  // An explicit --base-url always wins (re-point a key at staging, etc.); a
  // flag pairing is the user's deliberate cross-layer mix.
  let baseUrl = flagBaseUrl ?? resolved?.baseUrl
  const apiKey = resolved?.apiKey

  // Local-dev convenience: a key supplied via flag or env with no host at all
  // defaults to the local dev server, so `SPREE_API_KEY=sk_… spree api get …`
  // just works. Profile/project sources always carry their own host, so this
  // never silently re-points a saved remote key.
  if (!baseUrl && (resolved?.source === 'flags' || resolved?.source === 'env')) {
    baseUrl = LOCAL_DEV_URL
  }

  if (!baseUrl || !apiKey) {
    throw new CredentialError(
      [
        'No Admin API credentials found. Provide them via one of (host and key resolve together per source):',
        '  - flags:      --api-key <sk_...> (host defaults to ' +
          LOCAL_DEV_URL +
          '; pass --base-url for a remote store)',
        '  - env:        SPREE_API_KEY (host defaults to ' +
          LOCAL_DEV_URL +
          '; set SPREE_BASE_URL for a remote store)',
        '  - project:    run inside a Spree project with the dev stack up (auto-mints a read-only key)',
        '  - profile:    spree auth login --profile <name>',
      ].join('\n'),
    )
  }

  return {
    baseUrl,
    apiKey,
    source: resolved?.source ?? 'flags',
    profileName: resolved?.profileName,
    tokenPrefix: tokenPrefix(apiKey),
    scopes: resolved?.scopes,
  }
}