Cedros Login Server

Warning: Development Preview

This package is in early development (v0.0.x) and is not ready for production use. APIs may change without notice. Use at your own risk.

Production-ready authentication server with multi-tenancy, flexible auth methods, and comprehensive access control.

Features

Authentication Methods

• Email/Password: Registration and login with Argon2id password hashing
• Google OAuth: Sign-in via Google ID token verification
• Apple Sign In: Sign-in via Apple ID token verification
• Solana Wallet: Sign-in by signing a challenge message with Ed25519
• Instant Link: Passwordless email authentication
• WebAuthn/Passkeys: Passwordless authentication with passkeys and security keys
• TOTP MFA: Time-based one-time password with recovery codes

Multi-Tenancy

• Organizations: Create and manage workspaces
• Memberships: Users belong to multiple orgs with roles
• Invites: Email invitations with configurable expiry
• Org Switching: Switch active organization context

Access Control

• Built-in Roles: Owner, Admin, Member, Viewer with preset permissions
• Custom Roles: Define org-specific roles with granular permissions
• ABAC Policies: Attribute-based access control for fine-grained rules
• Authorization API: Check permissions via POST /authorize

Security

• JWT Tokens: Short-lived access tokens with refresh rotation
• Refresh Reuse Alerts: Reuse of rotated refresh tokens revokes all sessions and triggers security notifications
• Cookie Support: HTTP-only secure cookies for token storage
• Token Responses: When cookie auth is enabled, auth endpoints omit token fields from JSON responses
• Rate Limiting: Configurable sliding window rate limiter
• Login Lockout: Progressive lockout after failed attempts
• New Device Alerts: Security emails for unrecognized devices
• Audit Logging: Track all auth events with IP, user agent, and session ID
• TOTP Replay Protection: Each code can only be used once (S-14)
• Encryption at Rest: TOTP secrets encrypted with AES-256-GCM (S-22). Uses TOTP_ENCRYPTION_SECRET or falls back to JWT_SECRET.
• Step-Up Required for MFA Enrollment: MFA setup/enabling requires recent strong authentication
• Production Validation: Enforces COOKIE_SECURE and CORS_ORIGINS in production

Communications

• Outbox Pattern: Reliable async email delivery
• Email Templates: Verification, password reset, instant link, security alerts
• Retry with Backoff: Exponential backoff for failed deliveries

Storage

• PostgreSQL: Production-ready with sqlx migrations
• In-Memory: Development mode with no external dependencies

Quick Start

Prerequisites

• Rust 1.70+ (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh)
• PostgreSQL 14+ (optional, uses in-memory storage by default)

Run Locally

cd server

# Copy environment file
cp .env.example .env

# Edit .env and set JWT_SECRET (required)
# Generate with: openssl rand -base64 32
#
# Optional:
# - FRONTEND_URL for email links
# - SSO_CALLBACK_URL to override the SSO redirect (useful behind proxies)
# - AUTH_BASE_PATH to override the auth router base path (default: /auth)

# Run with in-memory storage (development)
cargo run

# Or run with PostgreSQL
 docker-compose -f ../docker-compose.yml up -d postgres
cargo run

The server starts at http://localhost:8080.

Using Docker

# Start PostgreSQL only
 docker-compose -f ../docker-compose.yml up -d postgres

# Start everything (requires building the image)
 docker-compose -f ../docker-compose.yml --profile full up -d

API Endpoints

All endpoints are served under AUTH_BASE_PATH (default: /auth). Paths below are relative to that base path.

Authentication

WebAuthn / Passkeys

Email Verification & Password Reset

Instant Link

MFA (TOTP)

Organizations

Members

Custom Roles

ABAC Policies

Invites

Authorization

Sessions

Credentials

Wallet (Server-Side Signing)

Credits

User Lookup (Server-to-Server)

These endpoints require system admin authentication (API key/JWT) and are intended for server-to-server flows (e.g. payments/webhooks) where only an external identifier is available.

API Keys

Audit Logs

Admin

System Settings

Runtime-configurable settings stored in the database. Changes take effect immediately without server restart.

Categories:

• privacy - Privacy period before withdrawal
• withdrawal - Withdrawal worker configuration (poll interval, batch size, timeouts)
• rate_limit - Rate limiting thresholds (auth, general, credit, window)

