@adonis-agora/authkit-server 0.34.0

package/build/commands/commands.json

@@ -0,0 +1,292 @@
+{
+  "version": 1,
+  "commands": [
+    {
+      "commandName": "authkit:eject",
+      "description": "Ejeta views Edge ou um controller do host-kit do @adonis-agora/authkit-server para customização local",
+      "namespace": "authkit",
+      "aliases": [],
+      "flags": [
+        {
+          "name": "views",
+          "flagName": "views",
+          "required": false,
+          "type": "boolean",
+          "description": "Copia as views Edge da lib para resources/views/authkit/"
+        },
+        {
+          "name": "controller",
+          "flagName": "controller",
+          "required": false,
+          "type": "string",
+          "description": "Copia um controller do host-kit (ex.: interaction) para app/controllers/authkit/"
+        }
+      ],
+      "args": [],
+      "options": {},
+      "filePath": "eject.js"
+    },
+    {
+      "commandName": "authkit:doctor",
+      "description": "Valida a configuração do AuthKit no host e imprime achados (✅/⚠️/❌). Sai com código !=0 se houver erros.",
+      "namespace": "authkit",
+      "aliases": [],
+      "flags": [],
+      "args": [],
+      "options": { "startApp": true },
+      "filePath": "doctor.js"
+    },
+    {
+      "commandName": "authkit:keys:rotate",
+      "description": "Rotaciona as chaves de assinatura JWKS managed: gera uma nova chave (novo kid) que passa a assinar e mantém as anteriores no JWKS por um período de graça (--retire remove de imediato; --dry-run só mostra o plano).",
+      "namespace": "authkit",
+      "aliases": [],
+      "flags": [
+        {
+          "name": "keep",
+          "flagName": "keep",
+          "required": false,
+          "type": "number",
+          "description": "Quantas chaves manter no JWKS (default 2)."
+        },
+        {
+          "name": "dryRun",
+          "flagName": "dry-run",
+          "required": false,
+          "type": "boolean",
+          "description": "Apenas mostra o plano da rotação; NÃO altera o keystore."
+        },
+        {
+          "name": "retire",
+          "flagName": "retire",
+          "required": false,
+          "type": "boolean",
+          "description": "Remove TODAS as chaves antigas de imediato (sem período de graça)."
+        }
+      ],
+      "args": [],
+      "options": { "startApp": true },
+      "filePath": "keys_rotate.js"
+    },
+    {
+      "commandName": "authkit:clients:create",
+      "description": "Cria um client OIDC no adapter/DB em runtime (sem redeploy). O secret é impresso uma vez.",
+      "namespace": "authkit",
+      "aliases": [],
+      "flags": [
+        {
+          "name": "clientId",
+          "flagName": "client-id",
+          "required": false,
+          "type": "string",
+          "description": "client_id desejado. Omitir gera um UUID aleatório."
+        },
+        {
+          "name": "redirectUri",
+          "flagName": "redirect-uri",
+          "required": false,
+          "type": "array",
+          "description": "redirect_uri(s) permitidas (repetível). Obrigatório."
+        },
+        {
+          "name": "postLogoutUri",
+          "flagName": "post-logout-uri",
+          "required": false,
+          "type": "array",
+          "description": "post_logout_redirect_uri(s) permitidas (repetível)."
+        },
+        {
+          "name": "grant",
+          "flagName": "grant",
+          "required": false,
+          "type": "array",
+          "description": "Grant types (repetível). Default: authorization_code + refresh_token."
+        },
+        {
+          "name": "public",
+          "flagName": "public",
+          "required": false,
+          "type": "boolean",
+          "description": "Cria um client público (sem secret; token_endpoint_auth_method=none)."
+        },
+        {
+          "name": "backchannelLogoutUri",
+          "flagName": "backchannel-logout-uri",
+          "required": false,
+          "type": "string",
+          "description": "Endpoint de OIDC Back-Channel Logout do RP."
+        },
+        {
+          "name": "json",
+          "flagName": "json",
+          "required": false,
+          "type": "boolean",
+          "description": "Output em JSON machine-readable."
+        }
+      ],
+      "args": [],
+      "options": { "startApp": true },
+      "filePath": "clients_create.js"
+    },
+    {
+      "commandName": "authkit:users:import",
+      "description": "Importa usuários de um arquivo JSON/NDJSON pelo account store (hashes entram como estão; lazy rehash no login).",
+      "namespace": "authkit",
+      "aliases": [],
+      "flags": [
+        {
+          "name": "file",
+          "flagName": "file",
+          "required": false,
+          "type": "string",
+          "description": "Caminho do arquivo JSON/NDJSON com os usuários."
+        },
+        {
+          "name": "dryRun",
+          "flagName": "dry-run",
+          "required": false,
+          "type": "boolean",
+          "description": "Valida e relata SEM persistir nada."
+        }
+      ],
+      "args": [],
+      "options": { "startApp": true },
+      "filePath": "import_users.js"
+    },
+    {
+      "commandName": "authkit:settings:list",
+      "description": "Lista todas as runtime settings presentes em `auth_settings`.",
+      "namespace": "authkit",
+      "aliases": [],
+      "flags": [
+        {
+          "name": "json",
+          "flagName": "json",
+          "required": false,
+          "type": "boolean",
+          "description": "Output em JSON machine-readable."
+        }
+      ],
+      "args": [],
+      "options": { "startApp": true },
+      "filePath": "settings_list.js"
+    },
+    {
+      "commandName": "authkit:settings:get",
+      "description": "Obtém uma runtime setting por key de `auth_settings`.",
+      "namespace": "authkit",
+      "aliases": [],
+      "flags": [
+        {
+          "name": "json",
+          "flagName": "json",
+          "required": false,
+          "type": "boolean",
+          "description": "Output em JSON machine-readable."
+        }
+      ],
+      "args": [
+        {
+          "name": "key",
+          "argumentName": "key",
+          "required": true,
+          "type": "string",
+          "description": "Nome da setting (ex.: lockout, session_policy)."
+        }
+      ],
+      "options": { "startApp": true },
+      "filePath": "settings_get.js"
+    },
+    {
+      "commandName": "authkit:settings:set",
+      "description": "Grava (upsert) uma runtime setting em `auth_settings`. Valida shape para keys conhecidas.",
+      "namespace": "authkit",
+      "aliases": [],
+      "flags": [
+        {
+          "name": "json",
+          "flagName": "json",
+          "required": false,
+          "type": "boolean",
+          "description": "Output em JSON machine-readable."
+        }
+      ],
+      "args": [
+        {
+          "name": "key",
+          "argumentName": "key",
+          "required": true,
+          "type": "string",
+          "description": "Nome da setting (ex.: lockout, session_policy, token_ttl)."
+        },
+        {
+          "name": "value",
+          "argumentName": "value",
+          "required": true,
+          "type": "string",
+          "description": "Valor JSON da setting (deve ser um objeto JSON válido)."
+        }
+      ],
+      "options": { "startApp": true },
+      "filePath": "settings_set.js"
+    },
+    {
+      "commandName": "authkit:settings:unset",
+      "description": "Remove uma runtime setting de `auth_settings` (reset ao config/default).",
+      "namespace": "authkit",
+      "aliases": [],
+      "flags": [
+        {
+          "name": "json",
+          "flagName": "json",
+          "required": false,
+          "type": "boolean",
+          "description": "Output em JSON machine-readable."
+        }
+      ],
+      "args": [
+        {
+          "name": "key",
+          "argumentName": "key",
+          "required": true,
+          "type": "string",
+          "description": "Nome da setting a remover (ex.: lockout, session_policy)."
+        }
+      ],
+      "options": { "startApp": true },
+      "filePath": "settings_unset.js"
+    },
+    {
+      "commandName": "authkit:accounts:expire-scan",
+      "description": "Varre contas inativas (account_expiration setting) e reporta expiradas/a expirar. Com --warn envia e-mail de aviso. Pensado para cron do host.",
+      "namespace": "authkit",
+      "aliases": [],
+      "flags": [
+        {
+          "name": "dryRun",
+          "flagName": "dry-run",
+          "required": false,
+          "type": "boolean",
+          "description": "Reporta sem enviar e-mails nem auditar."
+        },
+        {
+          "name": "warn",
+          "flagName": "warn",
+          "required": false,
+          "type": "boolean",
+          "description": "Envia e-mail de aviso às contas a expirar em breve (deduplicado via audit)."
+        },
+        {
+          "name": "json",
+          "flagName": "json",
+          "required": false,
+          "type": "boolean",
+          "description": "Output em JSON machine-readable."
+        }
+      ],
+      "args": [],
+      "options": { "startApp": true },
+      "filePath": "expire_scan.js"
+    }
+  ]
+}

