Pavin's Locker

Pavin's Locker is a cutting-edge web application dedicated to providing a secure and private space for your digital life. Its core mission is to offer robust, encrypted file storage and seamless sharing capabilities, ensuring that your sensitive data remains yours alone. With a focus on user control and state-of-the-art security, Pavin's Locker leverages end-to-end encryption, meaning your files are encrypted directly in your browser before they even touch our servers, and can only be decrypted by someone who possesses the unique passkey for the locker.

You can access the deployed application at https://pavin-locker.vercel.app/.

Key Features

• Secure Locker Creation: Easily create your own personal digital locker with a unique and memorable name. This locker serves as your private vault in the cloud.
• Passkey Protection: Every locker is safeguarded by a user-defined passkey. This critical feature ensures that only you and those you trust can gain access to the stored files.
• Comprehensive File Operations: Enjoy a full suite of file management tools. You can effortlessly upload new files, download existing ones to your local device, rename files for better organization, and delete files you no longer need.
• End-to-End Encryption: Security is paramount. Pavin's Locker ensures your files are encrypted on your device before being uploaded and can only be decrypted by users who have the correct passkey. This means no one else, not even the platform administrators, can access your unencrypted files.
• Shareable Links: Sharing your files is simple and secure. Generate a unique link to your locker and provide the passkey to trusted individuals, allowing them to access the contents you've stored.
• User Ownership & Control: You are the sole owner of your locker. Pavin's Locker gives you complete autonomy over your data, empowering you to manage your files and access permissions as you see fit.

Tech Stack

Pavin's Locker is built with a modern and robust technology stack:

• Next.js: A React framework for building server-side rendered and static web applications.
• TypeScript: A statically typed superset of JavaScript that enhances code quality and maintainability.
• Supabase: An open-source Firebase alternative, providing database, authentication, and real-time subscriptions.
• Tailwind CSS: A utility-first CSS framework for rapidly building custom user interfaces.
• bcrypt: A library for hashing passkeys securely.
• jose: A library for JSON Web Tokens (JWT) handling, used for secure session management and API authentication.

Getting Started

To get a local copy up and running, follow these simple steps.

Prerequisites

Ensure you have Node.js and npm (or yarn) installed on your system.

Running the Development Server

1. Clone the repository:

   git clone https://github.com/your-username/pavin-locker.git
   cd pavin-locker

2. Install NPM packages:

   npm install
   # or
   yarn install

3. Create a .env.local file in the root of your project and add your Supabase credentials (see "Setting up Supabase" below):

   NEXT_PUBLIC_SUPABASE_URL=YOUR_SUPABASE_URL
   NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY
   SUPABASE_SERVICE_ROLE_KEY=YOUR_SUPABASE_SERVICE_ROLE_KEY # Add this line
   JWT_SECRET=YOUR_SUPER_SECRET_JWT_SECRET_AT_LEAST_32_CHARACTERS_LONG

   Replace placeholders with your actual credentials and secrets. The SUPABASE_SERVICE_ROLE_KEY is needed for backend operations.
4. Run the development server:

   npm run dev
   # or
   yarn dev

   Open http://localhost:3000 with your browser to see the result.

Setting up Supabase

Pavin's Locker uses Supabase for its backend database and file storage.

1. Create a Supabase Project:

   • Go to Supabase and sign in or create an account.
   • Create a new project. Choose a name and region that suits you.

2. Set up Database Schema:

   • In your Supabase project dashboard, navigate to the "SQL Editor" (usually found in the sidebar).

   • Click on "+ New query" and run the following SQL commands one by one or all together to create the necessary tables and enable UUID generation:

     -- Enable UUID generation if not already enabled
     CREATE EXTENSION IF NOT EXISTS "uuid-ossp" WITH SCHEMA extensions;
     
     -- Create Lockers Table
     CREATE TABLE public.lockers (
         id UUID PRIMARY KEY DEFAULT extensions.uuid_generate_v4(),
         name TEXT UNIQUE NOT NULL,
         passkey TEXT NOT NULL,
         created_at TIMESTAMPTZ DEFAULT NOW()
     );
     
     -- Create Files Table
     CREATE TABLE public.files (
         id UUID PRIMARY KEY DEFAULT extensions.uuid_generate_v4(),
         locker_id UUID REFERENCES public.lockers(id) ON DELETE CASCADE,
         file_name TEXT NOT NULL,
         file_path TEXT NOT NULL,
         size INTEGER NOT NULL,
         uploaded_at TIMESTAMPTZ DEFAULT NOW()
     );

   • Ensure you execute CREATE EXTENSION IF NOT EXISTS "uuid-ossp" WITH SCHEMA extensions; first, or include it in the query. This function is crucial for generating unique IDs for your table entries.

