@adonis-agora/payments 0.2.0 → 0.4.0

package/dist/src/dashboard/actions.js

@@ -0,0 +1,112 @@
+/**
+ * Build the refund action over a driver resolver (the app's `PaymentsManager.driver`).
+ *
+ * The capability check happens BEFORE the call, matching `PaymentsManager.assertCapability`: a
+ * driver that declares `refunds: false` implements `refund()` only to throw, and discovering that
+ * from a gateway round-trip reads to the operator like a network failure.
+ */
+export function createRefundAction(resolveDriver) {
+    return async ({ provider, gatewayId, amount }) => {
+        let driver;
+        try {
+            driver = await resolveDriver(provider);
+        }
+        catch (error) {
+            // The manager's own message names which drivers ARE configured, which is exactly the
+            // next thing the operator needs to know.
+            return { kind: 'unavailable', message: messageOf(error, `provider "${provider}" not found`) };
+        }
+        if (driver.capabilities?.refunds !== true) {
+            return {
+                kind: 'unsupported',
+                message: `The "${provider}" gateway has no refund API. Refund this payment from the gateway's own dashboard.`,
+            };
+        }
+        try {
+            const refund = await driver.refund(gatewayId, amount);
+            return {
+                kind: 'ok',
+                refund: {
+                    gatewayId: refund.gatewayId,
+                    amount: refund.amount.amount,
+                    currency: refund.amount.currency,
+                    status: refund.status,
+                },
+            };
+        }
+        catch (error) {
+            return { kind: 'gateway-error', message: messageOf(error, 'the gateway refused the refund') };
+        }
+    };
+}
+/**
+ * Build the retry action over the store plus the app's webhook processor.
+ *
+ * The ledger dance is the fiddly part and it lives here, once:
+ *
+ * 1. `recordWebhookEvent` re-claims a `failed` row and hands the ORIGINAL delivery back — both
+ *    the raw payload and the NORMALIZED event recorded beside it. That is the only way to read
+ *    a stored delivery through the `BillingStore` contract.
+ * 2. The event is rebuilt from those two columns. It is NEVER re-parsed: `parseWebhook`
+ *    re-verifies a signature computed over headers the ledger does not keep, so rebuilding that
+ *    way answered `422` on Stripe, Adyen and every other gateway that signs — a retry that
+ *    worked for a minority of gateways, and only for the ones an attacker would not need to
+ *    forge. A row with no `normalized` (written before the migration) is `undeliverable`,
+ *    stated plainly, rather than half-replayed.
+ * 3. The row is put BACK to `failed` before `process` runs, because `WebhookProcessor.process`
+ *    claims through `recordWebhookEvent` itself, and a row sitting at `received` reads to it as
+ *    "in flight" — it would return `false` and run nothing at all. This is the one place that
+ *    subtlety is written down.
+ * 4. `process` claims it properly and marks it `processed` or `failed` with the real reason.
+ */
+export function createReplayAction(deps) {
+    return async ({ gatewayEventId, provider, type, previousError }) => {
+        const claimed = await deps.store.recordWebhookEvent({
+            gatewayEventId,
+            provider,
+            type,
+            // Ignored on the re-claim path — the row keeps the payload and the normalized event it
+            // was recorded with, which is precisely what we need back.
+            payload: {},
+        });
+        if (claimed === null)
+            return { kind: 'conflict' };
+        const row = claimed;
+        const ledgerId = String(row.id);
+        const restore = () => deps.store.markWebhookFailed(ledgerId, previousError ?? '');
+        if (row.normalized === null || row.normalized === undefined) {
+            // Put the row back exactly as the operator found it: this refusal is about THIS retry, and
+            // stamping it over the handler's original message would destroy the only record of why the
+            // event failed in the first place.
+            await restore();
+            return {
+                kind: 'undeliverable',
+                message: 'This event was recorded before `billing_webhook_events.normalized` existed, so the normalized event it carried was never stored and cannot be rebuilt without re-verifying the gateway signature — which needs headers this table has never kept. Deliveries received since then replay normally; nothing can backfill this one.',
+            };
+        }
+        const event = {
+            id: gatewayEventId,
+            provider,
+            type,
+            data: row.normalized,
+            raw: row.payload ?? {},
+        };
+        await restore();
+        try {
+            await deps.process(event);
+            return { kind: 'processed' };
+        }
+        catch (error) {
+            return { kind: 'failed', message: messageOf(error, 'the handler threw again') };
+        }
+    };
+}
+/** Every action reports a cause; an unreadable throw still gets a sentence rather than `{}`. */
+function messageOf(error, fallback) {
+    if (error instanceof Error && error.message !== '')
+        return error.message;
+    if (typeof error === 'string' && error !== '')
+        return error;
+    return fallback;
+}
+//# sourceMappingURL=actions.js.map

