@bob/auth (BobAuth Public SDK)

A high-performance, stateless authentication SDK. Use this package to integrate user registration, sign-in, and verification into your application.

🚀 Quick Start for AI Agents & Developers

1. Installation

npm install @bob/auth

2. Configure Environment

Your app needs three primary variables, which will be issued by the BobAuth team. You will be given a set for development/testing and another set for production.

Local Development (.env.local)

# Issued by BobAuth for your specific application
BOB_AUTH_ID=your_dev_app_id
BOB_AUTH_KEY=your_dev_auth_key
BOB_AUTH_URL=https://cool-dove-824.convex.cloud

Production

Issued by BobAuth for your specific application in production

BOB_AUTH_ID=your_prod_app_id BOB_AUTH_KEY=your_prod_auth_key BOB_AUTH_URL=https://adventurous-pheasant-246.convex.cloud

• SECURITY: Your BOB_AUTH_KEY should never be exposed in a public frontend. For production, perform the appSignin step in a backend function or use an ephemeral token approach.

🛠️ Usage Guide

Initialize and Authorize

BobAuth uses a Stateless Token model. You must first authorize your application to receive an appToken before making user requests.

import { BobAuthClient } from "@bob/auth";

const bob = new BobAuthClient({
  backendUrl: process.env.BOB_AUTH_URL
});

// 1. Authorize your App (Call this once on app init or backend side)
await bob.signin(
  process.env.BOB_AUTH_ID, 
  process.env.BOB_AUTH_KEY
);

User Signup

Allows a new user to register. Returns a userId and a pin (for simulation; in production, BobAuth sends this via email).

const { result, error } = await bob.userSignup({
  email: "[email protected]",
  password: "SecurePassword123!",
  firstName: "Justin"
});

if (result) {
  // Save result.userId and show PIN entry UI
}

Email Verification

Verify the user's account using the PIN.

await bob.userVerifyEmail({
  userId: "user_123",
  pin: "123456"
});

User Sign-in

Obtain a user identity and session.

const loginResult = await bob.userSignin({
  email: "[email protected]",
  password: "SecurePassword123!",
  ipAddress: "127.0.0.1"
});

if (loginResult.result) {
  console.log("Logged in user:", loginResult.result.current.user.firstName);
}

🛡️ Security Architecture

Stateless Performance

Unlike traditional auth, BobAuth user mutations do not require a database lookup to verify the application. The appToken is a cryptographically sealed payload that the server verifies instantly, ensuring zero performance penalty for high-traffic apps.

Credentials at Rest

Application authKeys are encrypted at rest on the BobAuth server. However, you must protect your authKey locally. Never commit it to git.

Suspensions & IP Blocking

BobAuth automatically handles brute-force protection. If your app receives error: "ip-blocked", the client's IP has been temporarily restricted due to too many failed attempts across different users.