🔐 Memoize Auth

OAuth authentication providers for The Memoize Project. Zero dependencies, fully typed.

Part of The Memoize Project — A modern flashcard application with FSRS spaced repetition

Getting Started · Documentation · Contributing

📚 About The Memoize Project

The Memoize Project is a modern, personal flashcard application designed for effective learning through spaced repetition. Born from a comprehensive architectural refactoring, the project embraces a micro-repository architecture where each context is independently maintained and versioned.

🎯 Project Context

• Mission: Building a powerful flashcard application with cutting-edge spaced repetition algorithms
• Evolution: Migrating from Anki's SM-2 algorithm to the more sophisticated FSRS (Free Spaced Repetition Scheduler)
• Architecture: Modern micro-repo structure with independent, focused modules
• Organization: github.com/the-memoize-project

🧩 Repository Purpose

This repository (auth) provides OAuth authentication capabilities for The Memoize application. It's designed to be:

• Lightweight: Zero dependencies, minimal footprint
• Secure: Follows OAuth 2.0 best practices
• Extensible: Easy to add new authentication providers
• Type-safe: Full TypeScript support

🌟 What is Memoize Auth?

Memoize Auth is a lightweight authentication library that provides OAuth 2.0 integration for modern web applications. It handles the complete OAuth flow including authorization URL generation, token exchange, and user profile fetching.

✨ Features

• 🔐 OAuth 2.0 Flow: Complete implementation of authorization code flow
• 🌐 Google OAuth: Built-in support for Google authentication
• 🎯 Zero Dependencies: No external dependencies required
• 📦 Tree-shakeable: Import only what you need
• 🔒 Type-safe: Full TypeScript support with detailed type definitions
• 🚀 Modern: ES modules with dual CJS/ESM builds

📦 Installation

npm install @the-memoize-project/auth

Or with other package managers:

bun add @the-memoize-project/auth
pnpm add @the-memoize-project/auth
yarn add @the-memoize-project/auth

🚀 Quick Start

Google OAuth Authentication

import Google from '@the-memoize-project/auth/google';

// 1. Configure the provider
Google.config({
  clientId: 'your-client-id.apps.googleusercontent.com',
  clientSecret: 'your-client-secret',
  redirectUri: 'http://localhost:3000/auth/callback'
});

// 2. Generate authorization URL and redirect user
const authUrl = Google.authorize();
window.location.href = authUrl;

// 3. Handle callback with authorization code
const code = new URLSearchParams(window.location.search).get('code');
const { accessToken } = await Google.callback(code);

// 4. Fetch user profile
const user = await Google.me(accessToken);
console.log(user);
// {
//   key: "1234567890",
//   email: "[email protected]",
//   name: "John Doe",
//   avatarUrl: "https://..."
// }

📖 API Documentation

Google Provider

Google.config(config)

Configures the Google OAuth provider with your application credentials.

Parameters:

• config.clientId (string): Your Google OAuth client ID
• config.clientSecret (string): Your Google OAuth client secret
• config.redirectUri (string): The redirect URI registered in Google Console

Returns: this (for method chaining)

Example:

Google.config({
  clientId: 'your-client-id.apps.googleusercontent.com',
  clientSecret: 'your-client-secret',
  redirectUri: 'http://localhost:3000/auth/callback'
});

Google.authorize()

Generates the Google OAuth authorization URL.

Returns: string - The authorization URL to redirect the user to

Throws: Error if config() hasn't been called

Example:

const authUrl = Google.authorize();
// Returns: https://accounts.google.com/o/oauth2/v2/auth?client_id=...

Google.callback(code)

Exchanges the authorization code for an access token.

Parameters:

• code (string): The authorization code received from the OAuth callback

Returns: Promise<{ accessToken: string }> - Object containing the access token

Throws: Error if config() hasn't been called

Example:

const { accessToken } = await Google.callback(authCode);

Google.me(accessToken)

Fetches the authenticated user's profile information.

Parameters:

• accessToken (string): The access token obtained from callback()

Returns: Promise<GoogleUser> - User profile object

interface GoogleUser {
  key: string;        // Google user ID
  email: string;      // User email address
  name: string;       // User display name
  avatarUrl: string;  // User profile picture URL
}

Example:

const user = await Google.me(accessToken);
console.log(`Welcome, ${user.name}!`);

🏗️ Architecture

The library follows a monorepo structure with individual packages for each authentication provider:

auth/
├── packages/
│   └── google/
│       ├── google.js         # Implementation
│       ├── index.js          # Package entry point
│       └── types.d.ts        # TypeScript definitions
├── dist/                     # Built files (CJS + ESM)
├── package.json              # Package configuration
├── tsconfig.json             # TypeScript configuration
├── vite.config.js            # Build configuration
└── README.md                 # This file

🔒 Security Considerations

• Never expose client secrets: Client secrets should only be used on the server side
• Use HTTPS in production: Always use HTTPS for redirect URIs in production
• Validate redirect URIs: Ensure redirect URIs are registered in your OAuth provider
• Store tokens securely: Use secure storage mechanisms for access tokens
• Implement CSRF protection: Use state parameters to prevent CSRF attacks

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Part of The Memoize Project ecosystem, designed to provide secure authentication for modern web applications.

Made with ❤️ by The Memoize Project Contributors