package/dist/src/dashboard/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../../src/dashboard/actions.ts"],"names":[],"mappings":"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"}

package/dist/src/dashboard/auth.d.ts

@@ -0,0 +1,136 @@
+import { type DashboardSession, type DashboardSessionUser } from './session_cookie.js';
+/**
+ * Framework-light `dashboardAuth` mechanism for the payments dashboard — config resolution, the
+ * open-redirect guard, the login decision, and session verification. NO AdonisJS types leak in
+ * (mirroring {@link file://./handlers.ts handlers.ts}), so every branch is unit-testable against a
+ * plain object with no HTTP server. The provider (`providers/dashboard_provider.ts`) adapts an
+ * `HttpContext` to these functions and owns the cookie read/write via AdonisJS's native cookie API.
+ *
+ * When configured it gates BOTH the dashboard HTML shell (a full-page navigation redirected `302`
+ * to a server-rendered login page) and the JSON API (a plain `401`) behind a signed session cookie.
+ * When left unconfigured the dashboard behaves exactly as before (no login/logout routes, no
+ * session guard).
+ *
+ * Ported from `@adonis-agora/durable`'s `src/dashboard/auth.ts` with only the names changed, so the
+ * Agora consoles share ONE auth story rather than each inventing its own.
+ */
+/** Host hook validating submitted credentials from the built-in login page (Mode B — standalone). */
+export type LoginHook = (username: string, password: string) => Promise<DashboardSessionUser | null> | DashboardSessionUser | null;
+/**
+ * Host hook validating the HOST APP's own auth off the raw request (Mode A — SSO / "open from your
+ * app"). Receives the underlying platform request object (an AdonisJS `Request['request']`, i.e. the
+ * raw Node `IncomingMessage`) rather than an AdonisJS type, so this module stays framework-light and
+ * unit-testable with no `HttpContext` — the provider passes it through untouched. Mirrors
+ * `@adonis-agora/durable`'s `SessionHook` byte-for-byte (same two-mode split).
+ */
+export type SessionHook = (request: unknown) => Promise<DashboardSessionUser | null> | DashboardSessionUser | null;
+/**
+ * Author-facing `dashboardAuth` option on `config/payments_dashboard.ts`. Gates the dashboard behind
+ * a signed session cookie, minted by whichever mode(s) are configured:
+ *
+ * - Mode B (`login`) — the built-in server-rendered login page (`GET <path>/login`), for a
+ *   standalone console with its own credentials.
+ * - Mode A (`session`) — `POST <path>/session`, for a host app that's already authenticated the
+ *   operator itself and wants a one-shot "open the console" button (a one-shot "open the console" button).
+ *
+ * Both may be configured together; at least one is required. The bundled dashboard SPA is unaware of
+ * which mode(s) are active — it only reacts to a 401's `{ auth: { modes } }` body (see
+ * `payments-client.ts`).
+ *
+ * Each hook is just a plain function that may be `async` and close over
+ * `app.container`/services (import them at the top of `config/payments_dashboard.ts`), so there is
+ * nothing extra to build for the async case.
+ */
+export interface DashboardAuthOptions {
+    /** REQUIRED HMAC-SHA256 signing key. Missing/empty => boot error (fail closed). */
+    secret: string;
+    /** Cookie TTL as a duration string (`'8h'`, `'30m'`, `'7d'`). Default `'8h'`. */
+    ttl?: string;
+    /** Validates submitted username/password; return the session user, or `null` to deny. Thrown
+     *  errors are treated as a denial (logged once, never surfaced to the client). May be async. */
+    login?: LoginHook;
+    /** Validates the host app's own auth off the raw request; return the session user, or `null` to
+     *  deny. Thrown errors are treated as a denial. May be async. */
+    session?: SessionHook;
+}
+/** Which auth surface(s) are active — carried on an API 401's `{ auth: { modes } }` body so the SPA
+ *  knows whether to offer the login page or just report "not authenticated". */
+export type AuthMode = 'session' | 'login';
+/** Resolved, validated `dashboardAuth` config shared by the guard, the login/session handlers, and
+ *  the page. */
+export interface ResolvedDashboardAuth {
+    secret: string;
+    ttlMs: number;
+    modes: AuthMode[];
+    login?: LoginHook;
+    session?: SessionHook;
+}
+/** Cookie name carrying the signed dashboard session. */
+export declare const SESSION_COOKIE_NAME = "payments_dashboard_session";
+/**
+ * Validate + resolve the `dashboardAuth` option. Returns `null` when unconfigured (today's
+ * unauthenticated behavior, unchanged). Throws at boot (fail closed) when configured but missing a
+ * secret, or neither `login` nor `session` is a function — the host learns immediately rather than
+ * shipping an un-mintable gate.
+ */
+export declare function resolveDashboardAuth(options: DashboardAuthOptions | undefined): ResolvedDashboardAuth | null;
+/**
+ * Guard a client-supplied redirect target against an open redirect: it must be a same-origin,
+ * root-relative path (`/payments/foo`), never a protocol-relative (`//evil.com`) or absolute
+ * (`https://evil.com`) URL. Falls back to `fallback` (the dashboard's own `basePath`) for anything
+ * else, including a missing/non-string value.
+ */
+export declare function sanitizeReturnTo(candidate: unknown, fallback: string): string;
+/**
+ * The framework-light outcome of a login attempt, mapped to HTTP by the provider:
+ * - `ok`       → set `cookieValue` as the session cookie, reply `200 { redirectTo }`.
+ * - `bad-request` → `400` (body missing string `username`/`password`).
+ * - `unauthorized` → uniform `401 { error }` for EVERY credential failure (unknown user, wrong
+ *   password, or a throwing hook) — no user-enumeration. `hookError` is set only when the hook
+ *   threw, so the provider can warn-log it once without changing the client-visible response.
+ */
+export type LoginOutcome = {
+    kind: 'ok';
+    cookieValue: string;
+    redirectTo: string;
+} | {
+    kind: 'bad-request';
+    message: string;
+} | {
+    kind: 'unauthorized';
+    message: string;
+    hookError?: unknown;
+};
+/**
+ * Decide a login attempt end-to-end (validate body → run hook → mint cookie) with no HTTP types.
+ * On success returns the signed cookie value to set plus the sanitized `redirectTo`; the password
+ * is forwarded to the hook AS-IS (empty string when blank), so the hook alone decides whether a
+ * password is required. `404`-worthy (Mode B not configured) is the provider's call, not this
+ * function's — it only runs once the provider has confirmed `auth.login` exists.
+ */
+export declare function performLogin(auth: ResolvedDashboardAuth, body: unknown, basePath: string, now?: number): Promise<LoginOutcome>;
+/**
+ * The framework-light outcome of a Mode A session-mint attempt (`POST <path>/session`), mapped to
+ * HTTP by the provider: `ok` → set the cookie, reply `204`; `unauthorized` → uniform `401` (the
+ * `session` hook returned/threw a denial).
+ */
+export type SessionOutcome = {
+    kind: 'ok';
+    cookieValue: string;
+} | {
+    kind: 'unauthorized';
+    hookError?: unknown;
+};
+/**
+ * Decide a Mode A session-mint attempt end-to-end: run the host's `session` hook against the raw
+ * platform request, and mint the cookie on success. No body to validate — the hook reads whatever it
+ * needs directly off `request` (its own cookie/JWT/header).
+ */
+export declare function performSession(auth: ResolvedDashboardAuth, request: unknown, now?: number): Promise<SessionOutcome>;
+/**
+ * Read + verify a session cookie value, returning the session or `null` when absent, tampered, or
+ * expired. Thin wrapper over {@link verifySessionCookie} so the provider never touches crypto.
+ */
+export declare function readSession(auth: ResolvedDashboardAuth, cookieValue: string | undefined, now?: number): DashboardSession | null;
+export type { DashboardSession, DashboardSessionUser } from './session_cookie.js';
+//# sourceMappingURL=auth.d.ts.map

