@nakedev/go-scaffold 0.3.3 → 0.4.3

package/dist/utils/rbac-patcher.js

@@ -78,24 +78,40 @@ function patchUserJWTForRbac(jwtGoPath) {
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:jwt-claims-values", "Role: role,", "Role: role,");
     fs_extra_1.default.writeFileSync(jwtGoPath, content);
 }
-// patchUserServiceForRbac wires a role.Service dependency into user.Service
-// (via a consumer-side roleChecker interface, same convention as
-// repository/mailer/tokenStore) and adds SetRole, the one place a user's
-// role actually changes after creation.
-function patchUserServiceForRbac(serviceGoPath) {
+// patchUserServiceForRbac adds the RBAC behavior to user.Service. The base
+// auth constructor already exposes Dependencies.Roles, so enabling RBAC does
+// not mutate a positional constructor signature anymore.
+function patchUserServiceForRbac(serviceGoPath, goModule, sessionsGoPath) {
     let content = fs_extra_1.default.readFileSync(serviceGoPath, "utf8");
     const roleCheckerInterface = [
-        "// roleChecker = what the service needs from the role domain to validate a",
+        "// RoleChecker is what the service needs from the role domain to validate a",
         "// role assignment — declared consumer-side, same convention as repository/mailer.",
-        "type roleChecker interface {",
+        "type RoleChecker interface {",
         "\tCodeExists(ctx context.Context, code string) (bool, error)",
         "}",
     ].join("\n");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-interfaces", roleCheckerInterface, "type roleChecker interface");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-fields", "roles roleChecker", "roles roleChecker");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-params", "roles roleChecker,", "roles roleChecker,");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-init", "roles: roles,", "roles: roles,");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:issue-access-token-args", "u.Role,", "u.Role,");
