@getbrevo/cli 2.0.2 → 2.1.0

package/dist/{templates → bin}/files/AGENTS.md.tmpl

@@ -33,11 +33,21 @@ Implements the authorization code flow to obtain access tokens for the Brevo API
 - Other grant types supported by the Brevo OAuth server but not wired into this scaffold: `client_credentials`
 
 ## OAuth flow
+{{#if private}}
 1. `/auth/login` — generates CSRF state, redirects user to `{OAUTH_BASE}/realms/{realm}/oauth/authorize`
 2. User authorizes -> OAuth server redirects to `/auth/callback` with an auth code
-3. Server validates state, exchanges code for access + refresh tokens via `POST /realms/{realm}/oauth/token`
+3. Server validates state, exchanges code for access + refresh tokens via `POST /realms/{realm}/oauth/token` (authenticated with `client_secret`)
 4. Verifies connection via `GET /realms/{realm}/oauth/userinfo`
 5. `/auth/refresh` — refreshes tokens using `refresh_token` grant
+{{/if}}
+{{#if public}}
+This is a **public app** — the flow uses **PKCE (RFC 7636)** and sends **no `client_secret`**:
+1. `/auth/login` — generates CSRF state + a PKCE `code_verifier`, then redirects user to `{OAUTH_BASE}/realms/{realm}/oauth/authorize` with `code_challenge` (S256) + `code_challenge_method=S256`
+2. User authorizes -> OAuth server redirects to `/auth/callback` with an auth code
+3. Server validates state, exchanges code + `code_verifier` (no `client_secret`) for access + refresh tokens via `POST /realms/{realm}/oauth/token`
+4. Verifies connection via `GET /realms/{realm}/oauth/userinfo`
+5. `/auth/refresh` — refreshes tokens using `refresh_token` grant (no `client_secret`)
+{{/if}}
 
 ## Development
 ```bash

package/dist/{templates → bin}/files/CLAUDE.md.tmpl

@@ -47,9 +47,17 @@ brevo app start oauth        # port is read from app-config.json; override with
 | `GET /realms/{realm}/.well-known/openid-configuration` | OIDC discovery |
 
 ## Key flows
+{{#if private}}
 - `/auth/login` — generates random CSRF state, redirects to OAuth authorize endpoint
 - `/auth/callback` — validates state, POSTs code to `/realms/{realm}/oauth/token`, stores tokens
 - `/auth/refresh` — refreshes tokens using `refresh_token` grant
+{{/if}}
+{{#if public}}
+This is a **public app**, so the flow uses **PKCE (RFC 7636)** and no client secret:
+- `/auth/login` — generates random CSRF state **and a PKCE `code_verifier`**, then redirects to the OAuth authorize endpoint sending `code_challenge` (S256 hash of the verifier) + `code_challenge_method=S256`. The verifier is stored server-side and never sent to the browser.
+- `/auth/callback` — validates state, POSTs code **plus the `code_verifier`** (no `client_secret`) to `/realms/{realm}/oauth/token`, stores tokens
+- `/auth/refresh` — refreshes tokens using the `refresh_token` grant (no `client_secret`)
+{{/if}}
 
 ## Next steps
 - Replace the in-memory token store in `src/oauth/token-store.js` with a real database (the global singleton is process-local so data is lost on restart, and it is not session-isolated, so multiple users/sessions/tabs can read or overwrite the same in-memory tokens)

package/dist/{templates → bin}/files/README.md.tmpl

@@ -55,28 +55,25 @@ Brevo OAuth integration for testing and implementing app authorization flows, sc
 
 ## Updating your app
 
-Push changes to Brevo directly from the CLI:
+`brevo app upload` has no edit flags — it always pushes the full contents of `app-config.json`. To change something, edit the file, then run:
 
 ```bash
-brevo app update --name "New Name"
-brevo app update --redirect-url https://myapp.com/callback
-brevo app update --name "New Name" --redirect-url https://myapp.com/callback
-brevo app update --logo-uri https://example.com/logo.png
+brevo app upload
 ```
 
-`--redirect-url` is repeatable and **appends** to existing URLs.
+For example, to rename the app or add a redirect URL, edit `appName` or `auth.redirectUris` in `app-config.json`:
 
-To avoid unintentionally accumulating stale redirect URLs over time:
+```bash
+# 1. Edit app-config.json (e.g. change "appName", or append to "auth.redirectUris")
+# 2. Push the change
+brevo app upload
+```
 
-- Periodically review your redirect list and remove obsolete entries in `app-config.json`.
-- Run `brevo app update` **without flags** to replace the remote configuration with the local file.
-- When flags are provided, the local `app-config.json` is updated automatically after a successful API call.
+`brevo app upload` always fetches the current server state first and shows a diff before pushing — review it before confirming (or pass `--yes` to skip the prompt).
 
-Outside this project directory, target an app by ID:
+To avoid unintentionally accumulating stale redirect URLs over time, periodically review `auth.redirectUris` in `app-config.json` and remove obsolete entries before running `brevo app upload`.
 
-```bash
-brevo app update --app-id {{APP_ID}} --name "New Name"
-```
+`brevo app upload` has no `--app-id` flag — it always resolves the app from this directory's `app-config.json`. To manage a different app, `cd` into that app's project directory (or use `brevo app credentials --app-id <id>` to inspect it without editing).
 
 ## Docs
 

package/dist/bin/files/app-config.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "appId": "{{APP_ID}}",
+  "appName": "{{APP_NAME}}",
+  "version": "{{APP_VERSION}}",
+  "logoUri": "{{LOGO_URI}}",
+  "distribution_type": "{{DISTRIBUTION}}",
+{{#if ui_app}}
+  "ui_app": {{UI_APP_JSON}},
+{{/if}}
+  "auth": {
+{{#if oauth}}
+    "scopes": {{SCOPES_JSON}},
+    "redirectUris": {{REDIRECT_URLS_JSON}}
+{{/if}}
+  }
+}

package/dist/{templates → bin}/files/src/oauth/.env.example.tmpl

@@ -1,8 +1,16 @@
 # Brevo OAuth Credentials — copy this file to .env.local and fill in your values
+{{#if private}}
 # Get CLIENT_ID and CLIENT_SECRET: brevo app credentials --reveal-secret
+{{/if}}
+{{#if public}}
+# Get CLIENT_ID: brevo app credentials
+# This is a public app — it uses PKCE (RFC 7636) and no client secret.
+{{/if}}
 
 CLIENT_ID=your_client_id_here
+{{#if private}}
 CLIENT_SECRET=your_client_secret_here
+{{/if}}
 REDIRECT_URI={{REDIRECT_URI}}
 
 # OAuth server

package/dist/{templates → bin}/files/src/oauth/.env.local.tmpl

@@ -2,7 +2,9 @@
 # Generated by: brevo app scaffold
 
 CLIENT_ID={{CLIENT_ID}}
+{{#if private}}
 CLIENT_SECRET={{CLIENT_SECRET}}
+{{/if}}
 REDIRECT_URI={{REDIRECT_URI}}
 
 # OAuth server

package/dist/{templates → bin}/files/src/oauth/handler.js.tmpl

@@ -38,7 +38,9 @@ const REVEAL_SCRIPT =
   '<script>document.querySelectorAll(".reveal-btn").forEach(function(btn){btn.addEventListener("click",function(){btn.parentElement.querySelector(".token-value").classList.add("revealed");btn.classList.add("hidden")})});</script>';
 
 const CLIENT_ID = process.env.CLIENT_ID;
+{{#if private}}
 const CLIENT_SECRET = process.env.CLIENT_SECRET;
+{{/if}}
 const REDIRECT_URI = process.env.REDIRECT_URI || '{{REDIRECT_URI}}';
 const OAUTH_BASE = process.env.OAUTH_BASE || '{{OAUTH_BASE}}';
 const OAUTH_REALM = process.env.OAUTH_REALM || '{{OAUTH_REALM}}';
@@ -55,19 +57,48 @@ try {
   console.warn('Warning: Could not read app-config.json — defaulting scopes to "all".');
 }
 
-// Step 1: Redirect user to authorization page
-router.get('/login', (req, res) => {
-  const state = require('crypto').randomBytes(16).toString('hex');
-  tokenStore.setState(state);
-
-  const authUrl = `${realmPath}/authorize?` +
+// Build the OAuth authorization URL. Extracted so /auth/login and the
+// server.js landing page render the exact same URL — no drift between the two.
+{{#if public}}
+// `codeChallenge` is the PKCE (RFC 7636) S256 challenge. Base64url output is
+// already URL-safe, so it is not re-encoded (matching the `state` treatment).
+function buildAuthorizeUrl({ state, codeChallenge }) {
+{{/if}}
+{{#if private}}
+function buildAuthorizeUrl({ state }) {
+{{/if}}
+  let authUrl = `${realmPath}/authorize?` +
     `response_type=code` +
     `&client_id=${encodeURIComponent(CLIENT_ID)}` +
     `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
     `&state=${state}` +
     `&scope=${encodeURIComponent(SCOPES)}`;
+{{#if public}}
+  authUrl += `&code_challenge=${codeChallenge}&code_challenge_method=S256`;
+{{/if}}
+  return authUrl;
+}
+
+// Step 1: Redirect user to authorization page
+router.get('/login', (req, res) => {
+  const crypto = require('crypto');
+  const state = crypto.randomBytes(16).toString('hex');
+  tokenStore.setState(state);
+{{#if public}}
+
+  // PKCE (RFC 7636): create a high-entropy verifier, keep it server-side, and
+  // send only its SHA-256 (S256) hash on the authorize request. The verifier
+  // itself is presented only later, on the token exchange in /auth/callback.
+  const codeVerifier = crypto.randomBytes(32).toString('base64url');
+  const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+  tokenStore.setVerifier(codeVerifier);
+
+  res.redirect(buildAuthorizeUrl({ state, codeChallenge }));
+{{/if}}
+{{#if private}}
 
-  res.redirect(authUrl);
+  res.redirect(buildAuthorizeUrl({ state }));
+{{/if}}
 });
 
 // Step 2: Handle the OAuth callback
@@ -94,7 +125,14 @@ router.get('/callback', async (req, res) => {
       new URLSearchParams({
         grant_type: 'authorization_code',
         client_id: CLIENT_ID,
+{{#if private}}
         client_secret: CLIENT_SECRET,
+{{/if}}
+{{#if public}}
+        // PKCE (RFC 7636): prove possession of the verifier generated in /login.
+        // Public clients hold no secret, so this replaces client_secret entirely.
+        code_verifier: tokenStore.getVerifier(),
+{{/if}}
         code,
         redirect_uri: REDIRECT_URI,
       }),
@@ -165,7 +203,9 @@ router.get('/refresh', async (req, res) => {
       new URLSearchParams({
         grant_type: 'refresh_token',
         client_id: CLIENT_ID,
+{{#if private}}
         client_secret: CLIENT_SECRET,
+{{/if}}
         refresh_token: refreshToken,
       }),
       { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } },
@@ -204,3 +244,5 @@ router.get('/refresh', async (req, res) => {
 });
 
 module.exports = router;
+// Exposed so server.js renders the same authorize URL the /login redirect uses.
+module.exports.buildAuthorizeUrl = buildAuthorizeUrl;

package/dist/{templates → bin}/files/src/oauth/server.js.tmpl

@@ -14,11 +14,21 @@ if (!fs.existsSync(envPath)) {
 
 require('dotenv').config({ path: envPath });
 
+{{#if private}}
 if (!process.env.CLIENT_ID || !process.env.CLIENT_SECRET) {
   console.error('\nError: CLIENT_ID and CLIENT_SECRET must be set in .env.local');
   console.error('Get your credentials with: brevo app credentials --reveal-secret\n');
   process.exit(1);
 }
+{{/if}}
+{{#if public}}
+// Public apps use PKCE (RFC 7636) — no client secret is involved.
+if (!process.env.CLIENT_ID) {
+  console.error('\nError: CLIENT_ID must be set in .env.local');
+  console.error('Get your credentials with: brevo app credentials\n');
+  process.exit(1);
+}
+{{/if}}
 
 if (!process.env.OAUTH_BASE || process.env.OAUTH_BASE.startsWith('{{')) {
   console.error('\nError: OAUTH_BASE is not set or contains a placeholder.');
@@ -33,24 +43,20 @@ if (!process.env.OAUTH_REALM || process.env.OAUTH_REALM.startsWith('{{')) {
 
 const express = require('express');
 const authRouter = require('./handler');
+const { buildAuthorizeUrl } = authRouter;
 
 const app = express();
 const PORT = process.env.PORT || 3009;
 
-const REDIRECT_URI = process.env.REDIRECT_URI || '{{REDIRECT_URI}}';
-let SCOPES = 'all';
-try {
-  const appConfig = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'app-config.json'), 'utf-8'));
-  if (appConfig.auth && appConfig.auth.scopes) SCOPES = appConfig.auth.scopes.join(' ');
-} catch {
-  console.warn('Warning: Could not read app-config.json — defaulting scopes to "all".');
-}
-const AUTH_URL = `${process.env.OAUTH_BASE}/realms/${process.env.OAUTH_REALM}/oauth/authorize`
-  + `?response_type=code`
-  + `&client_id=${encodeURIComponent(process.env.CLIENT_ID)}`
-  + `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`
-  + `&state=[random]`
-  + `&scope=${encodeURIComponent(SCOPES)}`;
+// Build the displayed authorization URL with the same helper /auth/login uses,
+// so what the landing page shows always matches what the redirect actually
+// sends. Placeholders (`[random]` state) stand in for the per-request values.
+{{#if private}}
+const AUTH_URL = buildAuthorizeUrl({ state: '[random]' });
+{{/if}}
+{{#if public}}
+const AUTH_URL = buildAuthorizeUrl({ state: '[random]', codeChallenge: '[generated-per-login]' });
+{{/if}}
 
 app.use('/auth', authRouter);
 

package/dist/{templates → bin}/files/src/oauth/token-store.js.tmpl

@@ -2,6 +2,9 @@
 
 let tokens = {};
 let csrfState = null;
+{{#if public}}
+let codeVerifier = null;
+{{/if}}
 
 module.exports = {
   saveTokens({ access_token, refresh_token, expires_in }) {
@@ -31,9 +34,25 @@ module.exports = {
   getState() {
     return csrfState;
   },
+{{#if public}}
+
+  // PKCE (RFC 7636): stash the code_verifier between /auth/login and
+  // /auth/callback. Same process-local, non-session-isolated limitation as the
+  // token store above — replace with your database in production.
+  setVerifier(verifier) {
+    codeVerifier = verifier;
+  },
+
+  getVerifier() {
+    return codeVerifier;
+  },
+{{/if}}
 
   clear() {
     tokens = {};
     csrfState = null;
+{{#if public}}
+    codeVerifier = null;
+{{/if}}
   },
 };