# auth

`auth` 只定义身份和权限边界，不把 JWT、Session、OAuth 或某个用户表绑定到核心框架。

## 核心用法

认证器把外部凭据转换成通用身份：

```go
type Authenticator interface {
    Authenticate(context.Context, string) (Principal, error)
}
```

把认证放在路由组上：

```go
private := app.Group("/api", auth.RequireAuth(authenticator))
private.GET("/me", getMe)

admin := private.Group("/admin", auth.RequireRole("admin"))
admin.POST("/users", createUser)
```

Handler 可以读取身份，但不需要知道 Token 的格式：

```go
principal, ok := auth.FromContext(ctx)
if !ok {
    return omni.Unauthorized("UNAUTHENTICATED", "authentication is required")
}
```

认证失败统一返回 `401 UNAUTHENTICATED`，身份存在但角色不满足统一返回 `403 FORBIDDEN`。无效 Token 的详细原因保留在错误链中，不出现在 HTTP 响应里。

`StaticAuthenticator` 只用于本地开发和测试，不能作为生产认证方案。生产项目实现 `Authenticator`，在实现内部校验 JWT、Session 或其他凭据，并返回 `Principal`。