@adonis-agora/authkit-core 0.7.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,25 @@
+# @adonis-agora/authkit-core
+
+Contratos compartilhados do AuthKit: `Identity`, `SessionResolver`, tipos de config
+do server e nomes de métricas. Sem runtime — consumido por `@adonis-agora/authkit-server` e `@adonis-agora/authkit-client`.
+
+Normalmente você não instala este pacote diretamente: ele vem como dependência
+do server e do client. Mas, se precisar dos tipos compartilhados:
+
+## Install
+
+```bash
+npm install @adonis-agora/authkit-core
+```
+
+## Usage
+
+```ts
+import type { Identity, SessionResolver } from '@adonis-agora/authkit-core'
+
+const resolver: SessionResolver = {
+  async resolve(): Promise<Identity | null> {
+    return null
+  },
+}
+```

package/build/index.d.ts

@@ -0,0 +1,6 @@
+export type { Identity, SessionResolver } from './src/types/identity.js';
+export type { ClientConfig, TtlConfig, JwksConfig, KeystoreStoreConfig, ObservabilityConfig, ResolvedAuthServerConfig, AccessTokenFormat, AccessTokenResourceConfig, AccessTokensConfig, } from './src/types/server_config.js';
+export { AUTHKIT_METRICS } from './src/metrics.js';
+export type { AuthkitMetricName } from './src/metrics.js';
+export { InMemorySnapshot, NoopRecorder } from './src/metrics_recorder.js';
+export type { MetricsRecorder, MetricsSnapshot } from './src/metrics_recorder.js';

package/build/index.js

@@ -0,0 +1,2 @@
+export { AUTHKIT_METRICS } from './src/metrics.js';
+export { InMemorySnapshot, NoopRecorder } from './src/metrics_recorder.js';

package/build/src/metrics.d.ts

@@ -0,0 +1,15 @@
+/** Nomes canônicos das métricas OTel emitidas pela lib (usados no Plano 3). */
+export declare const AUTHKIT_METRICS: {
+    readonly loginSuccess: "authkit.login.success";
+    readonly loginFailure: "authkit.login.failure";
+    readonly tokenIssued: "authkit.token.issued";
+    readonly refreshRotated: "authkit.refresh.rotated";
+    readonly grantRevoked: "authkit.grant.revoked";
+    readonly sessionsActive: "authkit.sessions.active";
+    readonly passwordHashDuration: "authkit.password.hash.duration";
+    readonly resolveDuration: "authkit.resolve.duration";
+    readonly resolveErrors: "authkit.resolve.errors";
+    readonly jwksRefresh: "authkit.jwks.refresh";
+    readonly tokenRefresh: "authkit.token.refresh";
+};
+export type AuthkitMetricName = (typeof AUTHKIT_METRICS)[keyof typeof AUTHKIT_METRICS];

package/build/src/metrics.js

@@ -0,0 +1,14 @@
+/** Nomes canônicos das métricas OTel emitidas pela lib (usados no Plano 3). */
+export const AUTHKIT_METRICS = {
+    loginSuccess: 'authkit.login.success',
+    loginFailure: 'authkit.login.failure',
+    tokenIssued: 'authkit.token.issued',
+    refreshRotated: 'authkit.refresh.rotated',
+    grantRevoked: 'authkit.grant.revoked',
+    sessionsActive: 'authkit.sessions.active',
+    passwordHashDuration: 'authkit.password.hash.duration',
+    resolveDuration: 'authkit.resolve.duration',
+    resolveErrors: 'authkit.resolve.errors',
+    jwksRefresh: 'authkit.jwks.refresh',
+    tokenRefresh: 'authkit.token.refresh',
+};

package/build/src/metrics_recorder.d.ts

@@ -0,0 +1,33 @@
+import { AUTHKIT_METRICS, type AuthkitMetricName } from './metrics.js';
+/** Recorder de métricas: counters e histograms nomeados. */
+export interface MetricsRecorder {
+    increment(name: AuthkitMetricName, attributes?: Record<string, string | number>): void;
+    record(name: AuthkitMetricName, value: number, attributes?: Record<string, string | number>): void;
+    /** snapshot agregado em memória (para rota JSON / dashboard) */
+    snapshot(): MetricsSnapshot;
+}
+export interface MetricsSnapshot {
+    counters: Record<string, number>;
+    histograms: Record<string, {
+        count: number;
+        sum: number;
+        min: number;
+        max: number;
+    }>;
+    updatedAt: number;
+}
+/** Agregador em memória reaproveitável por qualquer recorder. */
+export declare class InMemorySnapshot {
+    #private;
+    bump(name: string, by?: number): void;
+    observe(name: string, value: number): void;
+    read(): MetricsSnapshot;
+}
+/** No-op: usado quando observability está desligada. */
+export declare class NoopRecorder implements MetricsRecorder {
+    increment(): void;
+    record(): void;
+    snapshot(): MetricsSnapshot;
+}
+export { AUTHKIT_METRICS };
+export type { AuthkitMetricName };