# Get all settings
curl http://localhost:8080/admin/settings \
  -H "Authorization: Bearer <admin_token>"

# Update settings
curl -X PATCH http://localhost:8080/admin/settings \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"settings": [{"key": "privacy_period_secs", "value": "1209600"}]}'

Privacy Cash Admin (Deposits & Withdrawals)

Get System Status

Returns current Privacy Cash configuration and sidecar connection status:

curl http://localhost:8080/admin/privacy/status \
  -H "Authorization: Bearer <admin_token>"

Response:

{
  "enabled": true,
  "companyWallet": "ABC123...",
  "companyCurrency": "SOL",
  "privacyPeriodSecs": 604800,
  "privacyPeriodDisplay": "7 days",
  "minDepositLamports": 10000000,
  "minDepositSol": 0.01,
  "withdrawalPollIntervalSecs": 3600,
  "withdrawalBatchSize": 10,
  "withdrawalPercentage": 100,
  "partialWithdrawalCount": 0,
  "partialWithdrawalMinLamports": 500000000,
  "partialWithdrawalMinSol": 0.5,
  "sidecarStatus": "connected",
  "sidecarUrl": "http://127.0.0.1:****/",
  "webhookConfigured": true
}

Process Single Withdrawal

Process a specific withdrawal. Can force early withdrawal (before privacy period ends) with confirmation:

# Process withdrawal (must be past privacy period)
curl -X POST http://localhost:8080/admin/withdrawals/<session_id>/process \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{}'

# Force early withdrawal (before privacy period)
curl -X POST http://localhost:8080/admin/withdrawals/<session_id>/process \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

Response:

{
  "success": true,
  "sessionId": "...",
  "txSignature": "...",
  "earlyWithdrawal": false
}

Process All Withdrawals

Process ready withdrawals in a bounded batch (safe for large datasets). Re-run to continue processing:

curl -X POST "http://localhost:8080/admin/withdrawals/process-all?limit=50" \
  -H "Authorization: Bearer <admin_token>"

Response:

{
  "totalProcessed": 5,
  "totalSucceeded": 4,
  "totalFailed": 1,
  "results": [...]
}

Webhooks

Health

Usage Examples

Register and Login

# Register
curl -X POST http://localhost:8080/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecurePass1!", "name": "John Doe"}'

# Login
curl -X POST http://localhost:8080/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "SecurePass1!"}'

Organization Management

# Create organization
curl -X POST http://localhost:8080/orgs \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Team", "slug": "my-team"}'

# List organizations
curl http://localhost:8080/orgs \
  -H "Authorization: Bearer <access_token>"

# Switch active organization
curl -X POST http://localhost:8080/orgs/<org_id>/switch \
  -H "Authorization: Bearer <access_token>"

Invite Team Members

# Create invite
curl -X POST http://localhost:8080/orgs/<org_id>/invites \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"email": "teammate@example.com", "role": "member"}'

# Accept invite (by invitee)
curl -X POST http://localhost:8080/invites/accept \
  -H "Content-Type: application/json" \
  -d '{"token": "<invite_token>"}'

Check Authorization

# Check if user can perform action
curl -X POST http://localhost:8080/authorize \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "<org_id>",
    "action": "member:invite",
    "resource_type": "member"
  }'

# Response: {"allowed": true}

MFA Setup

Note: MFA during login is completed via POST /login/mfa using the temporary mfaToken returned by POST /login. The /mfa/verify and /mfa/recovery endpoints are intended for authenticated step-up checks, not initial login.

# Setup MFA (returns secret and QR code)
curl -X POST http://localhost:8080/mfa/setup \
  -H "Authorization: Bearer <access_token>"

# Enable MFA with TOTP code
curl -X POST http://localhost:8080/mfa/enable \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Credits Refunds

Refunds are a ledger reversal implemented as a positive adjustment linked back to the original credit transaction (referenceType='refund', referenceId=<originalTransactionId>).

User request:

# 1) Look up the original credits transaction
curl http://localhost:8080/credits/history \
  -H "Authorization: Bearer <access_token>"

# 2) Submit a refund request referencing the original transaction
curl -X POST http://localhost:8080/credits/refund-request \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "<credit_transaction_uuid>",
    "amountLamports": 5000000,
    "reason": "Accidental purchase"
  }'