package/dist/src/dashboard/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/dashboard/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAG1B,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AAEH,qGAAqG;AACrG,MAAM,MAAM,SAAS,GAAG,CACtB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,GAAG,oBAAoB,GAAG,IAAI,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,GAAG,oBAAoB,GAAG,IAAI,CAAC;AAExE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;oGACgG;IAChG,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;qEACiE;IACjE,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED;gFACgF;AAChF,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAE3C;gBACgB;AAChB,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAoBhE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,oBAAoB,GAAG,SAAS,GACxC,qBAAqB,GAAG,IAAI,CA0B9B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM7E;AAaD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAoBnE;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,qBAAqB,EAC3B,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,YAAY,CAAC,CAuBvB;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAElD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,OAAO,EAChB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,CAAC,CAezB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,qBAAqB,EAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,GAAG,CAAC,EAAE,MAAM,GACX,gBAAgB,GAAG,IAAI,CAMzB;AAED,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/src/dashboard/auth.js

@@ -0,0 +1,152 @@
+import { signSessionCookie, verifySessionCookie, } from './session_cookie.js';
+/** Cookie name carrying the signed dashboard session. */
+export const SESSION_COOKIE_NAME = 'payments_dashboard_session';
+const DEFAULT_TTL = '8h';
+const DEFAULT_TTL_MS = 8 * 60 * 60 * 1000;
+const DURATION_UNITS = {
+    s: 1000,
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+};
+/** Parse a `'<number><s|m|h|d>'` duration to ms; falls back to the 8h default on a bad value. */
+function durationToMs(ttl) {
+    const match = /^(\d+)([smhd])$/.exec(ttl.trim());
+    if (!match)
+        return DEFAULT_TTL_MS;
+    const unit = DURATION_UNITS[match[2] ?? ''];
+    if (unit === undefined)
+        return DEFAULT_TTL_MS;
+    return Number(match[1]) * unit;
+}
+/**
+ * Validate + resolve the `dashboardAuth` option. Returns `null` when unconfigured (today's
+ * unauthenticated behavior, unchanged). Throws at boot (fail closed) when configured but missing a
+ * secret, or neither `login` nor `session` is a function — the host learns immediately rather than
+ * shipping an un-mintable gate.
+ */
+export function resolveDashboardAuth(options) {
+    if (options === undefined)
+        return null;
+    if (typeof options.secret !== 'string' || options.secret === '') {
+        throw new Error('payments_dashboard: dashboardAuth.secret is required and must be a non-empty string ' +
+            '(HMAC-SHA256 signing key, 32+ bytes recommended). Failing closed.');
+    }
+    const hasLogin = typeof options.login === 'function';
+    const hasSession = typeof options.session === 'function';
+    if (!hasLogin && !hasSession) {
+        throw new Error('payments_dashboard: dashboardAuth needs at least one of `login` or `session` (a login hook or ' +
+            'a host-session hook).');
+    }
+    const modes = [];
+    if (hasSession)
+        modes.push('session');
+    if (hasLogin)
+        modes.push('login');
+    return {
+        secret: options.secret,
+        ttlMs: durationToMs(options.ttl ?? DEFAULT_TTL),
+        modes,
+        ...(hasLogin ? { login: options.login } : {}),
+        ...(hasSession ? { session: options.session } : {}),
+    };
+}
+/**
+ * Guard a client-supplied redirect target against an open redirect: it must be a same-origin,
+ * root-relative path (`/payments/foo`), never a protocol-relative (`//evil.com`) or absolute
+ * (`https://evil.com`) URL. Falls back to `fallback` (the dashboard's own `basePath`) for anything
+ * else, including a missing/non-string value.
+ */
+export function sanitizeReturnTo(candidate, fallback) {
+    if (typeof candidate !== 'string')
+        return fallback;
+    if (!candidate.startsWith('/'))
+        return fallback;
+    if (candidate.startsWith('//'))
+        return fallback;
+    if (candidate.includes('://'))
+        return fallback;
+    return candidate;
+}
+function isString(value) {
+    return typeof value === 'string';
+}
+const UNAUTHORIZED_MESSAGE = 'Invalid username or password.';
+/**
+ * Run a host hook (`login` or `session`) defensively: a throw is treated as a denial (uniform
+ * failure) so a buggy hook never 500s the endpoint into a stack-trace leak. The thrown error is
+ * surfaced on the outcome (`hookError`) so the provider can warn-log it once, but it never reaches
+ * the client.
+ */
+async function runHook(hook) {
+    try {
+        return { user: (await hook()) ?? null };
+    }
+    catch (error) {
+        return { user: null, error };
+    }
+}
+/**
+ * Decide a login attempt end-to-end (validate body → run hook → mint cookie) with no HTTP types.
+ * On success returns the signed cookie value to set plus the sanitized `redirectTo`; the password
+ * is forwarded to the hook AS-IS (empty string when blank), so the hook alone decides whether a
+ * password is required. `404`-worthy (Mode B not configured) is the provider's call, not this
+ * function's — it only runs once the provider has confirmed `auth.login` exists.
+ */
+export async function performLogin(auth, body, basePath, now) {
+    const parsed = (body ?? {});
+    if (!isString(parsed.username) || !isString(parsed.password)) {
+        return { kind: 'bad-request', message: 'Body must include string `username` and `password`.' };
+    }
+    const login = auth.login;
+    if (!login) {
+        return { kind: 'unauthorized', message: UNAUTHORIZED_MESSAGE };
+    }
+    const { user, error } = await runHook(() => login(parsed.username, parsed.password));
+    if (!user) {
+        return error !== undefined
+            ? { kind: 'unauthorized', message: UNAUTHORIZED_MESSAGE, hookError: error }
+            : { kind: 'unauthorized', message: UNAUTHORIZED_MESSAGE };
+    }
+    const cookieValue = signSessionCookie(user, {
+        secret: auth.secret,
+        ttlMs: auth.ttlMs,
+        ...(now !== undefined ? { now } : {}),
+    });
+    return { kind: 'ok', cookieValue, redirectTo: sanitizeReturnTo(parsed.returnTo, basePath) };
+}
+/**
+ * Decide a Mode A session-mint attempt end-to-end: run the host's `session` hook against the raw
+ * platform request, and mint the cookie on success. No body to validate — the hook reads whatever it
+ * needs directly off `request` (its own cookie/JWT/header).
+ */
+export async function performSession(auth, request, now) {
+    const session = auth.session;
+    if (!session)
+        return { kind: 'unauthorized' };
+    const { user, error } = await runHook(() => session(request));
+    if (!user) {
+        return error !== undefined
+            ? { kind: 'unauthorized', hookError: error }
+            : { kind: 'unauthorized' };
+    }
+    const cookieValue = signSessionCookie(user, {
+        secret: auth.secret,
+        ttlMs: auth.ttlMs,
+        ...(now !== undefined ? { now } : {}),
+    });
+    return { kind: 'ok', cookieValue };
+}
+/**
+ * Read + verify a session cookie value, returning the session or `null` when absent, tampered, or
+ * expired. Thin wrapper over {@link verifySessionCookie} so the provider never touches crypto.
+ */
+export function readSession(auth, cookieValue, now) {
+    if (cookieValue === undefined || cookieValue === '')
+        return null;
+    return verifySessionCookie(cookieValue, {
+        secret: auth.secret,
+        ...(now !== undefined ? { now } : {}),
+    });
+}
+//# sourceMappingURL=auth.js.map

