@nakedev/go-scaffold 0.5.2 → 0.5.3

package/dist/commands/auth.js

@@ -34,6 +34,10 @@ 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/{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" },
@@ -181,8 +185,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/{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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nakedev/go-scaffold",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "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

@@ -133,3 +133,38 @@ 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 }

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.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

@@ -116,6 +116,32 @@ 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 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 +149,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,8 +209,10 @@ 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_MFA_UNAVAILABLE":

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

@@ -0,0 +1,80 @@
+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/: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) 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)
+	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)
+	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 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,10 @@ 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/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 +172,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/repository.go.hbs

@@ -12,6 +12,7 @@ import (
 
 	"github.com/google/uuid"
 	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
 )
 
 type Repository struct {
@@ -68,6 +69,20 @@ func (r *Repository) FindIdentity(ctx context.Context, userID uuid.UUID, provide
 	return toDomainIdentity(&row), nil
 }
 
+func (r *Repository) ListIdentities(ctx context.Context, userID uuid.UUID) ([]domain.Identity, error) {
+	var rows []Identity
+	if err := tx.From(ctx, r.db).WithContext(ctx).
+		Where("user_id = ?", userID).
+		Order("created_at ASC, id ASC").Find(&rows).Error; err != nil {
+		return nil, persistenceError(err)
+	}
+	items := make([]domain.Identity, len(rows))
+	for i := range rows {
+		items[i] = *toDomainIdentity(&rows[i])
+	}
+	return items, nil
+}
+
 func (r *Repository) FindIdentityByProviderUID(ctx context.Context, provider domain.Provider, providerUID string) (*domain.Identity, error) {
 	var row Identity
 	if err := tx.From(ctx, r.db).WithContext(ctx).
@@ -88,6 +103,34 @@ func (r *Repository) UpdateIdentity(ctx context.Context, identity *domain.Identi
 	return persistenceError(tx.From(ctx, r.db).WithContext(ctx).Save(&row).Error)
 }
 
+// DeleteIdentity locks the user's identity rows before checking the count so
+// two concurrent unlink requests cannot both remove the last login method.
+func (r *Repository) DeleteIdentity(ctx context.Context, userID uuid.UUID, provider domain.Provider) error {
+	return persistenceError(tx.From(ctx, r.db).WithContext(ctx).Transaction(func(db *gorm.DB) error {
+		var rows []Identity
+		if err := db.Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("user_id = ?", userID).
+			Order("created_at ASC, id ASC").Find(&rows).Error; err != nil {
+			return err
+		}
+
+		var target *Identity
+		for i := range rows {
+			if rows[i].Provider == string(provider) {
+				target = &rows[i]
+				break
+			}
+		}
+		if target == nil {
+			return domain.ErrNotFound
+		}
+		if len(rows) <= 1 {
+			return domain.ErrLastIdentity
+		}
+		return db.Delete(&Identity{}, "id = ? AND user_id = ?", target.ID, userID).Error
+	}))
+}
+
 // CreateUserWithIdentity inserts the profile and its first login method in
 // one transaction. A user without an identity cannot authenticate.
 func (r *Repository) CreateUserWithIdentity(ctx context.Context, user *domain.User, identity *domain.Identity) error {

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

@@ -176,6 +176,7 @@ func (s *PgTokenStore) SetLoginTransaction(ctx context.Context, stateHash string
 	}
 	row := AuthToken{
 		TokenHash:     stateHash,
+		UserID:        transaction.UserID,
 		Kind:          kindOAuthState,
 		ExpiresAt:     transaction.ExpiresAt,
 		Provider:      transaction.Provider,
@@ -185,7 +186,7 @@ func (s *PgTokenStore) SetLoginTransaction(ctx context.Context, stateHash string
 	return tx.From(ctx, s.db).WithContext(ctx).
 		Where("token_hash = ?", stateHash).
 		Assign(map[string]any{
-			"user_id":        uuid.Nil,
+			"user_id":        transaction.UserID,
 			"kind":           kindOAuthState,
 			"expires_at":     transaction.ExpiresAt,
 			"provider":       transaction.Provider,
@@ -199,8 +200,9 @@ func (s *PgTokenStore) ConsumeLoginTransaction(ctx context.Context, stateHash st
 	err := tx.From(ctx, s.db).WithContext(ctx).Raw(
 		`DELETE FROM user_svc.auth_tokens
 		 WHERE token_hash = ? AND kind = ? AND expires_at > now()
-		 RETURNING provider, code_challenge, nonce, expires_at`,
+		 RETURNING user_id, provider, code_challenge, nonce, expires_at`,
 		stateHash, kindOAuthState).Row().Scan(
+		&transaction.UserID,
 		&transaction.Provider,
 		&transaction.CodeChallenge,
 		&transaction.Nonce,

package/templates/add/auth/internal/app/user/application/dto.go.hbs

@@ -43,6 +43,20 @@ type Session struct {
 	Current    bool
 }
 
+// IdentityResponse is the safe public view of a login identity. Provider
+// subjects and password hashes never cross the application/HTTP boundary.
+type IdentityResponse struct {
+	ID        uuid.UUID
+	Provider  string
+	CreatedAt time.Time
+}
+
+func ToIdentityResponse(identity domain.Identity) IdentityResponse {
+	return IdentityResponse{
+		ID: identity.ID, Provider: string(identity.Provider), CreatedAt: identity.CreatedAt,
+	}
+}
+
 type AuthResponse struct {
 	AccessToken  string
 	RefreshToken string

package/templates/add/auth/internal/app/user/application/errors.go.hbs

@@ -60,3 +60,19 @@ func errMFAConfig() error {
 func errUnknownRole() error {
 	return domain.Rule("USER_UNKNOWN_ROLE", "unknown role code", domain.ErrUnknownRole)
 }
+
+func errIdentityAlreadyLinked() error {
+	return domain.Rule("AUTH_IDENTITY_ALREADY_LINKED", "this login method is already linked", domain.ErrIdentityAlreadyLinked)
+}
+
+func errIdentityConflict() error {
+	return domain.Rule("AUTH_IDENTITY_CONFLICT", "this provider account is linked to another user", domain.ErrConflict)
+}
+
+func errIdentityNotFound() error {
+	return domain.Rule("AUTH_IDENTITY_NOT_FOUND", "login method not found", domain.ErrNotFound)
+}
+
+func errLastIdentity() error {
+	return domain.Rule("AUTH_LAST_IDENTITY", "you cannot remove your last login method", domain.ErrLastIdentity)
+}

package/templates/add/auth/internal/app/user/application/external_login.go.hbs

@@ -12,6 +12,8 @@ import (
 
 	"{{goModule}}/internal/app/user/domain"
 	"{{goModule}}/internal/shared/id"
+
+	"github.com/google/uuid"
 )
 
 // BeginLogin accepts the browser client's state and S256 PKCE challenge and
@@ -19,6 +21,21 @@ import (
 // The server persists a hashed state transaction binding provider, challenge,
 // and OIDC nonce before the callback reaches ExchangeLogin.
 func (s *Service) BeginLogin(ctx context.Context, providerName string, in LoginStartInput) (*Authorization, error) {
+	return s.beginProviderLogin(ctx, providerName, in, uuid.Nil)
+}
+
+// BeginIdentityLink starts an OAuth transaction that is bound to the
+// authenticated user. It is deliberately separate from BeginLogin: the
+// public login flow may resolve any user, while a link flow must never be
+// allowed to attach an identity to whichever account the provider returns.
+func (s *Service) BeginIdentityLink(ctx context.Context, userID uuid.UUID, providerName string, in LoginStartInput) (*Authorization, error) {
+	if userID == uuid.Nil {
+		return nil, NewOAuthError(OAuthStateInvalid, fmt.Errorf("authenticated user is required to link an identity"))
+	}
+	return s.beginProviderLogin(ctx, providerName, in, userID)
+}
+
+func (s *Service) beginProviderLogin(ctx context.Context, providerName string, in LoginStartInput, userID uuid.UUID) (*Authorization, error) {
 	provider, ok := s.providers.Lookup(providerName)
 	if !ok {
 		return nil, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("provider %q is not configured", providerName))
@@ -46,6 +63,7 @@ func (s *Service) BeginLogin(ctx context.Context, providerName string, in LoginS
 	}
 	if err := s.oauthTransactions.SetLoginTransaction(ctx, hashToken(in.State), LoginTransaction{
 		Provider:      providerName,
+		UserID:        userID,
 		CodeChallenge: in.CodeChallenge,
 		Nonce:         nonce,
 		ExpiresAt:     clock().Add(s.config.OAuthStateTTL),
@@ -56,37 +74,48 @@ func (s *Service) BeginLogin(ctx context.Context, providerName string, in LoginS
 }
 
 func (s *Service) ExchangeLogin(ctx context.Context, providerName string, in LoginExchangeInput) (*AuthResult, error) {
+	identity, err := s.exchangeExternalIdentity(ctx, providerName, in, uuid.Nil)
+	if err != nil {
+		return nil, err
+	}
+	u, err := s.findOrCreateExternalUser(ctx, identity)
+	if err != nil {
+		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("resolve external identity: %w", err))
+	}
+	return s.completeLogin(ctx, u, in.Session)
+}
+
+// exchangeExternalIdentity consumes the one-time transaction before asking
+// the provider to complete the code exchange. The transaction's UserID is
+// zero for public login and is the authenticated caller for identity linking.
+func (s *Service) exchangeExternalIdentity(ctx context.Context, providerName string, in LoginExchangeInput, userID uuid.UUID) (ExternalIdentity, error) {
 	provider, ok := s.providers.Lookup(providerName)
 	if !ok {
-		return nil, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("provider %q is not configured", providerName))
+		return ExternalIdentity{}, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("provider %q is not configured", providerName))
 	}
 	if !validOAuthValue(in.State) || !validPKCEValue(in.CodeVerifier) {
-		return nil, NewOAuthError(OAuthStateInvalid, fmt.Errorf("state and code verifier are required"))
+		return ExternalIdentity{}, NewOAuthError(OAuthStateInvalid, fmt.Errorf("state and code verifier are required"))
 	}
 	if !validOAuthValue(in.Code) {
-		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("authorization code is missing"))
+		return ExternalIdentity{}, NewOAuthError(OAuthFailed, fmt.Errorf("authorization code is missing"))
 	}
 
 	transaction, ok, err := s.oauthTransactions.ConsumeLoginTransaction(ctx, hashToken(in.State))
 	if err != nil {
-		return nil, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("consume oauth transaction: %w", err))
+		return ExternalIdentity{}, NewOAuthError(OAuthProviderUnavailable, fmt.Errorf("consume oauth transaction: %w", err))
 	}
-	if !ok || transaction.Provider != providerName || !validPKCEVerifier(in.CodeVerifier, transaction.CodeChallenge) {
-		return nil, NewOAuthError(OAuthStateInvalid, fmt.Errorf("oauth state or PKCE verifier is invalid"))
+	if !ok || transaction.Provider != providerName || transaction.UserID != userID || !validPKCEVerifier(in.CodeVerifier, transaction.CodeChallenge) {
+		return ExternalIdentity{}, NewOAuthError(OAuthStateInvalid, fmt.Errorf("oauth state or PKCE verifier is invalid"))
 	}
 
 	identity, err := provider.Complete(ctx, LoginCompleteInput{Code: in.Code, CodeVerifier: in.CodeVerifier, Nonce: transaction.Nonce})
 	if err != nil {
-		return nil, mapProviderError(err)
+		return ExternalIdentity{}, mapProviderError(err)
 	}
 	if identity.Provider != providerName {
-		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("provider identity name does not match the requested provider"))
+		return ExternalIdentity{}, NewOAuthError(OAuthFailed, fmt.Errorf("provider identity name does not match the requested provider"))
 	}
-	u, err := s.findOrCreateExternalUser(ctx, identity)
-	if err != nil {
-		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("resolve external identity: %w", err))
-	}
-	return s.completeLogin(ctx, u, in.Session)
+	return identity, nil
 }
 
 func validPKCEVerifier(verifier, challenge string) bool {

package/templates/add/auth/internal/app/user/application/identities.go.hbs

@@ -0,0 +1,97 @@
+package application
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"{{goModule}}/internal/app/user/domain"
+
+	"github.com/google/uuid"
+)
+
+func (s *Service) ListIdentities(ctx context.Context, userID uuid.UUID) ([]IdentityResponse, error) {
+	items, err := s.repo.ListIdentities(ctx, userID)
+	if err != nil {
+		return nil, fmt.Errorf("list login identities: %w", err)
+	}
+
+	out := make([]IdentityResponse, len(items))
+	for i := range items {
+		out[i] = ToIdentityResponse(items[i])
+	}
+	return out, nil
+}
+
+func (s *Service) ExchangeIdentityLink(ctx context.Context, userID uuid.UUID, providerName string, in LoginExchangeInput) (*IdentityResponse, error) {
+	if userID == uuid.Nil {
+		return nil, NewOAuthError(OAuthStateInvalid, fmt.Errorf("authenticated user is required to link an identity"))
+	}
+
+	identity, err := s.exchangeExternalIdentity(ctx, providerName, in, userID)
+	if err != nil {
+		return nil, err
+	}
+	return s.linkExternalIdentity(ctx, userID, identity)
+}
+
+func (s *Service) linkExternalIdentity(ctx context.Context, userID uuid.UUID, info ExternalIdentity) (*IdentityResponse, error) {
+	provider := domain.Provider(strings.TrimSpace(info.Provider))
+	if userID == uuid.Nil || provider == "" || strings.TrimSpace(info.Subject) == "" {
+		return nil, NewOAuthError(OAuthFailed, fmt.Errorf("external identity is incomplete"))
+	}
+
+	// Replaying the same provider account from the same user is idempotent.
+	// A provider subject already owned by another user is a conflict and must
+	// never be silently moved between accounts.
+	if existing, err := s.repo.FindIdentityByProviderUID(ctx, provider, info.Subject); err == nil {
+		if existing.UserID != userID {
+			return nil, errIdentityConflict()
+		}
+		out := ToIdentityResponse(*existing)
+		return &out, nil
+	} else if !errors.Is(err, domain.ErrNotFound) {
+		return nil, fmt.Errorf("find linked identity: %w", err)
+	}
+
+	// The database permits one identity per provider for each user. Return a
+	// controlled conflict instead of exposing a persistence duplicate error.
+	if _, err := s.repo.FindIdentity(ctx, userID, provider); err == nil {
+		return nil, errIdentityAlreadyLinked()
+	} else if !errors.Is(err, domain.ErrNotFound) {
+		return nil, fmt.Errorf("check existing provider identity: %w", err)
+	}
+
+	providerUID := info.Subject
+	identity := &domain.Identity{
+		ID: uuid.New(), UserID: userID, Provider: provider, ProviderUID: &providerUID,
+	}
+	if err := s.repo.CreateIdentity(ctx, identity); err != nil {
+		if errors.Is(err, domain.ErrConflict) {
+			return nil, errIdentityAlreadyLinked()
+		}
+		return nil, fmt.Errorf("link identity: %w", err)
+	}
+
+	out := ToIdentityResponse(*identity)
+	return &out, nil
+}
+
+func (s *Service) UnlinkIdentity(ctx context.Context, userID uuid.UUID, providerName string) error {
+	provider := domain.Provider(strings.TrimSpace(providerName))
+	if userID == uuid.Nil || provider == "" {
+		return errIdentityNotFound()
+	}
+	if err := s.repo.DeleteIdentity(ctx, userID, provider); err != nil {
+		switch {
+		case errors.Is(err, domain.ErrLastIdentity):
+			return errLastIdentity()
+		case errors.Is(err, domain.ErrNotFound):
+			return errIdentityNotFound()
+		default:
+			return fmt.Errorf("unlink identity: %w", err)
+		}
+	}
+	return nil
+}

package/templates/add/auth/internal/app/user/application/identities_test.go.hbs

@@ -0,0 +1,69 @@
+package application
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"{{goModule}}/internal/app/user/domain"
+
+	"github.com/google/uuid"
+)
+
+func TestService_IdentityLinkBindsOAuthTransactionToCaller(t *testing.T) {
+	provider, svc := validFakeProvider(t)
+	userID := uuid.New()
+	otherUserID := uuid.New()
+
+	if _, err := svc.BeginIdentityLink(context.Background(), userID, provider.Name(), validLoginStart()); err != nil {
+		t.Fatalf("begin identity link: %v", err)
+	}
+
+	_, err := svc.ExchangeIdentityLink(context.Background(), otherUserID, provider.Name(), validLoginExchange())
+	if got := oauthErrorCode(t, err); got != OAuthStateInvalid {
+		t.Fatalf("oauth code = %q, want %q", got, OAuthStateInvalid)
+	}
+	if provider.completeCnt != 0 {
+		t.Fatal("provider must not receive a transaction bound to another user")
+	}
+}
+
+func TestService_IdentityLinkIsIdempotentForSameProviderSubject(t *testing.T) {
+	provider, svc := validFakeProvider(t)
+	userID := uuid.New()
+
+	if _, err := svc.BeginIdentityLink(context.Background(), userID, provider.Name(), validLoginStart()); err != nil {
+		t.Fatalf("begin first identity link: %v", err)
+	}
+	first, err := svc.ExchangeIdentityLink(context.Background(), userID, provider.Name(), validLoginExchange())
+	if err != nil {
+		t.Fatalf("exchange first identity link: %v", err)
+	}
+
+	if _, err := svc.BeginIdentityLink(context.Background(), userID, provider.Name(), validLoginStart()); err != nil {
+		t.Fatalf("begin repeated identity link: %v", err)
+	}
+	second, err := svc.ExchangeIdentityLink(context.Background(), userID, provider.Name(), validLoginExchange())
+	if err != nil {
+		t.Fatalf("exchange repeated identity link: %v", err)
+	}
+	if first.ID != second.ID || first.Provider != second.Provider {
+		t.Fatalf("repeated link returned a different identity: first=%+v second=%+v", first, second)
+	}
+}
+
+func TestService_UnlinkIdentityRejectsRemovingLastLoginMethod(t *testing.T) {
+	userID := uuid.New()
+	providerUID := "local-user"
+	repo := &fakeRepo{}
+	repo.identities = append(repo.identities, domain.Identity{
+		ID: uuid.New(), UserID: userID, Provider: domain.ProviderLocal, ProviderUID: &providerUID,
+	})
+	svc := newTestService(repo, newFakeTokenStore())
+
+	err := svc.UnlinkIdentity(context.Background(), userID, string(domain.ProviderLocal))
+	var ruleErr *domain.RuleError
+	if !errors.As(err, &ruleErr) || ruleErr.Code != "AUTH_LAST_IDENTITY" {
+		t.Fatalf("unlink last identity error = %v, want AUTH_LAST_IDENTITY", err)
+	}
+}

package/templates/add/auth/internal/app/user/application/service.go.hbs

@@ -118,6 +118,10 @@ func (s *Service) SetRole(ctx context.Context, userID uuid.UUID, roleCode string
 // ServicePort is the inbound application boundary. HTTP, jobs, and future
 // transports depend on this capability set instead of the concrete service.
 type ServicePort interface {
+	ListIdentities(context.Context, uuid.UUID) ([]IdentityResponse, error)
+	BeginIdentityLink(context.Context, uuid.UUID, string, LoginStartInput) (*Authorization, error)
+	ExchangeIdentityLink(context.Context, uuid.UUID, string, LoginExchangeInput) (*IdentityResponse, error)
+	UnlinkIdentity(context.Context, uuid.UUID, string) error
 	// go-scaffold:service-interface
 	Register(context.Context, RegisterInput) (*AuthResult, error)
 	Login(context.Context, LoginInput) (*AuthResult, error)

package/templates/add/auth/internal/app/user/application/service_test.go.hbs

@@ -334,6 +334,7 @@ func (f *fakeMFAStore) ConsumeRecoveryCode(_ context.Context, userID uuid.UUID,
 type fakeRepo struct {
 	user              *domain.User
 	identity          *domain.Identity
+	identities        []domain.Identity
 	updateIdentityErr error
 	updateUserErr     error
 	failures          map[string]int
@@ -387,20 +388,61 @@ func (f *fakeRepo) UpdateUser(_ context.Context, u *domain.User) error {
 	return nil
 }
 func (f *fakeRepo) FindAll(context.Context, int, int) ([]domain.User, error) { return nil, nil }
-func (f *fakeRepo) FindIdentity(_ context.Context, userID uuid.UUID, _ domain.Provider) (*domain.Identity, error) {
-	if f.identity != nil && f.identity.UserID == userID {
+
+func (f *fakeRepo) FindIdentity(_ context.Context, userID uuid.UUID, provider domain.Provider) (*domain.Identity, error) {
+	for i := range f.identities {
+		if f.identities[i].UserID == userID && f.identities[i].Provider == provider {
+			copy := f.identities[i]
+			return &copy, nil
+		}
+	}
+	if f.identity != nil && f.identity.UserID == userID && f.identity.Provider == provider {
 		copy := *f.identity
 		return &copy, nil
 	}
 	return nil, domain.ErrNotFound
 }
-func (f *fakeRepo) FindIdentityByProviderUID(context.Context, domain.Provider, string) (*domain.Identity, error) {
+func (f *fakeRepo) ListIdentities(_ context.Context, userID uuid.UUID) ([]domain.Identity, error) {
+	out := make([]domain.Identity, 0, len(f.identities)+1)
+	for _, identity := range f.identities {
+		if identity.UserID == userID {
+			out = append(out, identity)
+		}
+	}
+	if f.identity != nil && f.identity.UserID == userID {
+		found := false
+		for _, identity := range out {
+			if identity.ID == f.identity.ID {
+				found = true
+				break
+			}
+		}
+		if !found {
+			out = append(out, *f.identity)
+		}
+	}
+	return out, nil
+}
+func (f *fakeRepo) FindIdentityByProviderUID(_ context.Context, provider domain.Provider, providerUID string) (*domain.Identity, error) {
+	for i := range f.identities {
+		if f.identities[i].Provider == provider && f.identities[i].ProviderUID != nil && *f.identities[i].ProviderUID == providerUID {
+			copy := f.identities[i]
+			return &copy, nil
+		}
+	}
+	if f.identity != nil && f.identity.Provider == provider && f.identity.ProviderUID != nil && *f.identity.ProviderUID == providerUID {
+		copy := *f.identity
+		return &copy, nil
+	}
 	return nil, domain.ErrNotFound
 }
 func (f *fakeRepo) CreateUserWithIdentity(context.Context, *domain.User, *domain.Identity) error {
 	return nil
 }
-func (f *fakeRepo) CreateIdentity(context.Context, *domain.Identity) error { return nil }
+func (f *fakeRepo) CreateIdentity(_ context.Context, identity *domain.Identity) error {
+	f.identities = append(f.identities, *identity)
+	return nil
+}
 func (f *fakeRepo) UpdateIdentity(_ context.Context, i *domain.Identity) error {
 	if f.updateIdentityErr != nil {
 		return f.updateIdentityErr
@@ -408,6 +450,35 @@ func (f *fakeRepo) UpdateIdentity(_ context.Context, i *domain.Identity) error {
 	f.identity = i
 	return nil
 }
+func (f *fakeRepo) DeleteIdentity(_ context.Context, userID uuid.UUID, provider domain.Provider) error {
+	count := 0
+	target := -1
+	for i := range f.identities {
+		if f.identities[i].UserID != userID {
+			continue
+		}
+		count++
+		if f.identities[i].Provider == provider {
+			target = i
+		}
+	}
+	legacyTarget := f.identity != nil && f.identity.UserID == userID && f.identity.Provider == provider
+	if legacyTarget {
+		count++
+	}
+	if target < 0 && !legacyTarget {
+		return domain.ErrNotFound
+	}
+	if count <= 1 {
+		return domain.ErrLastIdentity
+	}
+	if target >= 0 {
+		f.identities = append(f.identities[:target], f.identities[target+1:]...)
+	} else {
+		f.identity = nil
+	}
+	return nil
+}
 
 // go-scaffold:user-fake-repo-methods
 // go-scaffold:repository-stub-methods

package/templates/add/auth/internal/app/user/domain/errors.go.hbs

@@ -15,7 +15,9 @@ var (
 	ErrMFAAlreadyEnabled = errors.New("MFA is already enabled")
 	ErrMFANotEnrolled    = errors.New("MFA is not enrolled")
 	ErrMFASetupRequired  = errors.New("MFA setup is required")
-	ErrUnknownRole       = errors.New("unknown role")
+	ErrUnknownRole           = errors.New("unknown role")
+	ErrIdentityAlreadyLinked = errors.New("login identity is already linked")
+	ErrLastIdentity          = errors.New("cannot remove the last login identity")
 )
 
 type RuleError struct {

package/templates/add/auth/internal/app/user/ports/repository.go.hbs

@@ -16,10 +16,12 @@ type UserRepository interface {
 	UpdateUser(context.Context, *domain.User) error
 	FindAll(context.Context, int, int) ([]domain.User, error)
 	FindIdentity(context.Context, uuid.UUID, domain.Provider) (*domain.Identity, error)
+	ListIdentities(context.Context, uuid.UUID) ([]domain.Identity, error)
 	FindIdentityByProviderUID(context.Context, domain.Provider, string) (*domain.Identity, error)
 	CreateUserWithIdentity(context.Context, *domain.User, *domain.Identity) error
 	CreateIdentity(context.Context, *domain.Identity) error
 	UpdateIdentity(context.Context, *domain.Identity) error
+	DeleteIdentity(context.Context, uuid.UUID, domain.Provider) error
 	LoginLockedUntil(context.Context, string) (time.Time, error)
 	RecordLoginFailure(context.Context, string, int, time.Duration) error
 	ClearLoginFailures(context.Context, string) error
@@ -65,6 +67,7 @@ type RefreshTokenStore interface {
 
 type LoginTransaction struct {
 	Provider      string    `json:"provider"`
+	UserID        uuid.UUID `json:"user_id"`
 	CodeChallenge string    `json:"code_challenge"`
 	Nonce         string    `json:"nonce"`
 	ExpiresAt     time.Time `json:"expires_at"`

package/templates/create/base/.claude/skills/go-scaffold/SKILL.md.hbs

@@ -260,6 +260,15 @@ boundary. For browser OAuth, preserve this client-owned callback contract:
   `Pragma: no-cache`.
   Never accept a request-supplied redirect destination or place an access token,
   refresh token, authorization code, or state in a URI.
+- Authenticated identity management is a separate account flow, not another
+  login endpoint: list safe metadata at `GET /users/me/identities`, start and
+  finish linking at `POST /users/me/identities/:provider/link` and
+  `POST /users/me/identities/:provider/link/exchange`, and unlink with
+  `DELETE /users/me/identities/:provider`. Bind the server-side transaction to
+  the caller's user ID, never issue or replace a session during link exchange,
+  keep one identity per provider per user, and reject unlinking the last login
+  method. Provider subjects and password hashes must never cross the HTTP
+  boundary.
 - Map provider and validation failures to controlled public codes only:
   `oauth_denied`, `oauth_state_invalid`, `oauth_provider_unavailable`, and
   `oauth_failed`. Do not expose raw provider descriptions or technical causes.

package/templates/create/base/AGENTS.md.hbs

@@ -186,6 +186,14 @@ approval before changing their contract.
   rotation; responses expose only User-Agent and lifecycle timestamps, never
   refresh tokens or token hashes. The current access token carries the session
   ID as `sid` so the adapter can mark the current device.
+- Authenticated users can manage login identities through
+  `GET /users/me/identities`, `POST /users/me/identities/:provider/link`,
+  `POST /users/me/identities/:provider/link/exchange`, and
+  `DELETE /users/me/identities/:provider`. The link transaction is bound to
+  the current user as well as provider/state/PKCE/nonce; it can never create a
+  session or silently move a provider account between users. Return only safe
+  provider metadata, allow at most one identity per provider per user, and
+  refuse to unlink the last remaining login method.
 - Password reset and email verification consume a one-time token in the same
   retry-safe transaction as the user/identity update. A failed post-commit
   session revocation must not make a successful reset impossible to retry.

package/templates/create/base/README.md.hbs

@@ -198,6 +198,11 @@ Authenticated users can list active device sessions with
 `GET /users/me/sessions` and revoke an individual session with
 `DELETE /users/me/sessions/:id`; only User-Agent and session lifecycle
 timestamps are returned.
+They can also list safe login-provider metadata with
+`GET /users/me/identities`, link a provider through the authenticated
+`/users/me/identities/:provider/link` start/exchange flow, and unlink a
+provider with `DELETE /users/me/identities/:provider`; the last login method
+cannot be removed.
 For `cross-site`, configure HTTPS origins, `COOKIE_SAMESITE=none`,
 `COOKIE_SECURE=true`, and an exact allowed Origin; the API applies an Origin
 guard independently of CORS.

package/templates/create/features/docs/architecture.md.hbs

@@ -60,7 +60,7 @@ internal/
 ```
 
 Installed process and platform additions:
-{{#if auth}}- `cmd/seed` and `platform/authprovider/google/` for user bootstrap and Google OAuth/OIDC
+{{#if auth}}- `cmd/seed` and `platform/authprovider/google/` for user bootstrap, Google OAuth/OIDC login, and authenticated identity linking
 {{/if}}{{#if worker}}- `cmd/worker` and `platform/{mail,queue}/` for queue/SMTP jobs{{#if (eq queue "asynq")}}, plus `platform/cache/` for Redis{{/if}}
 {{/if}}{{#if observability}}- `platform/telemetry/` for the OTLP exporter
 {{/if}}{{#if rbac}}- `shared/middleware/authz.go` and `app/role/` for RBAC policy
@@ -73,10 +73,10 @@ a real external system.
 add a `shared/utils` or similarly generic package — name it after what it
 actually does.
 
-Optional feature boundaries are explicit: auth owns user authentication and
-provider ports; RBAC owns role policy and authorization; worker owns queue and
-mail adapters; observability owns metrics/tracing setup. They do not create a
-second domain architecture.
+Optional feature boundaries are explicit: auth owns user authentication,
+identity linking, and provider ports; RBAC owns role policy and authorization;
+worker owns queue and mail adapters; observability owns metrics/tracing setup.
+They do not create a second domain architecture.
 
 ## 3. API Style
 

package/templates/create/features/docs/techstack.md.hbs

@@ -15,7 +15,7 @@
 | Logging | `log/slog`, JSON handler |
 | Migrations | [golang-migrate](https://github.com/golang-migrate/migrate) |
 | Testing | stdlib `testing`, real Postgres for integration tests |
-| Authentication | {{#if auth}}JWT access/refresh sessions, password recovery, email verification, provider login, and MFA{{else}}optional via `go-scaffold add auth`{{/if}} |
+| Authentication | {{#if auth}}JWT access/refresh sessions, password recovery, email verification, provider login/linking, and MFA{{else}}optional via `go-scaffold add auth`{{/if}} |
 | Authorization | {{#if rbac}}RBAC role/permission middleware{{else}}optional RBAC via `go-scaffold add rbac`{{/if}} |
 | Background jobs | {{#if worker}}{{queue}} queue backend with SMTP mail and `cmd/worker`{{else}}optional via `go-scaffold add worker`{{/if}} |