package/build/commands/configure.d.ts

@@ -0,0 +1,2 @@
+import type Configure from '@adonisjs/core/commands/configure';
+export declare function configure(command: Configure): Promise<void>;

package/build/commands/configure.js

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stubsRoot } from '../stubs/main.js';
+import { resolveUiPreset, uiStubPaths } from './ui_preset.js';
+function assertPresetPrereqs(preset, appRoot) {
+    if (preset !== 'react')
+        return;
+    const pkgPath = join(appRoot, 'package.json');
+    const pkg = existsSync(pkgPath) ? JSON.parse(readFileSync(pkgPath, 'utf8')) : {};
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const hasInertia = !!deps['@adonisjs/inertia'];
+    const hasReact = !!deps['react'];
+    const hasVite = existsSync(join(appRoot, 'vite.config.ts')) || existsSync(join(appRoot, 'vite.config.js'));
+    if (!hasInertia || !hasReact || !hasVite) {
+        throw new Error('authkit --ui=react requer @adonisjs/inertia + react + Vite no app. ' +
+            'Rode `node ace add @adonisjs/inertia` (com React) antes, ou use --ui=edge|headless.');
+    }
+}
+export async function configure(command) {
+    const flag = command.parsedFlags?.ui;
+    const chosen = flag ?? (await command.prompt.choice('UI das telas de login/consent', ['edge', 'react', 'headless']));
+    const preset = resolveUiPreset(chosen);
+    assertPresetPrereqs(preset, command.app.makePath());
+    const codemods = await command.createCodemods();
+    // O preset react usa um stub de config dedicado que inclui `inertiaRenderer` com
+    // o allowlist `views` já preenchido — evitando SSR crash por páginas inexistentes.
+    const configStub = preset === 'react' ? 'config/authkit_react.stub' : 'config/authkit.stub';
+    await codemods.makeUsingStub(stubsRoot, configStub, {});
+    await codemods.makeUsingStub(stubsRoot, 'models/auth_user.stub', {});
+    for (const path of uiStubPaths(preset)) {
+        await codemods.makeUsingStub(stubsRoot, path, {});
+    }
+    await codemods.updateRcFile((rcFile) => {
+        rcFile.addProvider('@adonis-agora/authkit-server/authkit_server_provider');
+    });
+    await codemods.defineEnvValidations({
+        leadingComment: 'Variáveis do @adonis-agora/authkit-server (Authorization Server OIDC)',
+        variables: {
+            AUTHKIT_ISSUER: `Env.schema.string({ format: 'url', tld: false })`,
+        },
+    });
+    await codemods.defineEnvVariables({
+        AUTHKIT_ISSUER: 'http://localhost:3333/oidc',
+    });
+}

