Merge pull request #330 from cipherstash/stack-auth

feat: implement auth into stash cli

Author: calvinbrewer

.changeset/warm-wasps-joke.md

@@ -0,0 +1,5 @@
+---
+"@cipherstash/stack": minor
+---
+
+Implement stack auth into stash cli flow.

packages/stack/README.md

@@ -44,19 +44,29 @@ pnpm add @cipherstash/stack
 
 ## Quick Start
 
+### 1. Initialize and authenticate your project
+
+```bash
+npx stash init
+```
+
+The wizard will authenticate you, walk you through choosing a database connection method, build an encryption schema, and install the required dependencies.
+
+### 2. Encrypt and decrypt
+
 ```typescript
 import { Encryption } from "@cipherstash/stack"
 import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
 
-// 1. Define a schema
+// Define a schema
 const users = encryptedTable("users", {
   email: encryptedColumn("email").equality().freeTextSearch(),
 })
 
-// 2. Create a client (reads CS_* env vars automatically)
+// Create a client
 const client = await Encryption({ schemas: [users] })
 
-// 3. Encrypt a value
+// Encrypt a value
 const encrypted = await client.encrypt("hello@example.com", {
   column: users.email,
   table: users,
@@ -68,7 +78,7 @@ if (encrypted.failure) {
   console.log("Encrypted payload:", encrypted.data)
 }
 
-// 4. Decrypt the value
+// Decrypt the value
 const decrypted = await client.decrypt(encrypted.data)
 
 if (decrypted.failure) {
@@ -430,6 +440,16 @@ await secrets.delete("DATABASE_URL")
 
 The `stash` CLI is bundled with the package and available after install.
 
+### `stash auth`
+
+Authenticate with CipherStash.
+
+```bash
+npx stash auth login
+```
+
+This runs the device code flow: it opens your browser, you confirm the code, and a token is saved to `~/.cipherstash/auth.json`. No environment variables or credentials files are needed for local development.
+
 ### `stash init`
 
 Initialize CipherStash for your project with an interactive wizard.
@@ -440,11 +460,13 @@ npx stash init --supabase
 ```
 
 The wizard will:
-1. Choose your database connection method (Drizzle ORM, Supabase JS, Prisma, or Raw SQL)
-2. Build an encryption schema interactively or use a placeholder, then generate the encryption client file
-3. Install `@cipherstash/stack-forge` as a dev dependency for database tooling
+1. Authenticate with CipherStash (device code flow)
+2. Bind your device to the default Keyset
+3. Choose your database connection method (Drizzle ORM, Supabase JS, Prisma, or Raw SQL)
+4. Build an encryption schema interactively or use a placeholder, then generate the encryption client file
+5. Install `@cipherstash/stack-forge` as a dev dependency for database tooling
 
