@dudousxd/adonis-authkit-server 0.6.0 → 0.8.0

package/build/src/host/admin_api/api_users_controller.d.ts

@@ -0,0 +1,78 @@
+import '../augmentations.js';
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * Recurso de usuários da Admin REST API (R6). JSON puro (camelCase), erros no
+ * envelope `{ error: { code, message } }`. Toda escrita audita com `actor: 'admin-api'`.
+ */
+export default class ApiUsersController {
+    #private;
+    /** GET /users — listagem paginada com busca por e-mail. */
+    index(ctx: HttpContext): Promise<{
+        data: any[];
+        total: any;
+        page: number;
+        limit: number;
+    }>;
+    /** GET /users/:id */
+    show(ctx: HttpContext): Promise<void | {
+        id: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+        globalRoles: string[];
+        disabled: boolean;
+    }>;
+    /** POST /users — { email, name?, password? | invite?:true }. */
+    store(ctx: HttpContext): Promise<void | {
+        invited: boolean;
+        id: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+        globalRoles: string[];
+        disabled: boolean;
+    }>;
+    /** PATCH /users/:id — { globalRoles?, name?, avatarUrl? }. */
+    update(ctx: HttpContext): Promise<void | {
+        id: string;
+        email: string;
+        name: string | null;
+        avatarUrl: string | null;
+        globalRoles: string[];
+        disabled: boolean;
+    }>;
+    /** POST /users/:id/disable */
+    disable(ctx: HttpContext): Promise<void | {
+        id: any;
+        disabled: boolean;
+    }>;
+    /** POST /users/:id/enable */
+    enable(ctx: HttpContext): Promise<void | {
+        id: any;
+        disabled: boolean;
+    }>;
+    /** POST /users/:id/reset-password — envia o e-mail de reset. */
+    resetPassword(ctx: HttpContext): Promise<void | {
+        id: any;
+        sent: boolean;
+    }>;
+    /** GET /users/:id/sessions — sessões + grants ativos. */
+    sessions(ctx: HttpContext): Promise<{
+        canList: boolean;
+        sessions: {
+            id: string;
+            accountId: string;
+            loginTs: number | null;
+            amr: string[];
+        }[];
+        grants: {
+            id: string;
+            accountId: string;
+            clientId: string | null;
+            accessTokens: number;
+            refreshTokens: number;
+        }[];
+    }>;
+    /** POST /users/:id/revoke-sessions — revoga todas as sessões/grants. */
+    revokeSessions(ctx: HttpContext): Promise<import("../admin_sessions_service.js").RevokeResult>;
+}

package/build/src/host/admin_api/api_users_controller.js

