csrf

Overview ¶

Package csrf provides CSRF (Cross-Site Request Forgery) protection middleware for Hertz.

It implements the Double Submit Cookie pattern using HMAC-SHA256. Cookies are session-level and automatically cleared when the browser closes.

Hertz Backend Setup ¶

// Initialize CSRF protection
csrfProtect := csrf.New(
	csrf.SetKey("your-secret-key-at-least-32-bytes"),
	csrf.SetDomain("example.com"),
)

// CSRF token endpoint (called on first page load)
h.GET("/csrf-token", func(ctx context.Context, c *app.RequestContext) {
	csrfProtect.SetToken(c)
	c.JSON(200, utils.H{"message": "ok"})
})

// Login endpoint (refresh CSRF token after login for security)
h.POST("/auth/login", func(ctx context.Context, c *app.RequestContext) {
	// ... validate credentials ...
	csrfProtect.SetToken(c) // Refresh CSRF token
	c.JSON(200, utils.H{"accessToken": token})
})

// Protect API routes with CSRF middleware
api := h.Group("/api", csrfProtect.VerifyToken())
api.POST("/submit", submitHandler)
api.PUT("/update", updateHandler)
api.DELETE("/remove", removeHandler)

Angular Frontend Setup ¶

Angular has built-in XSRF support that works with default cookie/header names.

1. Configure HttpClient in app.config.ts:

import { provideHttpClient, withXsrfConfiguration } from '@angular/common/http';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withXsrfConfiguration({
        cookieName: 'XSRF-TOKEN',  // Must match backend default
        headerName: 'X-XSRF-TOKEN' // Must match backend default
      })
    )
  ]
};

2. Create CSRF service:

@Injectable({ providedIn: 'root' })
export class CsrfService {
  constructor(private http: HttpClient) {}

  initToken(): Observable<void> {
    return this.http.get<void>('/csrf-token', { withCredentials: true });
  }
}

3. Get CSRF token on app initialization (app.component.ts):

export class AppComponent implements OnInit {
  constructor(private csrfService: CsrfService) {}

  ngOnInit() {
    this.csrfService.initToken().subscribe();
  }
}

4. Refresh CSRF token after login (recommended):

login(credentials: LoginRequest) {
  return this.http.post<LoginResponse>('/auth/login', credentials, {
    withCredentials: true
  }).pipe(
    tap(res => localStorage.setItem('token', res.accessToken))
    // CSRF cookie is refreshed automatically by backend
  );
}

5. Ensure all HTTP requests include credentials:

this.http.post('/api/submit', data, { withCredentials: true })

Security Notes ¶

• Cookies are session-level (cleared when browser closes)
• XSRF-TOKEN cookie is readable by JavaScript (HttpOnly=false)
• XSRF-SALT cookie is HttpOnly=true for additional security
• Both cookies use SameSite=Strict to prevent cross-site requests
• Refresh CSRF token after login to prevent pre-auth token theft
• Always use HTTPS in production