Skip to content

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

ts
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çãoPapel
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.

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.

ts
signJwt(claims: Record<string, unknown>, options: SignOptions): Promise<string>

SignOptions:

CampoTipoEfeito
secretstringchave de assinatura (obrigatório)
alg?JwtAlgorithmalgoritmo de assinatura. Padrão 'HS256'
expiresInSeconds?numberdefine exp = iat + expiresInSeconds
notBeforeSeconds?numberdefine nbf = iat + notBeforeSeconds
issuer?stringdefine o claim iss
audience?stringdefine o claim aud
subject?stringdefine o claim sub

JwtAlgorithm é HS256/384/512, RS256/384/512, PS256/384/512, ES256/384/512 ou EdDSA.

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

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

ts
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:

ts
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, aud ou not-before → invalid_token
  • um token expirado → expired
  • um payload que falha no schema Zod → claims_mismatch (carregando issues estruturados)

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 ​

ts
// 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.registry

2. Conecte o jwtAuth ​

ts
// 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:

CampoTipoEfeito
secretstringchave de verificação (obrigatório)
claimsz.ZodTypeAnyschema que o payload deve satisfazer (obrigatório)
slot?stringscoped slot a preencher. Padrão 'currentUser'
alg?JwtAlgorithmalgoritmo esperado. Padrão 'HS256'
issuer?stringquando definido, exige este iss
audience?stringquando definido, exige este aud
header?stringheader de onde ler o token. Padrão 'authorization'
resolve?(claims, c) => usermapeia 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:

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

ts
// 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çãoerrormessage
header Authorization ausente / malformadounauthorizedMissing bearer token
assinatura inválida, alg errado, expiradounauthorizedInvalid or expired token
payload falha em claimsunauthorizedToken claims did not match (com issues.claims)
resolve retorna null / undefinedunauthorizedNo such user

Inválido e expirado colapsam em uma única mensagem propositalmente: o endpoint nunca é um oráculo de validade.

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

ts
// 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:

ts
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 ​

ts
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:

http
GET /admin/metrics
Authorization: Bearer <token for a non-admin>
→ 403  { "error": "forbidden", "message": "Insufficient permissions" }

requireClaim ​

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

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

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

ts
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/token do 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 por claims.sub do 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. signJwt produz 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/jwk via fromHono, ou chame uma biblioteca como jose em 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 declara provides: ['currentUser'], então o harness consegue provar que nenhuma route lê currentUser sem um middleware de auth em sua cadeia — a regra kata/scoped-slot-not-provided.
  • Falha explícita. jwtAuth curto-circuita com um Response em qualquer falha; ele não pode passar adiante e deixar o slot sem preencher.

Veja também ​

Código aberto — licença a definir. Feito com Hono + Zod.