heartbeads 0.4.0

package/lib/agent.ts

@@ -0,0 +1,29 @@
+import { Agent } from '@atproto/api'
+import { getGlobalOAuthClient } from './auth/client'
+import { getSession } from './session'
+
+/**
+ * Get an authenticated ATProto agent for the current user.
+ * Uses the OAuth session stored in the cookie to restore credentials.
+ * Returns null if not authenticated.
+ */
+export async function getAuthenticatedAgent(): Promise<Agent | null> {
+  const session = await getSession()
+  if (!session.did) {
+    return null
+  }
+
+  try {
+    const client = await getGlobalOAuthClient()
+    const oauthSession = await client.restore(session.did)
+
+    if (!oauthSession) {
+      return null
+    }
+
+    return new Agent(oauthSession)
+  } catch (err) {
+    console.error('Failed to restore authenticated agent:', err)
+    return null
+  }
+}

package/lib/api-helpers.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared helpers for /api/v1/* routes.
+ * Provides CORS headers, JSON response builders, and OPTIONS handler.
+ */
+
+import { NextResponse } from "next/server";
+
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type",
+};
+
+/**
+ * Build a JSON response with CORS and Cache-Control headers.
+ */
+export function jsonResponse(data: unknown, status = 200) {
+  return NextResponse.json(data, {
+    status,
+    headers: {
+      ...CORS_HEADERS,
+      "Cache-Control": "public, max-age=30",
+    },
+  });
+}
+
+/**
+ * Build an error JSON response with CORS headers (no caching).
+ */
+export function errorResponse(
+  error: string,
+  status: number,
+  hint?: string
+) {
+  return NextResponse.json(
+    { error, ...(hint ? { hint } : {}) },
+    { status, headers: CORS_HEADERS }
+  );
+}
+
+/**
+ * Preflight OPTIONS handler for CORS. Re-export from each route file.
+ */
+export function OPTIONS() {
+  return new NextResponse(null, { status: 204, headers: CORS_HEADERS });
+}

package/lib/auth/client.ts

