@ascendkit/nextjs 0.1.0

package/dist/server/auth-runtime.js

@@ -0,0 +1,123 @@
+import { buildAscendKitAuthFromConfig, createDisabledAuth } from "./ascendkit-auth";
+import { fetchAuthConfigConditional } from "./config-fetcher";
+function isCallbackPath(request) {
+    try {
+        return new URL(request.url).pathname.includes("/callback/");
+    }
+    catch {
+        return false;
+    }
+}
+async function shouldRetryWithPrevious(response) {
+    if (response.status === 404) {
+        return true;
+    }
+    if (response.status !== 400 && response.status !== 403) {
+        return false;
+    }
+    const contentType = (response.headers.get("content-type") || "").toLowerCase();
+    if (!contentType.includes("application/json")) {
+        return false;
+    }
+    const body = await response.clone().json().catch(() => null);
+    const detail = String(body?.error || body?.detail || body?.message || "").toLowerCase();
+    return detail.includes("provider") || detail.includes("oauth") || detail.includes("social");
+}
+export function createAscendKitAuthRuntime(options = {}) {
+    const publicKey = options.publicKey || process.env.ASCENDKIT_ENV_KEY || "";
+    const secretKey = options.secretKey || process.env.ASCENDKIT_SECRET_KEY || "";
+    const apiUrl = options.apiUrl || process.env.ASCENDKIT_API_URL || "https://api.ascendkit.com";
+    const callbackGraceMs = 5 * 60 * 1000;
+    const minRefreshIntervalMs = 10 * 1000;
+    let currentAuth = null;
+    let currentEtag;
+    let previousAuth = null;
+    let refreshInFlight = null;
+    let nextRefreshCheckAt = 0;
+    async function refreshAuth() {
+        const now = Date.now();
+        if (currentAuth && now < nextRefreshCheckAt) {
+            return;
+        }
+        if (refreshInFlight) {
+            return refreshInFlight;
+        }
+        const refreshTask = (async () => {
+            try {
+                const result = await fetchAuthConfigConditional(publicKey, secretKey, apiUrl, currentEtag);
+                if (result.notModified) {
+                    if (result.etag) {
+                        currentEtag = result.etag;
+                    }
+                    console.info("[AscendKit runtime] config_refresh_outcome=hit_304");
+                    if (!currentAuth) {
+                        currentAuth = createDisabledAuth(publicKey, apiUrl);
+                    }
+                    return;
+                }
+                if (!result.config) {
+                    console.warn("[AscendKit runtime] config_refresh_outcome=cold_fail reason=missing_config");
+                    if (!currentAuth) {
+                        currentAuth = createDisabledAuth(publicKey, apiUrl);
+                    }
+                    return;
+                }
+                const nextAuth = await buildAscendKitAuthFromConfig({
+                    publicKey,
+                    apiUrl,
+                    config: result.config,
+                    waitlistRedirectPath: options.waitlistRedirectPath,
+                    rejectedRedirectPath: options.rejectedRedirectPath,
+                });
+                if (currentAuth) {
+                    previousAuth = {
+                        auth: currentAuth,
+                        expiresAt: Date.now() + callbackGraceMs,
+                    };
+                }
+                currentAuth = nextAuth;
+                currentEtag = result.etag ?? currentEtag;
+                console.info("[AscendKit runtime] config_refresh_outcome=updated_200");
+            }
+            catch (err) {
+                console.warn("[AscendKit runtime] config_refresh_outcome=fallback_last_known_good", err instanceof Error ? err.message : err);
+                if (!currentAuth) {
+                    currentAuth = createDisabledAuth(publicKey, apiUrl);
+                }
+            }
+        })();
+        refreshInFlight = refreshTask.finally(() => {
+            refreshInFlight = null;
+            nextRefreshCheckAt = Date.now() + minRefreshIntervalMs;
+        });
+        return refreshInFlight;
+    }
+    async function getAuth() {
+        await refreshAuth();
+        if (!currentAuth) {
+            currentAuth = createDisabledAuth(publicKey, apiUrl);
+        }
+        return currentAuth;
+    }
+    async function handler(request) {
+        const activeAuth = await getAuth();
+        const callbackRequest = isCallbackPath(request) ? request.clone() : null;
+        const response = await activeAuth.handler(request);
+        if (callbackRequest
+            && previousAuth
+            && previousAuth.expiresAt > Date.now()
+            && await shouldRetryWithPrevious(response)) {
+            return previousAuth.auth.handler(callbackRequest);
+        }
+        return response;
+    }
+    async function getSession(headers) {
+        const activeAuth = await getAuth();
+        return await activeAuth.api.getSession({ headers });
+    }
+    return {
+        handler,
+        getSession,
+        getAuth,
+    };
+}

