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

userharbor-sqlalchemy provides a SQLAlchemy-based UserStore implementation for userharbor.

It stores:

• users
• email verification tokens
• sessions
• password reset tokens
• password hashes
• roles
• permissions
• user-to-role assignments
• role-to-permission assignments

Each user has at most one active email verification token and one active password reset token. Storing a new token of either kind removes that user's previous token. Users can have multiple active sessions.

The package only handles persistence. It does not send emails, expose HTTP endpoints, or implement application-specific authentication flows.

Usernames preserve their original casing while lookup and uniqueness use a Unicode case-folded key. The default model stores that key in the unique, indexed username_key column.

---

Installation

pip install userharbor-sqlalchemy

This package depends on userharbor and SQLAlchemy 2.x.

---

Example usage

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


class EmailSender:
    def send_verification(
        self,
        username: str,
        email: str,
        verification_token: str,
    ) -> None:
        print(f"Send verification token to {email}: {verification_token}")

    def send_password_reset(
        self,
        username: str,
        email: str,
        reset_token: str,
    ) -> None:
        print(f"Send password reset token to {email}: {reset_token}")

    def send_email_verified(self, username: str, email: str) -> None:
        print(f"Email verified for {email}")

    def send_password_changed(self, username: str, email: str) -> None:
        print(f"Password changed for {email}")

    def send_account_deleted(self, username: str, email: str) -> None:
        print(f"Account deleted for {email}")


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

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

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

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

harbor.verify_email("verification-token-from-email")

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

current_user = harbor.get_current_user(session_token)
print(current_user.username)

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

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

harbor.logout(session_token)

For real applications, replace EmailSender with an implementation that sends verification and password reset messages through your email provider.

---

Transactions

SQLAlchemyUserStore.transaction() provides a transaction context used by UserHarbor for multi-step operations such as email verification, password reset, password change, account deletion, and role or permission assignment. Successful blocks are committed; exceptions roll back all changes from the block.

---

Custom user models

A custom user model must provide username_key in addition to username, email, password_hash, and verified:

username: Mapped[str] = mapped_column(String(255), primary_key=True)
username_key: Mapped[str] = mapped_column(String(255), unique=True, index=True)

SQLAlchemyUserStore.create_user() fills username_key with username.casefold(). The unique constraint prevents accounts whose usernames differ only by casing, while username keeps the spelling selected during registration.

---

License

UserHarbor SQLAlchemy is released under the MIT License.