package/build/src/metrics_recorder.js

@@ -0,0 +1,32 @@
+import { AUTHKIT_METRICS } from './metrics.js';
+/** Agregador em memória reaproveitável por qualquer recorder. */
+export class InMemorySnapshot {
+    #counters = {};
+    #histograms = {};
+    #updatedAt = 0;
+    bump(name, by = 1) {
+        this.#counters[name] = (this.#counters[name] ?? 0) + by;
+        this.#updatedAt = Date.now();
+    }
+    observe(name, value) {
+        const h = this.#histograms[name] ?? { count: 0, sum: 0, min: value, max: value };
+        h.count += 1;
+        h.sum += value;
+        h.min = Math.min(h.min, value);
+        h.max = Math.max(h.max, value);
+        this.#histograms[name] = h;
+        this.#updatedAt = Date.now();
+    }
+    read() {
+        return { counters: { ...this.#counters }, histograms: { ...this.#histograms }, updatedAt: this.#updatedAt };
+    }
+}
+/** No-op: usado quando observability está desligada. */
+export class NoopRecorder {
+    increment() { }
+    record() { }
+    snapshot() {
+        return { counters: {}, histograms: {}, updatedAt: 0 };
+    }
+}
+export { AUTHKIT_METRICS };

package/build/src/types/identity.d.ts

@@ -0,0 +1,32 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Identidade resolvida por request a partir das claims OIDC validadas.
+ * Fronteira: só identidade (claims globais) — nada de domínio do app.
+ */
+export interface Identity {
+    /** claim `sub` */
+    userId: string;
+    email: string;
+    /** papéis globais, de uma claim custom (ex.: `roles`) */
+    globalRoles: string[];
+    /** claims OIDC padrão de perfil */
+    profile?: {
+        name?: string;
+        avatarUrl?: string;
+    };
+    /** `sid` quando presente */
+    sessionId?: string;
+    /** `iat` em epoch ms */
+    issuedAt: number;
+    /** `exp` em epoch ms */
+    expiresAt: number;
+    /** claims completas (escape hatch) */
+    raw: Record<string, unknown>;
+}
+/**
+ * Contrato do driver de resolução de sessão (estratégia por request).
+ * v1 do client implementa `resolvers.jwt()`.
+ */
+export interface SessionResolver {
+    resolve(ctx: HttpContext): Promise<Identity | null>;
+}

package/build/src/types/identity.js

@@ -0,0 +1 @@
+export {};

package/build/src/types/server_config.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Client OIDC persistido no adapter/DB, gerenciável via console admin ou Admin API
+ * em runtime. Usado internamente pela lib para representar clients em memória.
+ */
+export interface ClientConfig {
+    clientId: string;
+    clientSecret?: string;
+    redirectUris: string[];
+    postLogoutRedirectUris?: string[];
+    grants?: string[];
+    /** 'none' para public clients (SPA com PKCE) */
+    tokenEndpointAuthMethod?: 'client_secret_basic' | 'client_secret_post' | 'none';
+    /**
+     * Endpoint do RP que recebe o POST de OIDC Back-Channel Logout. Quando definido,
+     * o IdP envia um `logout_token` para esta URI ao encerrar a sessão/grant do usuário.
+     */
+    backchannelLogoutUri?: string;
+    /**
+     * Exige que o `logout_token` inclua a claim `sid` (session id). Mapeado para
+     * `backchannel_logout_session_required` do oidc-provider. Default: false.
+     */
+    backchannelLogoutSessionRequired?: boolean;
+}
+export interface TtlConfig {
+    accessToken?: string | number;
+    refreshToken?: string | number;
+    idToken?: string | number;
+    session?: string | number;
+}
+/** Config de onde o keystore managed mora. String = atalho p/ { driver:'file', path }. */
+export type KeystoreStoreConfig = string | {
+    driver: 'file';
+    path: string;
+} | {
+    driver: 'drive';
+    disk?: string;
+    key: string;
+} | {
+    driver: 'lucid';
+    table?: string;
+    connection?: string;
+    key?: string;
+} | {
+    driver: 'redis';
+    connection?: string;
+    key?: string;
+} | {
+    driver: 'hashicorp-vault';
+    endpoint: string;
+    path: string;
+    token?: string;
+    mount?: string;
+    field?: string;
+} | {
+    driver: 'aws-secrets-manager';
+    secretId: string;
+    region?: string;
+} | {
+    driver: 'gcp-secret-manager';
+    name: string;
+} | {
+    driver: 'azure-key-vault';
+    vaultUrl: string;
+    secretName: string;
+};
+export interface JwksConfig {
+    /** 'managed' = lib gera/rotaciona/persiste; 'jwks' = fornecido inline */
+    source: 'managed' | 'jwks';
+    /** usado quando source='managed' */
+    rotationDays?: number;
+    algorithm?: 'RS256' | 'ES256' | 'PS256' | 'EdDSA';
+    /**
+     * Onde o keystore PRIVADO managed é persistido. String = atalho p/ arquivo
+     * (`{driver:'file', path}`). Objeto `{ driver }` = cofre (file/drive/vault).
+     * Ausente = chave efêmera por boot (sem rotação real).
+     */
+    store?: KeystoreStoreConfig;
+    /** Encripta o keystore em repouso (APP_KEY). Default backend-aware: file/drive ON, vault real OFF. */
+    encrypt?: boolean;
+    /** usado quando source='jwks' */
+    keys?: Record<string, unknown>[];
+}
+export interface ObservabilityConfig {
+    metrics?: boolean;
+    jsonRoutes?: boolean;
+    dashboard?: boolean;
+}
+/** Formato de emissão de um Access Token. */
+export type AccessTokenFormat = 'opaque' | 'jwt';
+/**
+ * Configuração de um Resource Server (API) endereçável por um resource indicator
+ * (RFC 8707). O resource indicator é a CHAVE no mapa `resources` — uma URI que
+ * identifica a API (ex.: 'https://api.acme.com'). Quando o client solicita esse
+ * `resource` no authorize/token, o Access Token emitido herda estas opções.
+ */
+export interface AccessTokenResourceConfig {
+    /**
+     * Valor da claim `aud` do JWT AT. Default: o próprio resource indicator (a chave).
+     */
+    audience?: string;
+    /**
+     * Scopes que ESTA API aceita (space/array). Quando omitido, todos os scopes do
+     * provider são oferecidos a esta resource.
+     */
+    scopes?: string[];
+    /** Formato do AT para esta resource. Default: herda o `accessTokens.format`. */
+    format?: AccessTokenFormat;
+    /** TTL do AT (segundos) para esta resource. Default: herda `ttl.accessToken`. */
+    expiresIn?: number;
+}
+/**
+ * Access Tokens (RFC 9068 — JWT Profile for OAuth 2.0 Access Tokens).
+ *
+ * - `format: 'opaque'` (DEFAULT): o AT é uma string opaca introspecionável (comportamento atual).
+ * - `format: 'jwt'`: TODO AT vira um JWT RFC 9068 (`typ: at+jwt`, claims
+ *   iss/sub/aud/exp/iat/jti/client_id/scope), assinado com a chave do JWKS e
+ *   validável só com o discovery/jwks_uri.
+ *
+ * O `audience` (modo simples jwt) define a claim `aud` do token; default = issuer.
+ *
+ * `resources` mapeia resource indicators (RFC 8707) → configuração por API: cada
+ * chave é a URI da API que o client solicita via `resource`, permitindo audiences,
+ * scopes, formato e TTL distintos por API. O caso simples NÃO precisa de `resources`.
+ */
+export interface AccessTokensConfig {
+    /** Formato default de TODOS os ATs sem resource explícito. Default: 'opaque'. */
+    format?: AccessTokenFormat;
+    /**
+     * Claim `aud` do JWT AT no modo simples (sem `resources`). Também é o resource
+     * indicator default usado quando `format: 'jwt'`. Default: o issuer.
+     */
+    audience?: string;
+    /** Resource Servers (APIs) endereçáveis por resource indicator (RFC 8707). */
+    resources?: Record<string, AccessTokenResourceConfig>;
+}
+/** Forma normalizada do config do server (pós-`defineConfig`). */
+export interface ResolvedAuthServerConfig {
+    issuer: string;
+    clients: ClientConfig[];
+    ttl: Required<TtlConfig>;
+    jwks: JwksConfig;
+    globalRolesClaim: string;
+    cookieKeys: string[];
+    observability: ObservabilityConfig;
+}

package/build/src/types/server_config.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@adonis-agora/authkit-core",
+  "version": "0.7.0",
+  "description": "Shared core types and utilities for AuthKit — the AdonisJS OIDC/OAuth2 server and client toolkits.",
+  "license": "MIT",
+  "author": "dudousxd",
+  "homepage": "https://github.com/DavideCarvalho/adonis-authkit/tree/main/packages/authkit-core#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DavideCarvalho/adonis-authkit.git",
+    "directory": "packages/authkit-core"
+  },
+  "bugs": {
+    "url": "https://github.com/DavideCarvalho/adonis-authkit/issues"
+  },
+  "keywords": [
+    "adonisjs",
+    "oidc",
+    "oauth2",
+    "openid-connect",
+    "authentication",
+    "authkit"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "files": [
+    "build"
+  ],
+  "exports": {
+    ".": "./build/index.js",
+    "./types": "./build/index.js"
+  },
+  "devDependencies": {
+    "@adonisjs/core": "7.3.3",
+    "@adonisjs/tsconfig": "2.0.0",
+    "@types/node": "25.9.1",
+    "typescript": "6.0.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}