@nakedev/go-scaffold 0.4.0 → 0.4.3

package/README.md

@@ -4,7 +4,8 @@ A CLI that scaffolds a Gin + GORM + PostgreSQL Go backend, then keeps
 generating consistent domain modules into that project as it grows — the Go
 counterpart to nest-scaffold.
 
-You don't hand-wire a new domain into `cmd/api/wiring.go`, write the
+You don't hand-wire a new domain's repository/service/handler composition into
+`cmd/api/wiring.go`, write the
 handler/service/repository boilerplate, or decide error-handling conventions
 each time — the CLI does that, and every module it generates follows the
 same shape as the last one.
@@ -33,6 +34,84 @@ node bin/go-scaffold.js create my-api --defaults
 depending on your machine's npm/pnpm global-bin config — running
 `node bin/go-scaffold.js ...` directly sidesteps that.
 
+## Release: npm is locked to Git
+
+Git is the release source of truth. The package version, annotated tag, and
+tagged commit must agree before npm can publish:
+
+```text
+package.json 0.4.3
+       │
+       └── annotated tag v0.4.3 ──> the exact release commit
+                                      │
+                                      └── npm @nakedev/go-scaffold@0.4.3
+```
+
+`npm publish` runs `release:check` first, so publishing from an untagged,
+lightweight-tagged, dirty, or mismatched checkout fails before anything is
+sent to npm. The GitHub Actions workflow at
+`.github/workflows/release.yml` repeats that check, runs the full verification
+gate, publishes from the tag, and creates the GitHub Release.
+
+### One-time npm setup
+
+The preferred setup is npm Trusted Publishing with GitHub Actions (OIDC):
+
+1. In npm package settings for `@nakedev/go-scaffold`, add a GitHub Actions
+   trusted publisher for `NakePranob/go-scaffold`.
+2. Set the workflow filename to `release.yml` and environment to
+   `npm-release`.
+3. Allow `npm publish`. The workflow already requests the required OIDC
+   permission and uses Node 24.
+
+If Trusted Publishing is not used, add an npm granular token as the GitHub
+repository/environment secret `NPM_TOKEN`. Never commit a token or put it in
+`.npmrc`.
+
+### Branch policy
+
+`develop` is the integration branch. A PR into `main` must come from
+`develop` or `release/*`, and must bump `package.json` to a semver greater than
+the version on `main`. PRs into `develop` do not need a version bump.
+
+The `main-merge-policy` workflow checks this automatically. In GitHub branch
+rules, protect `main`, require a pull request, require the
+`main-merge-policy`, `verify`, and `packaged-artifact` checks, and disable
+force-pushes. Protect the `v*` tag pattern from updates and deletion as well.
+
+### Release flow
+
+```bash
+git switch develop
+git pull --ff-only origin develop
+git switch -c release/v0.4.3
+npm version 0.4.3 --no-git-tag-version
+pnpm run verify
+git add package.json
+git commit -m "chore: release v0.4.3"
+git push -u origin release/v0.4.3
+# open a PR from release/v0.4.3 into main
+
+# after the PR is merged, tag the merge commit on main
+git switch main
+git pull --ff-only origin main
+git tag -a v0.4.3 -m "v0.4.3"
+git push origin v0.4.3
+```
+
+Pushing the tag starts the release workflow. To retry a failed publish for a
+tag created after this workflow landed, use GitHub Actions' **Run workflow**
+with that tag; do not create a second tag for the same package version. A tag
+created before this guard existed should not be moved after it has been
+pushed — use the next patch version instead.
+
+## Requirements
+
+- Node.js `>=22.13` to run the CLI
+- Go `>=1.25` for the generated project
+- A running PostgreSQL instance; Docker is optional, but either `psql` or a
+  Docker container is needed by `make db-create`
+
 ## Quick start
 
 ```bash
@@ -51,12 +130,60 @@ go-scaffold generate module orders
 go-scaffold generate method orders approve --type patch
 ```
 
