@kura-iam/bff-kit

Fundacao Hono para BFFs que ficam na frente de APIs protegidas pelo Internal Auth IDP.

O pacote usa @kura-iam/service-sdk por baixo e entrega uma estrutura pequena:

• createBffApp: Hono app com secure headers, CORS opcional, request id e contexto auth;
• createAuthMiddleware: valida Authorization: Bearer <token> e opcionalmente uma permissao;
• createOriginGuard: bloqueia mutacoes vindas de origins nao confiaveis;
• createServiceProxy: proxy para upstreams usando client_credentials.

Requisitos

• Node.js 20 ou superior.
• Hono.
• Um client service cadastrado no IdP para o BFF chamar APIs internas.
• Resource servers cadastrados com audiences especificas por API.

Exemplo

import {
  createBffApp,
  createOriginGuard,
  createServiceProxy,
} from "@kura-iam/bff-kit"

const app = createBffApp({
  trustedOrigins: ["https://app.example.com"],
})

app.use(
  "/api/*",
  createOriginGuard({
    allowedOrigins: ["https://app.example.com"],
  }),
)

app.all(
  "/api/orders/*",
  createServiceProxy({
    pathPrefix: "/api/orders",
    upstreamBaseUrl: "https://orders.internal.example.com",
    serviceClient: {
      issuer: process.env.AUTH_ISSUER!,
      audience: "https://orders.internal.example.com",
      clientId: process.env.AUTH_CLIENT_ID!,
      clientSecret: process.env.AUTH_CLIENT_SECRET!,
    },
  }),
)

export default app

Uma chamada para /api/orders/v1/orders?status=open sera encaminhada para https://orders.internal.example.com/v1/orders?status=open com um token client_credentials do BFF.

Rotas protegidas por bearer

Quando o BFF receber bearer tokens diretamente, use o middleware de autenticacao:

import { createAuthMiddleware, createBffApp } from "@kura-iam/bff-kit"

const app = createBffApp()

app.use(
  "/api/me/*",
  createAuthMiddleware({
    issuer: process.env.AUTH_ISSUER!,
    audience: process.env.AUTH_AUDIENCE!,
    requiredPermission: "profile:read",
  }),
)

app.get("/api/me/profile", (c) => {
  return c.json({ subject: c.get("auth") })
})

Politica de seguranca

• createOriginGuard deve ser aplicado em rotas chamadas por browser antes de handlers mutaveis.
• Cada proxy deve usar uma audience especifica do upstream.
• Nao reutilize o mesmo client secret entre BFFs diferentes.
• Propague x-request-id para facilitar tracing entre BFF e APIs.

Escopo atual

Esta versao nao implementa sessao de browser, refresh token rotation, cookie vault ou CSRF token stateful. Esses pontos dependem da decisao de produto sobre como o BFF deve representar sessoes de usuario.

Quando essa politica for fechada, o proximo pacote/modulo deve adicionar:

• armazenamento server-side de sessao ou cookie criptografado;
• troca OAuth Authorization Code + PKCE para login browser;
• refresh token rotation;
• CSRF token pareado com cookie/session;
• logout coordenado entre BFF e IdP.

Publicacao

O publish deve acontecer via GitHub Actions com npm Trusted Publishing/OIDC, sem NPM_TOKEN. Configure o Trusted Publisher no npm com:

• provider: GitHub Actions;
• owner/repo: GabrielAlvesSantis/kura;
• workflow file: release.yml;
• environment: npm;
• access: public.

Antes de publicar:

pnpm --filter @kura-iam/bff-kit test
pnpm --filter @kura-iam/bff-kit check-types
pnpm --filter @kura-iam/bff-kit build
pnpm --filter @kura-iam/bff-kit pack --dry-run

Para publicar uma nova versao do BFF kit, faca merge na main, atualize a versao e crie uma tag de pacote:

git checkout main
git pull origin main
pnpm --filter @kura-iam/bff-kit version patch --no-git-tag-version
pnpm install --lockfile-only
git add packages/bff-kit/package.json pnpm-lock.yaml
git commit -m "chore: release bff-kit"
git tag bff-kit-v$(node -p "require('./packages/bff-kit/package.json').version")
git push origin main --tags

O workflow release.yml publica somente quando uma tag service-sdk-v*.*.*, bff-kit-v*.*.* ou packages-v*.*.* e enviada.