@adonis-agora/authkit-server 0.34.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davi de Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# @adonis-agora/authkit-server
+
+OpenID Connect / OAuth2 Authorization Server (Identity Provider) for AdonisJS — an idiomatic
+wrapper around [`oidc-provider`](https://github.com/panva/node-oidc-provider).
+
+## Features
+
+- **OIDC / OAuth2 AS** — authorization code + PKCE, refresh tokens (rotated), token exchange,
+  discovery, JWKS (managed + rotatable), revocation, introspection.
+- **MFA** — TOTP, WebAuthn passkeys, recovery codes, trusted-device skip.
+- **Passwordless** — magic-link email login and passkey-first login.
+- **Protocol extensions** — Device Flow (RFC 8628), DPoP (RFC 9449), PAR (RFC 9126), step-up
+  auth via `acr_values`, Dynamic Client Registration (RFC 7591/7592).
+- **Admin console** — user CRUD (+ disable), client CRUD, sessions, audit log (opt-in,
+  role-gated).
+- **Account console** — self-service apps/consent, security (password/email/sessions),
+  profile.
+- **Tokens & federation** — Personal Access Tokens, admin impersonation, back-channel logout,
+  RP-initiated logout.
+- **Hardening** — progressive account lockout, per-IP rate-limiting, audit logging with an
+  events/webhook fan-out, new-login email alerts.
+- **Operability** — i18n (English default, pt-BR built in), OpenTelemetry metrics, the
+  `authkit:doctor` and `authkit:rotate-keys` commands.
+
+> The remaining sections are in Portuguese pending a full translation pass.
+
+## Instalação
+
+```bash
+node ace add @adonis-agora/authkit-server
+# ou: pnpm add @adonis-agora/authkit-server && node ace configure @adonis-agora/authkit-server
+```
+
+O `configure` publica `config/authkit_server.ts`, o model `app/models/auth_user.ts`,
+o controller de interactions (`app/controllers/auth_interaction_controller.ts`) e
+registra o provider.
+
+## Montar as rotas OIDC
+
+```ts
+// start/routes.ts
+import router from '@adonisjs/core/services/router'
+import { registerOidcRoutes } from '@adonis-agora/authkit-server'
+
+registerOidcRoutes(router) // monta em /oidc por padrão
+```
+
+Defina `AUTHKIT_ISSUER` apontando para `<host>/oidc` (o issuer deve terminar no mount path).
+
+## Rotas de interaction (login/consentimento)
+
+O `oidc-provider` redireciona o usuário não autenticado para `interactions.url`
+(`/auth/interaction/:uid`). Essas telas são **suas** (o `configure` ejeta
+`app/controllers/auth_interaction_controller.ts`). Registre as rotas que apontam para ele:
+
+```ts
+// start/routes.ts
+import AuthInteractionController from '#controllers/auth_interaction_controller'
+
+router.get('/auth/interaction/:uid', [AuthInteractionController, 'show'])
+router.post('/auth/interaction/:uid/login', [AuthInteractionController, 'login'])
+router.post('/auth/interaction/:uid/consent', [AuthInteractionController, 'consent'])
+```
+
+Sem essas rotas o fluxo de autorização cai num 404 ao chegar na tela de login.
+
+## UI de login/consent (configurável)
+
+O `configure` ejeta as telas de interaction a partir de um preset escolhido:
+
+```bash
+node ace configure @adonis-agora/authkit-server --ui=edge
+# valores: edge | react | headless — se omitir, o configure pergunta
+```
+
+Cada preset publica:
+
+- **`headless`** — apenas o controller (`app/controllers/auth_interaction_controller.ts`).
+  `show` devolve JSON (`{ uid, prompt, params }`) e `login`/`consent` respondem JSON/erro.
+  Você constrói o front como quiser.
+- **`edge`** — controller + views Edge (`resources/views/authkit/login.edge` e
+  `consent.edge`). `show` renderiza a view de acordo com o prompt.
+- **`react`** — controller + páginas Inertia/React (`inertia/pages/authkit/login.tsx` e
+  `consent.tsx`). `show` faz `inertia.render`. Exige `@adonisjs/inertia` + Vite + React no
+  app — o `configure` valida essa stack antes de publicar o preset.
+
+Em todos os presets o controller ejetado é **casca**: a lógica vive em
+`service.interactions` (resolvido via `containerResolver.make('authkit.server')`), que expõe
+`details(ctx)`, `login(ctx, { email, password })` e `consent(ctx)`. Você edita só a parte de
+render/redirect.
+
+Quem decide se as credenciais valem é o `verifyCredentials` do `config/authkit_server.ts`
+— é o que o `service.interactions.login` chama. O default consulta o `AuthUser` por e-mail e
+usa `verifyPassword`; sobrescreva para plugar sua própria base de usuários.
+
+As 3 rotas que o consumidor registra são as mesmas da seção anterior:
+
+```ts
+import AuthInteractionController from '#controllers/auth_interaction_controller'
+
+router.get('/auth/interaction/:uid', [AuthInteractionController, 'show'])
+router.post('/auth/interaction/:uid/login', [AuthInteractionController, 'login'])
+router.post('/auth/interaction/:uid/consent', [AuthInteractionController, 'consent'])
+```
+
+## Persistência
+
+Escolha o backend no `config/authkit_server.ts`:
+- `adapters.redis({ connection })` — requer `@adonisjs/redis` configurado.
+- `adapters.database({ connection? })` — Lucid; rode a migração `authkit_oidc_payloads`.
+
+## Observabilidade
+
+A lib agrega métricas de auth (logins, tokens, refresh, grants revogados, duração/erros
+de resolve) e as expõe de forma opt-in.
+
+### Configuração
+
+No `config/authkit_server.ts`, use a chave `observability`:
+
+```ts
+observability: {
+  metrics: true,    // habilita a coleta/agregação de métricas
+  jsonRoutes: true, // libera a rota JSON de snapshot
+  dashboard: true,  // libera o dashboard HTML embutido
+}
+```
+
+### Rotas
+
+Passe as flags em `registerOidcRoutes` no `start/routes.ts`:
+
+```ts
+import { registerOidcRoutes } from '@adonis-agora/authkit-server'
+
+registerOidcRoutes(router, { metrics: true, dashboard: true })
+```
+
+- `GET /authkit/metrics` — snapshot agregado em JSON (`{ counters, histograms, updatedAt }`).
+- `GET /authkit/dashboard` — dashboard HTML embutido (auto-refresh a cada 5s, sem
+  dependência do Edge do consumidor).
+
+### OpenTelemetry
+
+As métricas são emitidas via OpenTelemetry **quando** `@opentelemetry/api` e `@adonisjs/otel`
+estão instalados. Sem esses pacotes a emissão é no-op — a agregação em memória (e as rotas
+JSON/HTML) continua funcionando normalmente.
+
+### Grafana
+
+O arquivo `assets/grafana/authkit-dashboard.json` pode ser importado diretamente no Grafana
+(Dashboards → Import). Ele usa nomes de métrica no padrão OTel→Prometheus (pontos viram
+underscores e counters ganham `_total`), portanto requer um exporter Prometheus no pipeline
+OTel para que as séries existam.
+
+## Notas
+- Access tokens são opacos; ID tokens são JWT (assinados pelo JWKS gerido).
+- PKCE (S256) é obrigatório; refresh tokens são rotacionados.

package/build/assets/grafana/authkit-dashboard.json

@@ -0,0 +1,118 @@
+{
+  "title": "AuthKit",
+  "uid": "authkit",
+  "schemaVersion": 39,
+  "version": 1,
+  "editable": true,
+  "graphTooltip": 0,
+  "time": { "from": "now-6h", "to": "now" },
+  "refresh": "30s",
+  "tags": ["authkit", "oidc", "auth"],
+  "templating": {
+    "list": [
+      {
+        "name": "datasource",
+        "label": "Datasource",
+        "type": "datasource",
+        "query": "prometheus",
+        "current": {},
+        "hide": 0,
+        "refresh": 1
+      }
+    ]
+  },
+  "panels": [
+    {
+      "id": 1,
+      "title": "Login (sucesso vs falha)",
+      "type": "timeseries",
+      "datasource": { "type": "prometheus", "uid": "${datasource}" },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
+      "fieldConfig": { "defaults": { "unit": "ops" }, "overrides": [] },
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": { "type": "prometheus", "uid": "${datasource}" },
+          "expr": "rate(authkit_login_success_total[5m])",
+          "legendFormat": "success"
+        },
+        {
+          "refId": "B",
+          "datasource": { "type": "prometheus", "uid": "${datasource}" },
+          "expr": "rate(authkit_login_failure_total[5m])",
+          "legendFormat": "failure"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "title": "Tokens emitidos vs refresh rotacionados",
+      "type": "timeseries",
+      "datasource": { "type": "prometheus", "uid": "${datasource}" },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
+      "fieldConfig": { "defaults": { "unit": "ops" }, "overrides": [] },
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": { "type": "prometheus", "uid": "${datasource}" },
+          "expr": "rate(authkit_token_issued_total[5m])",
+          "legendFormat": "issued"
+        },
+        {
+          "refId": "B",
+          "datasource": { "type": "prometheus", "uid": "${datasource}" },
+          "expr": "rate(authkit_refresh_rotated_total[5m])",
+          "legendFormat": "refresh rotated"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "title": "Grants revogados (total)",
+      "type": "stat",
+      "datasource": { "type": "prometheus", "uid": "${datasource}" },
+      "gridPos": { "h": 8, "w": 8, "x": 0, "y": 8 },
+      "fieldConfig": { "defaults": { "unit": "short" }, "overrides": [] },
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": { "type": "prometheus", "uid": "${datasource}" },
+          "expr": "sum(authkit_grant_revoked_total)",
+          "legendFormat": "revoked"
+        }
+      ]
+    },
+    {
+      "id": 4,
+      "title": "Resolve duration (p95)",
+      "type": "timeseries",
+      "datasource": { "type": "prometheus", "uid": "${datasource}" },
+      "gridPos": { "h": 8, "w": 8, "x": 8, "y": 8 },
+      "fieldConfig": { "defaults": { "unit": "s" }, "overrides": [] },
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": { "type": "prometheus", "uid": "${datasource}" },
+          "expr": "histogram_quantile(0.95, rate(authkit_resolve_duration_bucket[5m]))",
+          "legendFormat": "p95"
+        }
+      ]
+    },
+    {
+      "id": 5,
+      "title": "Erros de resolve (total)",
+      "type": "stat",
+      "datasource": { "type": "prometheus", "uid": "${datasource}" },
+      "gridPos": { "h": 8, "w": 8, "x": 16, "y": 8 },
+      "fieldConfig": { "defaults": { "unit": "short" }, "overrides": [] },
+      "targets": [
+        {
+          "refId": "A",
+          "datasource": { "type": "prometheus", "uid": "${datasource}" },
+          "expr": "sum(authkit_resolve_errors_total)",
+          "legendFormat": "errors"
+        }
+      ]
+    }
+  ]
+}

