@robelest/convex-auth 0.0.2 → 0.0.3-preview.1

package/src/cli/utils.ts

@@ -0,0 +1,248 @@
+/**
+ * Shared CLI utilities — logging, subprocess execution, file helpers.
+ *
+ * Eliminates duplication across index.ts, portal-upload.ts, portal-link.ts.
+ * All output goes to stderr so stdout can be piped cleanly.
+ */
+
+import chalk from "chalk";
+import { execFileSync } from "child_process";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { extname } from "path";
+
+// ---------------------------------------------------------------------------
+// Logging — unified output to stderr with chalk prefixes
+// ---------------------------------------------------------------------------
+
+const write = (msg: string) => process.stderr.write(msg + "\n");
+
+export const log = {
+  step:    (n: number, msg: string) => write(`${chalk.blue.bold(`[${n}]`)} ${chalk.bold(msg)}`),
+  success: (msg: string) => write(`${chalk.green("✔")} ${msg}`),
+  warn:    (msg: string) => write(`${chalk.yellow.bold("!")} ${msg}`),
+  error:   (msg: string, detail?: string) =>
+    write(`${chalk.red("✖")} ${msg}${detail ? `\n  ${chalk.grey(`Error: ${detail}`)}` : ""}`),
+  info:    (msg: string) => write(`${chalk.blue.bold("i")} ${msg}`),
+  blank:   () => write(""),
+  raw:     (msg: string) => write(msg),
+  indent:  (msg: string) => write(`  ${msg}`),
+} as const;
+
+// ---------------------------------------------------------------------------
+// Subprocess — safe execFile with argument arrays (no shell injection)
+// ---------------------------------------------------------------------------
+
+export type DeploymentOptions = {
+  prod?: boolean;
+  adminKey?: string;
+  url?: string;
+  previewName?: string;
+  deploymentName?: string;
+};
+
+/** Build CLI args array for Convex deployment selection. */
+export const deploymentArgs = (opts: DeploymentOptions): string[] => {
+  const args: string[] = [];
+  if (opts.adminKey)       args.push("--admin-key", opts.adminKey);
+  if (opts.url)            args.push("--url", opts.url);
+  else if (opts.prod)      args.push("--prod");
+  else if (opts.previewName)     args.push("--preview-name", opts.previewName);
+  else if (opts.deploymentName)  args.push("--deployment-name", opts.deploymentName);
+  return args;
+};
+
+/** Run `npx convex env get <name>` and return the value. */
+export const envGet = (name: string, opts: DeploymentOptions): string =>
+  execFileSync("npx", ["convex", "env", "get", ...deploymentArgs(opts), name], {
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"],
+  }).slice(0, -1); // strip trailing newline
+
+/** Run `npx convex env set <name> <value>`. */
+export const envSet = (
+  name: string,
+  value: string,
+  opts: DeploymentOptions & { hideValue?: boolean },
+): void => {
+  execFileSync(
+    "npx",
+    ["convex", "env", "set", ...deploymentArgs(opts), "--", name, value],
+    { stdio: opts.hideValue ? "ignore" : "inherit" },
+  );
+};
+
+/**
+ * Run a Convex function via `npx convex run` and return parsed JSON output.
+ * Uses execFile with argument arrays — no shell injection.
+ */
+export const convexRun = <T = unknown>(
+  functionPath: string,
+  args: Record<string, unknown>,
+  opts: { prod?: boolean } = {},
+): Promise<T> =>
+  new Promise((resolve, reject) => {
+    const { execFile } = require("child_process");
+    const cmdArgs = [
+      "convex", "run", functionPath,
+      JSON.stringify(args),
+      "--typecheck=disable",
+      "--codegen=disable",
+      ...(opts.prod ? ["--prod"] : []),
+    ];
+    execFile("npx", cmdArgs, { encoding: "utf-8" }, (error: any, stdout: string, stderr: string) => {
+      if (error) {
+        reject(new Error(`convex run ${functionPath} failed: ${stderr || stdout}`));
+        return;
+      }
+      try {
+        resolve(JSON.parse(stdout.trim()) as T);
+      } catch {
+        // If output is not JSON, return raw string as-is
+        resolve(stdout.trim() as T);
+      }
+    });
+  });
+
+// ---------------------------------------------------------------------------
+// MIME types
+// ---------------------------------------------------------------------------
+
+const MIME_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js":   "application/javascript; charset=utf-8",
+  ".mjs":  "application/javascript; charset=utf-8",
+  ".css":  "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png":  "image/png",
+  ".jpg":  "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif":  "image/gif",
+  ".svg":  "image/svg+xml",
+  ".ico":  "image/x-icon",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2":"font/woff2",
+  ".ttf":  "font/ttf",
+  ".txt":  "text/plain; charset=utf-8",
+  ".map":  "application/json",
+  ".webmanifest": "application/manifest+json",
+  ".xml":  "application/xml",
+  ".br":   "application/octet-stream",
+  ".gz":   "application/gzip",
+};
+
+export const getMimeType = (path: string): string =>
+  MIME_TYPES[extname(path).toLowerCase()] ?? "application/octet-stream";
+
+// ---------------------------------------------------------------------------
+// File helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check for an existing non-empty source file (.ts or .js) at the given
+ * base path (without extension). Returns the path if found, null otherwise.
+ */
+export const findExistingSource = (basePath: string): string | null =>
+  [".ts", ".js"]
+    .map((ext) => basePath + ext)
+    .find((p) => existsSync(p) && readFileSync(p, "utf-8").trim() !== "")
+    ?? null;
+
+/**
+ * Test whether an existing file already matches a template.
+ * Templates use `$$` as wildcards and `;` followed by newline as flexible separators.
+ */
+export const matchesTemplate = (existing: string, template: string): boolean =>
+  new RegExp(
+    template
+      .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+      .replace(/\\\$\\\$/g, ".*")
+      .replace(/;\n/g, ";.*"),
+    "s",
+  ).test(existing);
+
+/** Strip template markers from a source template. */
+export const stripMarkers = (template: string): string =>
+  template.replace(/\$\$/g, "");
+
+/**
+ * Higher-order function: ensure a file matches a template.
+ *
+ * - If the file doesn't exist → create it
+ * - If it already matches → log success
+ * - If it exists but doesn't match → show instructions and prompt
+ *
+ * Returns a configured function bound to the convex folder path + TS preference.
+ */
+export const createFileEnsurer = (
+  convexFolderPath: string,
+  usesTypeScript: boolean,
+  promptFn: (message: string) => Promise<void>,
+) => {
+  const path = require("path");
+
+  return async (
+    baseName: string,
+    template: string,
+    description: string,
+  ): Promise<void> => {
+    const source = stripMarkers(template);
+    const filePath = path.join(convexFolderPath, baseName);
+    const existing = findExistingSource(filePath);
+
+    if (existing) {
+      const content = readFileSync(existing, "utf-8");
+      if (matchesTemplate(content, template)) {
+        log.success(`${chalk.bold(existing)} already configured.`);
+        return;
+      }
+      log.info(`${chalk.bold(existing)} needs ${description}:`);
+      log.raw(`\n${indentBlock(source)}\n`);
+      await promptFn("Ready to continue?");
+      return;
+    }
+
+    const ext = usesTypeScript ? ".ts" : ".js";
+    const newPath = filePath + ext;
+    writeFileSync(newPath, source);
+    log.success(`Created ${chalk.bold(newPath)}`);
+  };
+};
+
+/** Indent a multiline string (2 spaces, first line not indented). */
+export const indentBlock = (s: string): string =>
+  s.replace(/^/gm, "  ").slice(2);
+
+// ---------------------------------------------------------------------------
+// Crypto helpers (for portal invite links)
+// ---------------------------------------------------------------------------
+
+export { randomBytes, createHash } from "crypto";
+
+/** Generate a URL-safe random token (32 bytes → 43 chars base64url). */
+export const generateToken = (): string =>
+  require("crypto").randomBytes(32).toString("base64url");
+
+/** SHA-256 hash a string and return the hex digest. */
+export const hashToken = (token: string): string =>
+  require("crypto").createHash("sha256").update(token).digest("hex");
+
+// ---------------------------------------------------------------------------
+// Package version
+// ---------------------------------------------------------------------------
+
+/** Read the auth package version from its own package.json. */
+export const getPackageVersion = (): string => {
+  try {
+    const pkgPath = require("path").resolve(__dirname, "..", "package.json");
+    return JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+  } catch {
+    // Fallback: if running from dist/bin.cjs, package.json is two levels up
+    try {
+      const pkgPath = require("path").resolve(__dirname, "..", "..", "package.json");
+      return JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+    } catch {
+      return "unknown";
+    }
+  }
+};