Admin review + process:

# List refund requests
curl "http://localhost:8080/admin/credits/refund-requests?status=pending&limit=50" \
  -H "Authorization: Bearer <admin_token>"

# Process a request (can be partial, but cannot exceed remaining refundable amount)
curl -X POST http://localhost:8080/admin/credits/refund-requests/<request_id>/process \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amountLamports": 2500000,
    "reason": "Approved partial refund"
  }'

# Reject a request
curl -X POST http://localhost:8080/admin/credits/refund-requests/<request_id>/reject \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Not eligible for refund"
  }'

Configuration

All configuration is via environment variables. See .env.example for the complete list.

Required

Optional

SSO (OIDC) Notes

• Issuer URLs must use https in production.
• Provider scopes must include openid and email.

Library Usage

Embed the auth router in your own Axum application:

use cedros_login::{router, Config, NoopCallback};
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let config = Config::from_env().expect("Failed to load config");
    let callback = Arc::new(NoopCallback);

    // Create auth router with in-memory storage (for development)
    let auth_router = router(config, callback);

    let app = axum::Router::new()
        .nest("/auth", auth_router)
        .layer(/* your middleware */);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Custom Callbacks

Implement the AuthCallback trait to hook into auth events:

use cedros_login::{AuthCallback, AuthCallbackPayload, AppError};
use async_trait::async_trait;
use serde_json::Value;

struct MyCallback;

#[async_trait]
impl AuthCallback for MyCallback {
    async fn on_authenticated(&self, payload: &AuthCallbackPayload) -> Result<Value, AppError> {
        println!("User {} logged in via {:?}", payload.user.id, payload.method);
        // Return custom data to include in auth response
        Ok(serde_json::json!({"subscription": "premium"}))
    }

    async fn on_registered(&self, payload: &AuthCallbackPayload) -> Result<Value, AppError> {
        println!("New user registered: {}", payload.user.id);
        // Provision resources, send welcome email, etc.
        Ok(Value::Null)
    }

    async fn on_logout(&self, user_id: &str) -> Result<(), AppError> {
        println!("User {} logged out", user_id);
        Ok(())
    }
}

Custom Email Service

Implement the EmailService trait for your email provider:

use cedros_login::{EmailService, VerificationEmailData, PasswordResetEmailData};
use async_trait::async_trait;

struct SendGridEmailService { /* ... */ }

#[async_trait]
impl EmailService for SendGridEmailService {
    async fn send_verification_email(
        &self,
        to: &str,
        data: &VerificationEmailData,
    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
        // Send via SendGrid, Postmark, etc.
        Ok(())
    }

    // Implement other email methods...
}

Embedded Wallet (Server-Side Signing)

The server includes an optional embedded Ed25519 wallet using 2-of-3 Shamir Secret Sharing for key management. The server performs all signing operations—users never see the raw private key.

Architecture

Auth Methods for Share A

• Email/password users: Reuse their login password
• OAuth users (Google/Apple): Create a 6+ digit PIN
• Passkey users: Use passkey PRF extension

Session-Based Unlock

Instead of requiring credentials for every sign operation, users unlock their wallet once per session:

1. POST /wallet/unlock with credential → server caches derived key
2. Subsequent POST /wallet/sign requests use cached key (no credential needed)
3. Key auto-expires after TTL (default 15 min) or on explicit POST /wallet/lock

Recovery Modes

Configure via WALLET_RECOVERY_MODE:

Security Model

• Server never has the full seed at rest (only JIT during signing)
• Server compromise → encrypted Share A + plaintext Share B → cannot sign without user credential
• Device compromise → nothing (shares stored server-side)
• Keys are zeroized from memory immediately after signing

Privacy Cash (Deposits & Withdrawals)

Optional privacy-preserving deposit system using the Privacy Cash protocol. Users deposit SOL/SPL tokens to their embedded wallet, funds are held for a configurable privacy period, then automatically withdrawn to the company wallet.

Deposit Types & Recovery Modes

Deposits work in all wallet recovery modes, but private (privacy-preserving) deposits require WALLET_RECOVERY_MODE=none:

Why private deposits require no-recovery mode: In recovery modes where users can export their private key, they could front-run withdrawal transactions by extracting their key and signing before the Privacy Cash relayer processes the batched withdrawal.