@@ -0,0 +1,221 @@
+import { NodeOAuthClient } from "@atproto/oauth-client-node";
+import { JoseKey } from "@atproto/jwk-jose";
+import { env } from "../env";
+import { getRawSession } from "../session";
+
+const oauthClientKey = "globalOAuthClient";
+// In development, clear cached client on hot reload to pick up config changes
+if (process.env.NODE_ENV !== "production") {
+  (global as Record<string, unknown>)[oauthClientKey] = null;
+}
+if (!(global as Record<string, unknown>)[oauthClientKey]) {
+  (global as Record<string, unknown>)[oauthClientKey] = null;
+}
+
+/**
+ * OAuth Client Configuration
+ *
+ * Supports two modes:
+ *
+ * 1. CONFIDENTIAL CLIENT (Production)
+ *    - Requires ATPROTO_JWK_PRIVATE and PUBLIC_URL environment variables
+ *    - Authenticates to auth servers using private key JWT
+ *    - Longer session lifetimes
+ *
+ * 2. PUBLIC CLIENT (Development fallback)
+ *    - Used when ATPROTO_JWK_PRIVATE is not set
+ *    - No client authentication
+ *    - Shorter session lifetimes
+ */
+
+// ============================================================================
+// In-Memory Store with Cookie Sync
+// ============================================================================
+
+const globalStoreKey = "oauthSharedStore";
+if (!(global as Record<string, unknown>)[globalStoreKey]) {
+  (global as Record<string, unknown>)[globalStoreKey] = new Map();
+}
+const sharedStore: Map<string, unknown> = (
+  global as Record<string, unknown>
+)[globalStoreKey] as Map<string, unknown>;
+
+// State store - in-memory only, used during short-lived OAuth flow
+const stateStore = {
+  async get(key: string) {
+    return sharedStore.get(`state:${key}`);
+  },
+  async set(key: string, value: unknown) {
+    sharedStore.set(`state:${key}`, value);
+  },
+  async del(key: string) {
+    sharedStore.delete(`state:${key}`);
+  },
+};
+
+// Session store - syncs with cookie for persistence
+const sessionStore = {
+  async get(key: string) {
+    const memValue = sharedStore.get(`session:${key}`);
+    if (memValue) {
+      return memValue;
+    }
+
+    try {
+      const session = await getRawSession();
+      if (session.oauthSession && session.did === key) {
+        const parsed = JSON.parse(session.oauthSession);
+        sharedStore.set(`session:${key}`, parsed);
+        return parsed;
+      }
+    } catch (err) {
+      console.warn("Failed to restore OAuth session from cookie:", err);
+    }
+
+    return undefined;
+  },
+  async set(key: string, value: unknown) {
+    sharedStore.set(`session:${key}`, value);
+
+    try {
+      const session = await getRawSession();
+      session.oauthSession = JSON.stringify(value);
+      await session.save();
+    } catch (err) {
+      console.warn("Failed to save OAuth session to cookie:", err);
+    }
+  },
+  async del(key: string) {
+    sharedStore.delete(`session:${key}`);
+
+    try {
+      const session = await getRawSession();
+      session.oauthSession = undefined;
+      await session.save();
+    } catch (err) {
+      console.warn("Failed to clear OAuth session from cookie:", err);
+    }
+  },
+};
+
+// ============================================================================
+// JWK Keyset Management
+// ============================================================================
+
+let cachedKeyset: Awaited<ReturnType<typeof JoseKey.fromImportable>>[] | null =
+  null;
+
+async function getKeyset() {
+  if (cachedKeyset) {
+    return cachedKeyset;
+  }
+
+  const jwkPrivate = env.ATPROTO_JWK_PRIVATE;
+  if (!jwkPrivate) {
+    return null; // Public client mode
+  }
+
+  try {
+    const jwk = JSON.parse(jwkPrivate);
+    const key = await JoseKey.fromImportable(jwk, jwk.kid || "key-1");
+    cachedKeyset = [key];
+    return cachedKeyset;
+  } catch (err) {
+    console.error("Failed to parse ATPROTO_JWK_PRIVATE:", err);
+    return null;
+  }
+}
+
+// ============================================================================
+// OAuth Client Factory
+// ============================================================================
+
+export const createClient = async () => {
+  const publicUrl = env.PUBLIC_URL;
+  // Must use 127.0.0.1 per RFC 8252 for ATProto OAuth localhost development
+  const localhostUrl = `http://127.0.0.1:${env.PORT}`;
+  const enc = encodeURIComponent;
+
+  // Confidential client mode is determined by having both PUBLIC_URL and a JWK
+  // private key — not by NODE_ENV. This lets remote deployments work regardless
+  // of how Next.js was started (next dev vs next start).
+  const hasJwk = !!env.ATPROTO_JWK_PRIVATE;
+  const hasPublicUrl = !!publicUrl;
+
+  let keyset = null;
+  try {
+    if (hasJwk && hasPublicUrl) {
+      keyset = await getKeyset();
+    }
+  } catch (err) {
+    console.error("Error getting keyset:", err);
+  }
+
+  const isConfidentialClient = keyset !== null && hasPublicUrl;
+  const url = isConfidentialClient ? publicUrl : localhostUrl;
+
+  // Build client metadata based on client type
+  const clientMetadata: Record<string, unknown> = {
+    client_name: "Beads Map",
+    client_uri: url,
+    dpop_bound_access_tokens: true,
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    scope: "atproto transition:generic",
+    application_type: "web",
+  };
+
+  if (isConfidentialClient) {
+    clientMetadata.client_id = `${publicUrl}/api/oauth/client-metadata.json`;
+    clientMetadata.redirect_uris = [`${publicUrl}/api/oauth/callback`];
+    clientMetadata.token_endpoint_auth_method = "private_key_jwt";
+    clientMetadata.token_endpoint_auth_signing_alg = "ES256";
+    clientMetadata.jwks_uri = `${publicUrl}/api/oauth/jwks.json`;
+  } else {
+    clientMetadata.client_id = `http://localhost?redirect_uri=${enc(`${url}/api/oauth/callback`)}&scope=${enc("atproto transition:generic")}`;
+    clientMetadata.redirect_uris = [`${url}/api/oauth/callback`];
+    clientMetadata.token_endpoint_auth_method = "none";
+  }
+
+  const clientConfig: Record<string, unknown> = {
+    clientMetadata,
+    stateStore,
+    sessionStore,
+  };
+
+  if (keyset) {
+    clientConfig.keyset = keyset;
+  }
+
+  return new NodeOAuthClient(
+    clientConfig as ConstructorParameters<typeof NodeOAuthClient>[0]
+  );
+};
+
+export const getGlobalOAuthClient = async () => {
+  const currentClient = (global as Record<string, unknown>)[oauthClientKey];
+  if (!currentClient) {
+    try {
+      const newClient = await createClient();
+      (global as Record<string, unknown>)[oauthClientKey] = newClient;
+      return newClient;
+    } catch (err) {
+      console.error("Failed to create OAuth client:", err);
+      throw err;
+    }
+  }
+  return currentClient as NodeOAuthClient;
+};
+
+/**
+ * Get the JWKS (public keys) for the confidential client.
+ */
+export async function getJwks(): Promise<{ keys: unknown[] } | null> {
+  const client = await getGlobalOAuthClient();
+
+  if ("jwks" in client && client.jwks) {
+    return client.jwks as { keys: unknown[] };
+  }
+
+  return null;
+}

