Household Locks & PIN Unlocking
Relevant source files
The following files were used as context for generating this wiki page:
Household Locks prevent unauthorized changes to a GoCasa instance by requiring an Admin's Personal Identification Number (PIN). While viewing information is always public, destructive or administrative actions like changing the calendar or modifying settings require a device to be in an "unlocked" state.
Sources: GLOSSARY.md, internal/app/members.go:102-110
Core Concepts
Admin Role
An Admin is a Household Member permitted to change system settings, manage other members, and handle integrations. Only Members with the "admin" role possess a PIN. The system enforces a rule that the Household must always have at least one active (non-archived) Admin to prevent complete lockout.
Sources: GLOSSARY.md, internal/app/members.go:26, internal/app/members.go:211-218
Locks
A Lock is an optional rule applied to specific application modules. When a module is locked, actions such as completing chores or editing events require a valid Admin PIN. Unlocking a device grants access to all locked administrative functions for a limited duration.
Sources: GLOSSARY.md, internal/app/members.go:121-128
Authentication Flow
The unlocking process uses a PIN pad where a user selects an Admin profile and enters a 4 to 8-digit numeric code.
The diagram above shows the logic flow from a restricted request to either action execution or the lock screen.
Sources: internal/app/members.go:121-128, internal/app/members.go:173-194
Session Management
GoCasa manages the unlocked state using a signed HMAC cookie named gocasa_unlock. This cookie contains the Admin ID and a timestamp. An unlock session remains valid for 5 minutes of inactivity. Every valid request resets this 5-minute idle timer by re-issuing the cookie.
Sources: internal/app/unlock.go:14-16, internal/app/unlock.go:27-35
| Cookie Component | Description |
|---|---|
gocasa_unlock | The cookie name used to track session state. |
| Admin ID | The database ID of the Admin who performed the unlock. |
| Last Active | Unix timestamp of the most recent authorized request. |
| MAC | HMAC-SHA256 signature using the SESSION_SECRET. |
Sources: internal/app/unlock.go:25-35
Security Constraints
Brute Force Protection
To prevent PIN guessing, GoCasa implements a lockout mechanism. After 5 consecutive failed attempts, the system blocks that specific Admin's PIN for 5 minutes. The block count is tracked in the database and applies across all devices.
Sources: internal/app/members.go:167-171, internal/app/recovery_test.go:13-25
Critical Logic Guards
The application uses the keepsAnAdmin SQL fragment to ensure administrative continuity. This guard prevents the last remaining Admin from being:
- Deleted
- Archived
- Demoted to a regular "member" role
Sources: internal/app/members.go:29, internal/app/members.go:211-218
PIN Recovery
If an Admin forgets their PIN, it can be reset through the command-line interface.
- Access the host terminal or container shell.
- Run the command:
gocasa reset-pin <Admin name or id>. - The system generates a random 6-digit PIN and clears any active PIN blocks.
- The Admin uses this temporary PIN to unlock Settings and set a new one.
Sources: internal/app/members.go:261-294, internal/app/recovery_test.go:88-95
Technical Implementation
Key Endpoints
The following endpoints manage the locking and unlocking lifecycle:
| Method | Path | Description |
|---|---|---|
GET | /lock | Displays the PIN pad with active Admin avatars. |
POST | /lock | Validates a submitted PIN and sets the session cookie. |
POST | /lock/now | Immediately clears the session cookie to lock the device. |
POST | /setup | Creates the first Admin (only when no members exist). |
Sources: internal/app/app.go:102-106, internal/web/settings_templ.go:79-85
Data Structure
The members table maintains the security state for each Admin.
-- Conceptual schema based on internal/app/members.go
CREATE TABLE members (
id INTEGER PRIMARY KEY,
role TEXT, -- 'admin' or 'member'
pin_hash BLOB, -- Bcrypt hash
pin_failures INTEGER DEFAULT 0,
pin_blocked_until INTEGER, -- Unix timestamp
archived BOOLEAN DEFAULT 0
);
Sources: internal/app/members.go:154-162, internal/app/members.go:183-188
Household Locks & PIN Unlocking provide a balance between the accessibility of a family dashboard and the security required for administrative control. By combining time-limited sessions, brute-force protection, and safety guards for the last Admin, GoCasa ensures that sensitive household data remains protected from unauthorized modification.