@adonis-agora/authkit-testing 0.3.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,93 @@
+# @adonis-agora/authkit-testing
+
+Test helpers so **host apps** built on AuthKit can test auth flows without booting
+an IdP. Mint real signed ID tokens validated by a local JWKS, fake the
+`ctx.auth` authenticator, fake an account store, and build valid identities.
+
+```sh
+pnpm add -D @adonis-agora/authkit-testing
+```
+
+## API
+
+### `createTestIdentity(overrides?)`
+
+Returns a valid `Identity` with sane defaults.
+
+```ts
+import { createTestIdentity } from '@adonis-agora/authkit-testing'
+
+const identity = createTestIdentity({ globalRoles: ['ADMIN'] })
+```
+
+### `mintTestIdToken({ issuer, clientId, claims?, key?, expiresInSeconds? })`
+
+Mints a **real** RS256-signed JWT plus the public JWKS that validates it. Returns
+`{ token, key, jwks }`.
+
+```ts
+import { mintTestIdToken, serveJwks } from '@adonis-agora/authkit-testing'
+import { resolvers } from '@adonis-agora/authkit-client'
+
+const { token, jwks } = await mintTestIdToken({
+  issuer: 'https://idp.test',
+  clientId: 'my-app',
+  claims: { sub: 'user-42', email: 'jane@test.dev', roles: ['ADMIN'] },
+})
+
+// Serve the JWKS in-process so resolvers.jwt({ jwksUri }) can validate it.
+const served = await serveJwks(jwks)
+const factory = resolvers.jwt({ jwksUri: served.jwksUri })
+const resolver = await factory.resolver({
+  issuer: 'https://idp.test',
+  clientId: 'my-app',
+  sessionKey: 'authkit',
+  globalRolesClaim: 'roles',
+})
+// ... use resolver in your host test, then:
+await served.close()
+```
+
+The `JwtResolver` uses `createRemoteJWKSet`, so it needs a URL — `serveJwks()`
+provides one locally with no external network. You can also reuse a single
+keypair across tokens via `generateTestKeyPair()` + the `key` option, or get the
+raw public JWKS object with `jwksFromKey(key)` / `testJwks(key)`.
+
+### `fakeAuthenticator({ identity?, user?, appRoles? })`
+
+Object satisfying the client's `Authenticator` surface, for injecting into
+`ctx.auth` in controller tests.
+
+```ts
+import { fakeAuthenticator } from '@adonis-agora/authkit-testing'
+
+const auth = fakeAuthenticator({
+  identity: createTestIdentity({ globalRoles: ['ADMIN'] }),
+  appRoles: ['editor'],
+})
+auth.hasGlobalRole('ADMIN') // true
+await auth.hasAppRole('editor') // true
+```
+
+Pass `identity: null` to simulate an anonymous request.
+
+### `fakeAccountStore(options?)`
+
+A capability-aware fake `AccountStore`. The core methods are always present;
+MFA, passkeys and account-security capabilities are opt-in so you can exercise
+the server's `supportsMfa` / `supportsPasskeys` / `supportsAccountSecurity`
+type guards.
+
+```ts
+import { fakeAccountStore } from '@adonis-agora/authkit-testing'
+
+const store = fakeAccountStore({
+  account: { id: 'u1', email: 'a@b.com', globalRoles: ['ADMIN'] },
+  withMfa: true,
+  overrides: { findById: async () => null },
+})
+```
+
+## License
+
+MIT

package/build/index.d.ts

@@ -0,0 +1,7 @@
+export { createTestIdentity } from './src/identity.js';
+export { mintTestIdToken, generateTestKeyPair, testJwks, jwksFromKey, serveJwks, } from './src/jwt.js';
+export type { TestKeyPair, MintTestIdTokenOptions, MintedToken, ServedJwks, } from './src/jwt.js';
+export { fakeAuthenticator } from './src/authenticator.js';
+export type { FakeAuthenticatorLike, FakeAuthenticatorOptions } from './src/authenticator.js';
+export { fakeAccountStore } from './src/account_store.js';
+export type { FakeAuthAccount, FakeAccountStoreOptions } from './src/account_store.js';

package/build/index.js

@@ -0,0 +1,4 @@
+export { createTestIdentity } from './src/identity.js';
+export { mintTestIdToken, generateTestKeyPair, testJwks, jwksFromKey, serveJwks, } from './src/jwt.js';
+export { fakeAuthenticator } from './src/authenticator.js';
+export { fakeAccountStore } from './src/account_store.js';