package/dist/src/dashboard/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/dashboard/auth.ts"],"names":[],"mappings":"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"}

package/dist/src/dashboard/define_config.d.ts

@@ -0,0 +1,80 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import { type DashboardAuthOptions, type ResolvedDashboardAuth } from './auth.js';
+/**
+ * Authorization guard for the dashboard. Runs before every dashboard route
+ * (API + HTML). Return `true` to allow the request, `false` to deny it (the
+ * provider replies `403`). May be async (e.g. an auth lookup).
+ *
+ * It receives the AdonisJS {@link HttpContext}, so it can read the session,
+ * a bearer token, an IP allow-list, etc.
+ */
+export type AuthorizeHook = (ctx: HttpContext) => boolean | Promise<boolean>;
+/** Shape of `config/payments_dashboard.ts`. */
+export interface PaymentsDashboardConfig {
+    /**
+     * Master switch. When `false`, the provider registers no routes at all — the
+     * dashboard is completely absent. Defaults to `true`.
+     */
+    enabled?: boolean;
+    /**
+     * URL prefix the dashboard + its API mount under. Defaults to `/payments`. The HTML is
+     * served at the prefix root; the JSON API lives under `<path>/api`.
+     *
+     * It shares that prefix with the machine endpoints — `POST /payments/webhook/:provider`
+     * and `GET /payments/client/status` — and does so safely, because every route this
+     * provider registers is an EXACT path (`/payments`, `/payments/assets/:file`,
+     * `/payments/api/…`, login/session/logout). There is no SPA catch-all, so the dashboard's
+     * `enforce` guard cannot reach a delivery it was never routed. If you ever add one, the
+     * webhook route is what it would swallow, and a 403'd webhook looks exactly like a gateway
+     * outage from the outside.
+     */
+    path?: string;
+    /**
+     * ISO 4217 code the SPA formats the money columns with. Cents stay integer cents on the
+     * wire either way — this only decides how the edge renders them. Defaults to `'BRL'`.
+     */
+    currency?: string;
+    /**
+     * Per-request authorization guard. Defaults to {@link defaultAuthorize}:
+     * allow everything OUTSIDE production, and in production require a bearer
+     * token matching the `PAYMENTS_DASHBOARD_TOKEN` env var (deny if it is unset).
+     */
+    authorize?: AuthorizeHook;
+    /**
+     * Optional built-in login screen. When set, the provider mounts a
+     * server-rendered `GET <path>/login` page plus `POST <path>/login` /
+     * `GET <path>/logout`, and stamps a session guard on the dashboard: an
+     * unauthenticated page navigation is redirected (`302`) to the login page and
+     * an unauthenticated API request gets `401`. The signed session cookie is
+     * minted only by the host's {@link DashboardAuthOptions.login} hook.
+     *
+     * This is ADDITIVE and composes WITH {@link authorize} (both must pass) — it
+     * does not replace it. Omit it entirely for no login/logout routes and no
+     * session guard. Missing `secret`/`login` fails closed at boot.
+     */
+    dashboardAuth?: DashboardAuthOptions;
+}
+/** A fully-resolved config — every field present (defaults applied). */
+export interface ResolvedPaymentsDashboardConfig {
+    enabled: boolean;
+    path: string;
+    currency: string;
+    authorize: AuthorizeHook;
+    /** Resolved built-in login config, or `null` when `dashboardAuth` is unconfigured. */
+    dashboardAuth: ResolvedDashboardAuth | null;
+}
+/**
+ * The default guard: open outside production; in production it requires a
+ * bearer token equal to `PAYMENTS_DASHBOARD_TOKEN`. If that env var is unset in
+ * production the dashboard is denied entirely (fail-closed) — you must opt in
+ * by setting a token or supplying your own {@link AuthorizeHook}.
+ *
+ * Identical posture to `@adonis-agora/durable`'s `defaultAuthorize`, down to the
+ * constant-time compare; only the env var name differs.
+ */
+export declare function defaultAuthorize(ctx: HttpContext): boolean;
+/** Apply defaults to a partial config, producing a fully-resolved one. */
+export declare function resolveConfig(config?: PaymentsDashboardConfig): ResolvedPaymentsDashboardConfig;
+/** Identity helper giving `config/payments_dashboard.ts` full type-checking. */
+export declare function defineConfig(config?: PaymentsDashboardConfig): PaymentsDashboardConfig;
+//# sourceMappingURL=define_config.d.ts.map

