@hexclave/next 1.0.3 → 1.0.6

package/src/global.css

@@ -0,0 +1,13 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+* {
+  @apply border-border;
+  .hide-password-toggle::-ms-reveal,
+  .hide-password-toggle::-ms-clear {
+    visibility: hidden;
+    pointer-events: none;
+    display: none;
+  }
+}

package/src/global.d.ts

@@ -0,0 +1,12 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import type { } from "react/canary";
+
+declare global {
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface ImportMeta {
+    readonly env?: Record<string, string | undefined>,
+  }
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+export * from './lib/hexclave-app';
+export { getConvexProvidersConfig } from "./integrations/convex";
+// Hexclave aliases and legacy Stack* names — @deprecated JSDoc lives on the original
+// declarations in @hexclave/shared/config so it survives dts bundling
+// (per-specifier JSDoc on re-exports does not).
+export type { HexclaveConfig, StackConfig } from "@hexclave/shared/config";
+export { defineHexclaveConfig, defineStackConfig } from "@hexclave/shared/config";
+
+export type { AnalyticsOptions, AnalyticsReplayOptions } from "./lib/hexclave-app/apps/implementations/session-replay";
+// Hexclave aliases and legacy Stack* names — @deprecated JSDoc lives on the original
+// declarations in the source files (so it survives dts bundling).
+export { HexclaveHandler, StackHandler } from "./components-page/hexclave-handler";
+export { useHexclaveApp, useStackApp } from "./lib/hooks";
+export { HexclaveProvider, StackProvider } from "./providers/hexclave-provider";
+export { HexclaveTheme, StackTheme } from './providers/theme-provider';
+export { useUser } from "./lib/hooks";
+
+export { AccountSettings } from "./components-page/account-settings";
+export { AuthPage } from "./components-page/auth-page";
+export { CliAuthConfirmation, useCliAuthConfirmation, type CliAuthConfirmationState, type CliAuthConfirmationStatus } from "./components-page/cli-auth-confirm";
+export { EmailVerification } from "./components-page/email-verification";
+export { ForgotPassword } from "./components-page/forgot-password";
+export { PasswordReset } from "./components-page/password-reset";
+export { SignIn } from "./components-page/sign-in";
+export { SignUp } from "./components-page/sign-up";
+export { CredentialSignIn as CredentialSignIn } from "./components/credential-sign-in";
+export { CredentialSignUp as CredentialSignUp } from "./components/credential-sign-up";
+export { UserAvatar } from "./components/elements/user-avatar";
+export { MagicLinkSignIn as MagicLinkSignIn } from "./components/magic-link-sign-in";
+export { MessageCard } from "./components/message-cards/message-card";
+export { OAuthButton } from "./components/oauth-button";
+export { OAuthButtonGroup } from "./components/oauth-button-group";
+export { SelectedTeamSwitcher } from "./components/selected-team-switcher";
+export { TeamSwitcher } from "./components/team-switcher";
+export { UserButton } from "./components/user-button";

package/src/integrations/convex/component/README.md

@@ -0,0 +1,74 @@
+# Hexclave Convex Component
+
+This component is the official way to integrate Hexclave with your Convex project.
+
+## Installation
+
+To get started, first install Hexclave using the setup wizard:
+
+```bash
+npx @hexclave/cli@latest init
+```
+
+## Get Started
+
+[Create a new Hexclave project](https://app.hexclave.com) and set the environment variables in Convex to the project ID & API key environment variables from the Hexclave dashboard. Also, add the same values to the `.env.local` file.
+
+Next, update or create a file in `convex/auth.config.ts`:
+
+```ts
+import { getConvexProvidersConfig } from "@hexclave/js/convex-auth.config";  // Vanilla JS
+// or: import { getConvexProvidersConfig } from "@hexclave/react/convex-auth.config";  // React
+// or: import { getConvexProvidersConfig } from "@hexclave/next/convex-auth.config";  // Next.js
+
+export default {
+  providers: getConvexProvidersConfig({
+    projectId: process.env.STACK_PROJECT_ID,  // or: process.env.NEXT_PUBLIC_STACK_PROJECT_ID
+  }),
+}
+```
+
+Next, update or create a file in `convex/convex.config.ts`:
+
+```ts
+import { defineApp } from "convex/server";
+import stackAuthComponent from "@hexclave/js/convex.config";  // Vanilla JS
+// or: import stackAuthComponent from "@hexclave/react/convex.config";  // React
+// or: import stackAuthComponent from "@hexclave/next/convex.config";  // Next.js
+
+
+const app = defineApp();
+app.use(stackAuthComponent);
+
+export default app;
+```
+
+Then, update your Convex client to use Hexclave:
+
+```ts
+convexClient.setAuth(hexclaveClientApp.getConvexClientAuth({}));  // browser JS
+convexReactClient.setAuth(hexclaveClientApp.getConvexClientAuth({}));  // React
+convexHttpClient.setAuth(hexclaveClientApp.getConvexHttpClientAuth({ tokenStore: requestObject }));  // HTTP, see Hexclave docs for more information on tokenStore
+```
+
+Now, you'll be able to access Hexclave's functionality from your frontend & backend:
+
+```ts
+// MyPage.tsx
+export function MyPage() {
+  // see https://docs.hexclave.com for more information on how to use Hexclave
+  const user = useUser();
+  return <div>Your email is {user.email}</div>;
+}
+
+// myFunctions.ts
+export const myQuery = query({
+  handler: async (ctx, args) => {
+    // In queries & mutations, use the special `getPartialUser` function to get user info
+    const obj = await hexclaveServerApp.getPartialUser({ from: "convex", ctx });
+    return JSON.stringify(obj);
+  },
+});
+```
+
+For more information on how to use Hexclave, see the [Hexclave docs](https://docs.hexclave.com).

package/src/integrations/convex/component/convex.config.ts

@@ -0,0 +1,9 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { defineComponent } from "convex/server";
+
+const component = defineComponent("stack_auth");
+
+export default component;

package/src/integrations/convex.ts

@@ -0,0 +1,28 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { urlString } from "@hexclave/shared/dist/utils/urls";
+import { defaultBaseUrl } from "../lib/hexclave-app/apps/implementations/common";
+
+export function getConvexProvidersConfig(options: {
+  baseUrl?: string,
+  projectId: string,
+}) {
+  const baseUrl = options.baseUrl || defaultBaseUrl;
+  const projectId = options.projectId;
+  return [
+    {
+      type: "customJwt",
+      issuer: new URL(urlString`/api/v1/projects/${projectId}`, baseUrl),
+      jwks: new URL(urlString`/api/v1/projects/${projectId}/.well-known/jwks.json`, baseUrl),
+      algorithm: "ES256",
+    },
+    {
+      type: "customJwt",
+      issuer: new URL(urlString`/api/v1/projects-anonymous-users/${projectId}`, baseUrl),
+      jwks: new URL(urlString`/api/v1/projects/${projectId}/.well-known/jwks.json?include_anonymous=true`, baseUrl),
+      algorithm: "ES256",
+    },
+  ];
+}

package/src/lib/auth.test.ts

@@ -0,0 +1,67 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+// @vitest-environment jsdom
+
+import { HexclaveClientInterface } from "@hexclave/shared";
+import { describe, expect, it, vi } from "vitest";
+import { getNewOAuthProviderOrScopeUrl } from "./auth";
+
+vi.mock("./cookie", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./cookie")>();
+  return {
+    ...actual,
+    saveVerifierAndState: async () => ({
+      codeChallenge: "<stripped code challenge>",
+      state: "<stripped state>",
+    }),
+  };
+});
+
+describe("getNewOAuthProviderOrScopeUrl", () => {
+  it("returns the OAuth URL without performing navigation", async () => {
+    window.history.replaceState({}, "", "/account?after_auth_return_to=%2Fsettings");
+
+    const iface = new HexclaveClientInterface({
+      clientVersion: "test",
+      getBaseUrl: () => "https://api.example.com",
+      getApiUrls: () => ["https://api.example.com"],
+      extraRequestHeaders: {},
+      projectId: "00000000-0000-4000-8000-000000000000",
+      publishableClientKey: "pck_test",
+    });
+    const session = iface.createSession({ refreshToken: null, accessToken: null });
+
+    const location = await getNewOAuthProviderOrScopeUrl(
+      iface,
+      {
+        provider: "github",
+        redirectUrl: "/handler/oauth-callback",
+        errorRedirectUrl: "/handler/error",
+        providerScope: "repo user",
+      },
+      session,
+    );
+
+    const url = new URL(location);
+    expect(`${url.origin}${url.pathname}`).toBe("https://api.example.com/api/v1/auth/oauth/authorize/github");
+    expect(Object.fromEntries(url.searchParams.entries())).toMatchInlineSnapshot(`
+      {
+        "after_callback_redirect_url": "http://localhost:3000/account?after_auth_return_to=%2Fsettings",
+        "client_id": "00000000-0000-4000-8000-000000000000",
+        "client_secret": "pck_test",
+        "code_challenge": "<stripped code challenge>",
+        "code_challenge_method": "S256",
+        "error_redirect_url": "http://localhost:3000/handler/error?after_auth_return_to=%2Fsettings",
+        "grant_type": "authorization_code",
+        "provider_scope": "repo user",
+        "redirect_uri": "http://localhost:3000/handler/oauth-callback?after_auth_return_to=%2Fsettings",
+        "response_type": "code",
+        "scope": "legacy",
+        "state": "<stripped state>",
+        "type": "link",
+      }
+    `);
+  });
+});

package/src/lib/auth.ts

@@ -0,0 +1,175 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { KnownError, HexclaveClientInterface } from "@hexclave/shared";
+import { InternalSession } from "@hexclave/shared/dist/sessions";
+import { HexclaveAssertionError, throwErr } from "@hexclave/shared/dist/utils/errors";
+import { Result } from "@hexclave/shared/dist/utils/results";
+import { deindent } from "@hexclave/shared/dist/utils/strings";
+import { constructRedirectUrl } from "../utils/url";
+import { consumeVerifierAndStateCookie, saveVerifierAndState } from "./cookie";
+export async function getNewOAuthProviderOrScopeUrl(
+  iface: HexclaveClientInterface,
+  options: {
+    provider: string,
+    redirectUrl: string,
+    errorRedirectUrl: string,
+    providerScope?: string,
+  },
+  session: InternalSession,
+): Promise<string> {
+  const { codeChallenge, state } = await saveVerifierAndState();
+  return await iface.getOAuthUrl({
+    provider: options.provider,
+    redirectUrl: constructRedirectUrl(options.redirectUrl, "redirectUrl"),
+    errorRedirectUrl: constructRedirectUrl(options.errorRedirectUrl, "errorRedirectUrl"),
+    afterCallbackRedirectUrl: constructRedirectUrl(window.location.href, "afterCallbackRedirectUrl"),
+    codeChallenge,
+    state,
+    type: "link",
+    session,
+    providerScope: options.providerScope,
+  });
+}
+
+/**
+ * Checks if the current URL has the query parameters for an OAuth callback, and if so, removes them.
+ *
+ * Must be synchronous for the logic in callOAuthCallback to work without race conditions.
+ */
+type OAuthCallbackConsumptionResult =
+  | {
+    type: "oauth-response",
+    originalUrl: URL,
+    codeVerifier: string,
+    state: string,
+  }
+  | {
+    type: "known-error",
+    error: KnownError,
+  };
+
+function consumeOAuthCallbackQueryParams(options?: {
+  dontWarnAboutMissingQueryParams?: boolean,
+}): OAuthCallbackConsumptionResult | null {
+  const oauthErrorParams = ["error", "error_description", "errorCode", "message", "details"] as const;
+  const requiredParams = ["code", "state"];
+  const originalUrl = new URL(window.location.href);
+  const knownErrorCode = originalUrl.searchParams.get("errorCode");
+  const knownErrorMessage = originalUrl.searchParams.get("message");
+  if (knownErrorCode && knownErrorMessage) {
+    const details = originalUrl.searchParams.get("details");
+    let detailsJson = {};
+    if (details) {
+      try {
+        detailsJson = JSON.parse(details);
+      } catch (error) {
+        throw new HexclaveAssertionError("OAuth callback returned malformed known-error details", {
+          details,
+          cause: error,
+        });
+      }
+    }
+
+    const newUrl = new URL(originalUrl);
+    for (const param of oauthErrorParams) {
+      newUrl.searchParams.delete(param);
+    }
+    window.history.replaceState({}, "", newUrl.toString());
+
+    return {
+      type: "known-error",
+      error: KnownError.fromJson({
+        code: knownErrorCode,
+        message: knownErrorMessage,
+        details: detailsJson,
+      }),
+    };
+  }
+
+  for (const param of requiredParams) {
+    if (!originalUrl.searchParams.has(param)) {
+      if (!options?.dontWarnAboutMissingQueryParams) {
+        console.warn(new Error(`Missing required query parameter on OAuth callback: ${param}. Maybe you opened or reloaded the oauth-callback page from your history?`));
+      }
+      return null;
+    }
+  }
+
+  const expectedState = originalUrl.searchParams.get("state") ?? throwErr("This should never happen; isn't state required above?");
+  const cookieResult = consumeVerifierAndStateCookie(expectedState);
+
+  if (!cookieResult) {
+    // If the state can't be found in the cookies, then the callback wasn't meant for us.
+    // Maybe the website uses another OAuth library?
+    console.warn(deindent`
+      Stack found an outer OAuth callback state in the query parameters, but not in cookies.
+
+      This could have multiple reasons:
+        - The cookie expired, because the OAuth flow took too long.
+        - The user's browser deleted the cookie, either manually or because of a very strict cookie policy.
+        - The cookie was already consumed by this page, and the user already logged in.
+        - You are using another OAuth client library with the same callback URL as Stack.
+        - The user opened the OAuth callback page from their history.
+
+      Either way, it is probably safe to ignore this warning unless you are debugging an OAuth issue.
+    `);
+    return null;
+  }
+
+
+  const newUrl = new URL(originalUrl);
+  for (const param of requiredParams) {
+    newUrl.searchParams.delete(param);
+  }
+
+  // let's get rid of the authorization code in the history as we
+  // don't redirect to `redirectUrl` if there's a validation error
+  // (as the redirectUrl might be malicious!).
+  //
+  // We use history.replaceState instead of location.assign(...) to
+  // prevent an unnecessary reload
+  window.history.replaceState({}, "", newUrl.toString());
+
+  return {
+    type: "oauth-response",
+    originalUrl,
+    codeVerifier: cookieResult.codeVerifier,
+    state: expectedState,
+  };
+}
+
+export async function callOAuthCallback(
+  iface: HexclaveClientInterface,
+  redirectUrl: string,
+  options?: {
+    dontWarnAboutMissingQueryParams?: boolean,
+  },
+) {
+  // note: this part of the function (until the return) needs
+  // to be synchronous, to prevent race conditions when
+  // callOAuthCallback is called multiple times in parallel
+  const consumed = consumeOAuthCallbackQueryParams(options);
+  if (!consumed) return Result.ok(undefined);
+  if (consumed.type === "known-error") {
+    throw consumed.error;
+  }
+
+  // the rest can be asynchronous (we now know that we are the
+  // intended recipient of the callback, and the only instance
+  // of callOAuthCallback that's running)
+  try {
+    return Result.ok(await iface.callOAuthCallback({
+      oauthParams: consumed.originalUrl.searchParams,
+      redirectUri: constructRedirectUrl(redirectUrl, "redirectUri"),
+      codeVerifier: consumed.codeVerifier,
+      state: consumed.state,
+    }));
+  } catch (e) {
+    if (KnownError.isKnownError(e)) {
+      throw e;
+    }
+    throw new HexclaveAssertionError("Error signing in during OAuth callback. Please try again.", { cause: e });
+  }
+}