package/build/commands/doctor.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import type { CommandOptions } from '@adonisjs/core/types/ace';
+export default class AuthkitDoctor extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static help: string[];
+    static options: CommandOptions;
+    run(): Promise<void>;
+    private print;
+}

package/build/commands/doctor.js

@@ -0,0 +1,113 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { BaseCommand } from '@adonisjs/core/ace';
+import { runAllChecks, hasErrors, signingKeyAgeFinding } from '../src/doctor/checks.js';
+import { DatabaseAdapter } from '../src/adapters/database_adapter.js';
+import { resolveAuthkitConfig } from '../src/commands/resolve_config.js';
+import { KeystoreManager, resolveKeystoreVault } from '../src/keys/keystore_manager.js';
+import { KeystoreCodec } from '../src/keys/keystore_codec.js';
+import { signingKeyAgeDays } from '../src/keys/keystore.js';
+import { defaultEncryptForStore } from '../src/define_config.js';
+import { loadEncryptionService } from '../src/keys/keystore_crypto.js';
+/**
+ * Tenta importar um peer; `true` se importável.
+ *
+ * Distingue "não instalado" de "instalado mas quebrado": só um erro de
+ * módulo-não-encontrado (`ERR_MODULE_NOT_FOUND`/`MODULE_NOT_FOUND`) é tratado como
+ * peer ausente (silencioso — é o caso esperado). Qualquer outro erro significa que
+ * o peer ESTÁ presente mas falhou ao carregar (import circular, erro de sintaxe,
+ * config inválida) — isso o doctor precisa gritar, senão um peer quebrado aparece
+ * como "ausente" e o diagnóstico mente.
+ */
+async function canImport(specifier, logger) {
+    try {
+        await import(__rewriteRelativeImportExtension(specifier));
+        return true;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== 'ERR_MODULE_NOT_FOUND' && code !== 'MODULE_NOT_FOUND') {
+            logger?.warning(`⚠️  ${specifier} está instalado mas falhou ao carregar: ${err.message}`);
+        }
+        return false;
+    }
+}
+export default class AuthkitDoctor extends BaseCommand {
+    static commandName = 'authkit:doctor';
+    static description = 'Valida a configuração do AuthKit no host e imprime achados (✅/⚠️/❌). Sai com código !=0 se houver erros.';
+    static help = [
+        'Roda uma bateria de checagens sobre a config `authkit` do host:',
+        'issuer/mountPath, clients, accountStore + capacidades, session, shield,',
+        'ally (social), rate-limit, admin, webauthn e jwks.',
+    ];
+    static options = { startApp: true };
+    async run() {
+        const config = await this.app.container.make('config');
+        // `defineConfig` exporta um config provider — resolve antes de inspecionar,
+        // senão todo campo aparece como "ausente" (provider cru não tem issuer etc.).
+        let authkitConfig = null;
+        try {
+            authkitConfig = await resolveAuthkitConfig(this.app, config.get('authkit', null));
+        }
+        catch (error) {
+            this.logger.logError(`❌ config/authkit.ts falhou ao resolver: ${error.message}`);
+            this.exitCode = 1;
+            return;
+        }
+        const sessionConfig = config.get('session', null) ?? null;
+        const input = {
+            authkitConfig,
+            sessionConfig,
+            peers: {
+                session: await canImport('@adonisjs/session', this.logger),
+                shield: await canImport('@adonisjs/shield', this.logger),
+                ally: await canImport('@adonisjs/ally', this.logger),
+                limiter: await canImport('@adonisjs/limiter', this.logger),
+            },
+            __adapterClasses: { DatabaseAdapter },
+        };
+        const findings = runAllChecks(input);
+        // Adiciona o finding de idade da chave de assinatura managed (best-effort).
+        const jwksInput = (authkitConfig?.jwksConfig ?? authkitConfig?.jwks);
+        if (jwksInput?.source === 'managed' && jwksInput?.store) {
+            try {
+                const vault = resolveKeystoreVault(jwksInput.store, { makePath: (p) => this.app.makePath(p), container: this.app.container });
+                const encrypt = jwksInput.encrypt ?? defaultEncryptForStore(jwksInput.store);
+                const enc = encrypt ? await loadEncryptionService().catch(() => undefined) : undefined;
+                const mgr = new KeystoreManager(vault, new KeystoreCodec({ encrypt, enc }), jwksInput.algorithm ?? 'RS256');
+                const store = await mgr.read().catch(() => null);
+                const maxAge = jwksInput.rotationDays ?? 90;
+                findings.push(signingKeyAgeFinding(signingKeyAgeDays(store), maxAge));
+            }
+            catch {
+                /* idade é best-effort no doctor */
+            }
+        }
+        this.print(findings);
+        if (hasErrors(findings)) {
+            this.exitCode = 1;
+        }
+    }
+    print(findings) {
+        const icon = (l) => (l === 'ok' ? '✅' : l === 'warn' ? '⚠️ ' : '❌');
+        this.logger.info('AuthKit doctor — checagem da configuração do host\n');
+        for (const f of findings) {
+            const line = `${icon(f.level)} ${f.message}`;
+            if (f.level === 'error')
+                this.logger.logError(line);
+            else if (f.level === 'warn')
+                this.logger.warning(line);
+            else
+                this.logger.success(line);
+        }
+        const errors = findings.filter((f) => f.level === 'error').length;
+        const warns = findings.filter((f) => f.level === 'warn').length;
+        this.logger.info(`\nResumo: ${errors} erro(s), ${warns} aviso(s).`);
+    }
+}