+## The 30-second flow
+
+The CLI has two layers of interaction: the command you choose, then only the
+questions that command still needs. Flags are answers, not requests to ask the
+same question again.
+
+```text
+go-scaffold create my-api
+  1. Docker + PostgreSQL?
+  2. OpenAPI files?
+  3. Metrics + tracing?
+  4. API route prefix?
+  5. Default module profile: Lean / CRUD / CQRS / Advanced?
+  6. Summary confirmation
+
+cd my-api
+go-scaffold generate module users
+  1. Module profile: Lean / CRUD / CQRS / Advanced?
+  2. Require an access token?              # only when auth is installed
+  3. Permission code?                      # only when auth + RBAC are installed
+  -> writes internal/app/user/, its migration, wiring, and config metadata
+```
+
+`Advanced` is the only path that asks the two lower-level architecture
+questions separately. `--profile` and `--defaults` are the scripted forms; the
+latter uses the project defaults recorded in `go-scaffold.config.json`.
+
 ## Commands
 
 Every `add` command shows what it's about to do and asks before writing;
 `-y/--yes` skips that (and `--defaults` implies it) for CI and scripts.
 Running `go-scaffold` with no arguments picks the command from a menu.
 
+### Wizard coverage
+
+The interactive path is deliberately available from both the bare command and
+the direct command form:
+
+| Command | Wizard coverage |
+|---|---|
+| `create [name]` | asks for the project name and settings that were not passed as flags |
+| `generate` / `generate module [name]` | chooses a target, module name, and module profile; `Advanced` asks the two underlying architecture questions |
+| `generate method [module] [name]` | asks for the existing module, method name, HTTP verb, GET mode, and lookup field when needed |
+| `generate migration [name]` | asks for the migration name when omitted |
+| `config` | edits future module defaults; existing modules are unchanged |
+| `config show` / `config validate` | intentionally no wizard: read-only print/validation commands |
+| `add` / `add worker` / `add auth` | chooses the feature, backend/topology, and confirmation where applicable |
+| `add rbac` / `add observability` | no parameter choice is needed; the direct command confirms, while bare `add` selects the target |
+| `undo` / `undo module [name]` | asks for the generated module and confirmation when omitted |
+
+Run any command with `--help` for the non-interactive equivalent. If a value is
+omitted in a non-TTY shell, the CLI exits before writing and tells you which
+flag or `--defaults` is required.
+
 
 ### `create <name>` — scaffold a new project
 
@@ -74,15 +201,21 @@ with `generate module`.
 
 | Option | Effect |
 |---|---|
-| `--defaults` | Skip the wizard, use defaults (Docker on, OpenAPI docs on, no route prefix) |
-| `--no-docker` | Skip `docker-compose.yml` |
-| `--no-openapi-docs` | Skip `docs/openapi.yaml` |
-| `--observability` | Prometheus `/metrics` + OpenTelemetry tracing (off by default — `add observability` does the same later) |
-| `--api-prefix <prefix>` | URL prefix every route is grouped under — opt in with e.g. `v1` or `api/v1`; omit it for none |
-
-Without `--defaults`, an interactive wizard asks the same four questions —
+| `--defaults` | Skip settings prompts; use Docker/OpenAPI on, no prefix, and Lean (`minimal + service`) defaults for future modules |
+| `--no-docker` | Do not create `docker-compose.yml` or include a local Postgres service |
+| `--no-openapi-docs` | Do not create `docs/openapi.yaml` or per-module OpenAPI files |
+| `--observability` | Include Prometheus `/metrics` + OpenTelemetry tracing; off unless passed |
+| `--api-prefix <prefix>` | Group every API route under a prefix such as `v1` or `api/v1`; omit for no prefix |
+| `--module-profile <lean\|crud\|cqrs>` | Default profile for future modules; replaces the two architecture questions |
+| `--module-surface <minimal\|crud>` | Legacy axis flag for future modules; use `--module-profile` for a clearer preset |
+| `--application-style <service\|cqrs>` | Legacy axis flag for future modules; use `--module-profile` for a clearer preset |
+
+Without `--defaults`, an interactive wizard asks the project questions —
 skipping any a flag already answered, so `create my-api --no-docker` never asks
-about Docker and never scaffolds it.
+about Docker and never scaffolds it. It also asks for the default module
+profile so future `generate module` commands start with the project's
+conventions. Choose `Advanced` when you intentionally want the less common
+CRUD + CQRS combination.
 The prefix is a single project-wide choice made once at `create` time —
 there's no per-domain versioning (a domain that needs a real breaking change
 gets a new domain package or a new DTO field, not a duplicated model pointed
