@brassproof/create

CLI tool to scaffold BRASS-protected applications with a single command.

Usage

Create a New Project

npx @brassproof/create create

Or install globally:

npm install -g @brassproof/create
brass create

Direct Project Creation

# Create Next.js app
npx @brassproof/create create next-app my-app

# Create Cloudflare Worker
npx @brassproof/create create worker my-worker

Project Types

Next.js App

Creates a Next.js 14 application with:

• BRASS React hooks (useBrass)
• Protected API routes (withBrassVerifier)
• Example form component
• TypeScript configuration
• Tailwind CSS setup

Generated structure:

my-app/
├── app/
│   ├── page.tsx              # Example form using useBrass
│   └── api/
│       └── submit/
│           └── route.ts       # Protected API route
├── package.json
├── .env.example
└── README.md

Next steps:

cd my-app
npm install
cp .env.example .env.local    # Add your BRASS credentials
npm run dev

Cloudflare Worker

Creates a Cloudflare Worker with:

• BRASS worker helper (createBrassWorker)
• KV namespace configuration
• Wrangler setup
• TypeScript configuration

Generated structure:

my-worker/
├── src/
│   └── index.ts              # Worker with BRASS protection
├── wrangler.toml             # Cloudflare configuration
├── package.json
└── README.md

Next steps:

cd my-worker
npm install
wrangler kv:namespace create BRASS_KV  # Create KV namespace
# Update wrangler.toml with KV namespace ID
wrangler secret put BRASS_SECRET_KEY
wrangler secret put BRASS_ISSUER_PUBKEY
wrangler deploy

Interactive Mode

Running brass create without arguments starts interactive mode:

$ brass create

🛡️  BRASS Project Creator

? What type of project do you want to create? › 
  Next.js App (with React hooks)
  Cloudflare Worker

? Project name: › my-brass-app

Environment Variables

Next.js Projects

Create .env.local:

BRASS_SECRET_KEY=your_secret_key_here
BRASS_ISSUER_PUBKEY=issuer_public_key_hex

Cloudflare Workers

Set secrets via Wrangler:

wrangler secret put BRASS_SECRET_KEY
wrangler secret put BRASS_ISSUER_PUBKEY

Get issuer public key:

curl https://brass-issuer.tomjwxf.workers.dev/pub

Commands

create [type] [name]

Create a new BRASS-protected project.

Arguments:

• type - Project type: next-app or worker
• name - Project directory name

Options:

• -h, --help - Display help
• -V, --version - Display version

Examples:

# Interactive mode
brass create

# Create Next.js app
brass create next-app my-nextjs-app

# Create Cloudflare Worker
brass create worker my-worker

What Gets Created

Next.js App

Dependencies:

• next - Next.js framework
• react - React library
• @brassproof/nextjs - BRASS Next.js integration
• @brassproof/verifier - Core verifier
• tailwindcss - Styling

Features:

• Protected API route example
• Client-side form with BRASS hook
• TypeScript support
• Tailwind CSS configuration
• Environment variable setup

Cloudflare Worker

Dependencies:

• @brassproof/cloudflare - BRASS Cloudflare integration
• @brassproof/verifier - Core verifier
• wrangler - Cloudflare CLI

Features:

• Protected worker handler
• KV namespace configuration
• Rate limiting setup
• TypeScript support
• Wrangler configuration

Customization

After creating a project, you can customize:

Rate Limits

Edit the rateLimits configuration:

// Next.js: app/api/submit/route.ts
export const POST = withBrassVerifier(handler, {
  scope: 'custom-scope',
  rateLimits: {
    'custom-scope': { maxRequests: 100, windowSeconds: 3600 }
  }
})

// Worker: src/index.ts
export default {
  fetch: createBrassWorker(handler, {
    rateLimits: {
      'message': { maxRequests: 50, windowSeconds: 3600 }
    }
  })
}

CORS Headers

// Worker
export default {
  fetch: createBrassWorker(handler, {
    corsHeaders: {
      'Access-Control-Allow-Origin': 'https://yourdomain.com',
    }
  })
}

Troubleshooting

"Directory already exists"

The CLI will prompt you to overwrite. Choose yes to replace the existing directory.

"npm install fails"

Ensure you have Node.js 18+ installed:

node --version

"wrangler command not found"

Install Wrangler globally:

npm install -g wrangler

Learn More

• BRASS Documentation
• @brassproof/nextjs
• @brassproof/cloudflare
• @brassproof/verifier

License

MIT - see LICENSE for details.