@@ -0,0 +1,135 @@
+import '../augmentations.js';
+import { AdminUsersService } from './admin_users_service.js';
+import { AdminSessionsService } from '../admin_sessions_service.js';
+import { userDto, sessionDto, grantDto, apiError } from './dto.js';
+const PAGE_SIZE = 20;
+/** Lê a config + monta o actor `admin-api` para auditoria. */
+async function ctxBits(ctx) {
+    const service = await ctx.containerResolver.make('authkit.server');
+    const cfg = service.config;
+    const actor = { actorId: null, ip: ctx.request.ip?.() ?? null, source: 'admin-api' };
+    return { service, cfg, actor };
+}
+/**
+ * Recurso de usuários da Admin REST API (R6). JSON puro (camelCase), erros no
+ * envelope `{ error: { code, message } }`. Toda escrita audita com `actor: 'admin-api'`.
+ */
+export default class ApiUsersController {
+    /** GET /users — listagem paginada com busca por e-mail. */
+    async index(ctx) {
+        const { cfg } = await ctxBits(ctx);
+        const search = ctx.request.input('search', '').trim();
+        const page = Math.max(1, Number.parseInt(ctx.request.input('page', '1'), 10) || 1);
+        const limit = Math.max(1, Math.min(100, Number.parseInt(ctx.request.input('limit', String(PAGE_SIZE)), 10) || PAGE_SIZE));
+        const result = await cfg.accountStore.listAccounts({ search, page, limit });
+        const users = new AdminUsersService(cfg);
+        const data = await Promise.all(result.data.map(async (u) => userDto(u, await users.isDisabled(u.id))));
+        return { data, total: result.total, page, limit };
+    }
+    /** GET /users/:id */
+    async show(ctx) {
+        const { cfg } = await ctxBits(ctx);
+        const id = ctx.request.param('id');
+        const account = await cfg.accountStore.findById(id);
+        if (!account)
+            return ctx.response.notFound(apiError('not_found', 'Usuário não encontrado.'));
+        const disabled = await new AdminUsersService(cfg).isDisabled(id);
+        return userDto(account, disabled);
+    }
+    /** POST /users — { email, name?, password? | invite?:true }. */
+    async store(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const email = ctx.request.input('email', '').trim();
+        const name = ctx.request.input('name') ?? null;
+        const password = ctx.request.input('password') ?? null;
+        const invite = ctx.request.input('invite') === true || ctx.request.input('invite') === 'true';
+        if (!email)
+            return ctx.response.badRequest(apiError('invalid_request', 'O campo email é obrigatório.'));
+        const users = new AdminUsersService(cfg);
+        const result = await users.create(ctx, { email, name, password, invite }, actor);
+        if (!result.ok) {
+            return ctx.response.conflict(apiError('email_taken', 'Já existe uma conta com este e-mail.'));
+        }
+        ctx.response.status(201);
+        return { ...userDto(result.account), invited: result.invited };
+    }
+    /** PATCH /users/:id — { globalRoles?, name?, avatarUrl? }. */
+    async update(ctx) {
+        const { cfg } = await ctxBits(ctx);
+        const id = ctx.request.param('id');
+        const account = await cfg.accountStore.findById(id);
+        if (!account)
+            return ctx.response.notFound(apiError('not_found', 'Usuário não encontrado.'));
+        const users = new AdminUsersService(cfg);
+        const roles = ctx.request.input('globalRoles');
+        if (Array.isArray(roles)) {
+            const normalized = Array.from(new Set(roles.map((r) => String(r).trim()).filter(Boolean)));
+            await users.setGlobalRoles(id, normalized);
+        }
+        const name = ctx.request.input('name');
+        const avatarUrl = ctx.request.input('avatarUrl');
+        if (name !== undefined || avatarUrl !== undefined) {
+            const patch = {};
+            if (name !== undefined)
+                patch.name = name;
+            if (avatarUrl !== undefined)
+                patch.avatarUrl = avatarUrl;
+            await users.updateProfile(id, patch);
+        }
+        const updated = await cfg.accountStore.findById(id);
+        return userDto(updated, await users.isDisabled(id));
+    }
+    /** POST /users/:id/disable */
+    async disable(ctx) {
+        return this.#setStatus(ctx, true);
+    }
+    /** POST /users/:id/enable */
+    async enable(ctx) {
+        return this.#setStatus(ctx, false);
+    }
+    async #setStatus(ctx, disable) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const id = ctx.request.param('id');
+        const applied = await new AdminUsersService(cfg).setStatus(id, disable, actor);
+        if (!applied) {
+            return ctx.response.conflict(apiError('capability_unsupported', 'O store de contas não suporta habilitar/desabilitar.'));
+        }
+        return { id, disabled: disable };
+    }
+    /** POST /users/:id/reset-password — envia o e-mail de reset. */
+    async resetPassword(ctx) {
+        const { cfg, actor } = await ctxBits(ctx);
+        const id = ctx.request.param('id');
+        const account = await new AdminUsersService(cfg).resetPassword(ctx, id, actor);
+        if (!account)
+            return ctx.response.notFound(apiError('not_found', 'Usuário não encontrado.'));
+        return { id, sent: true };
+    }
+    /** GET /users/:id/sessions — sessões + grants ativos. */
+    async sessions(ctx) {
+        const { service } = await ctxBits(ctx);
+        const id = ctx.request.param('id');
+        const admin = new AdminSessionsService(service);
+        const sessions = await admin.listSessions(id);
+        const grants = await admin.listGrants(id);
+        return {
+            canList: admin.canList,
+            sessions: sessions.map(sessionDto),
+            grants: grants.map(grantDto),
+        };
+    }
+    /** POST /users/:id/revoke-sessions — revoga todas as sessões/grants. */
+    async revokeSessions(ctx) {
+        const { service, cfg, actor } = await ctxBits(ctx);
+        const id = ctx.request.param('id');
+        const result = await new AdminSessionsService(service).revokeAll(id);
+        await cfg.audit?.record({
+            type: 'session.revoked_all',
+            accountId: id,
+            actorId: actor.actorId,
+            ip: actor.ip,
+            metadata: { actor: actor.source, ...result },
+        });
+        return result;
+    }
+}

