@kura-iam/service-sdk

SDK Node.js para micro-servicos que consomem o Internal Auth IDP.

Ele cobre dois casos:

• validar access tokens OIDC/JWT emitidos pelo IdP usando discovery e JWKS;
• obter tokens client_credentials para chamadas service-to-service.

Requisitos

• Node.js 20 ou superior.
• fetch, Request, Response e Headers globais disponiveis.
• Issuer HTTPS publico do IdP, normalmente https://auth.example.com/api/auth.
• Audience do resource server cadastrado no IdP.

Instalacao

pnpm add @kura-iam/service-sdk

O pacote deve ser publicado no registry npm da organizacao. Enquanto ele estiver sendo consumido por workspace, use a dependencia workspace:*.

Validar chamadas recebidas

import { authenticateRequest, authErrorResponse } from "@kura-iam/service-sdk"

const issuer = process.env.AUTH_ISSUER!
const audience = process.env.AUTH_AUDIENCE!

export async function handleRequest(request: Request) {
  try {
    const subject = await authenticateRequest(request, {
      issuer,
      audience,
      requiredPermission: "orders:read",
    })

    return Response.json({
      ok: true,
      subject,
    })
  } catch (error) {
    return authErrorResponse(error)
  }
}

authenticateRequest espera Authorization: Bearer <token>, valida assinatura, issuer, audience e, quando informado, a permissao exigida.

O retorno e um AuthSubject discriminado:

• kind: "service" para tokens client_credentials;
• kind: "user" para tokens de usuario.

Middleware com Hono

import { authenticateRequest, authErrorResponse } from "@kura-iam/service-sdk"
import { Hono } from "hono"

const app = new Hono()

app.use("/orders/*", async (c, next) => {
  try {
    const subject = await authenticateRequest(c.req.raw, {
      issuer: process.env.AUTH_ISSUER!,
      audience: process.env.AUTH_AUDIENCE!,
      requiredPermission: "orders:read",
    })

    c.set("auth", subject)
    await next()
  } catch (error) {
    return authErrorResponse(error)
  }
})

Chamar outro servico com client credentials

import { createServiceClient } from "@kura-iam/service-sdk"

const ordersClient = createServiceClient({
  issuer: process.env.AUTH_ISSUER!,
  audience: "https://orders.internal.example.com",
  clientId: process.env.AUTH_CLIENT_ID!,
  clientSecret: process.env.AUTH_CLIENT_SECRET!,
})

const response = await ordersClient.fetch("https://orders.internal.example.com/v1/orders")

O client faz discovery do token endpoint, solicita client_credentials, deduplica requisicoes concorrentes e renova o token antes da expiracao.

Permissoes

import { hasPermission, requirePermission } from "@kura-iam/service-sdk"

hasPermission(["orders:*"], "orders:write") // true
requirePermission(["orders:read"], "orders:read")

Sao suportados:

• permissao exata, como orders:read;
• wildcard global *;
• wildcard por recurso, como orders:*.

Configuracao recomendada por servico

AUTH_ISSUER=https://auth.example.com/api/auth
AUTH_AUDIENCE=https://orders.internal.example.com
AUTH_CLIENT_ID=...
AUTH_CLIENT_SECRET=...

Cada micro-servico deve validar tokens com a propria audience. Nao reutilize uma audience generica para APIs diferentes.

Publicacao

Antes de publicar:

pnpm --filter @kura-iam/service-sdk check-types
pnpm --filter @kura-iam/service-sdk test
pnpm --filter @kura-iam/service-sdk build
pnpm --filter @kura-iam/service-sdk pack --dry-run

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.

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

git checkout main
git pull origin main
pnpm --filter @kura-iam/service-sdk version patch --no-git-tag-version
pnpm install --lockfile-only
git add packages/service-sdk/package.json pnpm-lock.yaml
git commit -m "chore: release service-sdk"
git tag service-sdk-v$(node -p "require('./packages/service-sdk/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.

Tambem rode os E2E do servidor com permissao elevada antes de promover uma versao, porque eles validam o contrato real entre IdP e SDK.

Escopo

Este pacote e deliberadamente pequeno. Ele nao cria uma aplicacao BFF completa, nao gerencia sessoes de browser e nao define rotas. Essas responsabilidades pertencem a um template ou pacote separado de BFF.