package/dist/server/config-fetcher.d.ts

@@ -0,0 +1,22 @@
+import type { AuthConfig } from "../shared/types";
+export interface ConditionalAuthConfigResult {
+    notModified: boolean;
+    config?: AuthConfig;
+    etag?: string;
+}
+/**
+ * Fetches the full auth configuration from the AscendKit backend.
+ * Returns enabled providers, OAuth credentials (with secrets), and feature flags.
+ *
+ * Uses the server-config endpoint authenticated via secret key.
+ * Used by AscendKitAuth to configure Better Auth dynamically.
+ */
+export declare function fetchAuthConfig(publicKey: string, secretKey: string, apiUrl: string): Promise<AuthConfig>;
+/**
+ * Fetches auth configuration with conditional ETag support.
+ *
+ * - Sends If-None-Match when an ETag is provided
+ * - Returns notModified=true for 304 responses
+ */
+export declare function fetchAuthConfigConditional(publicKey: string, secretKey: string, apiUrl: string, etag?: string): Promise<ConditionalAuthConfigResult>;
+//# sourceMappingURL=config-fetcher.d.ts.map

package/dist/server/config-fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-fetcher.d.ts","sourceRoot":"","sources":["../../src/server/config-fetcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,MAAM,WAAW,2BAA2B;IAC1C,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAM/G;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,2BAA2B,CAAC,CAItC"}

package/dist/server/config-fetcher.js

@@ -0,0 +1,26 @@
+import { createHttpClient } from "../shared/http-client";
+/**
+ * Fetches the full auth configuration from the AscendKit backend.
+ * Returns enabled providers, OAuth credentials (with secrets), and feature flags.
+ *
+ * Uses the server-config endpoint authenticated via secret key.
+ * Used by AscendKitAuth to configure Better Auth dynamically.
+ */
+export async function fetchAuthConfig(publicKey, secretKey, apiUrl) {
+    const result = await fetchAuthConfigConditional(publicKey, secretKey, apiUrl);
+    if (!result.config) {
+        throw new Error("Server returned no auth config payload");
+    }
+    return result.config;
+}
+/**
+ * Fetches auth configuration with conditional ETag support.
+ *
+ * - Sends If-None-Match when an ETag is provided
+ * - Returns notModified=true for 304 responses
+ */
+export async function fetchAuthConfigConditional(publicKey, secretKey, apiUrl, etag) {
+    const http = createHttpClient({ publicKey, apiUrl, secretKey });
+    const result = await http.getConditional("/api/auth/settings/server-config", etag);
+    return { notModified: result.notModified, config: result.data, etag: result.etag };
+}

package/dist/server/email-sender.d.ts

@@ -0,0 +1,29 @@
+interface EmailSenderOptions {
+    waitlistEnabled?: boolean;
+}
+/**
+ * Creates email callback functions that route Better Auth's email events
+ * through the AscendKit backend's content service + SES delivery pipeline.
+ */
+export declare function createEmailSender(publicKey: string, apiUrl: string, options?: EmailSenderOptions): {
+    sendVerificationEmail({ user, url }: {
+        user: {
+            name: string;
+            email: string;
+        };
+        url: string;
+    }): Promise<void>;
+    sendResetPasswordEmail({ user, url }: {
+        user: {
+            name: string;
+            email: string;
+        };
+        url: string;
+    }): Promise<void>;
+    sendMagicLinkEmail({ email, url }: {
+        email: string;
+        url: string;
+    }): Promise<void>;
+};
+export {};
+//# sourceMappingURL=email-sender.d.ts.map

package/dist/server/email-sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-sender.d.ts","sourceRoot":"","sources":["../../src/server/email-sender.ts"],"names":[],"mappings":"AAqBA,UAAU,kBAAkB;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;yCAItD;QAAE,IAAI,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;0CAWrD;QAAE,IAAI,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;uCAWzD;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;EAU1E"}

package/dist/server/email-sender.js