-After `stash init`, create a CipherStash account at [dashboard.cipherstash.com/sign-up](https://dashboard.cipherstash.com/sign-up) to get your credentials, then run `npx stash-forge setup` to configure your database connection.
+After `stash init`, run `npx stash-forge setup` to configure your database.
 
 | Flag | Description |
 |------|-------------|
@@ -468,11 +490,15 @@ npx stash secrets delete -name DATABASE_URL -environment production
 | `stash secrets list` | `-environment` | `-e` | List all secret names in an environment |
 | `stash secrets delete` | `-name`, `-environment`, `-yes` | `-n`, `-e`, `-y` | Delete a secret (prompts for confirmation unless `-yes`) |
 
-The CLI reads credentials from the same `CS_*` environment variables described in [Configuration](#configuration).
-
 ## Configuration
 
-### Environment Variables
+### Local Development
+
+No environment variables or credentials are needed for local development. Run `npx @cipherstash/stack auth login` to authenticate via the device code flow, and the SDK and CLI will use the token saved to `~/.cipherstash/auth.json`.
+
+### Going to Production
+
+For production, CI/CD, and deployed environments, you'll need to set up machine credentials via environment variables:
 
 | Variable | Description |
 |-----|-------|
@@ -481,13 +507,7 @@ The CLI reads credentials from the same `CS_*` environment variables described i
 | `CS_CLIENT_KEY` | Client key material used with ZeroKMS for encryption |
 | `CS_CLIENT_ACCESS_KEY` | API key for authenticating with the CipherStash API |
 
-Store these in a `.env` file or set them in your hosting platform.
-
-Sign up at [cipherstash.com/signup](https://cipherstash.com/signup) and follow the onboarding to generate credentials.
-
-### TOML Config
-
-You can also configure credentials via `cipherstash.toml` and `cipherstash.secret.toml` files in your project root. See the [CipherStash docs](https://cipherstash.com/docs) for format details.
+See the [Going to Production](https://cipherstash.com/docs/stack/going-to-production) guide for full details on creating machine clients, setting up access keys, and configuring CI/CD pipelines.
 
 ### Programmatic Config
 

packages/stack/package.json

@@ -206,10 +206,11 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@byteslice/result": "^0.2.0",
+		"@byteslice/result": "0.2.0",
+		"@cipherstash/auth": "0.34.2",
 		"@cipherstash/protect-ffi": "0.21.0",
-		"evlog": "^1.9.0",
-		"uuid": "^13.0.0",
+		"evlog": "1.9.0",
+		"uuid": "13.0.0",
 		"zod": "3.24.2"
 	},
 	"peerDependencies": {

packages/stack/src/bin/commands/auth/index.ts

@@ -0,0 +1,33 @@
+import { bindDevice, login, selectRegion } from './login.js'
+
+const HELP = `
+Usage: stash auth <command>
+
+Commands:
+  login     Authenticate with CipherStash
+
+Examples:
+  stash auth login
+`.trim()
+
+export async function authCommand(args: string[]) {
+  const subcommand = args[0]
+
+  if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+    console.log(HELP)
+    return
+  }
+
+  switch (subcommand) {
+    case 'login': {
+      const region = await selectRegion()
+      await login(region)
+      await bindDevice()
+    }
+      break
+    default:
+      console.error(`Unknown auth command: ${subcommand}\n`)
+      console.log(HELP)
+      process.exit(1)
+  }
+}

packages/stack/src/bin/commands/auth/login.ts

@@ -0,0 +1,65 @@
+import * as p from '@clack/prompts'
+import auth from '@cipherstash/auth'
+const { beginDeviceCodeFlow, bindClientDevice } = auth
+
+// TODO: pull from the CTS API
+export const regions = [
+  { value: 'ap-southeast-2.aws', label: 'Asia Pacific (Sydney)' },
+  { value: 'eu-central-1.aws', label: 'Europe (Frankfurt)' },
+  { value: 'eu-west-1.aws', label: 'Europe (Ireland)' },
+  { value: 'us-east-1.aws', label: 'US East (N. Virginia)' },
+  { value: 'us-east-2.aws', label: 'US East (Ohio)' },
+  { value: 'us-west-1.aws', label: 'US West (N. California)' },
+  { value: 'us-west-2.aws', label: 'US West (Oregon)' },
+]
+
+export async function selectRegion(): Promise<string> {
+  const region = await p.select({
+    message: 'Select a region',
+    options: regions,
+  })
+
+  if (p.isCancel(region)) {
+    p.cancel('Cancelled.')
+    process.exit(0)
+  }
+
+  return region
+}
+
+export async function login(region: string) {
+  const s = p.spinner()
+
+  const pending = await beginDeviceCodeFlow(region, 'cli')
+
+  p.log.info(`Your code is: ${pending.userCode}`)
+  p.log.info(`Visit: ${pending.verificationUriComplete}`)
+  p.log.info(`Code expires in: ${pending.expiresIn}s`)
+
+  const opened = pending.openInBrowser()
+  if (!opened) {
+    p.log.warn('Could not open browser — please visit the URL above manually.')
+  }
+
+  s.start('Waiting for authorization...')
+  const auth = await pending.pollForToken()
+  s.stop('Authenticated! Token saved to ~/.cipherstash/auth.json')
+
+  p.log.info(
+    `Token expires at: ${new Date(auth.expiresAt * 1000).toISOString()}`,
+  )
+}
+
+export async function bindDevice() {
+  const s = p.spinner()
+  s.start('Binding device to the default Keyset...')
+
+  try {
+    await bindClientDevice()
+    s.stop('Your device has been bound to the default Keyset!')
+  } catch (error) {
+    s.stop('Failed to bind your device to the default Keyset!')
+    p.log.error(error instanceof Error ? error.message : 'Unknown error')
+    process.exit(1)
+  }
+}

packages/stack/src/bin/commands/init/index.ts

@@ -1,6 +1,7 @@
 import * as p from '@clack/prompts'
 import { createBaseProvider } from './providers/base.js'
 import { createSupabaseProvider } from './providers/supabase.js'
+import { authenticateStep } from './steps/authenticate.js'
 import { buildSchemaStep } from './steps/build-schema.js'
 import { installForgeStep } from './steps/install-forge.js'
 import { nextStepsStep } from './steps/next-steps.js'
@@ -13,6 +14,7 @@ const PROVIDER_MAP: Record<string, () => InitProvider> = {
 }
 
 const STEPS = [
+  authenticateStep,
   selectConnectionStep,
   buildSchemaStep,
   installForgeStep,

packages/stack/src/bin/commands/init/providers/base.ts

@@ -11,10 +11,7 @@ export function createBaseProvider(): InitProvider {
       { value: 'raw-sql', label: 'Raw SQL / pg' },
     ],
     getNextSteps(state: InitState): string[] {
-      const steps = [
-        'Create a CipherStash account and get your credentials:\n   https://dashboard.cipherstash.com/sign-up\n   Then set: CS_WORKSPACE_CRN, CS_CLIENT_ID, CS_CLIENT_KEY, CS_CLIENT_ACCESS_KEY',
-        'Set up your database: npx stash-forge setup',
-      ]
+      const steps = ['Set up your database: npx stash-forge setup']
 
       if (state.clientFilePath) {
         steps.push(`Edit your encryption schema: ${state.clientFilePath}`)

packages/stack/src/bin/commands/init/providers/supabase.ts

@@ -15,10 +15,7 @@ export function createSupabaseProvider(): InitProvider {
       { value: 'raw-sql', label: 'Raw SQL / pg' },
     ],
     getNextSteps(state: InitState): string[] {
-      const steps = [
-        'Create a CipherStash account and get your credentials:\n   https://dashboard.cipherstash.com/sign-up\n   Then set: CS_WORKSPACE_CRN, CS_CLIENT_ID, CS_CLIENT_KEY, CS_CLIENT_ACCESS_KEY',
-        'Set up your database: npx stash-forge setup',
-      ]
+      const steps = ['Set up your database: npx stash-forge setup']
 
       if (state.clientFilePath) {
         steps.push(`Edit your encryption schema: ${state.clientFilePath}`)

packages/stack/src/bin/commands/init/steps/authenticate.ts

@@ -0,0 +1,13 @@
+import { bindDevice, login, selectRegion } from '../../auth/login.js'
+import type { InitProvider, InitState, InitStep } from '../types.js'
+
+export const authenticateStep: InitStep = {
+  id: 'authenticate',
+  name: 'Authenticate with CipherStash',
+  async run(state: InitState, _provider: InitProvider): Promise<InitState> {
+    const region = await selectRegion()
+    await login(region)
+    await bindDevice()
+    return { ...state, authenticated: true }
+  },
+}

packages/stack/src/bin/commands/init/types.ts

@@ -18,6 +18,7 @@ export interface SchemaDef {
 }
 
 export interface InitState {
+  authenticated?: boolean
   connectionMethod?: ConnectionMethod
   clientFilePath?: string
   schemaGenerated?: boolean