The /deposit/config endpoint returns privateDepositsEnabled: false when recovery mode is enabled, allowing the UI to automatically route users to public deposit methods.

How It Works

1. Deposit: User sends SOL/USDC/USDT to their embedded wallet address
2. Privacy Period: Funds held in Privacy Cash account (default 7 days)
3. Auto-Withdrawal: Background worker processes ready withdrawals to company wallet
4. Credit: User's account credited with deposited amount

Timing Analysis Protection

To prevent correlation of deposits and withdrawals, the system supports two layers of timing obfuscation:

Withdrawal Percentage

Spread withdrawals over multiple cycles by only processing a percentage per batch:

# Process only 20% of ready withdrawals each hour
WITHDRAWAL_PERCENTAGE=20
WITHDRAWAL_POLL_INTERVAL_SECS=3600

With 10 ready withdrawals and 20% setting, only ~2 withdrawals per hour (randomly selected).

Partial Withdrawals

Additionally, some withdrawals can be split across multiple cycles:

# Up to 3 partial withdrawals per batch (30-70% of balance each)
PARTIAL_WITHDRAWAL_COUNT=3
PARTIAL_WITHDRAWAL_MIN_LAMPORTS=500000000  # 0.5 SOL minimum for partials

Sessions with balance ≥ 0.5 SOL may have a random portion (30-70%) withdrawn, leaving the remainder for future cycles. This adds variance to both timing AND amounts.

Example Privacy Configuration

For maximum timing obfuscation:

PRIVACY_PERIOD_SECS=604800           # 7 day minimum hold
WITHDRAWAL_POLL_INTERVAL_SECS=3600   # Check every hour
WITHDRAWAL_BATCH_SIZE=20             # Claim up to 20 at a time
WITHDRAWAL_PERCENTAGE=20             # Process ~20% per cycle
PARTIAL_WITHDRAWAL_COUNT=3           # Up to 3 partial withdrawals
PARTIAL_WITHDRAWAL_MIN_LAMPORTS=500000000  # 0.5 SOL min for partials

This configuration means:

• Deposits held for at least 7 days
• Every hour, ~20% of ready sessions processed
• Up to 3 of those may be partial (30-70%)
• Average time from "ready" to "fully withdrawn" spreads across multiple cycles

Fee Considerations

Privacy Cash charges ~0.006 SOL per withdrawal. The PARTIAL_WITHDRAWAL_MIN_LAMPORTS setting (default 0.5 SOL) ensures partial withdrawals only occur on balances large enough to avoid excessive fee overhead (~1.2% at 0.5 SOL).

Database Schema

The server uses 10 PostgreSQL tables:

Run Migrations

# Install sqlx-cli
cargo install sqlx-cli

# Run migrations
sqlx migrate run

Role & Permission System

Built-in Roles

Custom Roles

Create org-specific roles with custom permissions:

curl -X POST http://localhost:8080/orgs/<org_id>/roles \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Moderator",
    "description": "Can manage content but not members",
    "permissions": ["content:read", "content:write", "content:delete"]
  }'

ABAC Policies

Define fine-grained attribute-based rules:

curl -X POST http://localhost:8080/orgs/<org_id>/policies \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Owners can delete",
    "description": "Only resource owners can delete",
    "effect": "allow",
    "actions": ["delete"],
    "resource_type": "document",
    "conditions": {"owner_id": {"equals_subject": "user_id"}}
  }'

Password Requirements

• Minimum 10 characters
• At least 1 uppercase letter (A-Z)
• At least 1 lowercase letter (a-z)
• At least 1 number (0-9)
• At least 1 special character (@$!%*?&#^())

Rate Limits

Default limits (configurable):

Rate-limited responses return 429 Too Many Requests with headers:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset
• Retry-After

Note: Rate limiting is enforced in-memory per server instance. RATE_LIMIT_STORE accepts only memory today. In multi-instance deployments, limits are not shared across nodes. For distributed rate limiting, use a shared store (e.g., Redis) or front the service with a gateway that enforces global limits.

Testing

# Run all tests (515+ tests)
cargo test

# Run with logging
RUST_LOG=debug cargo test -- --nocapture

# Run specific test
cargo test test_name

License

MIT