package/build/src/host/admin_api/dto.d.ts

@@ -0,0 +1,57 @@
+import type { AuthAccount } from '../../accounts/account_store.js';
+import type { AdminClient, CreatedClient } from '../admin_clients_service.js';
+import type { AdminSession, AdminGrant } from '../admin_sessions_service.js';
+import type { StoredAuditEvent } from '../../audit/audit_sink.js';
+/** Projeta uma conta para a forma JSON (camelCase) da Admin REST API. */
+export declare function userDto(account: AuthAccount, disabled?: boolean): {
+    id: string;
+    email: string;
+    name: string | null;
+    avatarUrl: string | null;
+    globalRoles: string[];
+    disabled: boolean;
+};
+export declare function clientDto(client: AdminClient): {
+    clientId: string;
+    confidential: boolean;
+    grants: string[];
+    redirectUris: string[];
+    postLogoutRedirectUris: string[];
+    tokenEndpointAuthMethod: string;
+};
+/** Inclui o secret (mostrado UMA vez) em create/regenerate. */
+export declare function createdClientDto(created: CreatedClient): {
+    clientId: string;
+    clientSecret: string | null;
+};
+export declare function sessionDto(session: AdminSession): {
+    id: string;
+    accountId: string;
+    loginTs: number | null;
+    amr: string[];
+};
+export declare function grantDto(grant: AdminGrant): {
+    id: string;
+    accountId: string;
+    clientId: string | null;
+    accessTokens: number;
+    refreshTokens: number;
+};
+export declare function auditDto(event: StoredAuditEvent): {
+    id: string;
+    type: import("../../audit/audit_sink.js").AuditEventType;
+    accountId: string | null;
+    email: string | null;
+    clientId: string | null;
+    actorId: string | null;
+    ip: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: string | null;
+};
+/** Envelope de erro padrão da Admin REST API. */
+export declare function apiError(code: string, message: string): {
+    error: {
+        code: string;
+        message: string;
+    };
+};

package/build/src/host/admin_api/dto.js

@@ -0,0 +1,62 @@
+/** Projeta uma conta para a forma JSON (camelCase) da Admin REST API. */
+export function userDto(account, disabled = false) {
+    return {
+        id: account.id,
+        email: account.email,
+        name: account.name ?? null,
+        avatarUrl: account.avatarUrl ?? null,
+        globalRoles: account.globalRoles ?? [],
+        disabled,
+    };
+}
+export function clientDto(client) {
+    return {
+        clientId: client.clientId,
+        confidential: client.confidential,
+        grants: client.grants,
+        redirectUris: client.redirectUris,
+        postLogoutRedirectUris: client.postLogoutRedirectUris,
+        tokenEndpointAuthMethod: client.tokenEndpointAuthMethod,
+    };
+}
+/** Inclui o secret (mostrado UMA vez) em create/regenerate. */
+export function createdClientDto(created) {
+    return {
+        clientId: created.clientId,
+        clientSecret: created.clientSecret ?? null,
+    };
+}
+export function sessionDto(session) {
+    return {
+        id: session.id,
+        accountId: session.accountId,
+        loginTs: session.loginTs ?? null,
+        amr: session.amr ?? [],
+    };
+}
+export function grantDto(grant) {
+    return {
+        id: grant.id,
+        accountId: grant.accountId,
+        clientId: grant.clientId ?? null,
+        accessTokens: grant.accessTokens,
+        refreshTokens: grant.refreshTokens,
+    };
+}
+export function auditDto(event) {
+    return {
+        id: event.id,
+        type: event.type,
+        accountId: event.accountId ?? null,
+        email: event.email ?? null,
+        clientId: event.clientId ?? null,
+        actorId: event.actorId ?? null,
+        ip: event.ip ?? null,
+        metadata: event.metadata ?? null,
+        createdAt: event.createdAt instanceof Date ? event.createdAt.toISOString() : event.createdAt,
+    };
+}
+/** Envelope de erro padrão da Admin REST API. */
+export function apiError(code, message) {
+    return { error: { code, message } };
+}

