Domain Example

type: domain
id: auth
title: Authentication
status: draft
tags: [auth, security]
context: []


{% tldr scope="agent" %}
Models user identity and session management. Exposes actions for credential validation
and session lifecycle. Source of truth for all authentication-related data.
{% /tldr %}

{% domain id="auth" scope="agent" %}

  {% glossary %}
    {% term id="Session" %}An authenticated user context with a finite expiry.{% /term %}
    {% term id="Credential" %}An email + password pair used for identity verification.{% /term %}
  {% /glossary %}

  {% model %}
  ```dbml
  Table users {
    id         uuid        [pk,     note: "Primary identifier"]
    email      varchar     [unique, note: "Used as login identifier"]
    status     user_status [        note: "active | locked | suspended"]
    created_at timestamp

    Note: "User aggregate. Handles RegisterUser and LockAccount."
  }

  Table sessions {
    id         uuid      [pk]
    user_id    uuid      [ref: > users.id, note: "Owning user"]
    token      varchar   [unique]
    expires_at timestamp
    created_at timestamp

    Note: "Session aggregate. Handles CreateSession and ExpireSession."
  }

  Enum user_status {
    active    [note: "Normal access"]
    locked    [note: "Locked after repeated failures"]
    suspended [note: "Administratively suspended"]
  }
  ```
  {% /model %}

  {% api %}
    {% error id="invalid-credentials" code="INVALID_CREDENTIALS" %}
    The email/password combination is incorrect.
    {% /error %}

    {% operation name="login" type="write" %}
    In-process login operation that returns a session.

    {% property name="email" type="string" required=true /%}
    {% property name="password" type="string" required=true /%}

    {% returns %}
      {% property name="session-token" type="string" required=true /%}
      {% property name="expires-at" type="iso8601" required=true /%}
    {% /returns %}

    {% throws ref="invalid-credentials" /%}
    {% /operation %}

    {% action name="expire-session" %}
    Marks a session as expired. Triggered by timeout policy or explicit sign-out.
    {% /action %}

    {% event name="user-authenticated" %}
    Payload: `{ userId: string, sessionToken: string, expiresAt: string }`.
    {% /event %}

    {% event name="session-expired" %}
    Payload: `{ sessionId: string, userId: string }`.
    {% /event %}
  {% /api %}

{% /domain %}