package/dist/src/dashboard/define_config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../../src/dashboard/define_config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAE3B,MAAM,WAAW,CAAC;AAEnB;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAE7E,+CAA+C;AAC/C,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,oBAAoB,CAAC;CACtC;AAED,wEAAwE;AACxE,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,sFAAsF;IACtF,aAAa,EAAE,qBAAqB,GAAG,IAAI,CAAC;CAC7C;AAyCD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAQ1D;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAC3B,MAAM,GAAE,uBAA4B,GACnC,+BAA+B,CAajC;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,MAAM,GAAE,uBAA4B,GAAG,uBAAuB,CAE1F"}

package/dist/src/dashboard/define_config.js

@@ -0,0 +1,83 @@
+import { timingSafeEqual } from 'node:crypto';
+import { resolveDashboardAuth, } from './auth.js';
+/**
+ * Whether the process is running in production. Mirrors how AdonisJS reads the
+ * environment without taking a hard dependency on its env service.
+ */
+function isProduction() {
+    return (process.env.NODE_ENV ?? '').toLowerCase() === 'production';
+}
+/**
+ * Extract a bearer token from an `Authorization: Bearer <token>` header, a
+ * `token` query-string param, or an `x-payments-token` header — whichever is
+ * present. Returns `undefined` when none is supplied.
+ */
+function readToken(ctx) {
+    const header = ctx.request.header('authorization');
+    if (header) {
+        const match = /^Bearer\s+(.+)$/i.exec(header);
+        if (match?.[1])
+            return match[1].trim();
+    }
+    const xHeader = ctx.request.header('x-payments-token');
+    if (xHeader)
+        return xHeader.trim();
+    const qs = ctx.request.qs().token;
+    if (typeof qs === 'string' && qs.length > 0)
+        return qs;
+    return undefined;
+}
+/**
+ * Compare two secrets in constant time (guarding for equal byte-length first,
+ * since {@link timingSafeEqual} throws on a length mismatch). Returns `false`
+ * for any length difference, otherwise the timing-safe equality — so the token
+ * check leaks neither a match nor the token's length via response time.
+ */
+function secretsMatch(a, b) {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+/**
+ * The default guard: open outside production; in production it requires a
+ * bearer token equal to `PAYMENTS_DASHBOARD_TOKEN`. If that env var is unset in
+ * production the dashboard is denied entirely (fail-closed) — you must opt in
+ * by setting a token or supplying your own {@link AuthorizeHook}.
+ *
+ * Identical posture to `@adonis-agora/durable`'s `defaultAuthorize`, down to the
+ * constant-time compare; only the env var name differs.
+ */
+export function defaultAuthorize(ctx) {
+    if (!isProduction())
+        return true;
+    const expected = process.env.PAYMENTS_DASHBOARD_TOKEN;
+    if (!expected)
+        return false;
+    const provided = readToken(ctx);
+    if (provided === undefined)
+        return false;
+    // Constant-time compare to remove the timing side-channel from the token check.
+    return secretsMatch(provided, expected);
+}
+/** Apply defaults to a partial config, producing a fully-resolved one. */
+export function resolveConfig(config = {}) {
+    const rawPath = config.path ?? '/payments';
+    // Normalize: ensure a single leading slash and no trailing slash (root stays '/').
+    const trimmed = `/${rawPath.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+    return {
+        enabled: config.enabled ?? true,
+        path: trimmed === '/' ? '' : trimmed,
+        currency: config.currency ?? 'BRL',
+        authorize: config.authorize ?? defaultAuthorize,
+        // Validate + resolve now so a misconfigured secret/login fails closed at boot,
+        // not on the first login attempt. `null` when `dashboardAuth` is omitted.
+        dashboardAuth: resolveDashboardAuth(config.dashboardAuth),
+    };
+}
+/** Identity helper giving `config/payments_dashboard.ts` full type-checking. */
+export function defineConfig(config = {}) {
+    return config;
+}
+//# sourceMappingURL=define_config.js.map

package/dist/src/dashboard/define_config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../../src/dashboard/define_config.ts"],"names":[],"mappings":"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"}