NextMyDay/docs/specs/spec-004-identity-sessions.md

SPEC-004 — identity & sessions (internal/core/auth, internal/core/users)

Field	Value
Status	Implemented (2026-10-13) — see §8; build/vet/test/-race green · static CGO-free binary
Created	2026-10-13
Author	OpenArchitect
Target milestone	M0
Governing decisions	D-007 · D-008 · D-013 · D-020 · D-034 · PROJECT_PLAN.md §6
Related	SPEC-003 (door) · SPEC-005 (/setup) · SPEC-006 (enroll/login)

---

1. Goal

The data model and core services for users, identities, sessions, and the audit trail — the foundation the /setup, enroll/login, roles, and recovery slices build on.

---

2. Non-goals

• The HTTP door → SPEC-003. The flows → SPEC-005/006/007. Module data → modules own it.

---

3. The three anchors (D-013)

Anchor	Where	Rotates?
user_id	internal, stable; the first user = 1	no
guid	the access username in the path	yes (recovery)
email	contact + recovery authority	no

Stable user ≠ rotating identity. Credentials hang off an identity, never the user.

---

4. Schema (SQLite · WAL · foreign keys ON)

Table	Key columns
users	user_id PK · email UNIQUE NOT NULL · display_name · role (admin|director|manager|team) · manager_user_id FK NULL (NULL only for the admin) · passkey_opt_out BOOL DEFAULT 0 · status · created_at
identities	identity_id PK · user_id FK · guid UNIQUE (≥128-bit) · status (pending_enrollment|active|revoked) · created_at · enrolled_at · revoked_at
webauthn_credentials	credential_id PK · identity_id FK · public_key · sign_count · transports · aaguid · created_at
totp_secrets	identity_id FK · secret_encrypted (A9) · verified_at
sessions	session_id PK (opaque random) · identity_id FK · user_id · created_at · expires_at · revoked_at · client_ip · user_agent
recovery_requests	request_id PK · user_id FK · status (pending|approved|denied|expired) · requested_at · decided_by FK · decided_at · client_ip
audit_log	id PK · at · actor_user_id · action · subject · detail · client_ip · location (D-031) · correlation_id

Invariants

• Exactly one active identity per user (enforced by a partial unique index + service checks).
• guid is unique and never recycled; a revoked GUID is tombstoned (D-008).
• The admin is user_id = 1 and its manager_user_id is NULL (D-020, D-034).
• The enrollment window is bounded: now − identity.created_at ≤ enroll_window (A1).

---

5. Core services (contracts)

Audit metadata rides the context.Context — the door attaches it before calling any service:

ctx = audit.WithMeta(ctx, audit.Meta{ActorUserID, ClientIP, CorrelationID})

type Users interface {
    Create(ctx context.Context, creatorID int64, email, displayName string, role Role) (UserID int64, err error)
    Get(ctx context.Context, id int64) (User, error)
    SetRole(ctx context.Context, id int64, role Role) error          // ripple-down model (D-034)
    Manager(ctx context.Context, id int64) (Optional[UserID], error) // the chain
}

type Identities interface {
    Mint(ctx context.Context, userID int64) (IdentityID int64, guid string, err error) // pending_enrollment
    Activate(ctx context.Context, id int64) error                                      // pending -> active
    Rotate(ctx context.Context, userID int64) (guid string, err error)                 // recovery: revoke old, mint new
    Revoke(ctx context.Context, id int64) error                                        // revoke identity AND its sessions
    ByGUID(ctx context.Context, guid string) (Identity, error)                         // tombstoned -> not-found semantics
}

type Sessions interface {
    Mint(ctx context.Context, identityID int64, ip, ua string) (Session, error)
    Validate(ctx context.Context, sessionID string) (Session, error) // rejects empty · expired · revoked  [A2]
    Rotate(ctx context.Context, sessionID string) (Session, error)   // on login
    Revoke(ctx context.Context, sessionID string) error
    RevokeAll(ctx context.Context, identityID int64) error
    GC(ctx context.Context, now time.Time) (int, error)
}