@@ -91,18 +224,72 @@ below).
 
 **Config file** — every `create` writes `go-scaffold.config.json` to the
 project root; `generate` reads it back (or auto-detects from `go.mod` /
-directory layout if missing).
+directory layout if missing). It records project defaults and the resolved
+surface/application style of each generated module:
+
+```json
+{
+  "schemaVersion": 1,
+  "architecture": {
+    "style": "modular-monolith",
+    "defaultModuleSurface": "minimal",
+    "defaultApplicationStyle": "service"
+  },
+  "modules": {
+    "order": { "surface": "crud", "applicationStyle": "cqrs" }
+  }
+}
+```
+
+Run these from the generated project root. Use the wizard again later without
+recreating the project:
+
+```bash
+go-scaffold config                 # interactive project-default wizard
+go-scaffold config show            # print the resolved config
+go-scaffold config validate        # validate without changing anything
+```
+
+### Module profiles
+
+The wizard asks for one useful profile instead of forcing everyone to reason
+about two implementation axes up front:
+
+| Profile | Resolves to | Use it when |
+|---|---|---|
+| `lean` | minimal surface + one service | the domain should start small and grow endpoint by endpoint |
+| `crud` | CRUD surface + one service | the domain genuinely needs the standard list/get/create/update/delete starter |
+| `cqrs` | minimal surface + command/query handlers | reads and writes have different business models, invariants, or scaling pressure |
+| `Advanced` (wizard only) | choose both axes separately | you deliberately want a custom mix, including CRUD + CQRS |
+
+The scaffold is DDD-shaped rather than a complete tactical DDD implementation:
+it gives each domain a package boundary, repository port, application boundary,
+feature-local composition, and shared error conventions. It does not invent
+aggregates, value objects, domain events, or business invariants for you; those
+belong to the domain team.
+
+`minimal` means the generator does not invent five endpoints before the domain
+has real requirements. `CQRS` does not mean a second database, broker, or event
+bus here. It only separates command and query application handlers inside the
+same modular monolith.
 
 ### `generate module <name>` (alias `m`) — add a domain module
 
 ```bash
-go-scaffold generate module orders                  # asks for the shape (and auth, if installed)
-go-scaffold generate module orders --full           # opt-in CRUD skeleton, no prompt
-go-scaffold generate module orders --defaults       # safe minimal module, no prompt (CI/scripting)
+go-scaffold generate module orders                  # asks for profile (and auth, if installed)
+go-scaffold generate module orders --profile lean   # explicit Lean profile, no architecture prompt
+go-scaffold generate module orders --profile crud   # explicit CRUD profile, no architecture prompt
+go-scaffold generate module orders --profile cqrs   # explicit CQRS profile, no architecture prompt
+go-scaffold generate module orders --full --cqrs    # legacy flags: CRUD + separate command/query handlers
+go-scaffold generate module orders --defaults       # use project defaults, no prompt (CI/scripting)
 ```
 
-Anything you don't pass as a flag is asked for; `--defaults` takes the
-documented defaults (minimal, no auth) and asks nothing.
+Anything you don't pass as a flag is asked for; the prompt starts with the
+project defaults. `--defaults` uses those defaults without asking anything
+(fresh and legacy projects default to Lean, with no auth). `--profile` is the
+non-interactive equivalent of choosing a named profile for this module. The
+older `--full` and `--cqrs` flags remain supported for existing scripts; do not
+combine them with `--profile`.
 
 `--full` scaffolds:
 
@@ -113,12 +300,30 @@ internal/app/order/
 ├── errors.go             # ORDER_NOT_FOUND / ORDER_CONFLICT / ORDER_HAS_REFERENCES / ORDER_STALE
 ├── repository.go         # GORM data access
 ├── service.go            # business logic + repository interface (mockable)
+├── composition.go        # feature-local repository → service → handler wiring
 ├── handler.go            # Gin routes, registered under the project's API prefix
 ├── service_test.go       # unit test, function-backed repository stub
 ├── handler_test.go       # HTTP unit test, service stub, no DB
 └── repository_test.go    # Postgres integration test against migrated schema
 ```
 
+With `--cqrs`, the module also adds separate command/query application files:
+
+```text
+internal/app/order/
+├── commands.go            # command port + state-changing application handlers
+├── queries.go             # query port + read-only application handlers
+├── service.go             # compatibility facade; new wiring uses both handlers
+├── composition.go         # constructs command/query handlers separately
+└── cqrs_test.go            # command/query boundary tests
+```
+
+`--cqrs` works with both minimal and `--full` modules. It keeps one modular
+monolith and one database by default; CQRS here means separate application
+paths, not mandatory separate databases, brokers, or event sourcing. The
+default remains the simpler layered module because an empty command/query
+split adds ceremony without a business reason.
+
 The default minimal mode scaffolds the same `model`/`errors`/`repository` (so `generate
 method` always has a full data-access surface to call), but `dto`/`service`/
 `handler` start empty — no default CRUD, no routes, just the plumbing
@@ -128,13 +333,15 @@ surface, or you'd rather add endpoints one at a time.
 
 Both modes also:
 
-- Register the module in `cmd/api/wiring.go` (via marker comments — see
-  `// go-scaffold:*` in that file) — full wires an actual route, minimal
-  wires an empty route group
+- Register the module through its feature-local composition and the root
+  registration markers in `cmd/api/wiring.go` — full wires an actual route,
+  minimal wires an empty route group
 - Create the module's own Postgres schema (`<module>_svc`, e.g. `order_svc`)
