# Security Best Practices Standards for Jotai

This document outlines security best practices for Jotai, guiding developers toward writing secure and maintainable code while leveraging the latest features of the library. It will serve as a reference for developers and AI coding assistants.

## 1. Input Validation and Sanitization

### Standard 1.1: Validate All User Inputs

**Do This:** Validate every user input used to derive Jotai atom values. This includes data from forms, URL parameters, local storage, and other external sources.

**Don't Do This:** Directly use user input in your atom values without validation.

**Why:** Prevents common vulnerabilities like Cross-Site Scripting (XSS) and injection attacks. Jotai atoms, holding shared state, can amplify the impact of unvalidated data if it propagates throughout your application.

**Code Example:**

"""jsx

import { atom, useAtom } from 'jotai';

import { useState } from 'react';

// Anti-pattern: Directly using unvalidated input

// const userInputAtom = atom(userInput); // DANGEROUS!

// Properly validate the input before setting the atom.

const validatedInputAtom = atom('');

const ValidatedInputComponent = () => {

const [inputValue, setInputValue] = useState('');

const [validatedValue, setValidatedValue] = useAtom(validatedInputAtom);

const handleChange = (e) => {

const input = e.target.value;

// Basic Input Validation. Can apply more stringent validation using yup, zod, etc.

const isValid = input.length < 50 && /^[a-zA-Z0-9\s]*$/.test(input);

if (isValid) {

setValidatedValue(input);

} else {

console.warn("Invalid input: only alphanumeric characters and spaces, max 50 characters")

setValidatedValue(""); //clear the atom value to safe state

}

setInputValue(input); //still update the local controlled component state

};

return (

Validated Value: {validatedValue}

);

};

export default ValidatedInputComponent;

"""

### Standard 1.2: Sanitize Data Before Use

**Do This:** Sanitize user input before using it in the UI or storing it in local storage. Use a library like DOMPurify to prevent XSS attacks.

**Don't Do This:** Inject raw HTML from user input directly into the DOM.

**Why:** Sanitization removes potentially malicious code from user input preventing it from executing in the browser. This is an incredibly important defense-in-depth measure.

**Code Example:**

"""jsx

import { atom, useAtom } from 'jotai';

import DOMPurify from 'dompurify';

import { useMemo } from 'react';

const userInputAtom = atom('Hello, World!');

const SanitizedOutputComponent = () => {

const [unsafeInput] = useAtom(userInputAtom);

//Sanitize HTML content: prevents XSS attacks

const safeHTML = useMemo(() => DOMPurify.sanitize(unsafeInput), [unsafeInput]);

return (

// Use sanitized HTML

);

};

export default SanitizedOutputComponent;

"""

### Standard 1.3: Use Appropriate Encoding

**Do This:** When displaying user-provided data, ensure proper output encoding (e.g., HTML entity encoding) to prevent injection vulnerabilities.

**Don't Do This:** Neglect to encode user-provided data when rendering it, even after sanitization. Sanitization is not a silver bullet.

**Why:** Encoding ensures that special characters are interpreted correctly and not as code, acting as a secondary layer of defense alongside sanitization.

**Code Example:**

"""jsx

import { atom, useAtom } from 'jotai';

import { useMemo } from 'react';

const userNameAtom = atom(' user@example.com" onclick="alert(\'XSS\')"');

const DisplayNameComponent = () => {

const [unsafeName] = useAtom(userNameAtom);

// HTML Encode for Safe Display

const encodedName = useMemo(() => {

let temp = document.createElement('div');

temp.textContent = unsafeName;

return temp.innerHTML;

}, [unsafeName]);

return (

Welcome, {encodedName}!

);

};

export default DisplayNameComponent;

"""

## 2. Secure Atom Configuration and Usage

### Standard 2.1: Limit Atom Scope

**Do This:** Keep atom scope as narrow as possible. Avoid global atoms that can be inadvertently modified from anywhere in the application.

**Don't Do This:** Create overly broad, globally accessible atoms for storing sensitive information without proper access control.

**Why:** Minimizing the scope of atoms reduces the attack surface and makes it easier to track data flow.

**Code Example:**