+    if (!content.includes("type RoleChecker interface") && !content.includes("type roleChecker interface")) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-interfaces", roleCheckerInterface, "type RoleChecker interface");
+    }
+    // issueTokens moved out of service.go with auth's use-case split. Keep the
+    // patch compatible with both shapes: new projects patch sessions.go, while
+    // older generated projects still have the marker in service.go.
+    const tokenIssuePath = sessionsGoPath && fs_extra_1.default.existsSync(sessionsGoPath) ? sessionsGoPath : serviceGoPath;
+    let tokenIssueContent = tokenIssuePath === serviceGoPath ? content : fs_extra_1.default.readFileSync(tokenIssuePath, "utf8");
+    tokenIssueContent = (0, marker_patch_1.insertBeforeMarkerOnce)(tokenIssueContent, "// go-scaffold:issue-access-token-args", "u.Role,", "u.Role,");
+    if (tokenIssuePath === serviceGoPath) {
+        content = tokenIssueContent;
+    }
+    // Auth keeps its base service focused and therefore does not need RBAC's
+    // error/ORM imports until this optional method is patched in. Add them here
+    // instead of carrying unused imports in every auth-only project. The module
+    // argument is optional for callers that patch legacy projects whose service
+    // already imported apperror; new CLI calls always provide it.
+    if (goModule) {
+        content = (0, marker_patch_1.ensureImport)(content, "errors");
+        content = (0, marker_patch_1.ensureImport)(content, `${goModule}/internal/shared/apperror`);
+        content = (0, marker_patch_1.ensureImport)(content, "gorm.io/gorm");
+    }
     const setRoleMethod = [
         "// SetRole assigns userID a new role — validated against the role catalog",
         "// (not just the DB's FK) so a typo'd code fails with a clear 422 here",
@@ -107,33 +123,30 @@ function patchUserServiceForRbac(serviceGoPath) {
         "\t\tif errors.Is(err, gorm.ErrRecordNotFound) {",
         "\t\t\treturn nil, errNotFound()",
         "\t\t}",
-        "\t\treturn nil, apperror.NewInternal()",
+        "\t\treturn nil, apperror.NewInternal(err)",
         "\t}",
         "\texists, err := s.roles.CodeExists(ctx, roleCode)",
         "\tif err != nil {",
-        "\t\treturn nil, apperror.NewInternal()",
+        "\t\treturn nil, apperror.NewInternal(err)",
         "\t}",
         "\tif !exists {",
         "\t\treturn nil, errUnknownRole()",
         "\t}",
         "\tu.Role = roleCode",
         "\tif err := s.repo.UpdateUser(ctx, u); err != nil {",
-        "\t\treturn nil, apperror.NewInternal()",
+        "\t\treturn nil, apperror.NewInternal(err)",
         "\t}",
         "\treturn u, nil",
         "}",
     ].join("\n");
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-methods", setRoleMethod, "func (s *Service) SetRole(");
     fs_extra_1.default.writeFileSync(serviceGoPath, content);
+    if (tokenIssuePath !== serviceGoPath)
+        fs_extra_1.default.writeFileSync(tokenIssuePath, tokenIssueContent);
 }
-// patchUserServiceTestForRbac keeps service_test.go's single NewService call
-// site (newTestService) compiling once patchUserServiceForRbac adds the
-// roleChecker param above — same drift risk the handoff notes called out for
-// middleware.NewAuthz's call sites, just for this signature instead. The fake
-// itself is added here too, not pre-declared unconditionally in the
-// template: golangci-lint's unused check flags an unreferenced type+method
-// pair in the auth-only (pre-rbac) state, since nothing there yet implements
-// or needs a roleChecker.
+// patchUserServiceTestForRbac supplies a fake role capability through the
+// explicit Dependencies literal. The fake itself remains opt-in so auth-only
+// projects do not carry an unused RBAC test double.
 function patchUserServiceTestForRbac(serviceTestGoPath) {
     let content = fs_extra_1.default.readFileSync(serviceTestGoPath, "utf8");
     const fakeRoles = [
@@ -143,7 +156,7 @@ function patchUserServiceTestForRbac(serviceTestGoPath) {
         "func (fakeRoles) CodeExists(context.Context, string) (bool, error) { return true, nil }",
     ].join("\n");
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-test-types", fakeRoles, "type fakeRoles struct{}");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-test-args", "fakeRoles{},", "fakeRoles{},");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-service-test-deps", "Roles: fakeRoles{},", "Roles: fakeRoles{},");
     fs_extra_1.default.writeFileSync(serviceTestGoPath, content);
 }
 // patchUserDTOForRbac adds the request DTO for PATCH /users/:id/set-role and
@@ -164,13 +177,26 @@ function patchUserDTOForRbac(dtoGoPath) {
 // /permissions for the actual role/permission management API.
 function patchUserHandlerForRbac(handlerGoPath, goModule) {
     let content = fs_extra_1.default.readFileSync(handlerGoPath, "utf8");
+    // The base auth handler is intentionally only the route/composition surface;
+    // its endpoint implementations now live in sibling files. RBAC still
+    // patches its admin handlers into handler.go for marker compatibility, so
+    // make the imports required by those injected handlers explicit here rather
+    // than relying on imports that used to come from the old monolithic file.
+    content = (0, marker_patch_1.ensureImport)(content, "net/http");
+    content = (0, marker_patch_1.ensureImport)(content, `${goModule}/internal/shared/httpx`);
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-consts", 'const PermUserManageRole = "user:manage-role"', "PermUserManageRole");
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-consts", 'const PermUserRead = "user:read"', "PermUserRead");
     const paginationImport = `"${goModule}/internal/shared/pagination"`;
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-imports", paginationImport, "internal/shared/pagination");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-fields", "authz *middleware.Authz", "authz *middleware.Authz");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-params", "authz *middleware.Authz,", "authz *middleware.Authz,");
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-init", "authz: authz,", "authz: authz,");
+    if (!/\bauthz\s+(?:\*middleware\.Authz|authorizer)\b/.test(content)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-fields", "authz *middleware.Authz", "authz *middleware.Authz");
+    }
+    if (!/\bauthz\s+\.\.\.(?:\*middleware\.Authz|authorizer)\s*,/.test(content) && !/\bauthz\s+\*middleware\.Authz\s*,/.test(content)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-params", "authz *middleware.Authz,", "authz *middleware.Authz,");
+    }
+    if (!/authz:\s+authzMiddleware,/.test(content) && !/authz:\s+authz,/.test(content)) {
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-handler-init", "authz: authz,", "authz: authz,");
+    }
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-routes", 'usersGroup.GET("", h.authz.Require(PermUserRead), h.adminListUsers)', 'usersGroup.GET("", h.authz.Require(PermUserRead)');
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-routes", 'usersGroup.GET("/:id", h.authz.Require(PermUserRead), h.adminGetUser)', 'usersGroup.GET("/:id", h.authz.Require(PermUserRead)');
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-routes", 'usersGroup.PATCH("/:id/set-role", h.authz.Require(PermUserManageRole), h.setRole)', 'usersGroup.PATCH("/:id/set-role"');
@@ -233,28 +259,24 @@ function patchUserErrorsForRbac(errorsGoPath) {
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:user-errors", errFn, "func errUnknownRole(");
     fs_extra_1.default.writeFileSync(errorsGoPath, content);
 }
-// patchMainGoForRbac wires the role domain into cmd/api: its import, its
-// three models in the AutoMigrate call, and — the one place a plain insert
-// isn't enough — REPLACES the `add auth` PR's user.NewHandler(...) call with
-// a version that also builds roleSvc/authz and passes them through, plus
-// registers role's own routes right after it.
-// userSvcLineFor rebuilds the exact line `add auth` wrote, from the same
-// helper it used. Exported so the command can check for it *before* it starts
-// patching: every other file rbac touches is edited first, and until this
-// existed a mismatch here threw after user.NewService had already grown a
-// roleChecker parameter — leaving a project that no longer compiled and an
-// error telling you to restore a line that wouldn't have fixed it.
+// userSvcLineFor rebuilds the legacy line `add auth` wrote before auth got a
+// feature-local composition root. It remains here so `add rbac` can upgrade an
+// older generated project without pulling the old construction shape into new
+// output.
 function userSvcLineFor(goModule, store, worker) {
     const { tokenStore, mailer } = (0, auth_patcher_1.authWiringLines)({ goModule, queueBackend: "river", store, worker });
-    return `userSvc := user.NewService(user.NewRepository(db), ${tokenStore}, ${mailer}, cfg)`;
+    return `userSvc := user.NewService(user.NewRepository(db), ${tokenStore}, ${mailer}, cfg, application.NewProviderRegistry())`;
 }
 function assertRbacPatchable(mainGoPath, goModule, store, worker) {
-    const expected = userSvcLineFor(goModule, store, worker);
-    if (fs_extra_1.default.readFileSync(mainGoPath, "utf8").includes(expected))
+    const wiring = { goModule, queueBackend: "river", store, worker };
+    const content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
+    const expected = (0, auth_patcher_1.authHandlerLineFor)(wiring);
+    const legacyRoute = `user.NewHandler(userSvc, cfg.JWTSecret, cfg.JWTRefreshTTL, cfg.CookieSecure, cfg.CookieSameSite, ${(0, auth_patcher_1.authWiringLines)(wiring).limiter}).Register(api)`;
+    if (content.includes(expected) || content.includes(userSvcLineFor(goModule, store, worker)) || content.includes(legacyRoute))
         return;
-    throw new Error("cmd/api/wiring.go's userSvc line doesn't match what `add auth` wrote, so `add rbac` can't extend it.\n" +
+    throw new Error("cmd/api/wiring.go's auth route doesn't match what `add auth` wrote, so `add rbac` can't extend it.\n" +
         `Expected to find:\n  ${expected}\n\n` +
-        "It was probably hand-edited. Restore that line and re-run — nothing has been changed yet.");
+        "It was probably hand-edited. Restore that route and re-run — nothing has been changed yet.");
 }
 function patchMainGoForRbac(mainGoPath, goModule, store, worker) {
     let content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
@@ -272,37 +294,36 @@ function patchMainGoForRbac(mainGoPath, goModule, store, worker) {
     for (const line of migrateLines) {
         content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, line, line);
     }
-    // roleSvc and authz have to be declared *above* userSvc, which now takes
-    // roleSvc — so this rewrites the service line in place rather than
-    // appending at the marker (which would land below it).
-    // Rebuilt from the same helper `add auth` used, so a project on either store
-    // gets its own line matched rather than a hardcoded guess at one of them.
-    const { limiter } = (0, auth_patcher_1.authWiringLines)({ goModule, queueBackend: "river", store, worker });
-    const userSvcLine = userSvcLineFor(goModule, store, worker);
-    // Throw rather than skip: the roleSvc/authz declarations this rewrite adds
-    // are what the unconditional patches below refer to. Skipping quietly still
-    // emits `roleSvc`/`authz` references with nothing declaring them, so the
-    // command reports success over a main.go that doesn't compile.
-    if (!content.includes(userSvcLine)) {
-        throw new Error(`cmd/api/wiring.go's userSvc line doesn't match what \`add auth\` wrote, so \`add rbac\` can't extend it.\n` +
-            `Expected to find:\n  ${userSvcLine}\n\n` +
-            `It was probably hand-edited. Restore that line (add rbac will re-extend it), or apply the rbac wiring by hand:\n` +
-            `  roleSvc := role.NewService(role.NewRepository(db))\n` +
-            `  authz := middleware.NewAuthz(roleSvc.PermissionsOf, cfg.AuthzCacheTTL)\n` +
-            `  ...then pass roleSvc as user.NewService's last argument.`);
+    const wiring = { goModule, queueBackend: "river", store, worker };
+    const authRouteLine = (0, auth_patcher_1.authHandlerLineFor)(wiring);
+    const roleCompositionLine = "roleComposition := role.NewCompositionFromDB(db, cfg.JWTSecret, cfg.AuthzCacheTTL)";
+    const roleHandlerLine = "roleComposition.Handler.Register(api)";
+    if (content.includes(authRouteLine)) {
+        const authWithRoleLine = (0, auth_patcher_1.authHandlerLineFor)(wiring, ["roleComposition.Service", "roleComposition.Authz"]);
+        content = content.replace(authRouteLine, [roleCompositionLine, authWithRoleLine, roleHandlerLine].join("\n"));
+    }
+    else {
+        // Upgrade projects generated before auth's local composition root. The
+        // role feature is still constructed locally; only the legacy user service
+        // call needs an adapter until that project is regenerated.
+        const applicationImportLine = `"${goModule}/internal/app/user/application"`;
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, applicationImportLine, applicationImportLine);
+        const userSvcLine = userSvcLineFor(goModule, store, worker);
+        if (!content.includes(userSvcLine)) {
+            throw new Error(`cmd/api/wiring.go's auth route doesn't match what \`add auth\` wrote, so \`add rbac\` can't extend it.\n` +
+                `Expected to find:\n  ${authRouteLine}\n\n` +
+                "It was probably hand-edited. Restore that route and re-run — nothing has been changed yet.");
+        }
+        content = content.replace(userSvcLine, [roleCompositionLine, `${userSvcLine.slice(0, -1)}, roleComposition.Service)`].join("\n"));
+        const limiter = (0, auth_patcher_1.authWiringLines)(wiring).limiter;
+        const legacyRoute = `user.NewHandler(userSvc, cfg.JWTSecret, cfg.JWTRefreshTTL, cfg.CookieSecure, cfg.CookieSameSite, ${limiter}).Register(api)`;
+        const tail = ").Register(api)";
+        if (!content.includes(legacyRoute)) {
+            throw new Error("cmd/api/wiring.go is missing auth's legacy handler route while adding RBAC");
+        }
+        content = content.replace(legacyRoute, `${legacyRoute.slice(0, -tail.length)}, roleComposition.Authz${tail}`);
+        content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, ROUTE_MARKER, roleHandlerLine, roleHandlerLine);
     }
-    content = content.replace(userSvcLine, [
-        "roleSvc := role.NewService(role.NewRepository(db))",
-        "authz := middleware.NewAuthz(roleSvc.PermissionsOf, cfg.AuthzCacheTTL)",
-        `${userSvcLine.slice(0, -1)}, roleSvc)`,
-    ].join("\n"));
-    const userRouteLine = `user.NewHandler(userSvc, cfg.JWTSecret, cfg.JWTRefreshTTL, cfg.CookieSecure, cfg.CookieSameSite, ${limiter}).Register(api)`;
-    // strip the trailing `).Register(api)` — not just `.Register(api)` — so authz
-    // lands inside NewHandler's argument list rather than after its closing paren
-    const tail = ").Register(api)";
-    content = content.replace(userRouteLine, `${userRouteLine.slice(0, -tail.length)}, authz${tail}`);
-    const roleRouteLine = "role.NewHandler(roleSvc, cfg.JWTSecret, authz).Register(api)";
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, ROUTE_MARKER, roleRouteLine, roleRouteLine);
     fs_extra_1.default.writeFileSync(mainGoPath, content);
 }
 // patchCmdSeedForRbac makes the seeded admin actually an admin: wires a
@@ -313,9 +334,10 @@ function patchCmdSeedForRbac(seedMainGoPath, goModule) {
     let content = fs_extra_1.default.readFileSync(seedMainGoPath, "utf8");
     const importLine = `"${goModule}/internal/app/role"`;
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:seed-imports", importLine, importLine);
-    const roleSvcLine = "roleSvc := role.NewService(role.NewRepository(db))";
+    const roleSvcLine = "roleSvc := role.NewServiceFromDB(db)";
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:seed-services", roleSvcLine, roleSvcLine);
-    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:seed-user-service-args", "roleSvc,", "roleSvc,");
+    const seedRoleDependency = content.includes("user.Dependencies{") ? "Roles: roleSvc," : "roleSvc,";
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, "// go-scaffold:seed-user-service-args", seedRoleDependency, seedRoleDependency);
     const setRoleCall = [
         'if _, err := svc.SetRole(ctx, u.ID, "admin"); err != nil {',
         '\tlogger.Error("promote seed admin to admin role", "error", err)',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nakedev/go-scaffold",
-  "version": "0.3.3",
+  "version": "0.4.3",
   "description": "Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard",
   "repository": {
     "type": "git",
@@ -23,9 +23,13 @@
     "test:unit": "node --test tests/unit/*.test.mjs",
     "test:integration": "node --test tests/integration/*.test.mjs",
     "test:smoke": "node scripts/smoke-test.mjs",
+    "test:e2e": "playwright test --config=playwright.config.mjs",
+    "test:e2e:install": "playwright install chromium",
     "verify": "pnpm run build && pnpm run test",
+    "release:check": "node scripts/check-release.mjs",
+    "policy:main": "node scripts/check-main-merge.mjs",
     "prepack": "rm -rf dist && pnpm run build",
-    "prepublishOnly": "pnpm run verify"
+    "prepublishOnly": "pnpm run release:check && pnpm run verify"
   },
   "keywords": [
     "go",
@@ -49,6 +53,7 @@
     "pluralize": "^8.0.0"
   },
   "devDependencies": {
+    "@playwright/test": "1.55.0",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^24.0.0",
     "@types/pluralize": "^0.0.33",

package/templates/add/auth/cmd/seed/main.go.hbs

@@ -30,10 +30,20 @@ func main() {
 	}
 
 	// go-scaffold:seed-services
-	svc := user.NewService(
-		user.NewRepository(db), nil, nil, cfg,
+	svc := user.NewService(user.Dependencies{
+		Repository: user.NewRepository(db),
 		// go-scaffold:seed-user-service-args
-	)
+	}, user.AuthConfig{
+		JWTSecret:        cfg.JWTSecret,
+		JWTAccessTTL:     cfg.JWTAccessTTL,
+		JWTRefreshTTL:    cfg.JWTRefreshTTL,
+		JWTRefreshMaxTTL: cfg.JWTRefreshMaxTTL,
+		OAuthStateTTL:    cfg.OAuthStateTTL,
+		PasswordResetTTL: cfg.PasswordResetTTL,
+		PasswordResetURL: cfg.PasswordResetURL,
+		EmailVerifyTTL:   cfg.EmailVerifyTTL,
+		EmailVerifyURL:   cfg.EmailVerifyURL,
+	})
 	ctx := context.Background()
 
 	if email := os.Getenv("SEED_ADMIN_EMAIL"); email != "" {

package/templates/add/auth/docs/login.yaml.hbs

@@ -11,9 +11,19 @@ post:
   responses:
     "200":
       description: ok, refresh_token set as an httpOnly cookie
+      headers:
+        Cache-Control:
+          description: token responses are never cacheable
+          schema: { type: string, example: no-store }
+        Pragma:
+          description: legacy cache prevention for token responses
+          schema: { type: string, example: no-cache }
       content:
         application/json:
-          schema: { $ref: './schemas.yaml#/AuthResponse' }
+          schema:
+            oneOf:
+              - { $ref: './schemas.yaml#/AuthResponse' }
+              - { $ref: './schemas.yaml#/MFAChallengeResponse' }
     "400": { $ref: '../common/responses.yaml#/ValidationError' }
     "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
     "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

package/templates/add/auth/docs/mfa-verify.yaml.hbs

@@ -0,0 +1,19 @@
+post:
+  summary: Complete a login with a TOTP or recovery code
+  operationId: verifyMFA
+  tags: [auth]
+  security: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/MFAChallengeInput' }
+  responses:
+    "200":
+      description: authenticated; refresh_token set as an httpOnly cookie
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/AuthResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "429": { $ref: '../common/responses.yaml#/TooManyRequestsError' }

package/templates/add/auth/docs/provider-exchange.yaml.hbs

@@ -0,0 +1,40 @@
+post:
+  summary: Exchange a provider authorization code for a local session
+  description: The frontend callback route sends the code, the same state, and the PKCE verifier to the API. The API consumes a one-time server-side state transaction bound to the provider, S256 challenge, and OIDC nonce, uses its exact provider-registered redirect URI, validates the provider response, resolves the local identity, sets an HttpOnly refresh cookie, and returns an access token. The request has no redirect_uri, return_to, or frontend destination; credentials are never placed in a URI.
+  operationId: providerExchange
+  tags: [auth]
+  security: []
+  parameters:
+    - name: provider
+      in: path
+      required: true
+      schema: { type: string, example: google }
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: "./schemas.yaml#/OAuthExchangeInput"
+  responses:
+    "200":
+      description: local session created; refresh token is set only as an HttpOnly cookie
+      headers:
+        Set-Cookie:
+          description: HttpOnly refresh cookie
+          schema: { type: string }
+        Cache-Control:
+          description: token responses are never cacheable
+          schema: { type: string, example: no-store }
+        Pragma:
+          description: legacy cache prevention for token responses
+          schema: { type: string, example: no-cache }
+      content:
+        application/json:
+          schema:
+            oneOf:
+              - { $ref: "./schemas.yaml#/AuthResponse" }
+              - { $ref: "./schemas.yaml#/MFAChallengeResponse" }
+    "400":
+      description: controlled OAuth error (oauth_denied, oauth_state_invalid, or oauth_failed)
+    "503":
+      description: provider is unavailable or not configured

package/templates/add/auth/docs/provider-login.yaml.hbs

@@ -0,0 +1,31 @@
+get:
+  summary: Start an external OAuth login flow
+  description: Redirects the browser to the configured provider. The browser client supplies state and an S256 PKCE challenge; the server creates a one-time transaction bound to that state, provider, challenge, and OIDC nonce, then uses the exact provider-registered redirect URI. It never accepts a client redirect URI.
+  operationId: providerLogin
+  tags: [auth]
+  security: []
+  parameters:
+    - name: provider
+      in: path
+      required: true
+      schema: { type: string, example: google }
+    - name: state
+      in: query
+      required: true
+      schema: { type: string, minLength: 1 }
+    - name: code_challenge
+      in: query
+      required: true
+      schema:
+        type: string
+        minLength: 43
+        maxLength: 128
+        pattern: '^[A-Za-z0-9._~-]+$'
+    - name: code_challenge_method
+      in: query
+      required: true
+      schema: { type: string, enum: [S256] }
+  responses:
+    "302": { description: redirect to the provider's authorization endpoint }
+    "400": { description: missing or invalid state/PKCE parameters; response uses a controlled OAuth error code }
+    "503": { description: provider is unavailable or not configured }

package/templates/add/auth/docs/refresh.yaml.hbs

@@ -9,6 +9,13 @@ post:
   responses:
     "200":
       description: ok, a new refresh_token cookie is set
+      headers:
+        Cache-Control:
+          description: token responses are never cacheable
+          schema: { type: string, example: no-store }
+        Pragma:
+          description: legacy cache prevention for token responses
+          schema: { type: string, example: no-cache }
       content:
         application/json:
           schema: { $ref: './schemas.yaml#/AuthResponse' }

package/templates/add/auth/docs/register.yaml.hbs

@@ -11,6 +11,13 @@ post:
   responses:
     "201":
       description: created, refresh_token set as an httpOnly cookie
+      headers:
+        Cache-Control:
+          description: token responses are never cacheable
+          schema: { type: string, example: no-store }
+        Pragma:
+          description: legacy cache prevention for token responses
+          schema: { type: string, example: no-cache }
       content:
         application/json:
           schema: { $ref: './schemas.yaml#/AuthResponse' }

package/templates/add/auth/docs/reset-password.yaml.hbs

@@ -1,6 +1,6 @@
 post:
   summary: Reset a password using a reset token
-  description: The token is one-time use (consumed on success) and also revokes every existing refresh token for the account.
+  description: The token is consumed only after the password update and refresh-session revocation complete. If the session store is temporarily unavailable, the internal error response restores the token so the caller can retry the complete operation.
   operationId: resetPassword
   tags: [auth]
   security: []

package/templates/add/auth/docs/schemas.yaml.hbs

@@ -32,8 +32,66 @@ VerifyEmailInput:
   properties:
     token: { type: string }
 
+MFAChallengeInput:
+  type: object
+  required: [challenge, code]
+  additionalProperties: false
+  properties:
+    challenge: { type: string, minLength: 1 }
+    code: { type: string, minLength: 6, maxLength: 16 }
+
+MFACodeInput:
+  type: object
+  required: [code]
+  additionalProperties: false
+  properties:
+    code: { type: string, minLength: 6, maxLength: 16 }
+
+MFAChallengeResponse:
+  type: object
+  required: [mfa_required, challenge]
+  properties:
+    mfa_required: { type: boolean, example: true }
+    challenge: { type: string }
+
+MFAStatus:
+  type: object
+  required: [available, enabled]
+  properties:
+    available: { type: boolean }
+    enabled: { type: boolean }
+
+MFASetupResponse:
+  type: object
+  required: [secret, otpauth_uri]
+  properties:
+    secret: { type: string, description: show once and add to an authenticator app }
+    otpauth_uri: { type: string, format: uri }
+
+MFAConfirmResponse:
+  type: object
+  required: [recovery_codes]
+  properties:
+    recovery_codes:
+      type: array
+      items: { type: string }
+
+OAuthExchangeInput:
+  type: object
+  required: [code, state, code_verifier]
+  additionalProperties: false
+  properties:
+    code: { type: string, minLength: 1 }
+    state: { type: string, minLength: 1 }
+    code_verifier:
+      type: string
+      minLength: 43
+      maxLength: 128
+      pattern: '^[A-Za-z0-9._~-]+$'
+
 # access_token in the body; refresh_token is set as an httpOnly cookie, never
-# echoed back — see toCookieResponse in internal/app/user/dto.go.
+# echoed back — see toCookieResponse in internal/app/user/dto.go. All token
+# responses carry Cache-Control: no-store and Pragma: no-cache.
 AuthResponse:
   type: object
   properties:

package/templates/add/auth/docs/users-me-mfa-confirm.yaml.hbs

@@ -0,0 +1,19 @@
+post:
+  summary: Confirm MFA enrollment with a current TOTP code
+  operationId: confirmMyMFA
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/MFACodeInput' }
+  responses:
+    "200":
+      description: MFA enabled; recovery codes are returned once
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/MFAConfirmResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }

package/templates/add/auth/docs/users-me-mfa-disable.yaml.hbs

@@ -0,0 +1,15 @@
+post:
+  summary: Disable MFA for the current user
+  operationId: disableMyMFA
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/MFACodeInput' }
+  responses:
+    "204": { description: MFA disabled }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }

package/templates/add/auth/docs/users-me-mfa-setup.yaml.hbs

@@ -0,0 +1,14 @@
+post:
+  summary: Start MFA enrollment for the current user
+  operationId: setupMyMFA
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "200":
+      description: secret and otpauth URI; enrollment remains disabled until confirmed
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/MFASetupResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "409": { $ref: '../common/responses.yaml#/ConflictError' }
+    "503": { description: MFA is disabled by the operator }

package/templates/add/auth/docs/users-me-mfa.yaml.hbs

@@ -0,0 +1,12 @@
+get:
+  summary: Get the current user's MFA status
+  operationId: getMyMFAStatus
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "200":
+      description: MFA availability and enrollment status
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/MFAStatus' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }