Org Web Adapter

Editing hungryroot/scagent/conversation-session-ownership.org

:PROPERTIES:
:ID:       1df45111-5512-4360-ac81-76648e81eb23
:END:
#+title: scagent Conversations: session-based ownership (anonymous funnel)

* scagent Conversations: session-based ownership (anonymous funnel)
:PROPERTIES:
:CUSTOM_ID: scagent-conversations-session-based-ownership-anonymous-funnel
:END:
This document describes how =scagent= conversations are scoped to either
an authenticated *=Customer=* or an opaque client-generated *anonymous
session identifier*, so funnel flows can persist conversations before a
user logs in.

** Problem
:PROPERTIES:
:CUSTOM_ID: problem
:END:
Previously, =Conversation= stored a required *=customer=* foreign key,
and the conversations API required authentication keyed off
=request.user.customer=. That model could not represent chats that
belong only to a browser or app session (for example signup funnel UX)
where no =Customer= exists yet.

** Goals
:PROPERTIES:
:CUSTOM_ID: goals
:END:
- Store conversations owned by *=Customer=* when the client is
  authenticated, unchanged for existing behaviors.
- Store conversations keyed by a *=anonymous_session_id=* when there is
  no customer, using an identifier generated and held by the client (not
  Django's =session_key= unless the client chooses to use that value).
- Enforce access control so a caller can only list, read, or mutate
  conversations that match their identity (customer or session),
  analogous to the prior “no eavesdropping” guarantee for
  customer-scoped rows.

** Non-goals (current implementation)
:PROPERTIES:
:CUSTOM_ID: non-goals-current-implementation
:END:
- *Post-login merge*: automatically reassigning anonymous conversations
  to a =Customer= after signup is not implemented; that can be a
  separate workflow if product needs funnel history surfaced in-account.
- *Rate limiting / signed tokens*: the API accepts opaque session
  strings; additional abuse mitigation (throttling, HMAC-signed session
  tokens from a funnel bootstrap service, etc.) is left to operational
  and product decisions.

** Data model
:PROPERTIES:
:CUSTOM_ID: data-model
:END:
Implementation:
[[../../scagent/models.py][=scagent.models.Conversation=]].

| Field                  | Role                                                                                                                     |
|------------------------+--------------------------------------------------------------------------------------------------------------------------|
| =customer=             | Optional =ForeignKey= to =app.Customer=. Set when the conversation is owned by a logged-in user with a related customer. |
| =anonymous_session_id= | Optional =CharField= (=max_length=64=, indexed). Opaque identifier from the client when there is no =customer=.          |

*Integrity*

- Exactly one of =customer_id= *or* =anonymous_session_id= must be set
  (database *=CheckConstraint=*, XOR).
- When =anonymous_session_id= is not null it must be *non-empty* (second
  *=CheckConstraint=*).
- At the application layer, =Conversation.clean()= aligns with the same
  rules.

=external_conversation_id= remains the agent's unique conversation id
(globally unique as before).

** API behavior
:PROPERTIES:
:CUSTOM_ID: api-behavior
:END:
Implementation:
[[../../scagent/views/conversations.py][=scagent.views.conversations=]].

*** Authentication and permission
:PROPERTIES:
:CUSTOM_ID: authentication-and-permission
:END:
- *Authenticated users* with a linked *=Customer=*
  (=request.user.customer=): full access to conversations where
  =conversation.customer= matches that customer. The anonymous session
  header is *not* used for authorization in this path (even if present).
- *Authenticated users* without a *=Customer=* (for example staff or
  service principals): *cannot* use the anonymous session header to
  access these APIs; they receive *403* even when
  *=scagent.anonymous_session_auth_enabled=* is on and
  *=X-Anonymous-Session-Id=* is sent.
- *Unauthenticated clients* can only use the conversations API when
  dynamic config *=scagent.anonymous_session_auth_enabled=*
  (=BoolDynamicConfigEnum.ENABLE_SCAGENT_ANONYMOUS_SESSION_AUTH=) is
  active. When it is off, those requests receive *403* even if
  *=X-Anonymous-Session-Id=* is present. When it is on, callers must
  send a non-empty *=X-Anonymous-Session-Id=* on every request;
  permission is denied if the header is missing or blank (*403*).

*** Header
:PROPERTIES:
:CUSTOM_ID: header
:END:
| Header                   | Meaning                                                                                                                                                                           |
|--------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| =X-Anonymous-Session-Id= | Opaque string (for example a UUID) that identifies the funnel session. Must be sent consistently for create, list, retrieve, =add_message=, and =tool_calls= for anonymous flows. |

Create *does not* accept =anonymous_session_id= in the JSON body; the
server sets it from the header.

*** Query scoping
:PROPERTIES:
:CUSTOM_ID: query-scoping
:END:
- Customer path: =Conversation.objects.filter(customer=user.customer)=.
- Anonymous path:
  =Conversation.objects.filter(anonymous_session_id=<header>, customer__isnull=True)=.

Wrong session or another user's conversation yields *404* on detail
actions (same pattern as before for cross-customer access).

*** Messages
:PROPERTIES:
:CUSTOM_ID: messages
:END:
For user-authored messages (no =agent_identifier=), =Message.customer=
is set only when the request user is authenticated with a customer;
otherwise the message's =customer= stays null.

*** OpenAPI
:PROPERTIES:
:CUSTOM_ID: openapi
:END:
=drf-spectacular= documents the optional =X-Anonymous-Session-Id= header
on the conversations viewset.

** Security and logging
:PROPERTIES:
:CUSTOM_ID: security-and-logging
:END:
- Client-generated ids can be guessed or enumerated at scale; treat
  abuse controls (rate limits, signed tokens, funnel-only origins) as
  follow-up work if traffic warrants it.
- Avoid logging raw session identifiers in high-volume logs; use
  correlation ids or short hashes where project security guidelines
  require it.

** Migrations
:PROPERTIES:
:CUSTOM_ID: migrations
:END:
- =scagent/migrations/0005_conversation_anonymous_session.py= ---
  nullable =customer=, =anonymous_session_id=, XOR constraint.
- =scagent/migrations/0006_conversation_anon_nonempty_constraint.py= ---
  nonempty constraint for =anonymous_session_id=.

** Related code
:PROPERTIES:
:CUSTOM_ID: related-code
:END:
- Admin: [[../../scagent/admin.py][=scagent.admin=]] --- list display
  and search include =anonymous_session_id=.
- Tests:
  [[../../scagent/tests/views/test_conversations.py][=scagent.tests.views.test_conversations=]]
  --- =AnonymousConversationTestCase= (anonymous flows with the flag
  enabled), =AuthenticatedWithoutCustomerConversationTestCase= (*403*
  for authenticated users without a Customer even when the flag is on),
  =AnonymousConversationAuthFlagDisabledTestCase= (unauthenticated
  requests get *403* when the flag is off), and existing customer-scoped
  cases.