@adonis-agora/authkit-client 1.0.0-rc.5 → 1.0.0-rc.7

package/build/src/org_labels.js

@@ -0,0 +1,145 @@
+/**
+ * Organization display labels on a relying-party app, for the org pickers of every
+ * `@adonis-agora` console (`Context.tenantLabels`). The active org's name comes from the
+ * session's `org_name` claim; any other id is asked to the authkit server
+ * (`GET /api/orgs/labels?ids=`, authenticated with this app's client id and secret) and
+ * cached.
+ */
+/** Default path of authkit-server's labels endpoint. */
+export const ORG_LABELS_PATH = '/api/orgs/labels';
+const DEFAULT_TTL_MS = 5 * 60_000;
+const MAX_CACHE = 2_000;
+/** Ids per request: the server answers at most 100. */
+const BATCH = 100;
+/** Labels learned from session claims (`org_id` + `org_name`), newest last. */
+const fromClaims = new Map();
+function bounded(map, key, value) {
+    map.delete(key);
+    map.set(key, value);
+    if (map.size > MAX_CACHE) {
+        const oldest = map.keys().next().value;
+        if (oldest !== undefined)
+            map.delete(oldest);
+    }
+}
+/**
+ * Records the active org's name from a resolved session (`org_name` claim), so the
+ * labeler answers it with no call. Called by the `Authenticator`; best effort.
+ */
+export function rememberOrgLabel(identity) {
+    try {
+        const id = identity?.orgId;
+        const name = identity?.raw?.org_name;
+        if (typeof id === 'string' && id && typeof name === 'string' && name) {
+            if (fromClaims.get(id) !== name)
+                bounded(fromClaims, id, name);
+        }
+    }
+    catch {
+        // never breaks the request
+    }
+}
+/** Clears the labels learned from claims (tests). */
+export function __clearOrgLabelsForTests() {
+    fromClaims.clear();
+}
+function defaultEndpoint(issuer) {
+    return new URL(ORG_LABELS_PATH, issuer).href;
+}
+/**
+ * A label resolver backed by the authkit server. Ids of another tenant kind (`kind` other
+ * than `'organization'`) get no label. Never throws: an unreachable server answers what is
+ * already known, and the ids it could not resolve show as ids.
+ */
+export function authkitOrgLabels(options) {
+    if (!options?.issuer || !options.clientId || !options.clientSecret) {
+        throw new TypeError('authkitOrgLabels: issuer, clientId and clientSecret are required');
+    }
+    const endpoint = options.endpoint ?? defaultEndpoint(options.issuer);
+    const ttl = options.ttlMs ?? DEFAULT_TTL_MS;
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const basic = Buffer.from(`${encodeURIComponent(options.clientId)}:${encodeURIComponent(options.clientSecret)}`).toString('base64');
+    /** id → label (or `null` for "not an authkit org") until `expiresAt`. */
+    const cache = new Map();
+    const fetchBatch = async (ids) => {
+        const url = new URL(endpoint);
+        url.searchParams.set('ids', ids.join(','));
+        try {
+            const res = await doFetch(url.href, {
+                headers: { authorization: `Basic ${basic}`, accept: 'application/json' },
+                signal: AbortSignal.timeout(options.timeoutMs ?? 5_000),
+            });
+            if (!res.ok)
+                return null;
+            const body = (await res.json());
+            const labels = body?.labels;
+            if (!labels || typeof labels !== 'object')
+                return null;
+            const out = {};
+            for (const [id, label] of Object.entries(labels)) {
+                if (typeof label === 'string' && label)
+                    out[id] = label;
+            }
+            return out;
+        }
+        catch {
+            return null;
+        }
+    };
+    return async (ids, opts) => {
+        if (opts?.kind !== undefined && opts.kind !== 'organization')
+            return {};
+        const wanted = [
+            ...new Set((Array.isArray(ids) ? ids : []).filter((id) => typeof id === 'string' && id)),
+        ];
+        const result = {};
+        const missing = [];
+        const now = Date.now();
+        for (const id of wanted) {
+            const claimed = fromClaims.get(id);
+            if (claimed) {
+                result[id] = claimed;
+                continue;
+            }
+            const hit = cache.get(id);
+            if (hit && hit.expiresAt > now) {
+                if (hit.label)
+                    result[id] = hit.label;
+                continue;
+            }
+            missing.push(id);
+        }
+        for (let i = 0; i < missing.length; i += BATCH) {
+            const batch = missing.slice(i, i + BATCH);
+            const fetched = await fetchBatch(batch);
+            if (!fetched)
+                continue; // not cached: the next call retries
+            const expiresAt = Date.now() + ttl;
+            for (const id of batch) {
+                const label = fetched[id] ?? null;
+                bounded(cache, id, { label, expiresAt });
+                if (label)
+                    result[id] = label;
+            }
+        }
+        return result;
+    };
+}
+const TENANCY_SLOT = Symbol.for('@agora/context:tenancy');
+/**
+ * Registers `resolver` as the context's tenant labeler (`Context.setTenantLabeler`), so
+ * console org pickers show names. `tenancy.label` in `config/context.ts` still wins.
+ * Returns `false` (and does nothing) without `@adonis-agora/context`.
+ */
+export function installOrgLabeler(resolver) {
+    try {
+        const slot = globalThis[TENANCY_SLOT];
+        if (!slot || slot.version !== 1 || typeof slot.setTenantLabeler !== 'function')
+            return false;
+        slot.setTenantLabeler(resolver);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/build/src/register_oidc_client.d.ts

@@ -1,5 +1,6 @@
 import { type Identity } from '@adonis-agora/authkit-core';
 import type { HttpContext, Router } from '@adonisjs/core/http';
+import { type ConsolesAppLike } from './agora_consoles.js';
 /**
  * Mapa role → rota de redirect pós-login. `byGlobalRole` checa as roles globais do
  * IdP (claim do token) — a primeira correspondência vence; sem match → `default`.
@@ -36,6 +37,14 @@ export interface RegisterOidcClientOptions {
     loginMiddleware?: any;
     /** Query param repassado como hint ao authorize (ex.: `audience`). Default: `['audience']`. */
     passthroughParams?: string[];
+    /**
+     * Announce `POST {prefix}/logout` as the sign-out of every `@adonis-agora` console
+     * (`account.signOut` on the `'agora.consoles'` registry). Skipped when authkit-server runs
+     * in this app (it announces its own) or when something announced one first. Default: `true`.
+     */
+    announceSignOut?: boolean;
+    /** The application to announce on. Default: `@adonisjs/core/services/app`. */
+    app?: ConsolesAppLike;
 }
 /**
  * Registra as rotas OIDC de CLIENT (login/callback/logout [+ back-channel logout])

package/build/src/register_oidc_client.js

@@ -1,4 +1,5 @@
 import { ACCOUNT_EXTENSIONS_WELL_KNOWN } from '@adonis-agora/authkit-core';
+import { announceAgoraSignOut } from './agora_consoles.js';
 import { OidcCallbackError } from './authorization.js';
 import { buildEndSessionUrl } from './oidc_login.js';
 /**
@@ -117,6 +118,27 @@ export function registerOidcClient(router, options = {}) {
     }
     if (options.accountExtensions !== false)
         registerAccountExtensionsEndpoint(router);
+    if (options.announceSignOut !== false) {
+        void announceRpSignOut(options.app, `${prefix}/logout`);
+    }
+}
+/**
+ * Announces the RP logout on the consoles registry, unless authkit-server (which announces
+ * its account sign-out) runs in this app. Best effort: never throws.
+ */
+async function announceRpSignOut(app, action) {
+    try {
+        const target = app ??
+            (await import('@adonisjs/core/services/app')).default;
+        if (!target?.container)
+            return;
+        if (target.container.hasBinding('authkit.server'))
+            return;
+        await announceAgoraSignOut(target, action);
+    }
+    catch {
+        // no booted app (a bare router in tests) or a registry of another shape
+    }
 }
 /**
  * Mounts `GET`/`POST /.well-known/agora-account-extensions`, where the IdP's account console

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

@@ -9,10 +9,10 @@ type FetchImpl = (url: string, init: any) => Promise<{
  * produzia (a referência canônica): `sub`→userId, `email`, papéis na
  * `globalRolesClaim`, `name`/`picture`→profile, `sid`→sessionId, `iat`/`exp`
  * (segundos→ms, fallback 0), a org/tenant ativo (`orgId`/`orgSlug`/`orgRole`,
- * ver `deriveOrgId` — vale para o authkit E para IdPs de terceiros) e as claims
- * cruas em `raw`.
+ * ver `deriveOrgId` — vale para o authkit E para IdPs de terceiros), o ator real de
+ * uma impersonação (`actor`, da claim `act` — RFC 8693) e as claims cruas em `raw`.
  */
-export declare function buildIdentityFromClaims(claims: Record<string, unknown>, globalRolesClaim: string): Identity;
+export declare function buildIdentityFromClaims(claims: Record<string, unknown>, globalRolesClaim?: string): Identity;
 export interface IntrospectAuth {
     /** `bearer` envia `Authorization: Bearer <value>`; `basic` envia `Authorization: Basic <value>`. */
     type: 'bearer' | 'basic';

package/build/src/resolvers/identity.js

@@ -1,15 +1,16 @@
-import { deriveOrgId, deriveOrgRole, deriveOrgSlug } from '@adonis-agora/authkit-core';
+import { deriveActor, deriveOrgId, deriveOrgRole, deriveOrgSlug } from '@adonis-agora/authkit-core';
 /**
  * Mapeamento canônico de claims OIDC validadas → Identity, compartilhado pelos
  * resolvers `jwt`, `pat` e `opaque`. Espelha exatamente o que o `JwtResolver`
  * produzia (a referência canônica): `sub`→userId, `email`, papéis na
  * `globalRolesClaim`, `name`/`picture`→profile, `sid`→sessionId, `iat`/`exp`
  * (segundos→ms, fallback 0), a org/tenant ativo (`orgId`/`orgSlug`/`orgRole`,
- * ver `deriveOrgId` — vale para o authkit E para IdPs de terceiros) e as claims
- * cruas em `raw`.
+ * ver `deriveOrgId` — vale para o authkit E para IdPs de terceiros), o ator real de
+ * uma impersonação (`actor`, da claim `act` — RFC 8693) e as claims cruas em `raw`.
  */
-export function buildIdentityFromClaims(claims, globalRolesClaim) {
+export function buildIdentityFromClaims(claims, globalRolesClaim = 'roles') {
     const roles = claims[globalRolesClaim];
+    const actor = deriveActor(claims);
     return {
         userId: String(claims.sub ?? ''),
         email: typeof claims.email === 'string' ? claims.email : '',
@@ -22,6 +23,7 @@ export function buildIdentityFromClaims(claims, globalRolesClaim) {
         orgId: deriveOrgId(claims),
         orgSlug: deriveOrgSlug(claims),
         orgRole: deriveOrgRole(claims),
+        ...(actor ? { actor } : {}),
         issuedAt: typeof claims.iat === 'number' ? claims.iat * 1000 : 0,
         expiresAt: typeof claims.exp === 'number' ? claims.exp * 1000 : 0,
         raw: claims,

package/build/src/revocation/revocation_store.d.ts

@@ -37,11 +37,17 @@ export interface RevocationStore {
 }
 export interface LucidRevocationStoreOptions {
     /**
-     * Conexão Lucid a usar. Default: conexão primária. Aponte para uma conexão cujo
-     * `searchPath` enxergue o schema onde a tabela vive (ex.: `auth`). A tabela é
-     * compartilhável entre apps que apontam para o MESMO banco.
+     * Conexão Lucid a usar. Default: conexão primária. A tabela é compartilhável entre
+     * apps que apontam para o MESMO banco.
      */
     connection?: string;
+    /**
+     * Schema do banco onde a tabela vive (MySQL: o database) — o `schema.name` do
+     * authkit-server, ex.: `'auth'`. Escrito em cada statement (`"auth"."auth_session_revocations"`).
+     * Não use `searchPath` na conexão para isso: atrás de um PgBouncer em modo
+     * transaction, o `SET search_path` vaza para as conexões de outros clientes.
+     */
+    schema?: string;
     /** Nome da tabela. Default: `auth_session_revocations` (criada pelo schema auto-manage do server). */
     table?: string;
     /**

package/build/src/tenant_token.d.ts

@@ -19,7 +19,11 @@ export interface AuthkitTenantTokenOptions {
     scope?: string;
     /** Refresh this many seconds before the token expires. Default: 60. */
     refreshSkewSec?: number;
-    /** Token endpoint. Default: `token_endpoint` from the issuer's discovery document. */
+    /**
+     * Token endpoint. Default: `token_endpoint` from the issuer's discovery document
+     * (`{issuer}/.well-known/openid-configuration`). When discovery fails the token
+     * request fails too (no guessed path); the next call retries.
+     */
     tokenEndpoint?: string;
     /** Custom `fetch` (proxy, tests). Default: the global `fetch`. */
     fetch?: typeof fetch;

package/build/src/tenant_token.js

@@ -108,10 +108,13 @@ export class AuthkitTenantToken {
         let endpoint = o.tokenEndpoint;
         if (!endpoint) {
             try {
-                endpoint = (await discoverEndpoints(o.issuer, {
-                    onError: 'fallback',
-                    ...(o.fetch ? { fetchImpl: o.fetch } : {}),
-                })).tokenEndpoint;
+                endpoint =
+                    // Strict discovery: the token endpoint comes from the issuer's
+                    // `/.well-known/openid-configuration`, never from a guessed path.
+                    (await discoverEndpoints(o.issuer, {
+                        onError: 'throw',
+                        ...(o.fetch ? { fetchImpl: o.fetch } : {}),
+                    })).tokenEndpoint;
             }
             catch (cause) {
                 throw new TenantTokenError('could not resolve the token endpoint', undefined, undefined, {

package/build/src/tenant_verifier.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The control-plane half of service-tenant auth: verifies the `client_credentials` JWT
+ * a tenant process presents (see `authkitTenantToken`) against the issuer's keys, found
+ * by OIDC discovery. Remote-safe: authkit-server does not have to run in this process.
+ */
+import { type DiscoverOptions } from './discovery.js';
+/** What a control plane hands to its verifier. Only `token` is trusted, once verified. */
+export interface TenantVerifierRequest {
+    /** The token the tenant presented. */
+    token?: string | undefined;
+    /** The partition the request claims to be. Advisory only: the token decides. */
+    partition?: string | undefined;
+    /** Same as `partition` (the wire name some libs use). Advisory only. */
+    tenant?: string | undefined;
+}
+/** What a verified tenant token authenticates as. Everything comes from the token. */
+export interface VerifiedTenantToken {
+    /** The `partition` claim: the app this tenant is. */
+    partition: string;
+    /** The `environment` claim, when the token has one. */
+    environment?: string;
+    /** The `capabilities` claim (product-defined, e.g. `flags:ruleset:read`). `[]` when absent. */
+    capabilities: string[];
+    /** The `client_id` of the service-tenant client. */
+    clientId: string;
+    /** Epoch ms at which the token expires. */
+    expiresAt: number;
+}
+/** The function form every Agora control plane accepts as `verifyTenant`. */
+export type TenantVerifier = (request: TenantVerifierRequest) => Promise<VerifiedTenantToken | null>;
+export interface AuthkitTenantVerifierOptions {
+    /** Issuer URL of the authkit server (the `iss` of its tokens). */
+    issuer: string;
+    /**
+     * The resource this control plane answers for, e.g. `'urn:agora:flags'`. The token's
+     * `aud` must contain it.
+     */
+    resource: string;
+    /**
+     * The environment this control plane serves. Only tokens whose `environment` claim is
+     * exactly this value are accepted (a token without the claim is rejected). Without it,
+     * any environment is accepted and returned as claimed.
+     */
+    environment?: string;
+    /** Expected `aud` when the server declares a different `audience` for the resource. Default: `resource`. */
+    audience?: string;
+    /** Allowed clock skew in seconds for `exp`/`nbf`/`iat`. Default: 30. */
+    clockToleranceSec?: number;
+    /** Discovery options (custom `fetchImpl`, cache TTL, resilience policy). */
+    discovery?: Pick<DiscoverOptions, 'fetchImpl' | 'cacheTtlMs' | 'resilience' | 'overrides'>;
+}
+/** A tenant verifier usable both as a function and as an object with `verify`. */
+export type AuthkitTenantVerifierFn = TenantVerifier & {
+    verify(request: TenantVerifierRequest): Promise<VerifiedTenantToken | null>;
+};
+/**
+ * Verifies service-tenant tokens issued by an authkit server, on any server:
+ *
+ * - finds `jwks_uri` and the exact `issuer` through `{issuer}/.well-known/openid-configuration`
+ *   (cached; never a guessed path);
+ * - checks the signature (asymmetric algorithms only), `iss`, `aud` (= `resource`),
+ *   `typ: at+jwt`, `exp`, and that `sub` is the client (a `client_credentials` token);
+ * - reads `partition`, `capabilities` and `environment` from the token, never from the request.
+ *
+ * Returns `null` for a token that does not verify; throws when the issuer cannot be
+ * discovered (the request fails instead of being silently refused).
+ */
+export declare class AuthkitTenantVerifier {
+    #private;
+    constructor(options: AuthkitTenantVerifierOptions);
+    verify(request: TenantVerifierRequest): Promise<VerifiedTenantToken | null>;
+}
+/**
+ * The `verifyTenant` of a control plane, wherever authkit runs:
+ *
+ * ```ts
+ * // config/flags.ts (control plane)
+ * import { authkitTenantVerifier } from '@adonis-agora/authkit-client'
+ *
+ * verifyTenant: authkitTenantVerifier({
+ *   issuer: env.get('AUTHKIT_ISSUER'),
+ *   resource: 'urn:agora:flags',
+ * })
+ * ```
+ *
+ * The result is a function that also has `verify` (the class form).
+ */
+export declare function authkitTenantVerifier(options: AuthkitTenantVerifierOptions): AuthkitTenantVerifierFn;

package/build/src/tenant_verifier.js

@@ -0,0 +1,104 @@
+/**
+ * The control-plane half of service-tenant auth: verifies the `client_credentials` JWT
+ * a tenant process presents (see `authkitTenantToken`) against the issuer's keys, found
+ * by OIDC discovery. Remote-safe: authkit-server does not have to run in this process.
+ */
+import { errors as joseErrors, jwtVerify } from 'jose';
+import { discoverEndpoints } from './discovery.js';
+import { DEFAULT_ALGS, getJwks } from './jwks.js';
+function stringArray(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((v) => typeof v !== 'string'))
+        return null;
+    return value;
+}
+/**
+ * Verifies service-tenant tokens issued by an authkit server, on any server:
+ *
+ * - finds `jwks_uri` and the exact `issuer` through `{issuer}/.well-known/openid-configuration`
+ *   (cached; never a guessed path);
+ * - checks the signature (asymmetric algorithms only), `iss`, `aud` (= `resource`),
+ *   `typ: at+jwt`, `exp`, and that `sub` is the client (a `client_credentials` token);
+ * - reads `partition`, `capabilities` and `environment` from the token, never from the request.
+ *
+ * Returns `null` for a token that does not verify; throws when the issuer cannot be
+ * discovered (the request fails instead of being silently refused).
+ */
+export class AuthkitTenantVerifier {
+    #options;
+    constructor(options) {
+        if (!options?.issuer || !options.resource) {
+            throw new TypeError('authkitTenantVerifier: issuer and resource are required');
+        }
+        this.#options = options;
+    }
+    async verify(request) {
+        const token = request?.token;
+        if (typeof token !== 'string' || !token)
+            return null;
+        const o = this.#options;
+        const endpoints = await discoverEndpoints(o.issuer, { ...o.discovery, onError: 'throw' });
+        let payload;
+        try {
+            ({ payload } = await jwtVerify(token, getJwks(endpoints.jwksUri), {
+                issuer: endpoints.issuer,
+                audience: o.audience ?? o.resource,
+                algorithms: DEFAULT_ALGS,
+                typ: 'at+jwt',
+                clockTolerance: o.clockToleranceSec ?? 30,
+                requiredClaims: ['exp', 'sub'],
+            }));
+        }
+        catch (error) {
+            if (error instanceof joseErrors.JOSEError)
+                return null;
+            throw error;
+        }
+        const claims = payload;
+        // A client_credentials token: no user behind it, `sub` is the client.
+        const clientId = claims.client_id;
+        if (typeof clientId !== 'string' || payload.sub !== clientId)
+            return null;
+        const partition = claims.partition;
+        if (typeof partition !== 'string' || !partition)
+            return null;
+        const capabilities = stringArray(claims.capabilities);
+        if (capabilities === null)
+            return null;
+        const claimed = claims.environment;
+        if (claimed !== undefined && (typeof claimed !== 'string' || !claimed))
+            return null;
+        // Pinned: fail closed, a token without the claim is not "this environment".
+        if (o.environment && claimed !== o.environment)
+            return null;
+        const environment = claimed;
+        return {
+            partition,
+            ...(environment ? { environment } : {}),
+            capabilities,
+            clientId,
+            expiresAt: payload.exp * 1000,
+        };
+    }
+}
+/**
+ * The `verifyTenant` of a control plane, wherever authkit runs:
+ *
+ * ```ts
+ * // config/flags.ts (control plane)
+ * import { authkitTenantVerifier } from '@adonis-agora/authkit-client'
+ *
+ * verifyTenant: authkitTenantVerifier({
+ *   issuer: env.get('AUTHKIT_ISSUER'),
+ *   resource: 'urn:agora:flags',
+ * })
+ * ```
+ *
+ * The result is a function that also has `verify` (the class form).
+ */
+export function authkitTenantVerifier(options) {
+    const verifier = new AuthkitTenantVerifier(options);
+    const verify = (request) => verifier.verify(request);
+    return Object.assign(verify, { verify });
+}

package/build/src/webhook_receiver.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Receives authkit-server's signed event webhook on another server and re-emits each
+ * event on the local `@adonis-agora/diagnostics` bus as `agora:authkit:<type>`, with the
+ * same payload authkit-server emits in-process. Listeners such as authz provisioning
+ * (`onDiagnostic('authkit', 'organization.created', ...)`) then work unchanged when
+ * authkit runs elsewhere.
+ */
+import type { HttpContext, Router } from '@adonisjs/core/http';
+/** The event as authkit-server's webhook sends it (the signed JSON body). */
+export interface AuthkitWebhookEvent {
+    /** Unique per event; a repeated id is ignored. */
+    id: string;
+    /** The audit event type, e.g. `organization.created`, `member.added`. */
+    type: string;
+    accountId: string | null;
+    actorId: string | null;
+    email: string | null;
+    clientId: string | null;
+    orgId: string | null;
+    ip: string | null;
+    metadata: Record<string, unknown>;
+    /** When authkit dispatched it (ISO 8601). */
+    ts: string;
+}
+/** What is emitted on the diagnostics bus: authkit-server's in-process payload (no PII). */
+export interface AuthkitDiagnosticPayload {
+    type: string;
+    accountId: string | null;
+    actorId: string | null;
+    clientId: string | null;
+    orgId: string | null;
+}
+/** Remembers delivered ids for replay protection. */
+export interface WebhookReplayStore {
+    /**
+     * Records `id` for `ttlMs`. Returns `false` when it was already recorded (a replay).
+     * Shared stores (Redis `SET NX PX`) protect every instance of the app.
+     */
+    claim(id: string, ttlMs: number): boolean | Promise<boolean>;
+}
+export interface AuthkitWebhookOptions {
+    /** The secret configured in authkit-server's `events.webhook.secret`. */
+    secret: string;
+    /** Accept events whose `ts` is at most this many seconds away from now. Default: 300. */
+    toleranceSec?: number;
+    /** Where delivered ids are remembered. Default: in memory, per process. */
+    replayStore?: WebhookReplayStore;
+    /** Also receive the full event (with `email`, `ip`, `metadata`). Runs before the bus emit. */
+    onEvent?: (event: AuthkitWebhookEvent) => void | Promise<void>;
+    /** Re-emit on the diagnostics bus. Default: `true`. */
+    emit?: boolean;
+}
+/** Why a delivery was refused. */
+export type WebhookRejection = 'signature' | 'malformed' | 'expired' | 'replay';
+/** The verdict of {@link verifyAuthkitWebhook}. */
+export type WebhookVerification = {
+    ok: true;
+    event: AuthkitWebhookEvent;
+} | {
+    ok: false;
+    reason: WebhookRejection;
+};
+/** In-memory replay store: ids live for their TTL, at most `max` at a time. */
+export declare function memoryReplayStore(max?: number): WebhookReplayStore;
+/**
+ * Checks one delivery: the `x-authkit-signature` HMAC over the raw body, the shape, the
+ * `ts` window and the `id` (each id is accepted once). Pure apart from the replay store.
+ */
+export declare function verifyAuthkitWebhook(input: {
+    body: string;
+    signature: string | undefined | null;
+}, options: Pick<AuthkitWebhookOptions, 'secret' | 'toleranceSec'> & {
+    replayStore: WebhookReplayStore;
+}): Promise<WebhookVerification>;
+/**
+ * Emits `event` on the diagnostics bus as `agora:authkit:<type>` with authkit-server's
+ * redacted payload (`type`, `accountId`, `actorId`, `clientId`, `orgId`). No-op without
+ * `@adonis-agora/diagnostics`.
+ */
+export declare function emitAuthkitEvent(event: AuthkitWebhookEvent): void;
+/**
+ * The route handler for authkit-server's webhook. Answers `204` for an accepted (or
+ * replayed) delivery, `401` for a bad signature, `400` for a malformed or expired one.
+ * Needs the raw body: keep the route under the JSON body parser (the default) and out of
+ * CSRF (shield's `csrf.exceptRoutes`).
+ */
+export declare function authkitWebhookHandler(options: AuthkitWebhookOptions): (ctx: HttpContext) => Promise<unknown>;
+/**
+ * Mounts `POST path` (default `/authkit/webhook`) with {@link authkitWebhookHandler}:
+ *
+ * ```ts
+ * // start/routes.ts
+ * registerAuthkitWebhook(router, { secret: env.get('AUTHKIT_WEBHOOK_SECRET') })
+ * ```
+ *
+ * Point authkit-server's `events.webhook` at `https://<this app>/authkit/webhook` with the
+ * same secret, and add the path to shield's `csrf.exceptRoutes`.
+ */
+export declare function registerAuthkitWebhook(router: Router, options: AuthkitWebhookOptions & {
+    path?: string;
+}): void;