MiauInv/docs/DATABASE.md

Database Documentation

MiauInv uses SQLite for persistent storage. The schema is initialized in storage.InitDB and foreign-key enforcement is explicitly enabled with:

PRAGMA foreign_keys = ON;

The database stores users, refresh tokens, 2FA recovery codes, passkey credentials, passkey challenge state, inventory items, locations, projects, stock mappings, and project allocations.

Entity Overview

[users] 1 ──── N [refresh_tokens]
[users] 1 ──── N [two_factor_recovery_codes]
[users] 1 ──── N [passkey_credentials]

[passkey_challenges] stores short-lived WebAuthn ceremony state

[items] 1 ──── N [stock] N ──── 1 [locations]
[items] 1 ──── N [project_items] N ──── 1 [projects]

Tables

users

Stores account credentials, roles, and 2FA state.

Column	Type	Constraints	Description
id	TEXT	Primary key	User UUID.
username	TEXT	Not null, unique	Lowercased account name.
password	TEXT	Not null	bcrypt password hash.
role	TEXT	Not null	User role, for example user or admin.
two_factor_enabled	INTEGER	Not null, default 0	Boolean flag for TOTP 2FA state.
two_factor_secret	TEXT	Not null, default ''	TOTP secret used to validate authenticator codes. Empty when 2FA is disabled. During setup the secret is held in a short-lived signed setup token and is only stored after the first valid TOTP code.

Migration note: existing databases are migrated with ALTER TABLE statements for two_factor_enabled and two_factor_secret if those columns do not exist yet.

refresh_tokens

Stores refresh-token sessions. Tokens are stored as hashes, not plaintext.

Column	Type	Constraints	Description
id	TEXT	Primary key	Refresh-token row UUID.
user_id	TEXT	Not null, foreign key to users(id)	Owning user.
token_hash	TEXT	Not null	Hash of the refresh token.
expires_at	INTEGER	Not null	Unix timestamp for expiry.
created_at	INTEGER	Not null	Unix timestamp for creation.
revoked	INTEGER	Not null, default 0	Boolean revocation flag.
device_info	TEXT	Optional	User-Agent string recorded when the session is created.

Refresh-token rotation revokes the used refresh token and inserts a new row for the next token.

two_factor_recovery_codes

Stores recovery-code hashes for 2FA fallback login.

Column	Type	Constraints	Description
id	TEXT	Primary key	Recovery-code row UUID.
user_id	TEXT	Not null, foreign key to users(id) with ON DELETE CASCADE	Owning user.
code_hash	TEXT	Not null, unique with user_id	Hash of the normalized recovery code.
created_at	INTEGER	Not null	Unix timestamp for creation.
used_at	INTEGER	Nullable	Unix timestamp when the code was consumed. NULL means unused.

Recovery codes are deleted and replaced when the user regenerates them. A recovery code is consumed with an atomic update that only matches unused codes.

passkey_credentials

Stores WebAuthn passkey credentials for account login. Private keys are not stored by MiauInv; they remain in the authenticator, platform passkey provider, browser, or security key.

Column	Type	Constraints	Description
id	TEXT	Primary key	Passkey row UUID.
user_id	TEXT	Not null, foreign key to users(id) with ON DELETE CASCADE	Owning user.
credential_id	TEXT	Not null, unique	Base64url-encoded WebAuthn credential ID.
name	TEXT	Not null	User-visible passkey name.
credential_data	TEXT	Not null	Serialized WebAuthn credential data, including public-key material and authenticator metadata.
created_at	INTEGER	Not null	Unix timestamp for creation.
last_used_at	INTEGER	Nullable	Unix timestamp when the passkey was last used successfully.

passkey_challenges

Stores short-lived server-side WebAuthn session data for registration and login ceremonies. The browser receives only an opaque session_token.

Column	Type	Constraints	Description
token	TEXT	Primary key	Opaque challenge token returned to the client.
user_id	TEXT	Not null, default ''	Owning user for registration challenges. Empty for discoverable login challenges.
ceremony	TEXT	Not null	Challenge type, for example register or login.
session_data	TEXT	Not null	Serialized WebAuthn session data.
expires_at	INTEGER	Not null	Unix timestamp after which the challenge is rejected.

Challenge rows are consumed once during the finish step and expired rows are cleaned up opportunistically.

items

Stores tracked inventory items.