package/build/src/account_store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * DTO público da conta (espelha `AuthAccount` do server). Mantido local para o
+ * pacote de testing não depender do server em runtime (que arrasta Lucid etc.).
+ */
+export interface FakeAuthAccount {
+    id: string;
+    email: string;
+    globalRoles?: string[];
+    name?: string;
+    avatarUrl?: string;
+}
+export interface FakeAccountStoreOptions {
+    /** conta fixa retornada por findById/verifyCredentials/findByEmail. */
+    account?: FakeAuthAccount;
+    /** inclui métodos da capacidade MfaCapability (supportsMfa → true). */
+    withMfa?: boolean;
+    /** inclui métodos da capacidade WebauthnCapability (supportsPasskeys → true). */
+    withPasskeys?: boolean;
+    /** inclui métodos da capacidade AccountSecurityCapability (supportsAccountSecurity → true). */
+    withAccountSecurity?: boolean;
+    /** sobrescreve qualquer método individualmente. */
+    overrides?: Record<string, unknown>;
+}
+/**
+ * AccountStore mínimo para testes de host, capability-aware. O núcleo
+ * (findById/verifyCredentials/create/...) e a capacidade de provider-identity e
+ * admin sempre estão presentes; MFA, passkeys e account-security são opt-in via
+ * flags para exercitar os type guards `supports*` do server.
+ */
+export declare function fakeAccountStore(options?: FakeAccountStoreOptions): Record<string, unknown>;

package/build/src/account_store.js

@@ -0,0 +1,47 @@
+/**
+ * AccountStore mínimo para testes de host, capability-aware. O núcleo
+ * (findById/verifyCredentials/create/...) e a capacidade de provider-identity e
+ * admin sempre estão presentes; MFA, passkeys e account-security são opt-in via
+ * flags para exercitar os type guards `supports*` do server.
+ */
+export function fakeAccountStore(options = {}) {
+    const fixed = options.account ?? {
+        id: 'u1',
+        email: 'a@b.com',
+        globalRoles: ['ADMIN'],
+    };
+    const core = {
+        findById: async (id) => ({ ...fixed, id }),
+        verifyCredentials: async (email) => (email === fixed.email ? { ...fixed } : null),
+        findByEmail: async (email) => (email === fixed.email ? { ...fixed } : null),
+        create: async (input) => ({
+            id: 'new',
+            email: input.email,
+            globalRoles: input.globalRoles ?? [],
+        }),
+        findByProviderIdentity: async () => null,
+        linkProviderIdentity: async () => { },
+        issuePasswordResetToken: async () => null,
+        consumePasswordResetToken: async () => false,
+        issueEmailVerificationToken: async () => null,
+        consumeEmailVerificationToken: async () => false,
+        listAccounts: async () => ({ data: [{ ...fixed }], total: 1 }),
+        setGlobalRoles: async () => { },
+    };
+    if (options.withMfa) {
+        core.getMfaState = async () => ({ enabled: false });
+        core.enableMfa = async () => { };
+        core.disableMfa = async () => { };
+    }
+    if (options.withPasskeys) {
+        core.listPasskeys = async () => [];
+        core.registerPasskey = async () => { };
+        core.deletePasskey = async () => { };
+    }
+    if (options.withAccountSecurity) {
+        core.changePassword = async () => true;
+        core.requestEmailChange = async () => null;
+        core.confirmEmailChange = async () => ({ ok: false });
+    }
+    return { ...core, ...(options.overrides ?? {}) };
+}

package/build/src/authenticator.d.ts

@@ -0,0 +1,27 @@
+import type { Identity } from '@adonis-agora/authkit-core';
+/**
+ * Superfície pública do `Authenticator` do client (o que `ctx.auth` expõe).
+ * Reproduzida aqui para não acoplar o pacote de testing ao client em runtime.
+ */
+export interface FakeAuthenticatorLike {
+    getIdentity(): Promise<Identity | null>;
+    readonly identity: Identity | null;
+    authenticate(): Promise<Identity>;
+    check(): Promise<boolean>;
+    hasGlobalRole(role: string): boolean;
+    hasAppRole(role: string): Promise<boolean>;
+    getUser(): Promise<unknown>;
+}
+export interface FakeAuthenticatorOptions {
+    /** identidade resolvida; default = {@link createTestIdentity}. Passe `null` para simular anônimo. */
+    identity?: Identity | null;
+    /** usuário de domínio retornado por `getUser()`. */
+    user?: unknown;
+    /** roles de app reconhecidas por `hasAppRole`. */
+    appRoles?: string[];
+}
+/**
+ * Cria um objeto que satisfaz a superfície do `Authenticator` do client para
+ * injetar em `ctx.auth` em testes de controller — sem resolver tokens de verdade.
+ */
+export declare function fakeAuthenticator(options?: FakeAuthenticatorOptions): FakeAuthenticatorLike;

package/build/src/authenticator.js