package/build/commands/clients_create.d.ts

@@ -0,0 +1,27 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import type { CommandOptions } from '@adonisjs/core/types/ace';
+/**
+ * Cria um client OIDC no adapter/DB via {@link AdminClientsService}. O client fica
+ * disponível em runtime imediatamente, sem necessidade de redeploy. Para clients
+ * confidenciais, o secret é gerado aleatoriamente e impresso UMA ÚNICA VEZ — não é
+ * recuperável depois.
+ *
+ * Exemplos:
+ *   node ace authkit:clients:create --client-id=my-spa --redirect-uri=https://app/cb --public
+ *   node ace authkit:clients:create --client-id=my-api --redirect-uri=https://api/cb --redirect-uri=https://api/cb2 --grant=client_credentials
+ *   node ace authkit:clients:create --redirect-uri=https://app/cb --json
+ */
+export default class AuthkitClientsCreate extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static help: string[];
+    static options: CommandOptions;
+    clientId?: string;
+    redirectUri?: string[];
+    postLogoutUri?: string[];
+    grant?: string[];
+    public?: boolean;
+    backchannelLogoutUri?: string;
+    json?: boolean;
+    run(): Promise<void>;
+}

package/build/commands/clients_create.js

@@ -0,0 +1,121 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseCommand, flags } from '@adonisjs/core/ace';
+/**
+ * Cria um client OIDC no adapter/DB via {@link AdminClientsService}. O client fica
+ * disponível em runtime imediatamente, sem necessidade de redeploy. Para clients
+ * confidenciais, o secret é gerado aleatoriamente e impresso UMA ÚNICA VEZ — não é
+ * recuperável depois.
+ *
+ * Exemplos:
+ *   node ace authkit:clients:create --client-id=my-spa --redirect-uri=https://app/cb --public
+ *   node ace authkit:clients:create --client-id=my-api --redirect-uri=https://api/cb --redirect-uri=https://api/cb2 --grant=client_credentials
+ *   node ace authkit:clients:create --redirect-uri=https://app/cb --json
+ */
+export default class AuthkitClientsCreate extends BaseCommand {
+    static commandName = 'authkit:clients:create';
+    static description = 'Cria um client OIDC no adapter/DB em runtime (sem redeploy). O secret é impresso uma vez.';
+    static help = [
+        'Cria um client OIDC persistido no adapter via AdminClientsService, o mesmo',
+        'caminho usado pelo console admin e pelo registro dinâmico (RFC 7591).',
+        '',
+        'Para clients confidenciais (default), um secret aleatório é gerado e',
+        'impresso UMA ÚNICA VEZ no terminal — armazene-o imediatamente.',
+        '',
+        'Flags repetíveis (--flag=v1 --flag=v2):',
+        '  --redirect-uri      URI(s) de callback do client (obrigatório).',
+        '  --post-logout-uri   URI(s) de post-logout redirect.',
+        '  --grant             Grant types. Default: authorization_code + refresh_token.',
+        '',
+        'Exemplos:',
+        '  node ace authkit:clients:create --client-id=my-spa --redirect-uri=https://app/cb --public',
+        '  node ace authkit:clients:create --redirect-uri=https://app/cb --backchannel-logout-uri=https://app/bc',
+        '  node ace authkit:clients:create --client-id=my-app --redirect-uri=https://a/cb --redirect-uri=https://b/cb --json',
+    ];
+    static options = { startApp: true };
+    async run() {
+        const redirectUris = this.redirectUri ?? [];
+        if (redirectUris.length === 0) {
+            this.logger.logError('❌ --redirect-uri é obrigatório. Passe ao menos uma URI de callback.');
+            this.exitCode = 1;
+            return;
+        }
+        const service = await this.app.container.make('authkit.server');
+        const { AdminClientsService } = await import('../src/host/admin_clients_service.js');
+        const svc = new AdminClientsService(service);
+        const grantTypes = this.grant && this.grant.length > 0
+            ? this.grant
+            : ['authorization_code', 'refresh_token'];
+        const tokenEndpointAuthMethod = this.public ? 'none' : 'client_secret_basic';
+        const created = await svc.create({
+            clientId: this.clientId,
+            redirectUris,
+            postLogoutRedirectUris: this.postLogoutUri ?? [],
+            grantTypes,
+            tokenEndpointAuthMethod,
+            backchannelLogoutUri: this.backchannelLogoutUri,
+        });
+        if (this.json) {
+            const out = {
+                clientId: created.clientId,
+                redirectUris,
+                postLogoutRedirectUris: this.postLogoutUri ?? [],
+                grantTypes,
+                tokenEndpointAuthMethod,
+                confidential: !this.public,
+            };
+            if (created.clientSecret)
+                out.clientSecret = created.clientSecret;
+            if (this.backchannelLogoutUri)
+                out.backchannelLogoutUri = this.backchannelLogoutUri;
+            this.logger.info(JSON.stringify(out, null, 2));
+            return;
+        }
+        this.logger.success(`Client criado: ${created.clientId}`);
+        this.logger.info(`  redirect_uris: ${redirectUris.join(', ')}`);
+        this.logger.info(`  grant_types:   ${grantTypes.join(', ')}`);
+        this.logger.info(`  type:          ${this.public ? 'publico (sem secret)' : 'confidencial'}`);
+        if (this.backchannelLogoutUri) {
+            this.logger.info(`  backchannel:   ${this.backchannelLogoutUri}`);
+        }
+        if (created.clientSecret) {
+            this.logger.info('');
+            this.logger.success('CLIENT SECRET (mostrado UMA vez - armazene agora):');
+            this.logger.success(`  ${created.clientSecret}`);
+            this.logger.info('');
+        }
+    }
+}
+__decorate([
+    flags.string({ description: 'client_id desejado. Omitir gera um UUID aleatório.' })
+], AuthkitClientsCreate.prototype, "clientId", void 0);
+__decorate([
+    flags.array({ description: 'redirect_uri(s) permitidas (repetível). Obrigatório.' })
+], AuthkitClientsCreate.prototype, "redirectUri", void 0);
+__decorate([
+    flags.array({ description: 'post_logout_redirect_uri(s) permitidas (repetível).' })
+], AuthkitClientsCreate.prototype, "postLogoutUri", void 0);
+__decorate([
+    flags.array({
+        description: 'Grant types (repetível). Default: authorization_code + refresh_token.',
+    })
+], AuthkitClientsCreate.prototype, "grant", void 0);
+__decorate([
+    flags.boolean({
+        description: 'Cria um client público (sem secret; token_endpoint_auth_method=none). Default: false (confidencial).',
+    })
+], AuthkitClientsCreate.prototype, "public", void 0);
+__decorate([
+    flags.string({
+        description: 'Endpoint de OIDC Back-Channel Logout do RP (POST de logout_token).',
+    })
+], AuthkitClientsCreate.prototype, "backchannelLogoutUri", void 0);
+__decorate([
+    flags.boolean({
+        description: 'Output em JSON machine-readable (inclui clientId e clientSecret).',
+    })
+], AuthkitClientsCreate.prototype, "json", void 0);