-  and add the model to the `AutoMigrate(...)` call
+  and add the model to the development schema bootstrap
 - Append `migrations/<timestamp>_create_<plural>.{up,down}.sql`, which creates that
-  same schema for `AUTO_MIGRATE=false`/production
+  same schema for production
+- Record the resolved `minimal|crud` and `service|cqrs` choices in
+  `go-scaffold.config.json`; changing project defaults does not rewrite existing modules
 
 What it does **not** do: invent your fields or wire foreign keys between
 domains — see `docs/architect/patterns.md` in the generated project for the
@@ -148,9 +355,12 @@ go-scaffold generate method orders findByStatus --type get --get-mode one --fiel
 go-scaffold g me orders findOverdue --type get --get-mode all
 ```
 
-Patches an *existing* module's `handler.go`/`service.go` in place via the
-same marker-comment approach as `main.go` — never a whole new module. Never
-overwrites a method with the same name; picks a different one or errors.
+Patches an *existing* module's `handler.go`/`service.go` in place at the
+`// go-scaffold:*` markers — never a whole new module. Never overwrites a method
+with the same name; pick a different one or the command errors.
+For a module generated with `--cqrs`, it also patches `commands.go` for
+state-changing endpoints and `queries.go` for read endpoints, while keeping
+the compatibility facade in sync.
 
 | Option | Effect |
 |---|---|
@@ -185,8 +395,8 @@ the generated code doesn't compile, but this project was fine a moment ago.
 The most likely cause is drift: this project's internal/shared layer has been edited
 since it was scaffolded, so the templates this CLI emits no longer match it.
 
-  scaffolded with: go-scaffold 0.1.2
-  this CLI:        go-scaffold 0.3.0
+  scaffolded with: go-scaffold <project-version>
+  this CLI:        go-scaffold <cli-version>
 ```
 
 That happens because `generate`'s templates are written against the `shared/`
@@ -224,7 +434,6 @@ async email delivery, and `cmd/worker`.
 | Extra service to run | none | Redis |
 | Needed by `add auth` | no | no — `add auth --store` decides that separately |
 | Enqueue joins your DB transaction | yes | **no** — needs an outbox |
-| Throughput | thousands/sec | tens of thousands/sec |
 | Inspect pending jobs | plain SQL | asynqmon |
 
 The default is Postgres because a job enqueued inside `tx.Do` is then only
@@ -251,26 +460,51 @@ tx.Do(ctx, db, func(ctx context.Context) error {
 ### `add auth` — add email/password authentication
 
 ```bash
-go-scaffold add auth                    # asks where tokens should live, then confirms
+go-scaffold add auth                    # asks token store + browser topology, then confirms
 go-scaffold add auth --store postgres   # tokens in Postgres, no extra service
 go-scaffold add auth --store redis      # tokens in Redis, exact across replicas