"""jsx

// Bad: Global atom for user settings

// export const userSettingsAtom = atom({}); // BAD!

// Good: Component-scoped atoms -- ONLY components/modules that NEED access to the state can access it. Prevents accidental/malicious modification from unrelated parts of the app.

import { atom, useAtom } from 'jotai';

const createSettingsAtoms = () => {

const settingsAtom = atom({}); // Local setting atom

//Derived atom example if readonly access to a filtered set of settings is needed elsewhere.

const publicSettingsAtom = atom((get) => {

const allSettings = get(settingsAtom);

const { sensitiveData, ...publicSettings } = allSettings; //Omit sensitive fields before exposing

return publicSettings;

});

return { settingsAtom, publicSettingsAtom };

};

const SettingsComponent = () => {

const { settingsAtom, publicSettingsAtom } = createSettingsAtoms();

const [settings, setSettings] = useAtom(settingsAtom);

const [publicSettings] = useAtom(publicSettingsAtom);

return (

Settings: {JSON.stringify(settings)}

Public Settings: {JSON.stringify(publicSettings)}

);

};

export default SettingsComponent;

"""

### Standard 2.2: Secure Sensitive Data Storage

**Do This:** Encrypt sensitive data before storing it in atoms, especially if these atoms are persisted to local storage or transmitted over the network. Use vetted encryption libraries.

**Don't Do This:** Store API keys, passwords, or other sensitive data in plain text within atoms.

**Why:** Encryption protects sensitive data from unauthorized access if the application or device is compromised.

**Code Example:**

"""jsx

import { atom, useAtom } from 'jotai';

import CryptoJS from 'crypto-js'; // Example Encryption Library

import { useEffect } from 'react';

const secretKey = "YourEncryptionKey"; // NEVER HARDCODE KEYS IN PRODUCTION. Load from env vars/secure storage.

const encryptedDataAtom = atom(null);

const SecureStorageComponent = () => {

const [encryptedData, setEncryptedData] = useAtom(encryptedDataAtom);

// Example: Encrypt data before setting it to the atom

const encryptData = (data) => {

const ciphertext = CryptoJS.AES.encrypt(JSON.stringify(data), secretKey).toString();

setEncryptedData(ciphertext);

};

const decryptData = (ciphertext) => {

try {

const bytes = CryptoJS.AES.decrypt(ciphertext, secretKey);

const decrypted = bytes.toString(CryptoJS.enc.Utf8);

return JSON.parse(decrypted);

} catch (error) {

console.error("Decryption Error: ", error);

return null; //Handle decryption failures gracefully.

}

};

useEffect(() => {

// Simulate retrieving encrypted data

const storedEncryptedData = localStorage.getItem('sensitiveData');

if( storedEncryptedData) {

setEncryptedData(storedEncryptedData); // Restore encrypted data on component mount

}

}, [setEncryptedData]);

useEffect(() => {

if (encryptedData){

localStorage.setItem('sensitiveData', encryptedData); // Persist to storage on encryptedData atom change.

}

}, [encryptedData])

// Example usage:

const exampleData = { username: 'testuser', apiKey: 'SUPER_SECRET' };

return (

encryptData(exampleData)}>Encrypt and Store Data

{encryptedData && Encrypted Data: {encryptedData}}

{encryptedData && (

Decrypted User Name: {decryptData(encryptedData)?.username}

)}

);

};

export default SecureStorageComponent;

"""

### Standard 2.3: Atom Access Control (Context Based Access)

**Do This:** Implement context-based access control using Jotai's derived atoms. Only allow specific components or modules to access sensitive information.

**Don't Do This:** Directly expose sensitive data atoms to the entire application without proper access control.

**Why:** Limits the potential impact of a security breach by restricting access to sensitive data.

**Code Example:**

"""jsx

import { atom, useAtom, useStore } from 'jotai';

// Base Atom Holding User Data

const userDataAtom = atom({

id: 123,

username: 'secure_user',

role: 'admin',

sensitiveInfo: 'This is confidential data.'

});

// Derived Atom for Public User Profile

const publicProfileAtom = atom((get) => {

const { sensitiveInfo, ...profile } = get(userDataAtom); // Omit sensitive data

return profile;

});

// Derived Atom with Custom Access Logic

const adminDataAtom = atom((get) => {

const user = get(userDataAtom);

if (user.role === 'admin') {

return user.sensitiveInfo; // Only admins can access

}

return null; // Return null or undefined for unauthorized access

});

// Component Displaying the Data based on Role/Access

const UserProfileComponent = () => {

const [profile] = useAtom(publicProfileAtom);

return (Public Profile: {JSON.stringify(profile)})

}

const AdminPanelComponent = () => {

const [adminData] = useAtom(adminDataAtom);

return (

{adminData ? "Admin Data: ${adminData}" : "Access Denied"}

)

}

const AccessControlComponent = () => {

return (

)

}

export default AccessControlComponent;

"""