package/build/src/host/admin_api/token_verify_service.d.ts

@@ -0,0 +1,34 @@
+import type { ResolvedServerConfig } from '../../define_config.js';
+/** Resultado de introspecção genérica (PAT ou opaque access token). */
+export type VerifyResult = {
+    active: false;
+} | {
+    active: true;
+    /** 'pat' (Personal Access Token) ou 'access_token' (opaque AT do provider). */
+    tokenType: 'pat' | 'access_token';
+    sub: string;
+    email?: string | null;
+    name?: string | null;
+    roles?: string[];
+    scopes?: string[];
+    audience?: string | string[] | null;
+    clientId?: string | null;
+    exp?: number | null;
+};
+/**
+ * Introspecção genérica de token usada pela Admin REST API (`POST /tokens/verify`).
+ * Roteia por prefixo: tokens `pat_...` vão pelo {@link PatStore} (mesma rota do
+ * `/authkit/pat/introspect`); os demais são tratados como opaque access tokens e
+ * resolvidos pelo `AccessToken.find` do oidc-provider. Sempre best-effort: token
+ * desconhecido/expirado → `{ active: false }`.
+ */
+export declare class TokenVerifyService {
+    #private;
+    private cfg;
+    /** Provider do oidc-provider (service.provider) — para opaque AT. */
+    private provider;
+    constructor(cfg: ResolvedServerConfig, 
+    /** Provider do oidc-provider (service.provider) — para opaque AT. */
+    provider: any);
+    verify(token: string): Promise<VerifyResult>;
+}

package/build/src/host/admin_api/token_verify_service.js

@@ -0,0 +1,74 @@
+/**
+ * Introspecção genérica de token usada pela Admin REST API (`POST /tokens/verify`).
+ * Roteia por prefixo: tokens `pat_...` vão pelo {@link PatStore} (mesma rota do
+ * `/authkit/pat/introspect`); os demais são tratados como opaque access tokens e
+ * resolvidos pelo `AccessToken.find` do oidc-provider. Sempre best-effort: token
+ * desconhecido/expirado → `{ active: false }`.
+ */
+export class TokenVerifyService {
+    cfg;
+    provider;
+    constructor(cfg, 
+    /** Provider do oidc-provider (service.provider) — para opaque AT. */
+    provider) {
+        this.cfg = cfg;
+        this.provider = provider;
+    }
+    async verify(token) {
+        if (!token || typeof token !== 'string')
+            return { active: false };
+        if (token.startsWith('pat_'))
+            return this.#verifyPat(token);
+        return this.#verifyAccessToken(token);
+    }
+    async #verifyPat(token) {
+        if (!this.cfg.patStore)
+            return { active: false };
+        const meta = await this.cfg.patStore.findActiveByToken(token);
+        if (!meta)
+            return { active: false };
+        const account = await this.cfg.accountStore.findById(meta.accountId);
+        if (!account)
+            return { active: false };
+        return {
+            active: true,
+            tokenType: 'pat',
+            sub: account.id,
+            email: account.email,
+            name: account.name ?? null,
+            roles: account.globalRoles ?? [],
+            scopes: meta.scopes,
+            audience: meta.audience,
+            exp: meta.exp,
+        };
+    }
+    async #verifyAccessToken(token) {
+        let at;
+        try {
+            at = await this.provider?.AccessToken?.find(token);
+        }
+        catch {
+            return { active: false };
+        }
+        if (!at)
+            return { active: false };
+        // O oidc-provider expira artefatos sozinho; isExpired/exp como guarda extra.
+        if (typeof at.isExpired === 'boolean' && at.isExpired)
+            return { active: false };
+        const sub = at.accountId ?? '';
+        const account = sub ? await this.cfg.accountStore.findById(sub) : null;
+        const scopes = typeof at.scope === 'string' ? at.scope.split(' ').filter(Boolean) : [];
+        return {
+            active: true,
+            tokenType: 'access_token',
+            sub,
+            email: account?.email ?? null,
+            name: account?.name ?? null,
+            roles: account?.globalRoles ?? [],
+            scopes,
+            audience: at.aud ?? null,
+            clientId: at.clientId ?? null,
+            exp: typeof at.exp === 'number' ? at.exp : null,
+        };
+    }
+}