package/build/commands/eject.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import type { CommandOptions } from '@adonisjs/core/types/ace';
+export default class AuthkitEject extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static help: string[];
+    static options: CommandOptions;
+    views: boolean;
+    controller?: string;
+    run(): Promise<void>;
+}

package/build/commands/eject.js

@@ -0,0 +1,96 @@
+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';
+const KNOWN_CONTROLLERS = [
+    'interaction',
+    'registration',
+    'social',
+    'account_session',
+    'account_tokens',
+    'pat_introspection',
+];
+export default class AuthkitEject extends BaseCommand {
+    static commandName = 'authkit:eject';
+    static description = 'Ejeta views Edge ou um controller do host-kit do @adonis-agora/authkit-server para customização local';
+    static help = [
+        'Use --views para copiar as views Edge da lib para resources/views/authkit/.',
+        'Depois de ejetar as views, o app as servirá pelo ViewPath padrão',
+        '(sem o disco authkit::) — renomeie as chamadas view() nos controllers.',
+        '',
+        'Use --controller=<nome> para copiar um controller do host-kit para',
+        'app/controllers/authkit/<nome>_controller.ts e customizá-lo livremente.',
+        '',
+        `Controllers disponíveis: ${KNOWN_CONTROLLERS.join(', ')}`,
+    ];
+    static options = {};
+    async run() {
+        const fs = await import('node:fs');
+        const { fileURLToPath } = await import('node:url');
+        /**
+         * Resolve o diretório dentro de `host/` — prefere o build compilado,
+         * cai de volta para o src quando rodando no contexto de dev da lib.
+         */
+        const pickDir = (rel) => {
+            const built = new URL(`../build/host/${rel}`, import.meta.url);
+            const src = new URL(`../src/host/${rel}`, import.meta.url);
+            return fs.existsSync(fileURLToPath(built)) ? built : src;
+        };
+        if (this.views) {
+            const fromPath = fileURLToPath(pickDir('views'));
+            if (!fs.existsSync(fromPath)) {
+                this.logger.error('Diretório de views não encontrado. Execute `pnpm build` no pacote primeiro.');
+                this.exitCode = 1;
+                return;
+            }
+            const toPath = this.app.makePath('resources/views/authkit');
+            fs.mkdirSync(toPath, { recursive: true });
+            fs.cpSync(fromPath, toPath, { recursive: true });
+            this.logger.success(`Views Edge ejetadas → ${toPath}`);
+            this.logger.info('Lembre-se de ajustar as chamadas view() nos controllers para usar o caminho local ao invés do disco authkit::.');
+        }
+        if (this.controller) {
+            const knownList = KNOWN_CONTROLLERS;
+            if (!knownList.includes(this.controller)) {
+                this.logger.error(`Controller desconhecido: "${this.controller}". Disponíveis: ${KNOWN_CONTROLLERS.join(', ')}`);
+                this.exitCode = 1;
+                return;
+            }
+            const file = `${this.controller}_controller`;
+            const fromDirPath = fileURLToPath(pickDir('controllers'));
+            // Prefere .js (build) com fallback para .ts (src)
+            const jsPath = `${fromDirPath}/${file}.js`;
+            const tsPath = `${fromDirPath}/${file}.ts`;
+            const fromFilePath = fs.existsSync(jsPath) ? jsPath : tsPath;
+            const ext = fs.existsSync(jsPath) ? 'js' : 'ts';
+            if (!fs.existsSync(fromFilePath)) {
+                this.logger.error(`Arquivo do controller não encontrado: ${fromFilePath}. Execute \`pnpm build\` no pacote primeiro.`);
+                this.exitCode = 1;
+                return;
+            }
+            const toDirPath = this.app.makePath('app/controllers/authkit');
+            fs.mkdirSync(toDirPath, { recursive: true });
+            const toFilePath = `${toDirPath}/${file}.${ext}`;
+            fs.copyFileSync(fromFilePath, toFilePath);
+            this.logger.success(`Controller "${this.controller}" ejetado → ${toFilePath}`);
+            this.logger.info(`Atualize as rotas do host para apontar para app/controllers/authkit/${file}.`);
+        }
+        if (!this.views && !this.controller) {
+            this.logger.info('Nenhuma opção especificada. Use --views ou --controller=<nome>.');
+            this.logger.info(`Controllers disponíveis: ${KNOWN_CONTROLLERS.join(', ')}`);
+        }
+    }
+}
+__decorate([
+    flags.boolean({
+        description: 'Copia as views Edge da lib para resources/views/authkit/',
+    })
+], AuthkitEject.prototype, "views", void 0);
+__decorate([
+    flags.string({
+        description: `Copia um controller do host-kit (ex.: interaction) para app/controllers/authkit/`,
+    })
+], AuthkitEject.prototype, "controller", void 0);

package/build/commands/expire_scan.d.ts

@@ -0,0 +1,28 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import type { CommandOptions } from '@adonisjs/core/types/ace';
+/**
+ * Varre contas inativas e reporta expiradas/a expirar.
+ *
+ * Mecânica:
+ *   - "Última atividade" = último `login.success` da conta no audit (list capability).
+ *   - Sem audit queryável → aborta com aviso.
+ *   - --warn: envia e-mail de aviso às contas a expirar em breve (deduplicado via audit).
+ *   - --dry-run: reporta sem enviar e-mails nem auditar.
+ *   - --json: output machine-readable (estrutura ExpireScanResult).
+ *
+ * Exemplos:
+ *   node ace authkit:accounts:expire-scan
+ *   node ace authkit:accounts:expire-scan --dry-run
+ *   node ace authkit:accounts:expire-scan --warn
+ *   node ace authkit:accounts:expire-scan --warn --json
+ */
+export default class AuthkitExpireScan extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static help: string[];
+    static options: CommandOptions;
+    dryRun?: boolean;
+    warn?: boolean;
+    json?: boolean;
+    run(): Promise<void>;
+}