@@ -0,0 +1,58 @@
+import { createHttpClient } from "../shared/http-client";
+/**
+ * Append `verified=true` (and optionally `waitlisted=true`) to the
+ * callbackURL embedded in Better Auth's verification link so the provider
+ * can detect a successful verification on redirect and show the right
+ * in-modal confirmation.
+ */
+function tagVerificationCallback(verificationUrl, waitlistEnabled) {
+    try {
+        const url = new URL(verificationUrl);
+        const callback = url.searchParams.get("callbackURL") || "/";
+        const sep = callback.includes("?") ? "&" : "?";
+        const tags = waitlistEnabled ? "verified=true&waitlisted=true" : "verified=true";
+        url.searchParams.set("callbackURL", `${callback}${sep}${tags}`);
+        return url.toString();
+    }
+    catch {
+        return verificationUrl;
+    }
+}
+/**
+ * Creates email callback functions that route Better Auth's email events
+ * through the AscendKit backend's content service + SES delivery pipeline.
+ */
+export function createEmailSender(publicKey, apiUrl, options = {}) {
+    const http = createHttpClient({ publicKey, apiUrl });
+    return {
+        async sendVerificationEmail({ user, url }) {
+            await http.post("/api/auth/email/send", {
+                type: "email-verification",
+                to: user.email,
+                variables: {
+                    userName: user.name || "",
+                    verificationUrl: tagVerificationCallback(url, options.waitlistEnabled ?? false),
+                },
+            });
+        },
+        async sendResetPasswordEmail({ user, url }) {
+            await http.post("/api/auth/email/send", {
+                type: "password-reset",
+                to: user.email,
+                variables: {
+                    userName: user.name || "",
+                    resetUrl: url,
+                },
+            });
+        },
+        async sendMagicLinkEmail({ email, url }) {
+            await http.post("/api/auth/email/send", {
+                type: "magic-link",
+                to: email,
+                variables: {
+                    magicLinkUrl: url,
+                },
+            });
+        },
+    };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,10 @@
+export { AscendKitAuth } from "./ascendkit-auth";
+export { createAscendKitAuthRuntime } from "./auth-runtime";
+export { createAscendKitAdapter } from "./adapter";
+export { createAccessTokenHandler } from "./access-token";
+export { Analytics } from "./analytics";
+export { verifyWebhookSignature } from "./webhooks";
+export { toNextJsHandler } from "better-auth/next-js";
+export type { AscendKitAuthOptions } from "../shared/types";
+export type { AscendKitAuthRuntime } from "./auth-runtime";
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,YAAY,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/server/index.js

@@ -0,0 +1,7 @@
+export { AscendKitAuth } from "./ascendkit-auth";
+export { createAscendKitAuthRuntime } from "./auth-runtime";
+export { createAscendKitAdapter } from "./adapter";
+export { createAccessTokenHandler } from "./access-token";
+export { Analytics } from "./analytics";
+export { verifyWebhookSignature } from "./webhooks";
+export { toNextJsHandler } from "better-auth/next-js";

package/dist/server/oauth-proxy-plugin.d.ts

@@ -0,0 +1,10 @@
+import type { BetterAuthPlugin } from "better-auth";
+export interface AscendKitOAuthProxyPluginOptions {
+    publicKey: string;
+    apiUrl: string;
+    proxyProviders: string[];
+    waitlistRedirectPath?: string;
+    rejectedRedirectPath?: string;
+}
+export declare function ascendkitOAuthProxyPlugin(options: AscendKitOAuthProxyPluginOptions): BetterAuthPlugin;
+//# sourceMappingURL=oauth-proxy-plugin.d.ts.map

package/dist/server/oauth-proxy-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-proxy-plugin.d.ts","sourceRoot":"","sources":["../../src/server/oauth-proxy-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAKpD,MAAM,WAAW,gCAAgC;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAoED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gCAAgC,GACxC,gBAAgB,CAqIlB"}

package/dist/server/oauth-proxy-plugin.js

@@ -0,0 +1,156 @@
+import { createAuthEndpoint, createAuthMiddleware } from "better-auth/plugins";
+import { APIError } from "better-call";
+import * as z from "zod";
+const proxyCallbackQuerySchema = z.object({
+    ticket: z.string().optional(),
+    callback_url: z.string().optional(),
+    error: z.string().optional(),
+});
+function stripTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+function resolveCurrentOrigin(ctx) {
+    const requestUrl = ctx.request?.url;
+    if (typeof requestUrl === "string") {
+        return new URL(requestUrl).origin;
+    }
+    if (requestUrl instanceof URL) {
+        return requestUrl.origin;
+    }
+    if (ctx.context.baseURL) {
+        return new URL(ctx.context.baseURL).origin;
+    }
+    return "http://localhost:3000";
+}
+function sanitizeFinalCallback(callbackURL, currentOrigin) {
+    if (!callbackURL) {
+        return "/";
+    }
+    if (callbackURL.startsWith("/") && !callbackURL.startsWith("//")) {
+        return callbackURL;
+    }
+    try {
+        const parsed = new URL(callbackURL);
+        if (parsed.origin !== currentOrigin) {
+            return "/";
+        }
+        return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+    }
+    catch {
+        return "/";
+    }
+}
+function appendQuery(path, key, value) {
+    const parsed = new URL(path, "http://ascendkit.local");
+    parsed.searchParams.set(key, value);
+    return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+}
+function normalizeProxyError(rawError) {
+    const trimmed = rawError.trim();
+    const lowered = trimmed.toLowerCase();
+    if (lowered === "account is pending approval") {
+        return "waitlist_pending";
+    }
+    if (lowered === "account has been rejected") {
+        return "waitlist_rejected";
+    }
+    return trimmed;
+}
+export function ascendkitOAuthProxyPlugin(options) {
+    const proxyProviders = new Set(options.proxyProviders);
+    const apiUrl = stripTrailingSlash(options.apiUrl);
+    return {
+        id: "ascendkit-oauth-proxy",
+        endpoints: {
+            ascendkitOAuthProxyCallback: createAuthEndpoint("/callback/ascendkit-proxy", {
+                method: "GET",
+                query: proxyCallbackQuerySchema,
+            }, async (ctx) => {
+                const currentOrigin = resolveCurrentOrigin(ctx);
+                const finalCallback = sanitizeFinalCallback(ctx.query.callback_url, currentOrigin);
+                if (ctx.query.error) {
+                    const normalizedError = normalizeProxyError(ctx.query.error);
+                    if (normalizedError === "waitlist_pending" && options.waitlistRedirectPath) {
+                        const waitlistRedirect = sanitizeFinalCallback(options.waitlistRedirectPath, currentOrigin);
+                        throw ctx.redirect(waitlistRedirect);
+                    }
+                    if (normalizedError === "waitlist_rejected" && options.rejectedRedirectPath) {
+                        const rejectedRedirect = sanitizeFinalCallback(options.rejectedRedirectPath, currentOrigin);
+                        throw ctx.redirect(rejectedRedirect);
+                    }
+                    throw ctx.redirect(appendQuery(finalCallback, "error", normalizedError));
+                }
+                if (!ctx.query.ticket) {
+                    throw ctx.redirect(appendQuery(finalCallback, "error", "missing_ticket"));
+                }
+                let sessionToken;
+                try {
+                    const res = await fetch(`${apiUrl}/api/oauth/ticket/exchange`, {
+                        method: "POST",
+                        headers: {
+                            "Content-Type": "application/json",
+                            "X-AscendKit-Public-Key": options.publicKey,
+                        },
+                        body: JSON.stringify({ ticket: ctx.query.ticket }),
+                    });
+                    const json = await res.json().catch(() => ({}));
+                    if (!res.ok || !json.data?.sessionToken) {
+                        sessionToken = undefined;
+                    }
+                    else {
+                        sessionToken = json.data.sessionToken;
+                    }
+                }
+                catch {
+                    throw ctx.redirect(appendQuery(finalCallback, "error", "ticket_exchange_failed"));
+                }
+                if (!sessionToken) {
+                    throw ctx.redirect(appendQuery(finalCallback, "error", "ticket_exchange_failed"));
+                }
+                const sessionCookie = ctx.context.authCookies.sessionToken;
+                await ctx.setSignedCookie(sessionCookie.name, sessionToken, ctx.context.secret, sessionCookie.attributes);
+                // Clear cache cookie so Better Auth rehydrates session from adapter.
+                const sessionDataCookie = ctx.context.authCookies.sessionData;
+                ctx.setCookie(sessionDataCookie.name, "", {
+                    ...sessionDataCookie.attributes,
+                    maxAge: 0,
+                });
+                throw ctx.redirect(finalCallback);
+            }),
+        },
+        hooks: {
+            before: [
+                {
+                    matcher(context) {
+                        return !!context.path?.startsWith("/sign-in/social");
+                    },
+                    handler: createAuthMiddleware(async (ctx) => {
+                        const provider = ctx.body?.provider;
+                        if (!provider || !proxyProviders.has(provider)) {
+                            return;
+                        }
+                        const callbackURL = typeof ctx.body.callbackURL === "string"
+                            ? ctx.body.callbackURL
+                            : "/";
+                        const currentOrigin = resolveCurrentOrigin(ctx);
+                        const basePath = ctx.context.options.basePath || "/api/auth";
+                        const proxyCallbackURL = `${stripTrailingSlash(currentOrigin)}${basePath}/callback/ascendkit-proxy`;
+                        const authorizeURL = new URL(`${apiUrl}/api/oauth/authorize/${provider}`);
+                        authorizeURL.searchParams.set("pk", options.publicKey);
+                        authorizeURL.searchParams.set("callback_url", proxyCallbackURL);
+                        authorizeURL.searchParams.set("app_callback_url", callbackURL);
+                        const url = authorizeURL.toString();
+                        // Returning a plain object from a "before" hook can cause request headers
+                        // (including Content-Length) to leak into the response in Better Auth's
+                        // toAuthEndpoints bridge, which truncates JSON bodies. Throw a 200 APIError
+                        // payload instead so Better Auth client still receives { url, redirect }.
+                        throw new APIError(200, {
+                            url,
+                            redirect: !ctx.body.disableRedirect,
+                        });
+                    }),
+                },
+            ],
+        },
+    };
+}

package/dist/server/social-providers.d.ts

@@ -0,0 +1,12 @@
+import type { AuthConfig } from "../shared/types";
+/**
+ * Converts AscendKit auth config into Better Auth's socialProviders format.
+ *
+ * Better Auth expects: { google: { clientId, clientSecret }, github: { ... } }
+ * Our config returns the same shape from resolve_credentials() on the backend.
+ */
+export declare function buildSocialProviders(config: AuthConfig): Record<string, {
+    clientId: string;
+    clientSecret: string;
+}>;
+//# sourceMappingURL=social-providers.d.ts.map

package/dist/server/social-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"social-providers.d.ts","sourceRoot":"","sources":["../../src/server/social-providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,GACjB,MAAM,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CAQ5D"}

package/dist/server/social-providers.js

@@ -0,0 +1,15 @@
+/**
+ * Converts AscendKit auth config into Better Auth's socialProviders format.
+ *
+ * Better Auth expects: { google: { clientId, clientSecret }, github: { ... } }
+ * Our config returns the same shape from resolve_credentials() on the backend.
+ */
+export function buildSocialProviders(config) {
+    const providers = {};
+    for (const [name, creds] of Object.entries(config.oauth)) {
+        if (creds.flowType !== "proxy" && creds.clientId && creds.clientSecret) {
+            providers[name] = { clientId: creds.clientId, clientSecret: creds.clientSecret };
+        }
+    }
+    return providers;
+}

package/dist/server/webhooks.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Verify an AscendKit webhook signature.
+ *
+ * AscendKit signs every webhook request with an HMAC-SHA256 signature. The
+ * signature header contains a timestamp and one or more versioned signatures
+ * in the format: `t=<unix_seconds>,v1=<hex_hmac>`.
+ *
+ * The signed content is `<timestamp>.<raw_body>`, ensuring both freshness
+ * and integrity.
+ *
+ * @param secret - Your webhook signing secret.
+ * @param signatureHeader - The value of the `X-AscendKit-Signature` header.
+ * @param payload - The raw request body as a string.
+ * @param tolerance - Maximum allowed age of the timestamp in seconds (default 300).
+ * @returns `true` if the signature is valid and the timestamp is within tolerance.
+ *
+ * @example
+ * ```ts
+ * // app/api/webhooks/ascendkit/route.ts
+ * import { verifyWebhookSignature } from "@ascendkit/nextjs/server";
+ *
+ * export async function POST(req: Request) {
+ *   const body = await req.text();
+ *   const signature = req.headers.get("x-ascendkit-signature") ?? "";
+ *
+ *   const isValid = verifyWebhookSignature(
+ *     process.env.ASCENDKIT_WEBHOOK_SECRET!,
+ *     signature,
+ *     body,
+ *   );
+ *
+ *   if (!isValid) {
+ *     return new Response("Invalid signature", { status: 401 });
+ *   }
+ *
+ *   const event = JSON.parse(body);
+ *   // Handle the event...
+ *   return new Response("OK", { status: 200 });
+ * }
+ * ```
+ */
+export declare function verifyWebhookSignature(secret: string, signatureHeader: string, payload: string, tolerance?: number): boolean;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/server/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/server/webhooks.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAAkC,GAC5C,OAAO,CA8CT"}

package/dist/server/webhooks.js

@@ -0,0 +1,83 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** Default tolerance for timestamp validation (5 minutes). */
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * Verify an AscendKit webhook signature.
+ *
+ * AscendKit signs every webhook request with an HMAC-SHA256 signature. The
+ * signature header contains a timestamp and one or more versioned signatures
+ * in the format: `t=<unix_seconds>,v1=<hex_hmac>`.
+ *
+ * The signed content is `<timestamp>.<raw_body>`, ensuring both freshness
+ * and integrity.
+ *
+ * @param secret - Your webhook signing secret.
+ * @param signatureHeader - The value of the `X-AscendKit-Signature` header.
+ * @param payload - The raw request body as a string.
+ * @param tolerance - Maximum allowed age of the timestamp in seconds (default 300).
+ * @returns `true` if the signature is valid and the timestamp is within tolerance.
+ *
+ * @example
+ * ```ts
+ * // app/api/webhooks/ascendkit/route.ts
+ * import { verifyWebhookSignature } from "@ascendkit/nextjs/server";
+ *
+ * export async function POST(req: Request) {
+ *   const body = await req.text();
+ *   const signature = req.headers.get("x-ascendkit-signature") ?? "";
+ *
+ *   const isValid = verifyWebhookSignature(
+ *     process.env.ASCENDKIT_WEBHOOK_SECRET!,
+ *     signature,
+ *     body,
+ *   );
+ *
+ *   if (!isValid) {
+ *     return new Response("Invalid signature", { status: 401 });
+ *   }
+ *
+ *   const event = JSON.parse(body);
+ *   // Handle the event...
+ *   return new Response("OK", { status: 200 });
+ * }
+ * ```
+ */
+export function verifyWebhookSignature(secret, signatureHeader, payload, tolerance = DEFAULT_TOLERANCE_SECONDS) {
+    // Parse header: t=<timestamp>,v1=<hmac>
+    const parts = signatureHeader.split(",");
+    let timestamp;
+    let signatureHex;
+    for (const part of parts) {
+        const [key, value] = part.split("=", 2);
+        if (key === "t") {
+            timestamp = value;
+        }
+        else if (key === "v1") {
+            signatureHex = value;
+        }
+    }
+    if (!timestamp || !signatureHex) {
+        return false;
+    }
+    // Validate timestamp freshness
+    const timestampSeconds = parseInt(timestamp, 10);
+    if (Number.isNaN(timestampSeconds)) {
+        return false;
+    }
+    const now = Math.floor(Date.now() / 1000);
+    if (Math.abs(now - timestampSeconds) > tolerance) {
+        return false;
+    }
+    // Compute expected signature: HMAC-SHA256 of "<timestamp>.<payload>"
+    const signedContent = `${timestamp}.${payload}`;
+    const expectedHmac = createHmac("sha256", secret)
+        .update(signedContent)
+        .digest("hex");
+    // Constant-time comparison to prevent timing attacks
+    const expectedBuffer = Buffer.from(expectedHmac, "hex");
+    const receivedBuffer = Buffer.from(signatureHex, "hex");
+    if (expectedBuffer.length !== receivedBuffer.length) {
+        return false;
+    }
+    return timingSafeEqual(expectedBuffer, receivedBuffer);
+}

package/dist/shared/http-client.d.ts

@@ -0,0 +1,17 @@
+export interface HttpClientOptions {
+    publicKey: string;
+    apiUrl: string;
+    secretKey?: string;
+}
+export interface ConditionalGetResult<T> {
+    notModified: boolean;
+    data?: T;
+    etag?: string;
+}
+export declare function createHttpClient({ publicKey, apiUrl, secretKey }: HttpClientOptions): {
+    post: <T = any>(path: string, body: unknown) => Promise<T>;
+    get: <T = any>(path: string) => Promise<T>;
+    getConditional: <T = any>(path: string, etag?: string) => Promise<ConditionalGetResult<T>>;
+};
+export type HttpClient = ReturnType<typeof createHttpClient>;
+//# sourceMappingURL=http-client.d.ts.map

package/dist/shared/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../../src/shared/http-client.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,gBAAgB,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,iBAAiB;WAgB9D,CAAC,cAAc,MAAM,QAAQ,OAAO,KAAG,OAAO,CAAC,CAAC,CAAC;UASlD,CAAC,cAAc,MAAM,KAAG,OAAO,CAAC,CAAC,CAAC;qBAOvB,CAAC,cAAc,MAAM,SAAS,MAAM,KAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC;EA0BtG;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC"}