@@ -0,0 +1,39 @@
+import { createTestIdentity } from './identity.js';
+/**
+ * Cria um objeto que satisfaz a superfície do `Authenticator` do client para
+ * injetar em `ctx.auth` em testes de controller — sem resolver tokens de verdade.
+ */
+export function fakeAuthenticator(options = {}) {
+    const identity = options.identity === undefined ? createTestIdentity() : options.identity;
+    const appRoles = options.appRoles ?? [];
+    const user = 'user' in options ? options.user : identity;
+    return {
+        async getIdentity() {
+            return identity;
+        },
+        get identity() {
+            return identity;
+        },
+        async authenticate() {
+            if (!identity)
+                throw new Error('Não autenticado');
+            return identity;
+        },
+        async check() {
+            return identity !== null;
+        },
+        hasGlobalRole(role) {
+            return identity?.globalRoles.includes(role) ?? false;
+        },
+        async hasAppRole(role) {
+            if (!identity)
+                return false;
+            return appRoles.includes(role);
+        },
+        async getUser() {
+            if (!identity)
+                return null;
+            return user;
+        },
+    };
+}

package/build/src/identity.d.ts

@@ -0,0 +1,6 @@
+import type { Identity } from '@adonis-agora/authkit-core';
+/**
+ * Cria uma {@link Identity} válida com valores padrão sãos para usar em testes.
+ * Sobrescreva qualquer campo via `overrides`.
+ */
+export declare function createTestIdentity(overrides?: Partial<Identity>): Identity;

package/build/src/identity.js

@@ -0,0 +1,18 @@
+/**
+ * Cria uma {@link Identity} válida com valores padrão sãos para usar em testes.
+ * Sobrescreva qualquer campo via `overrides`.
+ */
+export function createTestIdentity(overrides = {}) {
+    const now = Date.now();
+    return {
+        userId: 'test-user-id',
+        email: 'test@example.com',
+        globalRoles: [],
+        profile: { name: 'Test User', avatarUrl: undefined },
+        sessionId: 'test-session-id',
+        issuedAt: now,
+        expiresAt: now + 60 * 60 * 1000,
+        raw: {},
+        ...overrides,
+    };
+}

package/build/src/jwt.d.ts

@@ -0,0 +1,62 @@
+import { type Server } from 'node:http';
+import { type JWK, type KeyLike } from 'jose';
+export interface TestKeyPair {
+    privateKey: KeyLike;
+    publicKey: KeyLike;
+    kid: string;
+}
+/** Gera um par de chaves RS256 extraível com um `kid` estável, para minting de tokens em testes. */
+export declare function generateTestKeyPair(kid?: string): Promise<TestKeyPair>;
+export interface MintTestIdTokenOptions {
+    /** claim `iss` — deve casar com o `issuer` configurado no resolver. */
+    issuer: string;
+    /** claim `aud` — deve casar com o `audience`/clientId configurado no resolver. */
+    clientId: string;
+    /** claims extras / overrides (ex.: `sub`, `email`, `roles`). */
+    claims?: Record<string, unknown>;
+    /** par de chaves para assinar; um novo é gerado se omitido. */
+    key?: TestKeyPair;
+    /** validade em segundos (default 3600). */
+    expiresInSeconds?: number;
+}
+export interface MintedToken {
+    /** o JWT assinado (RS256) real. */
+    token: string;
+    /** par de chaves usado (gerado ou fornecido). */
+    key: TestKeyPair;
+    /** JWKS público (apenas a chave pública) para validação local. */
+    jwks: {
+        keys: JWK[];
+    };
+}
+/**
+ * Emite um ID token JWT REAL assinado com RS256 (não um mock). O JWKS público
+ * resultante valida o token através do `JwtResolver` quando servido em
+ * {@link serveJwks} e apontado por `resolvers.jwt({ jwksUri })`.
+ */
+export declare function mintTestIdToken(options: MintTestIdTokenOptions): Promise<MintedToken>;
+/** Exporta o JWKS público (uma chave) de um par de chaves de teste. */
+export declare function testJwks(key: TestKeyPair): Promise<{
+    keys: JWK[];
+}>;
+/** Objeto pronto para alimentar um `createLocalJWKSet` — o JWKS público como `{ keys }`. */
+export declare function jwksFromKey(key: TestKeyPair): Promise<{
+    keys: JWK[];
+}>;
+export interface ServedJwks {
+    /** URL do endpoint JWKS in-process (passe ao `resolvers.jwt({ jwksUri })`). */
+    jwksUri: string;
+    /** servidor http subjacente. */
+    server: Server;
+    /** fecha o servidor (chame no `group.teardown`). */
+    close: () => Promise<void>;
+}
+/**
+ * Sobe um servidor http in-process que serve o JWKS público em
+ * `GET /.well-known/jwks.json`. O `JwtResolver` usa `createRemoteJWKSet`, então
+ * ele só aceita uma URL — este helper fornece essa URL localmente sem rede
+ * externa nem IdP.
+ */
+export declare function serveJwks(jwks: {
+    keys: JWK[];
+}): Promise<ServedJwks>;

