Use Neynar metadata for cast embeds

.env.example

@@ -38,6 +38,7 @@ APP_MNEMONIC = ''
 NEYNAR_API_KEY = ''
 SUPABASE_SERVICE_KEY = ''
 YOUTUBE_API_KEY = ''
+MORALIS_API_KEY = ''
 
 # These are specific to the environment
 # and so need to be configured locally
@@ -47,6 +48,8 @@ NEXT_PUBLIC_SUPABASE_URL = ''
 NEXT_PUBLIC_SUPABASE_ANON_KEY = ''
 NEXT_PUBLIC_PRIVY_API_KEY = ''
 NEXT_PUBLIC_ALCHEMY_API_KEY = ''  # Also used for the Nouns Home fidget RPC fallback
+# Optional: used for Directory fidget (ERC20 + NFT holders)
+NEXT_PUBLIC_MORALIS_API_KEY = ''
 
 # Nouns Home fidget (optional overrides)
 # NOUNS_RPC_URL = ''

.nvmrc

@@ -1 +1 @@
-v22.11.0
+22.12.0

README.md

@@ -21,11 +21,50 @@ a protocol for decentralized social apps: https://www.farcaster.xyz
    On Mac OS, for example:
    ```bash
    brew install supabase/tap/supabase
+   ```
+
+   Install Docker Desktop on macOS:
+   ```bash
+   brew install --cask docker
+   open /Applications/Docker.app
+   ```
+   Wait for Docker Desktop to finish initializing before continuing.
 
    On Linux:
-   install docker
-   install supabase
-   npx supabase init
+
+   First, install Homebrew (if not already installed):
+   ```bash
+   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+   ```
+   Follow the instructions in your terminal to add Homebrew to your PATH.
+   Generally, you'll need to run these commands (replace `.bashrc` with your shell configuration file if different):
+
+   ```bash
+   (echo; echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"') >> ~/.bashrc
+   eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
+   ```
+
+   You may also need to install some dependencies first (Debian/Ubuntu):
+   ```bash
+   sudo apt-get install build-essential procps curl file git
+   ```
+
+   Then install Supabase:
+   ```bash
+   brew install supabase/tap/supabase
+   ```
+
+   Install Docker (Debian/Ubuntu):
+   ```bash
+   sudo apt-get update
+   sudo apt-get install -y docker.io docker-compose-plugin
+   sudo systemctl enable --now docker
+   sudo usermod -aG docker "$USER"
+   ```
+   Log out/in (or restart your shell) so the new group membership takes effect.
+   For other distros, follow the [official Docker Engine docs](https://docs.docker.com/engine/install/).
+
+   Make sure Docker is installed and running before continuing.
 4. Install dependencies
    ```bash
    yarn install
@@ -47,13 +86,29 @@ a protocol for decentralized social apps: https://www.farcaster.xyz
 ```
 The script will attempt to start Supabase automatically if Docker is running; otherwise it will skip this step.
 
-9. Run the test suite
+9. **Seed the local database**
+   After Supabase is running and migrations are applied, seed the database:
+   ```bash
+   # Run migrations and seed SQL (if not already done)
+   supabase db reset
+
+   # Seed community configs and navPage spaces
+   yarn seed
+   ```
+
+   This will:
+   - Upload Nouns assets to ImgBB (if `NEXT_PUBLIC_IMGBB_API_KEY` is set)
+   - Create navPage space registrations
+   - Seed community configs (nouns, example, clanker)
+   - Upload navPage space configs to Supabase Storage
+
+10. Run the test suite
    ```bash
    yarn test
    ```
 
-9. cp .env.development.local .env.local
-10. yarn build
+11. cp .env.development.local .env.local
+12. yarn build
 
 ## Contributing and making Fidgets
 

docs/ARCHITECTURE/AUTHENTICATION.md

@@ -0,0 +1,254 @@
+# Authentication System
+
+The Nounspace authentication system combines Privy for wallet-based authentication with Farcaster for social identity, creating a seamless Web3 social experience.
+
+## Architecture Overview
+
+The authentication system consists of several key components:
+
+- **Privy Integration** - Primary authentication provider
+- **Farcaster Integration** - Social identity and protocol access
+- **Identity Management** - Multi-identity support with cryptographic keys
+- **Authenticator System** - Modular authentication methods
+
+## Core Components
+
+### 1. Privy Integration
+
+Privy handles the primary authentication flow:
+
+```typescript
+// Privy store manages user state
+interface PrivyState {
+  privyUser?: PrivyUser | null;
+}
+
+interface PrivyActions {
+  setPrivyUser: (user: PrivyUser | null) => void;
+}
+```
+
+**Key Features:**
+- Wallet connection (MetaMask, WalletConnect, etc.)
+- Social login options
+- User session management
+- Multi-wallet support
+
+### 2. Farcaster Integration
+
+Farcaster provides social identity and protocol access:
+
+```typescript
+// Farcaster store manages FID linking
+type FarcasterActions = {
+  getFidsForCurrentIdentity: () => Promise<void>;
+  registerFidForCurrentIdentity: (
+    fid: number,
+    signingKey: string,
+    signMessage: (messageHash: Uint8Array) => Promise<Uint8Array>,
+  ) => Promise<void>;
+  setFidsForCurrentIdentity: (fids: number[]) => void;
+  addFidToCurrentIdentity: (fid: number) => void;
+};
+```
+
+**Key Features:**
+- FID (Farcaster ID) linking to identities
+- Cryptographic signature verification
+- Social graph access
+- Cast and interaction capabilities
+
+### 3. Identity Management
+
+The system supports multiple identities per user:
+
+```typescript
+export type AccountStore = IdentityStore &
+  AuthenticatorStore &
+  PreKeyStore &
+  FarcasterStore &
+  PrivyStore & {
+    reset: () => void;
+    hasNogs: boolean;
+    setHasNogs: (v: boolean) => void;
+  };
+```
+
+**Identity Features:**
+- Multiple space identities
+- Cryptographic key management
+- Identity switching
+- Secure key storage
+
+### 4. Authenticator System
+
+Modular authentication methods for different services:
+
+```typescript
+// Authenticator manager handles method calls
+const authenticatorManager = useMemo<AuthenticatorManager>(() => ({
+  callMethod: async (
+    { requestingFidgetId, authenticatorId, methodName, isLookup = false },
+    ...args
+  ): Promise<AuthenticatorManagerResponse> => {
+    // Handle authenticator method calls
+  },
+  getInitializedAuthenticators: () => {
+    // Return available authenticators
+  }
+}));
+```
+
+## Authentication Flow
+
+### 1. Initial Setup
+
+1. **User connects wallet** via Privy
+2. **Identity creation** with cryptographic keys
+3. **Farcaster linking** (optional)
+4. **Authenticator setup** for services
+
+### 2. Farcaster Integration
+
+```typescript
+// Register FID for current identity
+const registerFidForCurrentIdentity = async (
+  fid: number,
+  signingKey: string,
+  signMessage: (messageHash: Uint8Array) => Promise<Uint8Array>,
+) => {
+  const request: Omit<FidLinkToIdentityRequest, "signature"> = {
+    fid,
+    identityPublicKey: get().account.currentSpaceIdentityPublicKey!,
+    timestamp: moment().toISOString(),
+    signingPublicKey: signingKey,
+  };
+
+  const signedRequest: FidLinkToIdentityRequest = {
+    ...request,
+    signature: bytesToHex(await signMessage(hashObject(request))),
+  };
+
+  // Submit to backend
+  const { data } = await axiosBackend.post<FidLinkToIdentityResponse>(
+    "/api/fid-link",
+    signedRequest,
+  );
+};
+```
+
+### 3. Identity Management
+
+```typescript
+// Identity store manages multiple identities
+interface IdentityStore {
+  spaceIdentities: SpaceIdentity[];
+  currentSpaceIdentityPublicKey: string | null;
+  getCurrentIdentity: () => SpaceIdentity | null;
+  getCurrentIdentityIndex: () => number;
+  setCurrentSpaceIdentityPublicKey: (key: string | null) => void;
+}
+```
+
+## Security Considerations
+
+### 1. Cryptographic Security
+
+- **Key Generation**: Secure random key generation
+- **Key Storage**: Encrypted local storage
+- **Signature Verification**: Cryptographic signature validation
+- **Key Rotation**: Support for key updates
+
+### 2. Privacy Protection
+
+- **Local Storage**: Sensitive data stored locally
+- **Encryption**: Keys encrypted with user wallet
+- **No Central Storage**: No centralized key storage
+
+### 3. Access Control
+
+- **Permission System**: Fidget-level permissions
+- **Method Authorization**: Authenticator method access control
+- **Identity Verification**: Cryptographic identity verification
+
+## API Integration
+
+### FID Linking
+
+```typescript
+// Link Farcaster FID to identity
+POST /api/fid-link
+{
+  "fid": number,
+  "identityPublicKey": string,
+  "timestamp": string,
+  "signingPublicKey": string,
+  "signature": string
+}
+```
+
+### Identity Management
+
+```typescript
+// Get FIDs for identity
+GET /api/fid-link?identityPublicKey={key}
+```
+
+## Development Patterns
+
+### 1. Adding New Authenticators
+
+```typescript
+// Create authenticator in src/authenticators/
+export const newAuthenticator = (config: AuthenticatorConfig) => ({
+  methods: {
+    methodName: async (params) => {
+      // Implementation
+    }
+  }
+});
+```
+
+### 2. Using Authenticators in Fidgets
+
+```typescript
+// Access authenticator in fidget
+const { callMethod } = useAuthenticatorManager();
+
+const result = await callMethod({
+  requestingFidgetId: 'my-fidget',
+  authenticatorId: 'farcaster:signers',
+  methodName: 'getUserInfo'
+});
+```
+
+### 3. Permission Management
+
+```typescript
+// Check permissions before calling methods
+const hasPermission = authenticatorConfig[authenticatorId]
+  .permissions[requestingFidgetId]?.includes(methodName);
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication Failures**: Check Privy configuration
+2. **FID Linking Issues**: Verify Farcaster integration
+3. **Permission Denied**: Check authenticator permissions
+4. **Key Management**: Ensure proper key storage
+
+### Debug Tools
+
+- Use React DevTools to inspect store state
+- Check browser console for authentication errors
+- Verify environment variables are set correctly
+- Test with different wallet providers
+
+## Future Considerations
+
+- Enhanced permission system
+- Multi-chain identity support
+- Advanced key management
+- Social recovery mechanisms