### Standard 2.4: Avoid Server-Side Rendering (SSR) Pitfalls

**Do This:** When using Jotai in SSR environments (Next.js, Remix), be extremely careful about unintentionally sharing state between users. Initialize atoms on a per-request basis.

**Don't Do This:** Declare atoms outside the component scope in a way that makes them shared singletones across different server requests. This can lead to information leakage.

**Why:** In SSR, atoms are initialized on the server and can be inadvertently shared across multiple user requests if not handled correctly, leading to data leaks and security vulnerabilities.

**Code Example (Next.js):**

"""jsx

// pages/profile.js (Next.js Example)

import { atom, useAtom } from 'jotai';

import { useEffect } from 'react';

// BAD: Shared atom across all requests

// const profileAtom = atom({username: null});

const ProfilePage = () => {

//GOOD: Initialize atom INSIDE the component, creating one per request

const profileAtom = atom({username: null});

const [profile, setProfile] = useAtom(profileAtom);

useEffect(() => {

// Simulate fetching user profile on the client side. In SSR, this would happen server-side.

const fetchProfile = async () => {

// Simulate API call:

const userData = { username: "user-${Math.random()}"};

setProfile(userData);

}

fetchProfile();

}, [setProfile]);

return (

Profile Page

Username: {profile.username}

);

};

export default ProfilePage;

"""

### Standard 2.5: Immutable Updates

**Do This:** Always use immutable update patterns when modifying atoms, especially when dealing with complex objects or arrays. Use spread syntax or dedicated immutable data structure libraries.

**Don't Do This:** Directly mutate the value stored in an atom. This can lead to unexpected side effects and difficulties in tracking state changes for debugging and auditing purposes. Could also cause unintended re-renders.

**Why:** Immutable updates prevent unintended side effects, improve performance due to predictable change detection, and simplify debugging. They are crucial for maintainability and security, especially in complex applications.

**Code Example:**

"""jsx

import { atom, useAtom } from 'jotai';

const itemsAtom = atom([{ id: 1, name: 'Item 1' }, { id: 2, name: 'Item 2' }]);

const ImmutableUpdateComponent = () => {

const [items, setItems] = useAtom(itemsAtom);

const addItem = () => {

// GOOD: Immutable Update Pattern (using spread).

setItems([...items, { id: Date.now(), name: "Item ${Date.now()}" }]);

//Alternatively, use map to perform immutable updates on array contents

//setItems(items.map(item => item.id === idToUpdate ? {...item, name: 'Updated Name'} : item))

};

const removeItem = (idToRemove) => {

// GOOD: Immutable Update Pattern (using filter)

setItems(items.filter(item => item.id !== idToRemove));

}

const updateItemName = (idToUpdate, newName) => {

// GOOD: map to perform immutable updates.

setItems(items.map(item => item.id === idToUpdate ? {...item, name: newName} : item))

}

return (

{items.map(item => (

{item.name}

removeItem(item.id)}>Remove

updateItemName(item.id, "Updated ${item.name}")}>Update Name

))}

Add Item

);

};

export default ImmutableUpdateComponent;

"""

## 3. Security Auditing and Monitoring

### Standard 3.1: Implement Logging and Monitoring

**Do This:** Log significant events related to atom state changes, especially changes involving sensitive data. Monitor logs for suspicious activity, such as unexpected data modifications or access attempts.

**Don't Do This:** Neglect logging atom changes or monitoring logs for unusual activity.

**Why:** Logging and monitoring provide visibility into the application's behavior and help detect security incidents.

**Code Example:**