package/build/src/host/avatar_storage.d.ts

@@ -0,0 +1,58 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { ResolvedUploadsConfig } from '../define_config.js';
+/**
+ * Upload de avatar do host-kit usando o `@adonisjs/drive` JÁ configurado no app.
+ * Mesmo princípio do default_mailer/rate_limit: por padrão usamos a infra do
+ * host (o disk DEFAULT do drive do app), sem o dev precisar escrever nada; tudo
+ * é sobreponível via `config/authkit.ts` (`uploads.avatars`).
+ *
+ * Best-effort / fail-safe: se `@adonisjs/drive` não estiver instalado/configurado,
+ * {@link storeAvatar} retorna `null` e a feature degrada para o input de URL.
+ * Nunca lança na request por causa de drive ausente.
+ */
+/**
+ * Service do `@adonisjs/drive` resolvido de forma preguiçosa. Tipado como `any` de
+ * propósito: a lib NÃO depende do drive em tempo de compilação (peer/opt-in).
+ */
+type DriveService = any;
+/**
+ * Permite reapontar/limpar o loader do drive (usado em testes).
+ * @internal
+ */
+export declare function __setDriveLoaderForTests(fn: (() => Promise<DriveService | null>) | undefined): void;
+/** Erro de validação do upload (mensagem já localizada no controller). */
+export declare class AvatarUploadError extends Error {
+    reason: 'extname' | 'size';
+    constructor(reason: 'extname' | 'size', message: string);
+}
+/** File de multipart mínimo que precisamos do `request.file('avatar')`. */
+export interface UploadedAvatar {
+    extname?: string | null;
+    size?: number;
+    /** Caminho temporário (drive lê daqui para stream). */
+    tmpPath?: string | null;
+    /** Move o arquivo para um disk do drive (API v3+). */
+    moveToDisk?: (key: string, options?: {
+        disk?: string;
+    }) => Promise<void>;
+}
+/**
+ * Indica se o drive do app está disponível (para a view decidir mostrar o input
+ * de arquivo). Best-effort: nunca lança.
+ */
+export declare function isDriveAvailable(): Promise<boolean>;
+/**
+ * Armazena o avatar no drive do host e retorna a URL pública.
+ *
+ * - Valida extensão (jpg/jpeg/png/webp) e tamanho (≤ maxSizeMb) — lança
+ *   {@link AvatarUploadError} se inválido (o controller traduz/flasha).
+ * - Usa o disk configurado em `uploads.avatars.disk` ou o disk DEFAULT do app.
+ * - Se o drive estiver ausente/não-configurado → retorna `null` (degrada para URL).
+ *
+ * Nunca lança por causa de drive ausente; só lança em validação.
+ */
+export declare function storeAvatar(_ctx: HttpContext, cfg: ResolvedUploadsConfig, file: UploadedAvatar, accountId: string, messages: {
+    extname: string;
+    size: string;
+}): Promise<string | null>;
+export {};

package/build/src/host/avatar_storage.js

