userharbor 0.6.0

Project status: UserHarbor is currently in an early stage of development. The API may change frequently. The library is not ready for production use yet.

UserHarbor is a framework-agnostic Python library for user account management.

Its goal is to provide a simple, stable, and framework-independent interface for common user-related operations:

• user registration,
• email verification,
• login,
• session management,
• logout from one or all sessions,
• password change,
• password reset,
• account deletion,
• role and permission checks.

UserHarbor is not a web framework. It does not provide routers, views, or HTTP endpoints. Instead, it exposes a simple domain-level API that can be integrated with FastAPI, Flask, Django, Litestar, CLI applications, or any other environment.

Installation

Install the core package if you want to provide your own UserStore and EmailSender implementations:

pip install userharbor

Install the core package with the official SQLAlchemy and SMTP adapters:

pip install "userharbor[sqlalchemy,smtp]"

The official adapters are documented in the integrations documentation:

• userharbor-sqlalchemy
• userharbor-smtp

Quick example

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from userharbor import UserHarbor
from userharbor_sqlalchemy import SQLAlchemyUserStore
from userharbor_smtp import SMTPEmailSender

engine = create_engine("sqlite:///users.db")
SessionLocal = sessionmaker(bind=engine)

store = SQLAlchemyUserStore(SessionLocal)
store.metadata.create_all(engine)

email_sender = SMTPEmailSender(
    host="smtp.example.com",
    port=587,
    username="smtp-user",
    password="smtp-password",
    from_email="noreply@example.com",
)

harbor = UserHarbor(
    secret_key="your-secret-key",
    store=store,
    email_sender=email_sender,
)

# Register a user
harbor.register(
    username="jane",
    email="jane@example.com",
    password="StrongPassword123!",
)

# Verify email address
harbor.verify_email("verification-token-from-email")

# Login
session_token = harbor.login(
    username="jane",
    password="StrongPassword123!",
)

# Verify session
if harbor.verify_session(session_token):
    print("User is logged in")

# Get current user
current_user = harbor.get_current_user(session_token)
print(current_user.username)

# Create roles and permissions
harbor.roles.create("admin")
harbor.permissions.create("users.delete")
harbor.roles.grant_permission("admin", "users.delete")
harbor.grant_role("jane", "admin")

# Check access
if harbor.has_permission(session_token, "users.delete"):
    print("User can delete users")

current_admin = harbor.require_role(session_token, "admin")
print(current_admin.username)

# Logout
harbor.logout(session_token)

# Change password
session_token = harbor.login(
    username="jane",
    password="StrongPassword123!",
)
harbor.change_password(
    old_password="StrongPassword123!",
    new_password="EvenStrongerPassword123!",
    session_token=session_token,
)

# Send password reset email
harbor.send_password_reset("jane@example.com")

# Reset password
harbor.reset_password(
    new_password="NewStrongPassword123!",
    reset_token="reset-token-from-email",
)

# Delete account
session_token = harbor.login(
    username="jane",
    password="NewStrongPassword123!",
)
harbor.delete_account(
    password="NewStrongPassword123!",
    session_token=session_token,
)

Documentation

The full documentation is available at userharbor.github.io/userharbor.

Useful pages:

• Architecture
• Roles and permissions
• Design principles
• Integrations
• Contributing

Architecture

UserHarbor consists of three main parts:

UserHarbor core
    ├── registration logic
    ├── login logic
    ├── session logic
    ├── password reset logic
    ├── role and permission checks
    ├── data validation
    ├── token generation
    └── password and token hashing

UserStore
    └── any implementation responsible for storing users, sessions, tokens, roles, and permissions

EmailSender
    └── any implementation responsible for sending email messages

The main userharbor package does not contain a concrete database implementation or email delivery implementation.

Instead, it relies on two protocols:

• UserStore,
• EmailSender.

This allows you to use official adapters or build your own integration.

Official integrations

UserHarbor core does not include database or email-provider implementations. Those responsibilities are handled by adapters that implement the core UserStore and EmailSender protocols.

Official integrations:

• userharbor-sqlalchemy provides a SQLAlchemy-based UserStore.
• userharbor-smtp provides an SMTP-based EmailSender.
• userharbor-fastapi is in preparation.

See the integrations documentation for detailed setup instructions.

Design principles

UserHarbor should remain simple, predictable, and easy to integrate.

1. Core should only do what is necessary

The main library is responsible for basic user account operations:

• registration,
• email verification,
• login,
• session management,
• logout,
• password reset,
• password change,
• user deletion,
• simple role-based access control.

Unusual business-specific cases should be implemented outside the library.

UserHarbor does not try to solve every identity-related problem.

The following are outside the scope of the core library:

• OAuth,
• OpenID Connect,
• social login,
• 2FA/MFA,
• ACL,
• organizations and teams,
• ownership and resource policies,
• policy engines,
• admin panels,
• ready-made HTTP endpoints,
• ready-made HTML views,
• integrations with specific frameworks.

Such features may be created as separate libraries or integrations, but they should not complicate the core project.

UserHarbor should not become an application framework.

2. Framework-agnostic before framework integrations

The main library should not depend on FastAPI, Django, Flask, Litestar, or any other framework.

Framework integrations should be created as separate libraries.

3. UserStore and EmailSender are dependencies

UserHarbor does not assume where users are stored.

UserHarbor does not assume how email messages are sent.

These responsibilities belong to adapters compatible with the UserStore and EmailSender interfaces.

4. Adapters should live outside the core

Integrations with databases, ORMs, email services, queues, frameworks, and providers should be developed as separate packages.

5. Stability is more important than feature count

After the public API becomes stable, further core development should focus mainly on:

• improving security,
• improving reliability,
• improving performance,
• maintaining compatibility.

New features should be added carefully.

6. Simple things should remain simple

The library should be easy to use in small projects, while still being possible to extend in larger applications.

Changelog

Changes for each release are documented in the GitHub release notes.

Contributing

The project is in an early stage of development and its API is not stable yet.

The most welcome areas of contribution are:

• public API design,
• security improvements,
• tests,
• documentation,
• UserStore implementations,
• EmailSender implementations,
• framework integrations as separate packages.

Before starting work on a storage or email integration, review the official adapters:

https://github.com/userharbor/userharbor-sqlalchemy
https://github.com/userharbor/userharbor-smtp

License

UserHarbor is released under the MIT License.