package/src/client/index.ts

@@ -1,5 +1,13 @@
 import { ConvexHttpClient } from "convex/browser";
-import { Value } from "convex/values";
+import { ConvexError, Value } from "convex/values";
+
+// Re-export error utilities so consumers can import from `@robelest/convex-auth/client`.
+export {
+  isAuthError,
+  parseAuthError,
+  AUTH_ERRORS,
+  type AuthErrorCode,
+} from "../server/errors.js";
 
 /**
  * Structural interface for any Convex client.
@@ -31,17 +39,32 @@ type AuthSession = {
   refreshToken: string;
 };
 
-type SignInResult = {
+/**
+ * Result of a `signIn` call.
+ *
+ * - `signingIn: true` — credentials were accepted and the user is authenticated.
+ * - `redirect` — OAuth flow initiated; redirect the user to `redirect.toString()`.
+ * - `totpRequired` — credentials valid but 2FA is needed; call `auth.totp.verify()`.
+ * - `verifier` — opaque string for multi-step flows (TOTP, passkey).
+ */
+export type SignInResult = {
+  /** `true` when sign-in completed and the user is authenticated. */
   signingIn: boolean;
+  /** OAuth redirect URL. Present when the provider requires a browser redirect. */
   redirect?: URL;
+  /** `true` when the account has TOTP enabled and a code is required. */
   totpRequired?: boolean;
+  /** Opaque verifier for multi-step flows (pass to `totp.verify` or passkey phase 2). */
   verifier?: string;
 };
 
 /** Reactive auth state snapshot returned by `auth.state` and `auth.onChange`. */
 export type AuthState = {
+  /** `true` during initial hydration before the first token is resolved. */
   isLoading: boolean;
+  /** `true` when a valid JWT exists (user is signed in). */
   isAuthenticated: boolean;
+  /** The raw JWT string, or `null` when not authenticated. */
   token: string | null;
 };
 