Column	Type	Constraints	Description
id	INTEGER	Primary key, autoincrement	Item ID.
name	TEXT	Not null	Item name.
category	TEXT	Optional	Category label.
description	TEXT	Optional	Item description.
total_quantity	INTEGER	Not null, default 0	Global quantity baseline.

locations

Stores physical or logical storage locations.

Column	Type	Constraints	Description
id	INTEGER	Primary key, autoincrement	Location ID.
name	TEXT	Not null, unique	Location name.

projects

Stores project contexts for item allocation.

Column	Type	Constraints	Description
id	INTEGER	Primary key, autoincrement	Project ID.
name	TEXT	Not null, unique	Project name.
description	TEXT	Optional	Project description.

stock

Maps item quantities to locations.

Column	Type	Constraints	Description
id	INTEGER	Primary key, autoincrement	Stock row ID.
item_id	INTEGER	Not null, foreign key to items(id)	Item reference.
location_id	INTEGER	Not null, foreign key to locations(id)	Location reference.
quantity	INTEGER	Not null	Quantity at this location.

project_items

Maps item quantities to projects.

Column	Type	Constraints	Description
id	INTEGER	Primary key, autoincrement	Association row ID.
item_id	INTEGER	Not null, foreign key to items(id)	Item reference.
project_id	INTEGER	Not null, foreign key to projects(id)	Project reference.
quantity	INTEGER	Not null	Quantity allocated to the project.

Data Integrity

Foreign keys

Foreign keys are enabled per connection. Because most inventory foreign keys do not define explicit cascade behavior, SQLite blocks deletion of referenced items, locations, or projects while dependent rows exist.

two_factor_recovery_codes.user_id and passkey_credentials.user_id use ON DELETE CASCADE, so deleting a user also deletes their recovery-code and passkey rows.

Uniqueness

The following values are unique:

• users.username
• locations.name
• projects.name
• two_factor_recovery_codes(user_id, code_hash)
• passkey_credentials.credential_id

Current schema limitations

The current schema does not yet enforce all business rules at the database level. In particular:

• items.total_quantity has no explicit CHECK(total_quantity >= 0) constraint.
• stock.quantity has no explicit CHECK(quantity >= 0) constraint.
• project_items.quantity has no explicit CHECK(quantity >= 0) constraint.
• Duplicate stock rows for the same (item_id, location_id) pair are not prevented by a unique constraint.
• Duplicate project allocations for the same (item_id, project_id) pair are not prevented by a unique constraint.

These constraints should be added in a future migration once the desired application behavior is finalized.

Important Queries and Behaviors

User lookup

Users can be loaded by lowercased username or ID. Username updates store the new username lowercased.

Password update

When the password is updated:

1. The new password is bcrypt-hashed.
2. The users.password field is updated.
3. Existing refresh tokens for that user are revoked.
4. A new session is issued.

Passkey registration

When a passkey is registered:

1. The current password is verified.
2. A WebAuthn registration challenge is stored in passkey_challenges.
3. The finish step consumes the challenge.
4. The WebAuthn credential is verified.
5. A row is inserted into passkey_credentials.
6. Existing refresh tokens for the user are revoked.
7. A new session is issued for the current browser.

Passkey login

When passkey login completes:

1. A discoverable WebAuthn login challenge is consumed from passkey_challenges.
2. The credential assertion is verified against the stored credential data.
3. The stored credential data and last_used_at value are updated.
4. A normal access/refresh session is issued.

Passkey removal

When a passkey is removed or all passkeys are disabled:

1. The current password is verified.
2. The matching passkey row, or all rows for the user, are deleted.
3. Existing refresh tokens for the user are revoked.
4. A new session is issued for the current browser.

2FA enable

When 2FA is enabled:

1. The temporary setup token is validated.
2. The supplied TOTP code is validated against the setup secret.
3. Existing recovery codes are deleted.
4. New recovery-code hashes are inserted.
5. users.two_factor_enabled is set to 1 and users.two_factor_secret is set to the confirmed secret.
6. Existing refresh tokens are revoked and a new session is issued for the current browser.

2FA disable

When 2FA is disabled:

1. two_factor_enabled is set to 0.
2. two_factor_secret is cleared.
3. Recovery-code rows for the user are deleted.
4. Refresh tokens for the user are revoked.

Recovery-code use

A recovery code is consumed with an update equivalent to:

UPDATE two_factor_recovery_codes
SET used_at = ?
WHERE user_id = ? AND code_hash = ? AND used_at IS NULL;

The login succeeds only if exactly one row is updated.