-go-scaffold add auth --defaults         # Postgres, no prompt at all (CI/scripting)
+go-scaffold add auth --defaults         # Postgres + local same-site topology (CI/scripting)
+go-scaffold add auth --browser-topology cross-site --yes
 ```
 
 Adds JWT access tokens, refresh-token rotation with reuse detection,
 registration/login/logout, password reset, email verification, failed-login
-lockout, and Google OAuth routes. Apply the generated migrations;
-`AUTO_MIGRATE=true` is convenient in development, while production should use
-`migrate up`.
-
-No prerequisites. On a project with no worker the verification and reset mail
-is sent inline, and `add worker` later moves it onto the queue for you — the
-two endpoints that send mail block on SMTP until you do.
-
-| `--store` | Tokens and rate-limit counters | Extra service |
+lockout, and generic provider OAuth routes (Google is the first adapter). Apply
+the generated migrations. Development may bootstrap tables for convenience;
+production must run `migrate up` first.
+
+The browser frontend owns its single provider callback route. It generates
+`state` and an S256 PKCE verifier/challenge, starts
+`GET /auth/{provider}/login`, handles both success and provider-cancel/error
+responses in that route, then sends `code`, `state`, and `code_verifier` to
+`POST /auth/{provider}/exchange`. The API uses the exact
+`GOOGLE_OAUTH_REDIRECT_URI` registered with the provider, creates the local
+session, sets the HttpOnly refresh cookie, and returns JSON. The backend also
+consumes a one-time transaction binding provider, state, S256 challenge, and
+OIDC nonce before completing the exchange. It never accepts a
+request-supplied `redirect_uri`/`return_to`, redirects to a configured frontend
+URL, or places tokens/code/state in a URI. Native/mobile flow is out of scope
+for this scaffold phase.
+
+`AUTH_BROWSER_TOPOLOGY` is only the cookie/CORS deployment policy, separate
+from the provider redirect URI. For a genuinely cross-site frontend use
+`--browser-topology cross-site`, deploy over HTTPS, set
+`COOKIE_SAMESITE=none` and `COOKIE_SECURE=true`, and add the exact frontend
+origin to `CORS_ALLOWED_ORIGINS` separately. SameSite=None requests also pass
+an exact Origin guard because CORS alone is not CSRF protection. Token
+responses use `Cache-Control: no-store` and `Pragma: no-cache`; configure
+`JWT_REFRESH_MAX_TTL_MIN` so refresh rotation cannot extend beyond its absolute
+lifetime.
+
+No prerequisites. On a project with no worker, the registration-verification,
+resend-verification, and password-reset mail flows are sent inline, and `add
+worker` later moves them onto the queue for you. Until then, those auth flows
+block on SMTP when a mail server is configured.
+
+| `--store` | Refresh/recovery tokens and rate-limit counters | Extra service |
 |---|---|---|
 | `postgres` (default) | `user_svc.auth_tokens`, counters in-process | none |
-| `redis` | Redis | Redis |
+| `redis` | refresh + rate-limit counters in Redis; recovery in `user_svc.auth_tokens` | Redis |
 
 The rate limiter follows the store rather than being chosen separately, because
 "I want this exact across replicas" is one decision. With `postgres` the per-IP
@@ -286,8 +520,8 @@ go-scaffold generate module secrets --auth --permission secret:manage
 
 Requires `add auth`. Adds role/permission administration, cached authorization
 middleware, and role assignment. Its migration seeds the default roles and
-permissions, so apply it with `migrate up`: AutoMigrate creates tables but does
-not run SQL seed statements.
+permissions, so apply it with `migrate up`; table creation does not run SQL
+seed statements.
 
 ### `add observability` — add metrics + tracing
 
@@ -313,8 +547,8 @@ go-scaffold undo m orders --yes         # skip the confirm
 The inverse of `generate module`, for the case it's actually the inverse of:
 a module you didn't mean to generate — a typo'd name, a domain you decided
 against. It deletes `internal/app/<name>/`, the per-module docs folder, **and
-the module's migration files**, and reverses the import/AutoMigrate/route in
-`main.go` plus the paths/schemas in `docs/openapi.yaml`. Restores the
+the module's migration files**, and reverses the import/bootstrap/route in
+`cmd/api/wiring.go` plus the paths/schemas in `docs/openapi.yaml`. Restores the
 `_ = api` placeholder if it was the last module, so the project still builds.
 
 Deleting the migrations is the point. `migrations/embed.go` is a `//go:embed
@@ -331,9 +565,10 @@ working tree, so `undo` proves it first and refuses loudly otherwise:
   `migrate ... down` first, then try again.
 
 The table itself is never dropped either way — `undo` only reverses what the
-CLI wrote. Prefer it to hand-deleting the folder: it also un-wires `main.go`,
-`.golangci.yml` and the OpenAPI index, and it refuses when another domain
-still imports this one rather than leaving you an un-compilable project.
+CLI wrote. Prefer it to hand-deleting the folder: it also un-wires
+`cmd/api/wiring.go`, `.golangci.yml` and the OpenAPI index, and it refuses when
+another domain still imports this one rather than leaving you an un-compilable
+project.
 
 ## Why no per-domain versioning
 
@@ -343,8 +578,8 @@ twice with different behavior. It was cut: the migration (and usually the
 DB table) is shared between "versions" of the same domain, but each version
 got its own physically-copied `model.go` — nothing stopped the two structs
 from drifting apart. Verified against a real Postgres instance:
-`AutoMigrate` silently accepted a column typed `int` in one version's model
-and `float64` in the other for the *same* column, converging it to
+development schema bootstrapping silently accepted a column typed `int` in
+one version's model and `float64` in the other for the *same* column, converging it to
 `numeric` with no error — the two versions would then read/write the same
 data with different, silently incompatible interpretations.
 