@@ -0,0 +1,125 @@
+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;
+};
+let driveServicePromise;
+/**
+ * Importa o service de drive do HOST de forma preguiçosa e fail-safe.
+ * Se `@adonisjs/drive` não estiver instalado, resolve `null`.
+ */
+async function loadDrive() {
+    if (!driveServicePromise) {
+        // Indireção via variável: o `@adonisjs/drive` é peer/opcional e pode não estar
+        // instalado na lib, então o specifier não é resolvido em build-time.
+        const specifier = '@adonisjs/drive/services/main';
+        driveServicePromise = import(__rewriteRelativeImportExtension(specifier))
+            .then((mod) => mod.default ?? null)
+            .catch(() => null);
+    }
+    return driveServicePromise;
+}
+/**
+ * Permite reapontar/limpar o loader do drive (usado em testes).
+ * @internal
+ */
+export function __setDriveLoaderForTests(fn) {
+    if (fn) {
+        driveServicePromise = fn();
+    }
+    else {
+        driveServicePromise = undefined;
+    }
+}
+/** Extensões aceitas para o avatar (imagem raster comum). */
+const ALLOWED_EXTNAMES = ['jpg', 'jpeg', 'png', 'webp'];
+/** Erro de validação do upload (mensagem já localizada no controller). */
+export class AvatarUploadError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'AvatarUploadError';
+    }
+}
+/**
+ * Indica se o drive do app está disponível (para a view decidir mostrar o input
+ * de arquivo). Best-effort: nunca lança.
+ */
+export async function isDriveAvailable() {
+    return (await loadDrive()) !== null;
+}
+/**
+ * Resolve a extensão validada do arquivo enviado.
+ * Lança {@link AvatarUploadError} se ext/size forem inválidos.
+ */
+function validate(file, cfg, messages) {
+    const ext = (file.extname ?? '').toLowerCase().replace(/^\./, '');
+    if (!ALLOWED_EXTNAMES.includes(ext)) {
+        throw new AvatarUploadError('extname', messages.extname);
+    }
+    const maxBytes = cfg.avatars.maxSizeMb * 1024 * 1024;
+    if (typeof file.size === 'number' && file.size > maxBytes) {
+        throw new AvatarUploadError('size', messages.size);
+    }
+    return ext;
+}
+/**
+ * Gera uma chave única para o avatar dentro do diretório configurado.
+ * `${directory}/${accountId}-${random}.${ext}`
+ */
+function buildKey(cfg, accountId, ext) {
+    const random = Math.random().toString(36).slice(2, 10);
+    return `${cfg.avatars.directory}/${accountId}-${random}.${ext}`;
+}
+/**
+ * Armazena o avatar no drive do host e retorna a URL pública.
+ *
+ * - Valida extensão (jpg/jpeg/png/webp) e tamanho (≤ maxSizeMb) — lança
+ *   {@link AvatarUploadError} se inválido (o controller traduz/flasha).
+ * - Usa o disk configurado em `uploads.avatars.disk` ou o disk DEFAULT do app.
+ * - Se o drive estiver ausente/não-configurado → retorna `null` (degrada para URL).
+ *
+ * Nunca lança por causa de drive ausente; só lança em validação.
+ */
+export async function storeAvatar(_ctx, cfg, file, accountId, messages) {
+    const drive = await loadDrive();
+    if (!drive)
+        return null;
+    const ext = validate(file, cfg, messages);
+    // Resolve o disk: o configurado, ou o DEFAULT do drive do app.
+    let disk;
+    try {
+        disk = cfg.avatars.disk ? drive.use(cfg.avatars.disk) : drive.use();
+    }
+    catch {
+        // disk inválido/não-configurado — degrada para URL.
+        return null;
+    }
+    if (!disk)
+        return null;
+    const key = buildKey(cfg, accountId || 'account', ext);
+    // API @adonisjs/drive v3+: o file de multipart move-se direto para o disk.
+    // `moveToDisk` lê do tmpPath e usa o disk informado (ou o default da config).
+    if (typeof file.moveToDisk === 'function') {
+        await file.moveToDisk(key, cfg.avatars.disk ? { disk: cfg.avatars.disk } : undefined);
+    }
+    else if (file.tmpPath) {
+        // Fallback: lê do tmpPath e escreve via putStream no disk resolvido.
+        const fs = await import('node:fs');
+        await disk.putStream(key, fs.createReadStream(file.tmpPath));
+    }
+    else {
+        return null;
+    }
+    try {
+        return await disk.getUrl(key);
+    }
+    catch {
+        // disk sem getUrl público — retorna a key como referência relativa.
+        return key;
+    }
+}