homeio

Public

Forked from doctor-io/homeio

Branch: main
Latest commit: 958d74616 October 2026

Authentication And Sessions

Purpose

Homeio is currently single-user. Authentication uses a username/password account, scrypt password hashing, and an HMAC-SHA256 signed session token stored in the homeio_session HTTP-only cookie.

Locations

Server-side: lib/server/modules/auth/
Client-side: components/auth/, hooks/useCurrentUser.ts, login/register pages under app/
Routes: app/api/auth/

Key Files

File	Role
`lib/server/modules/auth/service.ts`	Register, login, logout, authenticate, unlock
`lib/server/modules/auth/session-token.ts`	HMAC token creation and verification
`lib/server/modules/auth/password.ts`	scrypt hashing and verification
`lib/server/modules/auth/cookies.ts`	Cookie name and cookie options
`lib/server/modules/auth/repository.ts`	`users` and `sessions` queries
`lib/server/modules/auth/api.ts`	Shared `requireApiSession()` helper for protected API routes
`lib/server/modules/auth/rate-limit.ts`	In-memory failed-login limiter
`app/api/auth/login/route.ts`	Login endpoint
`app/api/auth/me/route.ts`	Current session endpoint

Public API

registerUser()
loginUser()
logoutSession()
authenticateSession()
requireApiSession()
verifyUnlockPassword()
createSessionToken()
parseSessionToken()

Contracts

lib/shared/auth/session.ts

Database Tables

users
sessions

API Routes Owned

POST /api/auth/login
POST /api/auth/logout
GET /api/auth/me
POST /api/auth/register
GET /api/auth/status
POST /api/auth/unlock

Known Issues

Login rate limiting is in-memory only: 5 failures per 15 minutes per normalized username/client IP.
No central auth middleware; protected /api/v1/** routes must call requireApiSession() and are checked by app/api/v1/__tests__/auth-architecture.test.ts.
The audit notes passwordHash circulates in authenticated session lookup results.
Development/test session secret defaults are allowed, but production startup rejects known defaults and secrets shorter than 32 characters.

How To Extend

To add a protected auth-adjacent feature:

Add types to lib/shared/auth/session.ts or a new contract file.
Add service code in lib/server/modules/auth/.
Add repository functions if user/session persistence changes.
Add route code under app/api/auth/ or protected /api/v1/**.
Call requireApiSession() in protected /api/v1/** route handlers.
Add route and service tests.