Autenticação JWT
Um JWT (JSON Web Token) é uma string compacta e assinada que carrega um conjunto de claims — fatos sobre quem chama, como "id de usuário 42, email ada@…". Como ele é assinado com um secret que apenas o seu servidor conhece, o servidor pode confiar nesses claims após uma verificação de assinatura barata — sem sessão no banco, sem round-trip no banco de dados.
@katajs-framework/core/jwt entrega os blocos de construção para esse fluxo, para que você não tenha que escrever um verificador na mão: assinar um token, verificá-lo, autenticar uma requisição em um scoped slot e autorizar esse slot com guards. Não adiciona nenhuma dependência nova — @katajs-framework/core/jwt é um subpath tree-shakeable construído sobre hono/jwt, e hono já é uma peer dependency (ADR-0013).
import {
signJwt,
verifyJwt,
jwtAuth,
guard,
requireRole,
requireClaim,
} from '@katajs-framework/core/jwt'Tudo aqui é uma função. Sem classes, sem decorators, sem container de IoC. Um token inválido ou expirado é um resultado normal, não uma exceção — por isso o verifyJwt retorna um Result, e o jwtAuth renderiza o envelope de erro unificado em vez de lançar.
O que o Kata NÃO entrega
Login, hashing de senha, o armazenamento de usuários, rotação de refresh-token, sessões e provedores remotos de JWKS / OIDC (Auth0, Cognito, Clerk) são seus. @katajs-framework/core/jwt é a costura de verificar-e-autorizar; o modelo de credencial e identidade é BYO. Veja O que é seu abaixo.
As quatro peças
| Função | Papel |
|---|---|
signJwt(claims, opts) | assina um objeto de claims em um JWT compacto |
verifyJwt(token, opts) | verifica + faz parse Zod de um token → um Result (nunca lança) |
jwtAuth(opts) | um handler de middleware que autentica uma requisição e preenche um scoped slot |
guard(opts) / requireRole(...) / requireClaim(...) | handlers de middleware que autorizam (403) |
signJwt e verifyJwt são as primitivas stateless — elas não sabem nada sobre o context do Kata. jwtAuth e os guards são a camada que conhece o Kata: eles retornam um handler de middleware (não um middleware completo), então você mantém o wrapper defineMiddleware({ provides: [...] }) no ponto de chamada, onde o sistema de tipos e o lint conseguem lê-lo.
Descreva os claims
Um payload de JWT é dado sem tipo até você validá-lo. Declare um schema Zod para os claims que você espera; jwtAuth faz parse de todo token decodificado por ele, de modo que um payload controlado por um atacante nunca chega a um handler como um blob sem tipo (o tipo any é proibido). Schemas ficam em <domain>.schema.ts.
// src/modules/users/users.schema.ts
import { z } from 'zod'
// `sub` é o claim padrão de subject do JWT (o id do usuário); `name`/`email`
// seguem junto como claims extras. Claims registrados como `iat`/`exp` são
// removidos por este object schema.
export const UserClaimsSchema = z.object({
sub: z.string().min(1),
name: z.string().min(1),
email: z.string().email(),
})
export type UserClaims = z.infer<typeof UserClaimsSchema>Sem um domínio users dedicado? Coloque os claims junto
Nem todo app tem um domínio users. Quando o único conceito de identidade é uma identidade mínima de login/posse — sem CRUD de usuário, sem um módulo users dedicado — não crie um só para guardar um tipo. Declare User e UserClaimsSchema no arquivo de schema do módulo que já possui a rota de emissão do token, por exemplo src/modules/auth/auth.schema.ts. Este é um layout suportado e endossado, não uma solução alternativa: tudo mais nesta página (o scoped slot, jwtAuth, resolve) funciona sem mudanças — só o caminho de import de User/UserClaimsSchema muda.
Assine um token: signJwt
signJwt é um wrapper funcional fino sobre o sign do hono/jwt. Ele sempre carimba iat (issued-at = agora). As opções de claims registrados abaixo derivam seus claims e sobrescrevem qualquer chave de mesmo nome no primeiro argumento.
signJwt(claims: Record<string, unknown>, options: SignOptions): Promise<string>SignOptions:
| Campo | Tipo | Efeito |
|---|---|---|
secret | string | chave de assinatura (obrigatório) |
alg? | JwtAlgorithm | algoritmo de assinatura. Padrão 'HS256' |
expiresInSeconds? | number | define exp = iat + expiresInSeconds |
notBeforeSeconds? | number | define nbf = iat + notBeforeSeconds |
issuer? | string | define o claim iss |
audience? | string | define o claim aud |
subject? | string | define o claim sub |
JwtAlgorithm é HS256/384/512, RS256/384/512, PS256/384/512, ES256/384/512 ou EdDSA.
// src/modules/auth/auth.route.ts
import { signJwt } from '@katajs-framework/core/jwt'
import { JWT_SECRET, TOKEN_TTL_SECONDS } from '../../config'
import { defineRoute } from '../../context'
import { TokenRequestSchema, TokenResponseSchema } from './auth.schema'
export const mintTokenRoute = defineRoute({
method: 'POST',
path: '/auth/token',
input: { body: TokenRequestSchema }, // { id, name, email }
output: TokenResponseSchema, // { token }
handler: async (c) => {
const { id, name, email } = c.input.body
const token = await signJwt(
{ name, email },
{ secret: JWT_SECRET, subject: id, expiresInSeconds: TOKEN_TTL_SECONDS },
)
return { token }
},
})signJwt só rejeita em uma chave ou algoritmo mal configurados — um erro de programação sem nenhum branch tratado pelo chamador. Essa é a assimetria deliberada com verifyJwt, que retorna um Result.
Isto não é login
Essa route confia em quem a chama, então não é assim que você autentica usuários reais — ela existe para que o exemplo (e sua suíte Hurl) consiga obter um token sem ferramentas externas. Um endpoint de produção verifica as credenciais (ou um código OAuth) antes de assinar. Veja O que é seu.
Verifique um token: verifyJwt
verifyJwt checa a assinatura e os claims de tempo (e iss / aud quando informados) via hono/jwt, depois faz parse do payload pelo seu schema de claims. Ele retorna um Result discriminado — nunca lança.
verifyJwt<S extends z.ZodTypeAny>(
token: string,
options: VerifyOptions<S>,
): Promise<JwtVerifyResult<z.infer<S>>>VerifyOptions recebe secret, claims (o schema; seu z.infer é o tipo de sucesso) e os opcionais alg (padrão 'HS256'), issuer e audience. Quando issuer / audience estão definidos, o claim correspondente é obrigatório.
const result = await verifyJwt(token, {
secret: JWT_SECRET,
claims: UserClaimsSchema,
})
if (result.ok) {
result.claims // UserClaims tipado
} else {
result.error.code // 'invalid_token' | 'expired' | 'claims_mismatch'
}O formato do erro:
type JwtErrorCode = 'invalid_token' | 'expired' | 'claims_mismatch'
type JwtError = {
readonly code: JwtErrorCode
readonly message: string
// presente apenas em 'claims_mismatch' — o mesmo formato FieldIssue[] do
// envelope de erro de validação
readonly issues?: FieldIssue[]
}Três baldes, para que quem chama sempre saiba qual tipo de falha ocorreu:
- uma falha de assinatura, estrutura, algoritmo,
iss,audou not-before →invalid_token - um token expirado →
expired - um payload que falha no schema Zod →
claims_mismatch(carregandoissuesestruturados)
Você raramente chama verifyJwt diretamente no código de uma route — jwtAuth o envolve. Recorra a ele quando verificar um token fora da cadeia de middleware da requisição (um background job, um upgrade de websocket, um CLI).
Autentique uma requisição: jwtAuth
jwtAuth é a camada que conhece o Kata sobre o verifyJwt. Ele lê Authorization: Bearer <token>, verifica e escreve o resultado em um scoped slot. Ele retorna um handler de middleware — você é dono do wrapper defineMiddleware({ provides: [...] }), então o literal provides fica grepável e verificável pelo lint no ponto de chamada.
1. Declare o slot
// src/context.ts
import { defineContext, scoped, singleton } from '@katajs-framework/core'
import type { User } from './modules/users/users.schema'
export const k = defineContext({
logger: singleton(logger),
currentUser: scoped<User>(), // um User por requisição
})
export const { defineRoute, defineMiddleware, createApp } = k
export type AppRegistry = typeof k.registry2. Conecte o jwtAuth
// src/middlewares/auth.ts
import { jwtAuth } from '@katajs-framework/core/jwt'
import { JWT_SECRET } from '../config'
import { defineMiddleware } from '../context'
import { type User, UserClaimsSchema } from '../modules/users/users.schema'
export const requireUser = defineMiddleware({
provides: ['currentUser'] as const,
handler: jwtAuth({
secret: JWT_SECRET,
claims: UserClaimsSchema,
// claims → User. Em um app real: carregue do seu store por claims.sub.
resolve: (claims): User => ({ id: claims.sub, name: claims.name, email: claims.email }),
}),
})provides: ['currentUser'] as const é estrutural. O as const preserva a chave literal para que o sistema de tipos e a regra de lint kata/jwt-auth-provides-slot possam verificar que um middleware jwtAuth({ slot }) declara o slot que ele preenche. Como o jwtAuth faz seu c.set internamente, a regra genérica kata/middleware-provides-mismatch não consegue ver essa atribuição — então kata/jwt-auth-provides-slot (ADR-0013) é a regra que checa a ligação do slot aqui.
JwtAuthOptions:
| Campo | Tipo | Efeito |
|---|---|---|
secret | string | chave de verificação (obrigatório) |
claims | z.ZodTypeAny | schema que o payload deve satisfazer (obrigatório) |
slot? | string | scoped slot a preencher. Padrão 'currentUser' |
alg? | JwtAlgorithm | algoritmo esperado. Padrão 'HS256' |
issuer? | string | quando definido, exige este iss |
audience? | string | quando definido, exige este aud |
header? | string | header de onde ler o token. Padrão 'authorization' |
resolve? | (claims, c) => user | mapeia claims → o valor armazenado no slot |
O hook resolve
Sem resolve, o slot guarda os claims validados pelo Zod literalmente. Com resolve, ele guarda o que você retornar — e o tipo do slot passa a ser esse valor, não z.infer<claims>. Ele roda depois da validação dos claims e recebe o context do middleware como segundo argumento, então pode ser async:
handler: jwtAuth({
secret: JWT_SECRET,
claims: UserClaimsSchema,
resolve: async (claims, c) => c.get('db').users.findById(claims.sub),
})Essa é a costura onde um app real carrega o usuário completo do seu store por claims.sub. Retornar null ou undefined significa "token válido, mas não existe tal usuário" e renderiza um 401 — distinto de um 403, que é uma decisão de autorização que um guard toma.
Mantenha segredos fora do slot
resolve decide o que cai no slot. Retorne seu User; nunca o token bruto ou o secret de assinatura.
3. Consuma o slot em uma route
Uma route adere via use: [...]. Uma vez que requireUser tenha rodado, c.get('currentUser') retorna o valor tipado de forma síncrona.
// src/modules/users/users.route.ts
import { defineRoute } from '../../context'
import { requireUser } from '../../middlewares/auth'
import { UserSchema } from './users.schema'
export const meRoute = defineRoute({
method: 'GET',
path: '/me',
use: [requireUser],
input: {},
output: UserSchema,
handler: async (c) => c.get('currentUser'),
})Falhas de autenticação (401)
Toda falha de autenticação curto-circuita a cadeia com o envelope de erro unificado como um 401 — o handler nunca roda:
| Situação | error | message |
|---|---|---|
header Authorization ausente / malformado | unauthorized | Missing bearer token |
| assinatura inválida, alg errado, expirado | unauthorized | Invalid or expired token |
payload falha em claims | unauthorized | Token claims did not match (com issues.claims) |
resolve retorna null / undefined | unauthorized | No such user |
Inválido e expirado colapsam em uma única mensagem propositalmente: o endpoint nunca é um oráculo de validade.
GET /me
→ 401 { "error": "unauthorized", "message": "Missing bearer token" }
GET /me
Authorization: Bearer eyJhbGc…
→ 200 { "id": "42", "name": "Ada", "email": "ada@example.com" }
GET /me
Authorization: Bearer not-a-real-jwt
→ 401 { "error": "unauthorized", "message": "Invalid or expired token" }Autorize: guards (403)
A autenticação prova quem você é; a autorização decide o que você pode fazer. Um guard lê um scoped slot que ele não provê e rejeita com um 403 quando seu predicado diz não. requireRole, requireClaim e guard retornam todos um handler puro — não um Middleware<R> — então, exatamente como o guard abaixo, quem chama envolve com defineMiddleware({ provides: [] as const, handler }). A ordem no array use: é o contrato: o guard precisa vir depois do middleware que preenche o slot.
// em uma route — requireUser PRECISA vir antes do guard
import { requireRole } from '@katajs-framework/core/jwt'
const requireAdmin = defineMiddleware({
provides: [] as const,
handler: requireRole<AppRegistry>('admin'),
})
export const adminRoute = defineRoute({
method: 'GET',
path: '/admin/metrics',
use: [requireUser, requireAdmin], // 401 se não autenticado, 403 se não for admin
input: {},
output: MetricsSchema,
handler: async (c) => collectMetrics(),
})Faça o guard sobre um campo, então estenda seus claims (e o tipo do slot) com ele:
export const UserClaimsSchema = z.object({
sub: z.string().min(1),
name: z.string().min(1),
email: z.string().email(),
role: z.enum(['user', 'admin']),
})requireRole
requireRole<R, S>(role: string | readonly string[], options?: { slot?: S })Permite apenas quando o role do valor do slot é (um dos) role. Lê o slot padrão currentUser. S — a chave do slot — é inferido de options.slot (ou usa o padrão 'currentUser') e checado contra o registry de R, exatamente como o guard abaixo. Um não-admin recebe:
GET /admin/metrics
Authorization: Bearer <token for a non-admin>
→ 403 { "error": "forbidden", "message": "Insufficient permissions" }requireClaim
requireClaim<R, S>(
key: string,
expected: unknown | ((value: unknown) => boolean),
options?: { slot?: S },
)Permite apenas quando o claim do valor do slot em key casa com expected — por igualdade estrita, ou por predicado quando expected é uma função.
import { requireClaim } from '@katajs-framework/core/jwt'
// exige um email verificado
const requireVerified = defineMiddleware({
provides: [] as const,
handler: requireClaim('email_verified', true),
})
// ou com um predicado
const requirePaidPlan = defineMiddleware({
provides: [] as const,
handler: requireClaim('plan', (v) => v === 'pro' || v === 'team'),
})guard
A forma geral. Forneça qualquer predicado sobre o valor do slot; ele pode ser async e recebe o context do middleware como segundo argumento.
guard<R, S extends ScopedKeys<R> = 'currentUser'>(options: GuardOptions<R, S>)GuardOptions: authorize (o predicado, obrigatório), slot? (padrão 'currentUser'), code? (padrão 'forbidden') e message? (padrão 'Insufficient permissions').
slot é genérico sobre R: o parâmetro de authorize é inferido como o tipo real do slot que ele nomeia — você só fornece R explicitamente, nunca um segundo argumento de tipo para o tipo dos claims.
import { guard } from '@katajs-framework/core/jwt'
// Apenas o dono do recurso pode lê-lo.
const requireOwner = defineMiddleware({
provides: [] as const,
handler: guard<AppRegistry>({
authorize: (user, c) => user.id === c.raw.req.param('id'),
code: 'forbidden',
message: 'Not your resource',
}),
})requireRole e requireClaim são açúcar fino sobre guard.
Mudança incompatível: slot agora é checado contra o registry
Antes, guard<R, C>({ slot, authorize }) recebia slot como uma string pura e C como uma asserção não verificada do que ele guardava — guard({ slot: 'currentOrg', authorize: (m: Membership) => m.role === 'owner' }) compilava mesmo com currentOrg guardando um Org, e em vez disso respondia 403 a toda requisição em runtime. slot agora é S extends ScopedKeys<R> e o parâmetro de authorize é derivado do próprio R, então essa chamada é um erro de tsc. Remova qualquer segundo argumento de tipo explícito que você passava a guard / requireRole / requireClaim — ele agora é inferido, e passar o antigo tipo dos claims ali não compila contra a nova constraint S extends ScopedKeys<R>.
O que é seu
@katajs-framework/core/jwt para deliberadamente na fronteira de verificar-e-autorizar. O modelo de credencial e identidade é BYO:
- Login. Verifique as credenciais (ou um código OAuth) na sua própria route, então chame
signJwt. O/auth/tokendo exemplo confia em quem o chama e é um substituto, não um login. - Hashing de senha. O Kata não entrega hashing. Use uma biblioteca confiável (argon2, bcrypt, scrypt) na sua camada de service.
- Armazenamento de usuários.
resolveé a costura para carregar um usuário porclaims.subdo seu banco de dados. O Kata não fornece um. - Refresh tokens. Rotação, listas de revogação e armazenamento de refresh-token são seus.
signJwtproduz um access token stateless; tudo o que é stateful ao redor dele é código do app. - JWKS / OIDC remoto. Auth0, Cognito, Clerk e verificação via JWKS ficam além da fronteira framework-vs-BYO da v0.3. Monte
hono/jwkviafromHono, ou chame uma biblioteca comojoseem um verify customizado (ADR-0013).
Por que um scoped slot, não um global
- Isolamento por requisição. Um global de módulo vazaria o usuário de uma requisição para a próxima sob concorrência. Um scoped slot é armazenado por requisição.
- Verificável estaticamente. Toda leitura é
c.get('currentUser')e todo provedor declaraprovides: ['currentUser'], então o harness consegue provar que nenhuma route lêcurrentUsersem um middleware de auth em sua cadeia — a regrakata/scoped-slot-not-provided. - Falha explícita.
jwtAuthcurto-circuita com umResponseem qualquer falha; ele não pode passar adiante e deixar o slot sem preencher.
Veja também
- Receita de auth — o passo a passo de ponta a ponta que esta página condensa.
- Referência de
@katajs-framework/core/jwt— assinaturas completas. - Middleware & scoped slots — como
provideseuse:se compõem. - Erros — o envelope de erro unificado que os guards e o
jwtAuthrenderizam. - ADR-0013 — por que
hono/jwt, por que um subpath, a fronteira BYO.