package/build/src/jwt.js

@@ -0,0 +1,73 @@
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { SignJWT, exportJWK, generateKeyPair, } from 'jose';
+const ALG = 'RS256';
+/** Gera um par de chaves RS256 extraível com um `kid` estável, para minting de tokens em testes. */
+export async function generateTestKeyPair(kid = randomUUID()) {
+    const { privateKey, publicKey } = await generateKeyPair(ALG, { extractable: true });
+    return { privateKey, publicKey, kid };
+}
+/**
+ * Emite um ID token JWT REAL assinado com RS256 (não um mock). O JWKS público
+ * resultante valida o token através do `JwtResolver` quando servido em
+ * {@link serveJwks} e apontado por `resolvers.jwt({ jwksUri })`.
+ */
+export async function mintTestIdToken(options) {
+    const key = options.key ?? (await generateTestKeyPair());
+    const expiresIn = options.expiresInSeconds ?? 3600;
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const baseClaims = {
+        sub: 'test-user-id',
+        email: 'test@example.com',
+        ...options.claims,
+    };
+    const token = await new SignJWT(baseClaims)
+        .setProtectedHeader({ alg: ALG, kid: key.kid })
+        .setIssuer(options.issuer)
+        .setAudience(options.clientId)
+        .setIssuedAt(nowSeconds)
+        .setExpirationTime(nowSeconds + expiresIn)
+        .sign(key.privateKey);
+    return { token, key, jwks: await testJwks(key) };
+}
+/** Exporta o JWKS público (uma chave) de um par de chaves de teste. */
+export async function testJwks(key) {
+    const jwk = await exportJWK(key.publicKey);
+    jwk.use = 'sig';
+    jwk.alg = ALG;
+    jwk.kid = key.kid;
+    return { keys: [jwk] };
+}
+/** Objeto pronto para alimentar um `createLocalJWKSet` — o JWKS público como `{ keys }`. */
+export async function jwksFromKey(key) {
+    return testJwks(key);
+}
+/**
+ * Sobe um servidor http in-process que serve o JWKS público em
+ * `GET /.well-known/jwks.json`. O `JwtResolver` usa `createRemoteJWKSet`, então
+ * ele só aceita uma URL — este helper fornece essa URL localmente sem rede
+ * externa nem IdP.
+ */
+export async function serveJwks(jwks) {
+    const body = JSON.stringify(jwks);
+    const server = createServer((req, res) => {
+        if (req.url?.startsWith('/.well-known/jwks.json')) {
+            res.writeHead(200, { 'content-type': 'application/json' });
+            res.end(body);
+            return;
+        }
+        res.writeHead(404);
+        res.end();
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Falha ao obter a porta do servidor JWKS de teste');
+    }
+    const jwksUri = `http://127.0.0.1:${address.port}/.well-known/jwks.json`;
+    return {
+        jwksUri,
+        server,
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+    };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@adonis-agora/authkit-testing",
+  "version": "0.3.0",
+  "description": "Test helpers for apps built on AuthKit: mint real signed ID tokens with a local JWKS, fake authenticators and account stores, and build valid identities — so host apps can test auth flows without booting an IdP.",
+  "license": "MIT",
+  "author": "dudousxd",
+  "homepage": "https://github.com/DavideCarvalho/adonis-authkit/tree/main/packages/authkit-testing#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DavideCarvalho/adonis-authkit.git",
+    "directory": "packages/authkit-testing"
+  },
+  "bugs": {
+    "url": "https://github.com/DavideCarvalho/adonis-authkit/issues"
+  },
+  "keywords": [
+    "adonisjs",
+    "authentication",
+    "authkit",
+    "testing",
+    "jwt",
+    "jwks",
+    "oidc"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "files": [
+    "build"
+  ],
+  "exports": {
+    ".": "./build/index.js",
+    "./types": "./build/index.js"
+  },
+  "dependencies": {
+    "jose": "^5.9.0",
+    "@adonis-agora/authkit-core": "0.7.0"
+  },
+  "devDependencies": {
+    "@adonisjs/tsconfig": "2.0.0",
+    "@japa/assert": "4.2.0",
+    "@japa/runner": "5.3.0",
+    "@poppinss/ts-exec": "1.4.4",
+    "@types/node": "25.9.1",
+    "typescript": "6.0.3",
+    "@adonis-agora/authkit-client": "0.9.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import=@poppinss/ts-exec bin/test.ts"
+  }
+}