@@ -357,7 +592,9 @@ out of sync with.
 ## Project structure produced by `create`
 
 ```text
-cmd/api/wiring.go
+cmd/api/
+├── main.go                  # process entry point and exit handling
+└── wiring.go                # composition root: infrastructure + domain registration
 internal/
 ├── platform/database/
 ├── shared/{config,apperror,dberr,httpx,id,middleware,pagination,tx}/
@@ -383,8 +620,9 @@ go-scaffold.config.json
 
 ## Supported stack
 
-Pinned in the generated `go.mod` — this table mirrors
-`templates/create/base/go.mod.hbs`, which is the source of truth.
+Pinned base dependencies in the generated `go.mod` — this table mirrors
+`templates/create/base/go.mod.hbs`, which is the source of truth. `add auth`,
+`add worker`, and `add observability` append their optional dependencies.
 
 | Package | Version |
 |---|---|

package/dist/commands/auth.js

@@ -18,6 +18,7 @@ const migrations_1 = require("../utils/migrations");
 const openapi_patcher_1 = require("../utils/openapi-patcher");
 const gocheck_1 = require("../utils/gocheck");
 const gomod_patcher_1 = require("../utils/gomod-patcher");
+const auth_wizard_1 = require("../prompts/auth-wizard");
 // URL (relative to the api prefix) -> docs file (relative to docs/) for every
 // route `add auth` registers — kept next to AUTH_FILES's route list so the
 // two are easy to eyeball together when a route changes.
@@ -29,20 +30,26 @@ const AUTH_OPENAPI_PATHS = [
     { urlPath: "/auth/forgot-password", file: "./auth/forgot-password.yaml" },
     { urlPath: "/auth/reset-password", file: "./auth/reset-password.yaml" },
     { urlPath: "/auth/verify-email", file: "./auth/verify-email.yaml" },
-    { urlPath: "/auth/google/login", file: "./auth/google-login.yaml" },
-    { urlPath: "/auth/google/callback", file: "./auth/google-callback.yaml" },
+    { urlPath: "/auth/{provider}/login", file: "./auth/provider-login.yaml" },
+    { urlPath: "/auth/{provider}/exchange", file: "./auth/provider-exchange.yaml" },
     { urlPath: "/users/me", file: "./auth/users-me.yaml" },
     { urlPath: "/users/me/resend-verification", file: "./auth/users-me-resend-verification.yaml" },
     { urlPath: "/users/me/logout-all", file: "./auth/users-me-logout-all.yaml" },
+    { urlPath: "/users/me/mfa", file: "./auth/users-me-mfa.yaml" },
+    { urlPath: "/users/me/mfa/setup", file: "./auth/users-me-mfa-setup.yaml" },
+    { urlPath: "/users/me/mfa/confirm", file: "./auth/users-me-mfa-confirm.yaml" },
+    { urlPath: "/users/me/mfa/disable", file: "./auth/users-me-mfa-disable.yaml" },
+    { urlPath: "/auth/mfa/verify", file: "./auth/mfa-verify.yaml" },
 ];
 // addAuth scaffolds email/password authentication: a users+identities model
-// pair, JWT access tokens, a Redis-backed refresh token store with
+// pair, JWT access tokens, a selectable refresh token store with
 // rotation + reuse detection, and register/login/refresh/logout/me. No RBAC
 // (no roles/permissions) — that's a separate opt-in on top of this, since
 // most projects need "is this caller logged in" long before they need "can
 // this caller do X".
-async function addAuth(store = "postgres", projectDir = process.cwd()) {
+async function addAuth(store = "postgres", projectDir = process.cwd(), browserTopology = auth_wizard_1.DEFAULT_BROWSER_TOPOLOGY) {
     const config = (0, config_1.readConfig)(projectDir);
+    const browser = (0, auth_wizard_1.validateBrowserTopology)(browserTopology);
     // No longer a prerequisite. Without a worker the verification and reset mail
     // goes out inline instead of through a queue — a real trade (those two
     // endpoints then block on SMTP), but not one worth forcing a second binary
@@ -63,7 +70,11 @@ async function addAuth(store = "postgres", projectDir = process.cwd()) {
         (0, platform_patcher_1.patchConfigForSMTP)(path_1.default.join(projectDir, "internal", "shared", "config", "config.go"));
         patchEnvExampleForSMTP(path_1.default.join(projectDir, ".env.example"));
     }
-    await (0, template_renderer_1.applyTemplateEntries)(projectDir, (0, auth_manifest_1.authFiles)(store), { goModule: config.goModule });
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, (0, auth_manifest_1.authFiles)(store), {
+        goModule: config.goModule,
+        redis: store === "redis",
+        worker,
+    });
     const migrationsDir = path_1.default.join(projectDir, "migrations");
     fs_extra_1.default.ensureDirSync(migrationsDir);
     const usersVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
@@ -71,6 +82,11 @@ async function addAuth(store = "postgres", projectDir = process.cwd()) {
         { template: "add/auth/migrations/create_users.up.sql.hbs", output: path_1.default.join("migrations", `${usersVersion}_create_users.up.sql`) },
         { template: "add/auth/migrations/create_users.down.sql.hbs", output: path_1.default.join("migrations", `${usersVersion}_create_users.down.sql`) },
     ], {});
+    const mfaVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
+        { template: "add/auth/migrations/create_mfa.up.sql.hbs", output: path_1.default.join("migrations", `${mfaVersion}_create_mfa.up.sql`) },
+        { template: "add/auth/migrations/create_mfa.down.sql.hbs", output: path_1.default.join("migrations", `${mfaVersion}_create_mfa.down.sql`) },
+    ], {});
     // identities references users(id) — must apply strictly after it. A
     // second newMigrationVersion() call, scanning the dir again now that the
     // users pair is already written, guarantees a later (or same-second,
@@ -87,13 +103,13 @@ async function addAuth(store = "postgres", projectDir = process.cwd()) {
         { template: "add/auth/migrations/create_login_throttle.up.sql.hbs", output: path_1.default.join("migrations", `${throttleVersion}_create_login_throttle.up.sql`) },
         { template: "add/auth/migrations/create_login_throttle.down.sql.hbs", output: path_1.default.join("migrations", `${throttleVersion}_create_login_throttle.down.sql`) },
     ], {});
-    if (store === "postgres") {
-        const authTokensVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
-        await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
-            { template: "add/auth/migrations/create_auth_tokens.up.sql.hbs", output: path_1.default.join("migrations", `${authTokensVersion}_create_auth_tokens.up.sql`) },
-            { template: "add/auth/migrations/create_auth_tokens.down.sql.hbs", output: path_1.default.join("migrations", `${authTokensVersion}_create_auth_tokens.down.sql`) },
-        ], {});
-    }
+    // Recovery tokens are always stored in Postgres so consumption and the user
+    // update can share one transaction, even when refresh rotation uses Redis.
+    const authTokensVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
+        { template: "add/auth/migrations/create_auth_tokens.up.sql.hbs", output: path_1.default.join("migrations", `${authTokensVersion}_create_auth_tokens.up.sql`) },
+        { template: "add/auth/migrations/create_auth_tokens.down.sql.hbs", output: path_1.default.join("migrations", `${authTokensVersion}_create_auth_tokens.down.sql`) },
+    ], {});
     // Only meaningful when there is a worker; readConfig fills this from the
     // adapter file on disk, so the only way it is still unknown is a project
     // that has internal/platform/queue with neither adapter in it. Guessing
@@ -120,7 +136,7 @@ async function addAuth(store = "postgres", projectDir = process.cwd()) {
         // go-redis only when something in this project actually constructs a client
         ...(store === "redis" ? ["github.com/redis/go-redis/v9 v9.22.0"] : []),
     ]);
-    patchEnvExample(path_1.default.join(projectDir, ".env.example"));
+    patchEnvExample(path_1.default.join(projectDir, ".env.example"), browser);
     patchMakefile(path_1.default.join(projectDir, "Makefile"));
     let docsMessage = "";
     const openapiPath = path_1.default.join(projectDir, "docs", "openapi.yaml");
@@ -146,13 +162,14 @@ async function addAuth(store = "postgres", projectDir = process.cwd()) {
         ? "verification + password-reset mail goes through the queue"
         : "verification + password-reset mail is sent inline (no worker) — run `add worker` later to move it onto the queue");
     console.log(store === "postgres"
-        ? "tokens + rate-limit counters: Postgres (user_svc.auth_tokens) and in-process — no Redis"
-        : "tokens + rate-limit counters: Redis");
+        ? "refresh + recovery tokens: Postgres (user_svc.auth_tokens), rate-limit counters in-process — no Redis"
+        : "refresh tokens + rate-limit counters: Redis; recovery tokens: Postgres (user_svc.auth_tokens)");
     console.log("registered POST /auth/{register,login,refresh,logout,forgot-password,reset-password,verify-email}, " +
-        "GET /auth/google/{login,callback}, GET /users/me, and " +
-        "POST /users/me/{resend-verification,logout-all} in cmd/api/wiring.go" +
+        "GET /auth/{provider}/login, POST /auth/{provider}/exchange, GET /users/me, and " +
+        "POST /users/me/{resend-verification,logout-all,mfa/setup,mfa/confirm,mfa/disable}, " +
+        "GET /users/me/mfa, and POST /auth/mfa/verify in cmd/api/wiring.go" +
         docsMessage);
-    console.log(picocolors_1.default.dim("\nnext: go mod tidy, then apply the new migrations (AUTO_MIGRATE=true picks them up automatically in dev)\n" +
+    console.log(picocolors_1.default.dim("\nnext: go mod tidy, then apply the new migrations with `make migrate-up` before production\n" +
         "seed an admin: SEED_ADMIN_EMAIL=... SEED_ADMIN_PASSWORD=... make seed"));
 }
 function patchMakefile(makefilePath) {
@@ -183,7 +200,7 @@ function patchMakefile(makefilePath) {
     content = content.replace(/\nbuild:/, () => `${target}\nbuild:`);
     fs_extra_1.default.writeFileSync(makefilePath, content);
 }
-function patchEnvExample(envExamplePath) {
+function patchEnvExample(envExamplePath, browserTopology) {
     if (!fs_extra_1.default.existsSync(envExamplePath))
         return;
     let content = fs_extra_1.default.readFileSync(envExamplePath, "utf8");
@@ -195,13 +212,15 @@ function patchEnvExample(envExamplePath) {
             "JWT_SECRET=dev-secret-change-me\n" +
             "JWT_ACCESS_TTL_MIN=15\n" +
             "JWT_REFRESH_TTL_MIN=43200\n" +
-            "COOKIE_SECURE=false\n" +
+            "JWT_REFRESH_MAX_TTL_MIN=43200\n" +
+            "OAUTH_STATE_TTL_MIN=10\n" +
+            `COOKIE_SECURE=${browserTopology === "cross-site" ? "true" : "false"}\n` +
             "# strict | lax | none — the refresh cookie's SameSite. Keep strict while the\n" +
             "# frontend is the same site as this API (localhost:3000 -> localhost:8080 is,\n" +
             "# and so is app.example.com -> api.example.com). A frontend on a different\n" +
             "# site entirely needs none, together with COOKIE_SECURE=true, or the browser\n" +
             "# never sends the cookie to /auth/refresh and sessions die at every expiry.\n" +
-            "COOKIE_SAMESITE=strict\n" +
+            `COOKIE_SAMESITE=${browserTopology === "cross-site" ? "none" : "strict"}\n` +
             "\nPASSWORD_RESET_TTL_MIN=30\n" +
             "PASSWORD_RESET_URL=http://localhost:3000/reset-password\n" +
             "\nEMAIL_VERIFY_TTL_MIN=1440\n" +
@@ -209,7 +228,19 @@ function patchEnvExample(envExamplePath) {
             "\n# leave the Google vars unset to disable Google login (register/login/refresh still work)\n" +
             "GOOGLE_CLIENT_ID=\n" +
             "GOOGLE_CLIENT_SECRET=\n" +
-            "GOOGLE_REDIRECT_URL=\n";
+            "# exact browser callback URI registered with the provider (frontend-owned route)\n" +
+            "GOOGLE_OAUTH_REDIRECT_URI=\n" +
+            "\n# cookie/CORS deployment topology; the frontend owns its provider callback route\n" +
+            `AUTH_BROWSER_TOPOLOGY=${browserTopology}\n` +
+            "\n# MFA is globally off by default. When enabled, set a base64-encoded 32-byte\n" +
+            "# AES-256 key (for example: openssl rand -base64 32). Users still opt in\n" +
+            "# individually through /users/me/mfa/setup and /users/me/mfa/confirm.\n" +
+            "AUTH_MFA_ENABLED=false\n" +
+            "MFA_ISSUER=go-scaffold\n" +
+            "MFA_ENCRYPTION_KEY=\n" +
+            "MFA_CHALLENGE_TTL_MIN=5\n" +
+            "MFA_TOTP_WINDOW=1\n" +
+            "MFA_RECOVERY_CODE_COUNT=10\n";
     fs_extra_1.default.writeFileSync(envExamplePath, content);
 }
 // ensureRedis adds internal/platform/cache + its config/env/main.go wiring