@nakedev/go-scaffold 0.5.2 → 0.5.4

package/README.md

@@ -478,6 +478,10 @@ Auth adds:
 - JWT access tokens and refresh-token rotation with reuse detection
 - registration, login, logout, refresh, password reset, and email verification
 - generic provider OAuth routes, with Google as the first adapter
+- account identity storage split into `users`, `user_emails`,
+  `password_credentials`, and `external_identities`; a Google-only user can
+  add a password through `POST /users/me/identities/local` without creating a
+  second account
 - failed-login lockout and user-session management
 - MFA endpoints and configuration hooks
 - internal/app/user, auth middleware, cmd/seed, migrations, and OpenAPI

package/dist/commands/auth.js

@@ -34,6 +34,11 @@ const AUTH_OPENAPI_PATHS = [
     { 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/identities", file: "./auth/users-me-identities.yaml" },
+    { urlPath: "/users/me/identities/local", file: "./auth/users-me-identity-local-link.yaml" },
+    { urlPath: "/users/me/identities/{provider}/link", file: "./auth/users-me-identity-link.yaml" },
+    { urlPath: "/users/me/identities/{provider}/link/exchange", file: "./auth/users-me-identity-link-exchange.yaml" },
+    { urlPath: "/users/me/identities/{provider}", file: "./auth/users-me-identity.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/sessions", file: "./auth/users-me-sessions.yaml" },
@@ -44,8 +49,8 @@ const AUTH_OPENAPI_PATHS = [
     { 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 selectable refresh token store with
+// addAuth scaffolds email/password authentication: an account plus separate
+// email, password-credential, and external-identity records, JWT access tokens, a selectable refresh token store with
 // rotation + reuse detection, register/login/refresh/logout/me, and
 // per-user session listing/revocation. No RBAC
 // (no roles/permissions) — that's a separate opt-in on top of this, since
@@ -86,20 +91,26 @@ async function addAuth(store = "postgres", projectDir = process.cwd(), browserTo
         { 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 emailVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
+        { template: "add/auth/migrations/create_user_emails.up.sql.hbs", output: path_1.default.join("migrations", `${emailVersion}_create_user_emails.up.sql`) },
+        { template: "add/auth/migrations/create_user_emails.down.sql.hbs", output: path_1.default.join("migrations", `${emailVersion}_create_user_emails.down.sql`) },
+    ], {});
+    const passwordVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
+        { template: "add/auth/migrations/create_password_credentials.up.sql.hbs", output: path_1.default.join("migrations", `${passwordVersion}_create_password_credentials.up.sql`) },
+        { template: "add/auth/migrations/create_password_credentials.down.sql.hbs", output: path_1.default.join("migrations", `${passwordVersion}_create_password_credentials.down.sql`) },
+    ], {});
+    const externalIdentityVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
+        { template: "add/auth/migrations/create_external_identities.up.sql.hbs", output: path_1.default.join("migrations", `${externalIdentityVersion}_create_external_identities.up.sql`) },
+        { template: "add/auth/migrations/create_external_identities.down.sql.hbs", output: path_1.default.join("migrations", `${externalIdentityVersion}_create_external_identities.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,
-    // bumped) timestamp rather than assuming +1 by hand.
-    const identitiesVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
-    await (0, template_renderer_1.applyTemplateEntries)(projectDir, [
-        { template: "add/auth/migrations/create_identities.up.sql.hbs", output: path_1.default.join("migrations", `${identitiesVersion}_create_identities.up.sql`) },
-        { template: "add/auth/migrations/create_identities.down.sql.hbs", output: path_1.default.join("migrations", `${identitiesVersion}_create_identities.down.sql`) },
-    ], {});
     // the failed-attempt counter is not a store choice — lockout has to survive a
     // deploy and mean the same thing on every replica whichever store holds tokens
     const throttleVersion = (0, migrations_1.newMigrationVersion)(migrationsDir);
@@ -181,8 +192,9 @@ async function addAuth(store = "postgres", projectDir = process.cwd(), browserTo
     console.log("registered POST /auth/{register,login,refresh,logout,forgot-password,reset-password,verify-email}, " +
         "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/sessions, DELETE /users/me/sessions/{id}, " +
-        "GET /users/me/mfa, and POST /auth/mfa/verify in cmd/api/wiring.go" +
+        "GET /users/me/{identities,sessions,mfa}, POST /users/me/identities/local, POST /users/me/identities/{provider}/{link,link/exchange}, " +
+        "DELETE /users/me/identities/{provider}, DELETE /users/me/sessions/{id}, " +
+        "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 with `make migrate-up` before production\n" +
         "seed an admin: SEED_ADMIN_EMAIL=... SEED_ADMIN_PASSWORD=... make seed"));

package/dist/commands/method.js

@@ -84,6 +84,8 @@ async function generateHexagonalMethod(config, naming, methodNameArg, opts, proj
             ? {
                 repositoryModelType: "User",
                 repositoryToDomain: "toDomainUser",
+                repositoryToDomainCall: "r.toDomainUser(ctx, &row)",
+                repositoryToDomainCallReturnsError: true,
                 repositoryErrorMapper: "persistenceError",
                 repositoryStubReceiver: "f *fakeRepo",
                 handlerErrorMapper: "toHTTPError",

package/dist/templates/auth-manifest.js

@@ -17,12 +17,14 @@ const SHARED = [
     { template: "add/auth/internal/app/user/application/dto.go.hbs", output: "internal/app/user/application/dto.go" },
     { template: "add/auth/internal/app/user/application/errors.go.hbs", output: "internal/app/user/application/errors.go" },
     { template: "add/auth/internal/app/user/application/external_login.go.hbs", output: "internal/app/user/application/external_login.go" },
+    { template: "add/auth/internal/app/user/application/identities.go.hbs", output: "internal/app/user/application/identities.go" },
     { template: "add/auth/internal/app/user/application/jwt.go.hbs", output: "internal/app/user/application/jwt.go" },
     { template: "add/auth/internal/app/user/application/local_auth.go.hbs", output: "internal/app/user/application/local_auth.go" },
     { template: "add/auth/internal/app/user/application/mfa_service.go.hbs", output: "internal/app/user/application/mfa_service.go" },
     { template: "add/auth/internal/app/user/application/mfa_service_test.go.hbs", output: "internal/app/user/application/mfa_service_test.go" },
     { template: "add/auth/internal/app/user/application/oauth.go.hbs", output: "internal/app/user/application/oauth.go" },
     { template: "add/auth/internal/app/user/application/provider_test.go.hbs", output: "internal/app/user/application/provider_test.go" },
+    { template: "add/auth/internal/app/user/application/identities_test.go.hbs", output: "internal/app/user/application/identities_test.go" },
     { template: "add/auth/internal/app/user/application/recovery.go.hbs", output: "internal/app/user/application/recovery.go" },
     { template: "add/auth/internal/app/user/application/recovery_service.go.hbs", output: "internal/app/user/application/recovery_service.go" },
     { template: "add/auth/internal/app/user/application/service.go.hbs", output: "internal/app/user/application/service.go" },
@@ -39,6 +41,7 @@ const SHARED = [
     { template: "add/auth/internal/app/user/adapters/inbound/http/handler_recovery.go.hbs", output: "internal/app/user/adapters/inbound/http/handler_recovery.go" },
     { template: "add/auth/internal/app/user/adapters/inbound/http/handler_test.go.hbs", output: "internal/app/user/adapters/inbound/http/handler_test.go" },
     { template: "add/auth/internal/app/user/adapters/inbound/http/handler_user.go.hbs", output: "internal/app/user/adapters/inbound/http/handler_user.go" },
+    { template: "add/auth/internal/app/user/adapters/inbound/http/handler_identity.go.hbs", output: "internal/app/user/adapters/inbound/http/handler_identity.go" },
     { template: "add/auth/internal/app/user/adapters/inbound/http/session_cookie.go.hbs", output: "internal/app/user/adapters/inbound/http/session_cookie.go" },
     { template: "add/auth/internal/app/user/adapters/outbound/password/bcrypt.go.hbs", output: "internal/app/user/adapters/outbound/password/bcrypt.go" },
     { template: "add/auth/internal/app/user/adapters/outbound/password/bcrypt_test.go.hbs", output: "internal/app/user/adapters/outbound/password/bcrypt_test.go" },

package/dist/utils/auth-patcher.js

@@ -122,6 +122,9 @@ function patchMainGoForAuth(mainGoPath, w) {
         'if cfg.IsProd() && cfg.JWTSecret == "dev-secret-change-me" {',
         '\treturn errors.New("JWT_SECRET is still the dev default — set a real secret before deploying with APP_ENV=production")',
         "}",
+        'if cfg.IsProd() && len([]byte(cfg.JWTSecret)) < 32 {',
+        '\treturn errors.New("JWT_SECRET must be at least 32 bytes before deploying with APP_ENV=production")',
+        "}",
     ].join("\n");
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_CHECKS_MARKER, checkBlock, "JWT_SECRET is still the dev default");
     // Without SMTP the mail client logs the message instead of sending it — a
@@ -164,7 +167,13 @@ function patchMainGoForAuth(mainGoPath, w) {
         "}",
     ].join("\n");
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMA_MARKER, schemaBlock, "CREATE SCHEMA IF NOT EXISTS user_svc");
-    const migrateLines = ["&usermodel.User{},", "&usermodel.Identity{},", "&usermodel.LoginThrottle{},"];
+    const migrateLines = [
+        "&usermodel.User{},",
+        "&usermodel.UserEmail{},",
+        "&usermodel.PasswordCredential{},",
+        "&usermodel.ExternalIdentity{},",
+        "&usermodel.LoginThrottle{},",
+    ];
     // Recovery tokens are always durable in Postgres, even when refresh tokens
     // live in Redis, so reset/verification can share the user transaction.
     migrateLines.push("&usermodel.AuthToken{},");

package/dist/utils/hexagonal-method-patcher.js

@@ -299,14 +299,25 @@ function patchHexagonalMethod(paths, naming, method, opts, goModule) {
         const column = (0, naming_1.toDbName)(opts.field);
         const modelType = paths.repositoryModelType ?? `${naming.pascalName}Model`;
         const toDomain = paths.repositoryToDomain ?? "toDomain";
+        const toDomainCall = paths.repositoryToDomainCall ?? `${toDomain}(&row)`;
+        const toDomainCallReturnsError = paths.repositoryToDomainCallReturnsError ?? false;
         const errorMapper = paths.repositoryErrorMapper ?? "mapDatabaseError";
+        const mapping = toDomainCallReturnsError
+            ? [
+                `\tm, err := ${toDomainCall}`,
+                `\tif err != nil {`,
+                `\t\treturn nil, ${errorMapper}(err)`,
+                `\t}`,
+                `\treturn m, nil`,
+            ]
+            : [`\treturn ${toDomainCall}, nil`];
         adapter = insert(adapter, REPOSITORY_METHODS_MARKER, [
             `func (r *Repository) FindBy${fieldPascal}(ctx context.Context, ${fieldParam} string) (*domain.${naming.pascalName}, error) {`,
             `\tvar row ${modelType}`,
             `\tif err := tx.From(ctx, r.db).WithContext(ctx).First(&row, "${column} = ?", ${fieldParam}).Error; err != nil {`,
             `\t\treturn nil, ${errorMapper}(err)`,
             `\t}`,
-            `\treturn ${toDomain}(&row), nil`,
+            ...mapping,
             `}`,
             "",
         ].join("\n"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nakedev/go-scaffold",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard",
   "repository": {
     "type": "git",

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

@@ -3,7 +3,7 @@ RegisterInput:
   required: [email, password, name]
   properties:
     email: { type: string, format: email }
-    password: { type: string, format: password, minLength: 8 }
+    password: { type: string, format: password, minLength: 8, maxLength: 72 }
     name: { type: string }
 
 LoginInput:
@@ -11,7 +11,7 @@ LoginInput:
   required: [email, password]
   properties:
     email: { type: string, format: email }
-    password: { type: string, format: password }
+    password: { type: string, format: password, maxLength: 72 }
 
 ForgotPasswordInput:
   type: object
@@ -24,7 +24,7 @@ ResetPasswordInput:
   required: [token, new_password]
   properties:
     token: { type: string }
-    new_password: { type: string, format: password, minLength: 8 }
+    new_password: { type: string, format: password, minLength: 8, maxLength: 72 }
 
 VerifyEmailInput:
   type: object
@@ -133,3 +133,45 @@ SessionsResponse:
     sessions:
       type: array
       items: { $ref: '#/SessionResponse' }
+
+IdentityResponse:
+  type: object
+  required: [id, provider, created_at]
+  properties:
+    id: { type: string, format: uuid }
+    provider: { type: string, example: google }
+    created_at: { type: string, format: date-time }
+
+IdentitiesResponse:
+  type: object
+  required: [identities]
+  properties:
+    identities:
+      type: array
+      items: { $ref: '#/IdentityResponse' }
+
+IdentityLinkStartInput:
+  type: object
+  required: [state, code_challenge, code_challenge_method]
+  additionalProperties: false
+  properties:
+    state: { type: string, minLength: 1 }
+    code_challenge:
+      type: string
+      minLength: 43
+      maxLength: 128
+      pattern: '^[A-Za-z0-9._~-]+$'
+    code_challenge_method: { type: string, enum: [S256] }
+
+IdentityLinkStartResponse:
+  type: object
+  required: [authorization_url]
+  properties:
+    authorization_url: { type: string, format: uri }
+
+LocalIdentityLinkInput:
+  type: object
+  required: [password]
+  additionalProperties: false
+  properties:
+    password: { type: string, format: password, minLength: 8, maxLength: 72 }

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

@@ -0,0 +1,13 @@
+get:
+  summary: List login identities for the current user
+  description: Returns safe provider metadata only; provider subjects and password hashes are never exposed.
+  operationId: listMyIdentities
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  responses:
+    "200":
+      description: linked login identities
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/IdentitiesResponse' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }

package/templates/add/auth/docs/users-me-identity-link-exchange.yaml.hbs

@@ -0,0 +1,26 @@
+post:
+  summary: Complete linking a provider identity to the current user
+  description: Consumes the one-time OAuth transaction and links the provider subject to the caller. It never creates or switches a session.
+  operationId: exchangeIdentityLink
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  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: linked identity
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/IdentityResponse' }
+    "400": { description: invalid OAuth state or provider response }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "409": { description: provider identity is already linked or owned by another user }
+    "503": { description: provider unavailable }

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

@@ -0,0 +1,25 @@
+post:
+  summary: Start linking a provider identity to the current user
+  description: Creates a one-time OAuth transaction bound to the authenticated user and returns the provider authorization URL.
+  operationId: startIdentityLink
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  parameters:
+    - name: provider
+      in: path
+      required: true
+      schema: { type: string, example: google }
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/IdentityLinkStartInput' }
+  responses:
+    "200":
+      description: provider authorization URL
+      content:
+        application/json:
+          schema: { $ref: './schemas.yaml#/IdentityLinkStartResponse' }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "503": { description: provider unavailable }

package/templates/add/auth/docs/users-me-identity-local-link.yaml.hbs

@@ -0,0 +1,16 @@
+post:
+  summary: Add an email/password login to the current user
+  description: Creates a password credential for the authenticated account. It does not create another account, even when the account originally signed in with Google.
+  operationId: linkMyLocalIdentity
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema: { $ref: './schemas.yaml#/LocalIdentityLinkInput' }
+  responses:
+    "204": { description: email/password login linked }
+    "400": { $ref: '../common/responses.yaml#/ValidationError' }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "409": { description: email/password login is already linked }

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

@@ -0,0 +1,15 @@
+delete:
+  summary: Unlink a login identity from the current user
+  operationId: unlinkMyIdentity
+  tags: [users]
+  security: [{ bearerAuth: [] }]
+  parameters:
+    - name: provider
+      in: path
+      required: true
+      schema: { type: string, example: google }
+  responses:
+    "204": { description: login identity unlinked }
+    "401": { $ref: '../common/responses.yaml#/UnauthorizedError' }
+    "404": { description: login identity not found }
+    "409": { description: cannot remove the last login identity }

package/templates/add/auth/internal/app/user/adapters/inbound/http/dto.go.hbs

@@ -13,13 +13,13 @@ import (
 // transport-neutral inputs from handler mapping code.
 type registerInput struct {
 	Email    string `json:"email" binding:"required,email"`
-	Password string `json:"password" binding:"required,min=8"`
+	Password string `json:"password" binding:"required,min=8,max=72"`
 	Name     string `json:"name" binding:"required"`
 }
 
 type loginInput struct {
 	Email    string `json:"email" binding:"required,email"`
-	Password string `json:"password" binding:"required"`
+	Password string `json:"password" binding:"required,max=72"`
 }
 
 type loginExchangeInput struct {
@@ -62,7 +62,7 @@ type forgotPasswordInput struct {
 
 type resetPasswordInput struct {
 	Token       string `json:"token" binding:"required"`
-	NewPassword string `json:"new_password" binding:"required,min=8"`
+	NewPassword string `json:"new_password" binding:"required,min=8,max=72"`
 }
 
 type verifyEmailInput struct {
@@ -116,6 +116,36 @@ type sessionsResponse struct {
 	Sessions []sessionResponse `json:"sessions"`
 }
 
+type identityLinkStartInput struct {
+	State               string `json:"state" binding:"required"`
+	CodeChallenge       string `json:"code_challenge" binding:"required"`
+	CodeChallengeMethod string `json:"code_challenge_method" binding:"required"`
+}
+
+type identityLinkExchangeInput struct {
+	Code         string `json:"code" binding:"required"`
+	State        string `json:"state" binding:"required"`
+	CodeVerifier string `json:"code_verifier" binding:"required"`
+}
+
+type localIdentityLinkInput struct {
+	Password string `json:"password" binding:"required,min=8,max=72"`
+}
+
+type identityLinkStartResponse struct {
+	AuthorizationURL string `json:"authorization_url"`
+}
+
+type identityResponse struct {
+	ID        uuid.UUID `json:"id"`
+	Provider  string    `json:"provider"`
+	CreatedAt time.Time `json:"created_at"`
+}
+
+type identitiesResponse struct {
+	Identities []identityResponse `json:"identities"`
+}
+
 func toSessionResponse(session userapp.Session) sessionResponse {
 	return sessionResponse{
 		ID: session.ID, UserAgent: session.UserAgent, CreatedAt: session.CreatedAt,
@@ -123,6 +153,18 @@ func toSessionResponse(session userapp.Session) sessionResponse {
 	}
 }
 
+func toIdentityLinkStartInput(in identityLinkStartInput) userapp.LoginStartInput {
+	return userapp.LoginStartInput{State: in.State, CodeChallenge: in.CodeChallenge, CodeChallengeMethod: in.CodeChallengeMethod}
+}
+
+func toIdentityLinkExchangeInput(in identityLinkExchangeInput) userapp.LoginExchangeInput {
+	return userapp.LoginExchangeInput{Code: in.Code, State: in.State, CodeVerifier: in.CodeVerifier}
+}
+
+func toIdentityResponse(identity userapp.IdentityResponse) identityResponse {
+	return identityResponse{ID: identity.ID, Provider: identity.Provider, CreatedAt: identity.CreatedAt}
+}
+
 func toCookieResponse(auth *userapp.AuthResponse) authCookieResponse {
 	return authCookieResponse{AccessToken: auth.AccessToken, TokenType: auth.TokenType, ExpiresIn: auth.ExpiresIn}
 }

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler.go.hbs

@@ -115,6 +115,7 @@ func (h *Handler) Register(rg gin.IRouter) {
 	mfaSetupLimit := middleware.RateLimit(h.limiter, "mfa-setup", 5, time.Minute)
 	mfaConfirmLimit := middleware.RateLimit(h.limiter, "mfa-confirm", 5, time.Minute)
 	mfaDisableLimit := middleware.RateLimit(h.limiter, "mfa-disable", 5, time.Minute)
+	identityLinkLimit := middleware.RateLimit(h.limiter, "identity-link", 10, time.Minute)
 
 	authGroup := rg.Group("/auth")
 	authGroup.POST("/register", registerLimit, h.register)
@@ -138,6 +139,7 @@ func (h *Handler) Register(rg gin.IRouter) {
 	usersGroup.POST("/me/mfa/setup", mfaSetupLimit, h.setupMFA)
 	usersGroup.POST("/me/mfa/confirm", mfaConfirmLimit, h.confirmMFA)
 	usersGroup.POST("/me/mfa/disable", mfaDisableLimit, h.disableMFA)
+	h.registerIdentityRoutes(usersGroup, identityLinkLimit)
 	// Admin user routes are enabled only when the optional RBAC authorizer is
 	// supplied by the composition root. Auth-only projects keep the endpoint
 	// surface limited to authentication and the current-user operations.
@@ -207,10 +209,14 @@ func toHTTPError(err error) error {
 		switch ruleErr.Code {
 		case "USER_NOT_FOUND":
 			status = http.StatusNotFound
-		case "USER_EMAIL_TAKEN", "AUTH_ALREADY_VERIFIED", "AUTH_MFA_ALREADY_ENABLED", "AUTH_MFA_NOT_ENROLLED", "AUTH_MFA_SETUP_REQUIRED":
+		case "USER_EMAIL_TAKEN", "AUTH_ALREADY_VERIFIED", "AUTH_MFA_ALREADY_ENABLED", "AUTH_MFA_NOT_ENROLLED", "AUTH_MFA_SETUP_REQUIRED", "AUTH_IDENTITY_ALREADY_LINKED", "AUTH_IDENTITY_CONFLICT", "AUTH_LAST_IDENTITY":
 			status = http.StatusConflict
+		case "AUTH_IDENTITY_NOT_FOUND":
+			status = http.StatusNotFound
 		case "AUTH_INVALID_CREDENTIALS", "AUTH_INVALID_TOKEN", "AUTH_MFA_INVALID":
 			status = http.StatusUnauthorized
+		case "AUTH_INVALID_PASSWORD":
+			status = http.StatusBadRequest
 		case "AUTH_MFA_UNAVAILABLE":
 			status = http.StatusServiceUnavailable
 		case "AUTH_TOO_MANY_ATTEMPTS":

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler_identity.go.hbs

@@ -0,0 +1,107 @@
+package httpadapter
+
+import (
+	"errors"
+	"net/http"
+
+	userapp "{{goModule}}/internal/app/user/application"
+	"{{goModule}}/internal/shared/httpx"
+
+	"github.com/gin-gonic/gin"
+)
+
+// registerIdentityRoutes keeps account-linking routes out of the main auth
+// route file while the handler remains in the same inbound adapter package.
+func (h *Handler) registerIdentityRoutes(usersGroup gin.IRouter, linkLimiter gin.HandlerFunc) {
+	usersGroup.GET("/me/identities", h.listIdentities)
+	usersGroup.POST("/me/identities/local", linkLimiter, h.linkLocalIdentity)
+	usersGroup.POST("/me/identities/:provider/link", linkLimiter, h.beginIdentityLink)
+	usersGroup.POST("/me/identities/:provider/link/exchange", linkLimiter, h.exchangeIdentityLink)
+	usersGroup.DELETE("/me/identities/:provider", h.unlinkIdentity)
+}
+
+func (h *Handler) linkLocalIdentity(c *gin.Context) {
+	setNoStoreHeaders(c)
+	if !h.requireBrowserOrigin(c) {
+		return
+	}
+	var in localIdentityLinkInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(httpx.BindErr(err))
+		return
+	}
+	if err := h.svc.LinkLocalIdentity(c.Request.Context(), currentUserID(c), in.Password); err != nil {
+		c.Error(toHTTPError(err))
+		return
+	}
+	c.Status(http.StatusNoContent)
+}
+
+func (h *Handler) listIdentities(c *gin.Context) {
+	setNoStoreHeaders(c)
+	items, err := h.svc.ListIdentities(c.Request.Context(), currentUserID(c))
+	if err != nil {
+		c.Error(toHTTPError(err))
+		return
+	}
+	out := make([]identityResponse, len(items))
+	for i := range items {
+		out[i] = toIdentityResponse(items[i])
+	}
+	c.JSON(http.StatusOK, identitiesResponse{Identities: out})
+}
+
+func (h *Handler) beginIdentityLink(c *gin.Context) {
+	setNoStoreHeaders(c)
+	if !h.requireBrowserOrigin(c) {
+		return
+	}
+	var in identityLinkStartInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(httpx.BindErr(err))
+		return
+	}
+	authorization, err := h.svc.BeginIdentityLink(c.Request.Context(), currentUserID(c), c.Param("provider"), toIdentityLinkStartInput(in))
+	if err != nil {
+		c.Error(h.oauthAppError(c.Param("provider"), err))
+		return
+	}
+	c.JSON(http.StatusOK, identityLinkStartResponse{AuthorizationURL: authorization.URL})
+}
+
+func (h *Handler) exchangeIdentityLink(c *gin.Context) {
+	setNoStoreHeaders(c)
+	if !h.requireBrowserOrigin(c) {
+		return
+	}
+	var in identityLinkExchangeInput
+	if err := c.ShouldBindJSON(&in); err != nil {
+		c.Error(h.oauthAppError(c.Param("provider"), userapp.NewOAuthError(userapp.OAuthFailed, err)))
+		return
+	}
+	identity, err := h.svc.ExchangeIdentityLink(c.Request.Context(), currentUserID(c), c.Param("provider"), toIdentityLinkExchangeInput(in))
+	if err != nil {
+		c.Error(h.identityLinkError(c.Param("provider"), err))
+		return
+	}
+	c.JSON(http.StatusOK, toIdentityResponse(*identity))
+}
+
+func (h *Handler) identityLinkError(provider string, err error) error {
+	var oauthErr *userapp.OAuthError
+	if errors.As(err, &oauthErr) {
+		return h.oauthAppError(provider, err)
+	}
+	return toHTTPError(err)
+}
+
+func (h *Handler) unlinkIdentity(c *gin.Context) {
+	if !h.requireBrowserOrigin(c) {
+		return
+	}
+	if err := h.svc.UnlinkIdentity(c.Request.Context(), currentUserID(c), c.Param("provider")); err != nil {
+		c.Error(toHTTPError(err))
+		return
+	}
+	c.Status(http.StatusNoContent)
+}

package/templates/add/auth/internal/app/user/adapters/inbound/http/handler_test.go.hbs

@@ -4,6 +4,7 @@ import (
 	"context"
 	"crypto/sha256"
 	"encoding/base64"
+	"errors"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
@@ -12,6 +13,8 @@ import (
 	"time"
 
 	"{{goModule}}/internal/app/user/application"
+	"{{goModule}}/internal/app/user/domain"
+	"{{goModule}}/internal/shared/apperror"
 	"{{goModule}}/internal/shared/middleware"
 
 	"github.com/gin-gonic/gin"
@@ -154,6 +157,11 @@ func TestHandler_ProviderExchangeReturnsJSONAndSetsRefreshCookie(t *testing.T) {
 func TestHandler_SessionRoutesAreProtected(t *testing.T) {
 	router := newOAuthTestRouter(t)
 	for _, route := range []struct{ method, path string }{
+		{http.MethodGet, "/users/me/identities"},
+		{http.MethodPost, "/users/me/identities/local"},
+		{http.MethodPost, "/users/me/identities/fake/link"},
+		{http.MethodPost, "/users/me/identities/fake/link/exchange"},
+		{http.MethodDelete, "/users/me/identities/fake"},
 		{http.MethodGet, "/users/me/sessions"},
 		{http.MethodDelete, "/users/me/sessions/00000000-0000-0000-0000-000000000001"},
 	} {
@@ -165,6 +173,19 @@ func TestHandler_SessionRoutesAreProtected(t *testing.T) {
 	}
 }
 
+func TestHandler_IdentityLinkErrorPreservesConflictStatus(t *testing.T) {
+	h := NewHandler(stubService{}, "test-secret", time.Hour, true, "strict", allowAllLimiter{})
+	mapped := h.identityLinkError("fake", domain.Rule("AUTH_IDENTITY_CONFLICT", "identity conflict", domain.ErrConflict))
+
+	var appErr *apperror.AppError
+	if !errors.As(mapped, &appErr) {
+		t.Fatalf("mapped error = %T, want *apperror.AppError", mapped)
+	}
+	if appErr.HTTPStatus != http.StatusConflict || appErr.Code != "AUTH_IDENTITY_CONFLICT" {
+		t.Fatalf("mapped error = status %d code %q, want 409 AUTH_IDENTITY_CONFLICT", appErr.HTTPStatus, appErr.Code)
+	}
+}
+
 func TestHandler_ProviderCallbackIsFrontendOwnedAndErrorsDoNotRedirect(t *testing.T) {
 	router := newOAuthTestRouter(t)
 	callback := httptest.NewRequest(http.MethodGet, "/auth/fake/callback?error=access_denied&error_description=do-not-leak", nil)

package/templates/add/auth/internal/app/user/adapters/outbound/postgres/mfa_store_test.go.hbs

@@ -53,7 +53,7 @@ func TestPostgresMFAStore_ConsumesChallengesAndRecoveryCodesOnce(t *testing.T) {
 	store := NewPostgresMFAStore(db)
 	ctx := context.Background()
 	userID := uuid.New()
-	if err := db.Create(&User{ID: userID, Email: "mfa-store-" + uuid.NewString() + "@example.com"}).Error; err != nil {
+	if err := db.Create(&User{ID: userID}).Error; err != nil {
 		t.Fatalf("create test user: %v", err)
 	}
 	t.Cleanup(func() { _ = db.Delete(&User{}, "id = ?", userID).Error })