type Audit interface {
    // event: bootstrap · enroll · login · logout · recovery request/approve/deny · revoke
    Record(ctx context.Context, e Event)
}

Every mutating service call writes an audit row, taking actor · client IP · correlation from the context (A11).

---

6. Session lifecycle

• Mint on successful enroll/login → an opaque random id; cookie set by the door (SPEC-003).
• Validate on every request: the row must exist, not expired, not revoked, and the session id must be non-empty (A2).
• Rotate on login (fixation defence). Revoke on logout; RevokeAll when an identity is rotated or revoked (D-007).
• GC expired rows on a schedule — but never the principal's last valid session.

---

7. Acceptance criteria

#	Criterion
AC-1	Two active identities for one user is impossible (index + service)
AC-2	guid is unique; a revoked GUID is never reissued (tombstoned)
AC-3	Sessions.Validate("") → error (empty id rejected, A2)
AC-4	An expired/revoked session → error; RevokeAll kills every session of an identity
AC-5	Identities.Rotate revokes the old identity and all its sessions, and mints a new GUID
AC-6	Creating a user with role = admin when user 1 exists is rejected (one admin, D-034/§7.1)
AC-7	Every service mutation writes an audit_log row (A11)
AC-8	totp_secrets.secret_encrypted is never stored or logged in plaintext (A9)

---

8. Implementation notes (accepted rulings)

Built 2026-10-13. go build · go vet · go test (incl. -race) green; CGO_ENABLED=0 build is a static binary; modernc.org/sqlite in the dep graph, no mattn/go-sqlite3. AC-1…AC-8 all pass.

Architect rulings on the builder's open questions:

#	Question	Ruling
R-1	Services can't populate client_ip/correlation_id (no context in §5).	Thread context.Context + audit.Meta (§5 rewritten). The door attaches the meta. Must land before SPEC-003.
R-2	The CHECK ((role='admin') = (manager_user_id IS NULL)) couples role and manager.	Confirmed intended — the one admin is the root (§7.1/§5.3).
R-3	RevokeAll records an anonymous actor.	Resolved by R-1 — the actor comes from the context (approver/operator/system).
R-4	(raised while building SPEC-003) auth.Mint/Rotate/Revoke hard-code the owning user as actor.	Use the context actor (creator/approver); record the affected user as the subject. Adjust the identity services accordingly.

Accepted deviations (Class B, reversible):

1. Two service types over one auth.Core (IdentitiesService / SessionsService) — one Go type can't hold two same-named methods. Interfaces match §5.
2. Identities.ByGUID also returns revoked rows, so Resolver.GUID() maps a tombstoned GUID to not found (→ 404) while staying auditable.
3. Users.Create(creatorID=0) = the bootstrap path — only while users is empty, only for role=admin. SPEC-005 drives it.
4. Additive helpers not in §5: users.Count/ByEmail, identities.WithinEnrollmentWindow, the TOTP seam (PutTOTPSecret/TOTPSecret/MarkTOTPVerified).
5. Code defaults (config comes later, D-035): session TTL 24h · enrollment window 72h.
6. Enums not enumerated in §4: users.status ∈ {active, disabled}; credential_id as BLOB; transports as comma-text. TOTP sealed with AES-256-GCM.
7. Migration 0002_passkey_opt_out.sql (D-041, 2026-10-14) adds users.passkey_opt_out INTEGER NOT NULL DEFAULT 0 — append-only, 0001_init untouched. Users gains PasskeyOptOut (read) and SetPasskeyOptOut (write, audited user.passkey_opt_out); User carries the field. It is a user preference, so it survives identity rotation (D-008).

Packages added: internal/core/store · internal/core/audit · internal/core/users · internal/core/auth. internal/core/routing tests still pass.