"""jsx

import { atom, useAtom, useStore } from 'jotai';

import { useEffect } from 'react';

const sensitiveDataAtom = atom('initial sensitive data');

const LoggingComponent = () => {

const [sensitiveData, setSensitiveData] = useAtom(sensitiveDataAtom);

const store = useStore(); //Jotai Store Instance.

useEffect(() => {

// Log state changes to the console (in a real application, send to a logging service).

console.log('Sensitive data changed:', sensitiveData);

// In production, replace console.log with a secure logging mechanism

reportAtomChange(store, sensitiveDataAtom, sensitiveData)

}, [sensitiveData, store]);

const handleChange = (newData) => {

setSensitiveData(newData);

};

return (

handleChange('New Sensitive Data')}>

Change Data

Current Data: {sensitiveData}

);

};

function reportAtomChange(store, atom, newValue) {

const atomName = atom.debugLabel || 'unlabeledAtom';// getAtomName(atom) //function not included by default but can be implemented through Symbol('debugLabel')

console.log("[ATOM UPDATE] ${atomName}:", newValue);

//Real world implementations use proper structured logging like Sentry, Datadog, etc.

// Sentry.captureMessage("Atom ${atomName} updated", {

// level: 'info',

// extra: {

// newValue: JSON.stringify(newValue),

// },

// });

}

export default LoggingComponent;

"""

### Standard 3.2: Regular Security Audits

**Do This:** Conduct regular security audits of your Jotai code, paying attention to data flow, access control, and potential vulnerabilities.

**Don't Do This:** Assume your Jotai code is secure without periodic reviews.

**Why:** Audits help identify and address security weaknesses before they can be exploited. Consider using static analysis tool specializing in React and Javascript security.

### Standard 3.3: Dependency Management

**Do This:** Keep Jotai and all other dependencies up-to-date to patch known security vulnerabilities. Use tools like "npm audit" or "yarn audit" and Dependabot to automate dependency updates.

**Don't Do This:** Ignore dependency updates, especially security-related ones.

**Why:** Outdated dependencies are a common source of security vulnerabilities. Automated tools drastically reduce the risk of using vulnerable packages in production.

## 4. API Security

### Standard 4.1: Secure API Interactions

**Do This:** When atoms are populated with data fetched from APIs, ensure those APIs are secure. Use HTTPS, proper authentication (e.g., JWT), and authorization mechanisms.

**Don't Do This:** Use insecure HTTP connections or expose sensitive data via APIs without authentication.

**Why:** Securing APIs is critical because they often serve as the entry point for attackers. Data from external sources should never be implicitly trusted.

**Code Example:**

"""jsx

import { atom, useAtom } from 'jotai';

import axios from 'axios';

const apiDataAtom = atom(null);

const SecureAPIComponent = () => {

const [apiData, setApiData] = useAtom(apiDataAtom);

const fetchData = async () => {

try {

const response = await axios.get('/api/secure-data', { // Ensure HTTPS and proper endpoint

headers: {

Authorization: "Bearer ${localStorage.getItem('authToken')}", // JWT Auth

});

setApiData(response.data);

} catch (error) {

console.error('API Error:', error);

// Handle errors appropriately (e.g., redirect to login).

}

};

return (

Fetch Secure Data

{apiData && API Data: {JSON.stringify(apiData)}}

);

};

export default SecureAPIComponent;

"""

### Standard 4.2: Rate Limiting

**Do This:** Implement rate limiting on API endpoints that populate Jotai atoms, especially those exposed to public users.

**Don't Do This:** Allow unrestricted access to APIs, which can lead to denial-of-service (DoS) attacks.

**Why:** Rate limiting prevents abuse and ensures that legitimate users can access API resources reliably.

## 5. Jotai-Specific Considerations

### Standard 5.1: Understand Jotai Internals

**Do This:** Familiarize yourself with Jotai's core principles, including atom derivation, subscription models, and batched updates. This understanding is crucial for identifying potential security implications of your code.

**Don't Do This:** Treat Jotai as a black box. Lack of understanding can lead to subtle vulnerabilities that are difficult to detect.

**Why:** In-depth knowledge of Jotai facilitates writing secure code and effectively debugging issues.

### Standard 5.2: Be Mindful of Atom Derivations

**Do This:** When deriving atoms, carefully consider the security implications of the derivation logic. Ensure that derived atoms do not inadvertently expose sensitive information or introduce vulnerabilities.

**Don't Do This:** Create complex, untrusted atom derivations that could be exploited if not handled with care.