@@ -110,14 +133,17 @@ function resolveUrl(convex: ConvexTransport, explicit?: string): string {
 /**
  * Create a framework-agnostic auth client.
  *
+ * Returns an object with `signIn`, `signOut`, `onChange`, `state`,
+ * `passkey`, and `totp` — everything needed for client-side auth.
+ *
  * ### SPA mode (default)
  *
  * ```ts
- * import { ConvexClient } from 'convex/browser'
- * import { client } from '\@robelest/convex-auth/client'
+ * import { ConvexClient } from 'convex/browser';
+ * import { client } from '@robelest/convex-auth/client';
  *
- * const convex = new ConvexClient(CONVEX_URL)
- * const auth = client({ convex })
+ * const convex = new ConvexClient(CONVEX_URL);
+ * const auth = client({ convex });
  * ```
  *
  * ### SSR / proxy mode
@@ -126,13 +152,16 @@ function resolveUrl(convex: ConvexTransport, explicit?: string): string {
  * const auth = client({
  *   convex,
  *   proxy: '/api/auth',
- *   initialToken: tokenFromServer, // read from httpOnly cookie during SSR
- * })
+ *   token: tokenFromServer, // JWT read from httpOnly cookie during SSR
+ * });
  * ```
  *
  * In proxy mode all auth operations go through the proxy URL.
  * Tokens are stored in httpOnly cookies server-side — the client
- * only holds the JWT in memory.
+ * holds the JWT in memory only.
+ *
+ * @param options - Client configuration. See {@link ClientOptions}.
+ * @returns Auth client with `signIn`, `signOut`, `onChange`, `state`, `passkey`, and `totp`.
  */
 export function client(options: ClientOptions) {
   const { convex, proxy } = options;
@@ -243,6 +272,13 @@ export function client(options: ClientOptions) {
     isLoading = false;
     const changed = updateSnapshot();
     if (hadPendingLoad || changed) {
+      // Re-sync the Convex client so it picks up the new token immediately.
+      // Without this, the initial convex.setAuth(fetchAccessToken) from
+      // initialization never re-polls and queries run unauthenticated after
+      // magic link code exchange.
+      if (!proxy) {
+        convex.setAuth(fetchAccessToken);
+      }
       notify();
     }
   };
@@ -259,9 +295,19 @@ export function client(options: ClientOptions) {
       body: JSON.stringify(body),
     });
     if (!response.ok) {
-      const error = await response.json().catch(() => ({}));
+      const errorBody = await response.json().catch(() => ({} as Record<string, unknown>));
+      // Reconstruct ConvexError when the proxy forwards structured auth error data.
+      if (
+        typeof errorBody === "object" &&
+        errorBody !== null &&
+        "authError" in errorBody &&
+        typeof (errorBody as Record<string, unknown>).authError === "object"
+      ) {
+        throw new ConvexError((errorBody as Record<string, unknown>).authError as Value);
+      }
       throw new Error(
-        (error as any).error ?? `Proxy request failed: ${response.status}`,
+        (errorBody as Record<string, unknown>).error as string ??
+          `Proxy request failed: ${response.status}`,
       );
     }
     return response.json();
@@ -312,6 +358,33 @@ export function client(options: ClientOptions) {
   // signIn
   // ---------------------------------------------------------------------------
 
+  /**
+   * Sign in with a provider.
+   *
+   * @param provider - Provider ID (e.g. `"email"`, `"password"`, `"google"`).
+   *   Omit when exchanging an OAuth code (the code carries the provider info).
+   * @param args - Provider-specific arguments. Pass a `Record<string, Value>`
+   *   or `FormData`. Common fields: `email`, `password`, `code`, `redirectTo`.
+   * @returns A {@link SignInResult} indicating the outcome.
+   *
+   * @example Email magic link
+   * ```ts
+   * await auth.signIn('email', { email: 'user@example.com' });
+   * ```
+   *
+   * @example Password
+   * ```ts
+   * const result = await auth.signIn('password', { email, password, flow: 'signIn' });
+   * if (result.totpRequired) {
+   *   await auth.totp.verify({ code: totpCode, verifier: result.verifier! });
+   * }
+   * ```
+   *
+   * @example OAuth (triggers redirect)
+   * ```ts
+   * await auth.signIn('google'); // redirects to Google
+   * ```
+   */
   const signIn = async (
     provider?: string,
     args?: FormData | Record<string, Value>,
@@ -390,6 +463,13 @@ export function client(options: ClientOptions) {
   // signOut
   // ---------------------------------------------------------------------------
 
+  /**
+   * Sign out the current user.
+   *
+   * Invalidates the server session and clears local token state.
+   * Errors are silently caught — calling `signOut` on an already
+   * signed-out user is a no-op.
+   */
   const signOut = async () => {
     if (proxy) {
       try {
@@ -502,12 +582,15 @@ export function client(options: ClientOptions) {
   // ---------------------------------------------------------------------------
 
   /**
-   * Subscribe to auth state changes. Immediately invokes the callback
-   * with the current state and returns an unsubscribe function.
+   * Subscribe to auth state changes. Invokes the callback immediately
+   * with the current state, then again on every state transition.
    *
    * ```ts
-   * const unsub = auth.onChange(setState)
+   * const unsub = auth.onChange(setState);
    * ```
+   *
+   * @param cb - Callback receiving the latest {@link AuthState}.
+   * @returns An unsubscribe function.
    */
   const onChange = (cb: (state: AuthState) => void): (() => void) => {
     cb(snapshot);
@@ -555,7 +638,11 @@ export function client(options: ClientOptions) {
       }
     } else {
       // SPA mode: hydrate from localStorage, then handle OAuth code flow.
-      void hydrateFromStorage().then(() => handleCodeFlow());
+      void hydrateFromStorage().then(() =>
+        handleCodeFlow().catch((error: unknown) => {
+          console.error("[convex-auth] Code exchange failed:", error);
+        }),
+      );
     }
   }
 
@@ -1029,8 +1116,11 @@ export function client(options: ClientOptions) {
     get state(): AuthState {
       return snapshot;
     },
+    /** Sign in with a provider. See {@link SignInResult} for return shape. */
     signIn,
+    /** Sign out and clear all token state. */
     signOut,
+    /** Subscribe to auth state changes. Returns an unsubscribe function. */
     onChange,
     /** Passkey (WebAuthn) authentication helpers. */
     passkey,

package/src/component/_generated/component.ts

@@ -210,6 +210,67 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         any,
         Name
       >;
+      keyDelete: FunctionReference<
+        "mutation",
+        "internal",
+        { keyId: string },
+        any,
+        Name
+      >;
+      keyGetByHashedKey: FunctionReference<
+        "query",
+        "internal",
+        { hashedKey: string },
+        any,
+        Name
+      >;
+      keyGetById: FunctionReference<
+        "query",
+        "internal",
+        { keyId: string },
+        any,
+        Name
+      >;
+      keyInsert: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          expiresAt?: number;
+          hashedKey: string;
+          name: string;
+          prefix: string;
+          rateLimit?: { maxRequests: number; windowMs: number };
+          scopes: Array<{ resource: string; actions: Array<string> }>;
+          userId: string;
+        },
+        any,
+        Name
+      >;
+      keyList: FunctionReference<"query", "internal", {}, any, Name>;
+      keyListByUserId: FunctionReference<
+        "query",
+        "internal",
+        { userId: string },
+        any,
+        Name
+      >;
+      keyPatch: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          data: {
+            lastUsedAt?: number;
+            name?: string;
+            rateLimit?: { maxRequests: number; windowMs: number };
+            rateLimitState?: { attemptsLeft: number; lastAttemptTime: number };
+            revoked?: boolean;
+            scopes?: Array<{ resource: string; actions: Array<string> }>;
+          };
+          keyId: string;
+        },
+        any,
+        Name
+      >;
       memberAdd: FunctionReference<
         "mutation",
         "internal",

package/src/component/index.ts

@@ -9,14 +9,19 @@
  */
 
 export {
+  /**
+   * The low-level factory function used internally by the `Auth` class.
+   * Re-exported as `AuthFactory` to avoid naming conflicts with the
+   * `Auth` class (the recommended public API). Prefer `new Auth(...)`.
+   */
   Auth as AuthFactory,
   Tokens,
   Doc,
   SignInAction,
   SignOutAction,
 } from "../server/implementation/index.js";
-export { Portal as PortalFactory } from "../server/portal.js";
-export { Auth, Portal } from "../server/convex-auth.js";
+export { Auth, Portal, AuthCtx } from "../server/convex-auth.js";
+export type { AuthCtxConfig } from "../server/convex-auth.js";
 export type {
   ConvexAuthConfig,
   AuthProviderConfig,
@@ -28,5 +33,9 @@ export type {
   GenericActionCtxWithAuthConfig,
   AuthProviderMaterializedConfig,
   ConvexAuthMaterializedConfig,
+  ApiKeyConfig,
+  KeyScope,
+  ScopeChecker,
+  KeyRecord,
 } from "../server/types.js";
 export type { GenericDoc } from "../server/convex_types.js";