Skip to main content

​
Context

Proving who you are and staying proven are different problems. Authentication (FS-IDN-0003) is a credential exchange that happens once; a session is a standing claim that has to be revocable, inspectable and bounded — and it is what an attacker actually steals. The tension is a familiar one: short sessions are safer and drive users to weaken their own security out of irritation. The resolution here is a long session with re-authentication on sensitive actions, so daily work is uninterrupted while the operations that matter ask again. An organization-scoped detail follows from FS-IDN-0001: a user in three organizations has sessions that can be revoked per organization. Deactivating someone from one account must not sign them out of the other two.

​
Scope (normative)

  • identity.sessions with device, IP, user agent and expiry.
  • Session listing and per-session revocation by the user.
  • Bulk revocation on password change, MFA change and membership deactivation.
  • Re-authentication prompts on sensitive actions.
  • Organization-scoped revocation.
  • Suspicious-session detection: a new device or a distant location notifies the user.

​
Non-scope (normative)

  • Machine credentials — FS-IDN-0006. An API key is not a session and has no device.
  • Member sessions, which live in core.
  • IP allowlisting, which is a per-tenant hardening option (DEC-D6) and belongs to a later security policy feature.

​
Behaviour (normative)

  1. A session records device, IP and user agent at creation and updates last_seen_at. The user can see all of it — a session list that does not say where is not actionable.
  2. Sessions are revocable individually, in bulk, and per organization. Revocation takes effect on the next request, never on the next cache expiry.
  3. A revoked session is never deleted: the row is retained with revoked_at and the reason, because “when did that access stop” is an incident question.
  4. Sensitive actions re-prompt for authentication regardless of session age: changing a password, changing MFA, creating or rotating an API key, granting a sensitive permission, starting an impersonation. The list is in the code as a decorator, not in a document that drifts.
  5. A password change, an MFA change or a membership deactivation revokes the relevant sessions automatically and notifies the user.
  6. A sign-in from an unrecognised device notifies the user by email. Notification, not blocking: blocking on a new device makes travel a support ticket.
  7. Session tokens are opaque, hashed at rest, and rotated on privilege change so a token captured before a role change cannot use the new role.
  8. Expiry is absolute, not only idle. An idle-only session lives forever on a machine nobody uses.

​
Data (normative)

​
API (normative)

​
Events (normative)

None on the outbox. Session lifecycle is audit-logged; new-device notifications go through messaging as a product category message, driven by the audit entry rather than a domain event.

​
Acceptance criteria (normative)

  1. A revoked session is rejected on its very next request.
  2. Revoking a session for organization A leaves the same user’s session for organization B valid.
  3. A password change revokes every other session and leaves the current one alive.
  4. Every sensitive action re-prompts, proven by a test that enumerates the decorated routes.
  5. A token captured before a role change cannot exercise the new role.
  6. A revoked session row is still readable a year later with its reason.
  7. A sign-in from an unrecognised device produces exactly one notification.
  8. Negative: no session survives its absolute expiry, however recently it was used.

​
Execution

Single slice, synchronous command. Session storage is Better Auth’s with our columns added; validation is cached in Upstash with revocation invalidating the entry.

​
Open questions

​
Changelog

​
Delivery record

Not implemented yet.