**Why:** Atom derivations can perform transformations or aggregations and these must be secured just like any other part of the data flow.

By adhering to these security best practices, developers can build robust and secure Jotai applications, minimizing the risk of vulnerabilities and data breaches. This document serves as a living guide, updated with the latest security insights and Jotai features.

Cline

This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.

Overview

The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.

Key Concepts

Purpose of .clinerules

Defines project-specific guidelines and requirements
Enforces consistent coding standards
Establishes documentation practices
Sets testing and quality requirements
Configures error handling preferences

File Location

Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.

Rule Structure

1. Project Overview

# Project Overview
project:
  name: 'Your Project Name'
  description: 'Brief project description'
  stack:
    - technology: 'Framework/Language'
      version: 'X.Y.Z'
    - technology: 'Database'
      version: 'X.Y.Z'

2. Code Standards

# Code Standards
standards:
  style:
    - 'Use consistent indentation (2 spaces)'
    - 'Follow language-specific naming conventions'
  documentation:
    - 'Include JSDoc comments for all functions'
    - 'Maintain up-to-date README files'
  testing:
    - 'Write unit tests for all new features'
    - 'Maintain minimum 80% code coverage'

3. Security Rules

# Security Guidelines
security:
  authentication:
    - 'Implement proper token validation'
    - 'Use environment variables for secrets'
  dataProtection:
    - 'Sanitize all user inputs'
    - 'Implement proper error handling'

Best Practices

Writing Effective Rules

Be Specific
- Use clear, actionable language
- Provide examples where helpful
- Define measurable criteria
Maintain Organization
- Group related rules together
- Use consistent formatting
- Keep critical rules at the top
Regular Updates
- Review rules periodically
- Update based on team feedback
- Document changes in version control

Common Patterns

# Common Patterns Example
patterns:
  components:
    - pattern: 'Use functional components by default'
    - pattern: 'Implement error boundaries for component trees'
  stateManagement:
    - pattern: 'Use React Query for server state'
    - pattern: 'Implement proper loading states'

Integration with Development Workflow

Using with Version Control

Commit the Rules
- Include .clinerules in version control
- Document rule changes in commit messages
- Review rule changes as part of PR process
Team Collaboration
- Discuss rule changes with team
- Maintain changelog for rule updates
- Ensure all team members understand rules

Troubleshooting

Common Issues

Rules Not Being Applied
- Verify file location (must be in root directory)
- Check file formatting
- Ensure Cline has access to the file
Conflicting Rules
- Review rule hierarchy
- Resolve conflicts explicitly
- Document rule precedence
Performance Considerations
- Keep rules concise and focused
- Avoid overly complex rule structures
- Regular cleanup of obsolete rules

Examples

Basic Project Setup

# Basic .clinerules Example
project:
  name: 'Web Application'
  type: 'Next.js Frontend'
  standards:
    - 'Use TypeScript for all new code'
    - 'Follow React best practices'
    - 'Implement proper error handling'

testing:
  unit:
    - 'Jest for unit tests'
    - 'React Testing Library for components'
  e2e:
    - 'Cypress for end-to-end testing'

documentation:
  required:
    - 'README.md in each major directory'
    - 'JSDoc comments for public APIs'
    - 'Changelog updates for all changes'

Advanced Configuration

# Advanced .clinerules Example
project:
  name: 'Enterprise Application'
  compliance:
    - 'GDPR requirements'
    - 'WCAG 2.1 AA accessibility'

architecture:
  patterns:
    - 'Clean Architecture principles'
    - 'Domain-Driven Design concepts'

security:
  requirements:
    - 'OAuth 2.0 authentication'
    - 'Rate limiting on all APIs'
    - 'Input validation with Zod'

Security Best Practices Standards for Jotai

Cline

Overview

Key Concepts

Purpose of .clinerules

File Location

Rule Structure

1. Project Overview

2. Code Standards

3. Security Rules

Best Practices

Writing Effective Rules

Common Patterns

Integration with Development Workflow

Using with Version Control

Troubleshooting

Common Issues

Examples

Basic Project Setup

Advanced Configuration

Related Rules

Deployment and DevOps Standards for Jotai

Component Design Standards for Jotai

Core Architecture Standards for Jotai

Code Style and Conventions Standards for Jotai

Testing Methodologies Standards for Jotai