3. Create Storage Bucket:

   • Navigate to "Storage" from the sidebar in your Supabase project dashboard.
   • Click on "Create new bucket".
   • Name the bucket locker-files.
   • For initial setup simplicity, you can make the bucket public. However, please note: Pavin's Locker is designed to use signed URLs for file downloads, which is a more secure approach than relying on a fully public bucket. For production, you should configure appropriate Row Level Security (RLS) policies on your files table and corresponding storage bucket policies to restrict direct access, ensuring files are only served via these secure, time-limited signed URLs.

4. Obtain Supabase Credentials:

   • In your Supabase project dashboard, go to "Project Settings" (usually found at the bottom of the sidebar or under a gear icon).
   • Navigate to the "API" section.
   • You will find your Project URL (e.g., https://your-project-ref.supabase.co) and your anon public key. These are needed for NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY.
   • Under "Project API keys", you will also find your service_role key. This is needed for SUPABASE_SERVICE_ROLE_KEY.
   • The JWT_SECRET is a value you must generate yourself. It should be a strong, random string of at least 32 characters.

Environment Variables

Pavin's Locker requires certain environment variables to be set for it to connect to Supabase and manage security features like JWT signing. These variables should be placed in a file named .env.local at the root of your project. This file is included in .gitignore by default to ensure your secret keys are not accidentally committed to version control.

Create the .env.local file in the project's root directory and add the following variables:

• NEXT_PUBLIC_SUPABASE_URL: The URL of your Supabase project. This is used by the client-side Supabase library.
• NEXT_PUBLIC_SUPABASE_ANON_KEY: The anon (anonymous) public key for your Supabase project. This is also used by the client-side Supabase library for operations that don't require elevated privileges.
• SUPABASE_SERVICE_ROLE_KEY: The service role key for your Supabase project. This key bypasses Row Level Security and should be kept strictly secret. It is used by backend functions for administrative tasks or operations requiring elevated privileges. Do not expose this key on the client side.
• JWT_SECRET: A long, random, and strong secret string (at least 32 characters) used for signing and verifying JSON Web Tokens (JWTs). JWTs are crucial for session management and authenticating API requests. This must be kept strictly secret. You can generate a suitable string using a password manager or an online secure string generator.

Example .env.local file:

NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_long_supabase_anon_key_here
SUPABASE_SERVICE_ROLE_KEY=your_very_secret_supabase_service_role_key_here
JWT_SECRET=your_super_secret_and_long_random_jwt_signature_key_here

Important:

• Replace the placeholder values with your actual Supabase project URL, anon key, service role key, and your chosen JWT secret.
• The SUPABASE_SERVICE_ROLE_KEY and JWT_SECRET are highly sensitive. Ensure they are never committed to your repository or exposed publicly. The .env.local file is typically ignored by Git for this reason.

Project Structure

The project follows a standard Next.js application structure. Here's an overview of the key directories:

• src/app: Contains the core application code, organized according to the Next.js App Router conventions. This includes pages (route handlers), layouts, and specific components tied to routes.
• src/actions: Holds server-side actions, primarily used for form submissions and data mutations. These Next.js Server Actions allow secure and direct interaction with your backend logic from client components.
• src/components: A collection of reusable UI components (e.g., buttons, modals, cards) that are used across different parts of the application.
• src/lib: This directory is for utility functions, helper scripts, and configurations. It typically houses the Supabase client initialization, JWT handling logic, and other shared helper modules.
• public: Stores all static assets that are served directly by the web server. This includes images, fonts, icons, and other files that don't need to be processed by the build pipeline.

Available Scripts

In the project directory, you can run the following commands:

• npm run dev

  • Runs the application in development mode with Turbopack for faster development builds.
  • Open http://localhost:3000 to view it in the browser.
  • The page will reload if you make edits. You will also see any lint errors in the console.

• npm run build

  • Builds the application for production deployment.
  • It correctly bundles React in production mode and optimizes the build for the best performance.
  • The build artifacts will be stored in the .next/ directory.

• npm run start

  • Starts the production server for the built application.
  • This command should be run after you have built the application with npm run build.
  • It serves the optimized production build.

• npm run lint

  • Lints the codebase using Next.js's built-in ESLint configuration.
  • This helps to identify and fix stylistic and code quality issues.

Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

If you want to add more detailed contributing guidelines later, you can expand this section.

License

MIT License

Copyright (c) 2025 Pavin Cletus

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.