package/lib/auth.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+import {
+  useState,
+  useEffect,
+  useCallback,
+  createContext,
+  useContext,
+} from "react";
+
+export interface AuthSession {
+  did: string;
+  handle: string;
+  displayName?: string;
+  avatar?: string;
+}
+
+export type AuthStatus = "idle" | "authorizing" | "authenticated" | "error";
+
+interface AuthState {
+  status: AuthStatus;
+  session: AuthSession | null;
+  error: Error | null;
+  isLoading: boolean;
+}
+
+const AuthContext = createContext<{
+  state: AuthState;
+  login: (handle: string) => Promise<void>;
+  logout: () => Promise<void>;
+} | null>(null);
+
+/**
+ * Auth Provider - wraps the app to provide authentication state.
+ * Checks session status on mount via /api/status.
+ */
+export function AuthProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState<AuthState>({
+    status: "idle",
+    session: null,
+    error: null,
+    isLoading: true,
+  });
+
+  // Check session status on mount
+  useEffect(() => {
+    let cancelled = false;
+
+    const checkStatus = async () => {
+      try {
+        const response = await fetch("/api/status");
+        if (response.ok) {
+          const data = await response.json();
+          if (data.did && !cancelled) {
+            setState({
+              status: "authenticated",
+              session: {
+                did: data.did,
+                handle: data.handle || data.did,
+                displayName: data.displayName,
+                avatar: data.avatar,
+              },
+              error: null,
+              isLoading: false,
+            });
+            return;
+          }
+        }
+      } catch (error) {
+        console.error("Failed to check auth status:", error);
+      }
+      if (!cancelled) {
+        setState((prev) => ({ ...prev, isLoading: false }));
+      }
+    };
+
+    checkStatus();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // Login - initiates OAuth flow, redirects to PDS authorization
+  const login = useCallback(async (handle: string) => {
+    setState((prev) => ({
+      ...prev,
+      status: "authorizing",
+      isLoading: true,
+      error: null,
+    }));
+
+    try {
+      const normalizedHandle = handle.includes(".")
+        ? handle
+        : `${handle}.bsky.social`;
+
+      const response = await fetch("/api/login", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          handle: normalizedHandle,
+          returnTo: window.location.pathname + window.location.search,
+        }),
+      });
+
+      if (!response.ok) {
+        const data = await response.json();
+        throw new Error(data.error || "Login failed");
+      }
+
+      const data = await response.json();
+      window.location.href = data.redirectUrl;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Login failed");
+      setState({ status: "error", session: null, error, isLoading: false });
+      throw error;
+    }
+  }, []);
+
+  // Logout - clears server session
+  const logout = useCallback(async () => {
+    try {
+      await fetch("/api/logout", { method: "POST" });
+    } catch (error) {
+      console.error("Logout request failed:", error);
+    }
+    setState({ status: "idle", session: null, error: null, isLoading: false });
+  }, []);
+
+  return (
+    <AuthContext.Provider value={{ state, login, logout }}>
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+/**
+ * Hook to access auth state and actions.
+ * Must be used within an AuthProvider.
+ */
+export function useAuth() {
+  const context = useContext(AuthContext);
+
+  if (!context) {
+    throw new Error("useAuth must be used within an AuthProvider");
+  }
+
+  const { state, login, logout } = context;
+
+  return {
+    status: state.status,
+    session: state.session,
+    error: state.error,
+    isLoading: state.isLoading,
+    isAuthenticated: state.status === "authenticated",
+    login,
+    logout,
+  };
+}