Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@ POSTGRES_USER=postgres
POSTGRES_PASSWORD=change-me-local-only
DATABASE_URL=postgresql+asyncpg://postgres:change-me-local-only@localhost:5432/ai_email
DEBUG=false
AUTH_MODE=hybrid
TRUST_DEV_HEADERS=false
LEGACY_EMAIL_OWNER_USER_ID=
ENCRYPTION_KEY=

# AI features. Leave blank to disable LLM/embedding-backed flows locally.
Expand Down
100 changes: 88 additions & 12 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,15 @@ The backend owns persistence, threading, search, AI summaries, and outbound
send orchestration. The frontend consumes the backend contracts and renders
inbox, detail, thread history, reply composer, and network graph surfaces.

The current frontend shell is organized around three operator-facing work
surfaces: inbox triage, detail/conversation review, and a context/judgment/
execution rail. Desktop now exposes board-style summary cards above the main
workspace, while mobile uses a five-item bottom navigation (`받은 메일`, `맥락
종합`, `판단 포인트`, `실행 항목`, `설정`) and swipe gestures to push email
threads into a persisted per-user `ExecutionItem` queue. The frontend still
keeps a user-scoped local cache for rendering/subscription, but queue creation
and completion now flow through `/api/execution-items`.

## Threading boundary

`backend/services/threading_service.py` is the canonical domain service for
Expand All @@ -23,10 +32,42 @@ documented in `docs/threading-contract.md`.

## Data and tenancy boundary

The current `emails` table does not have an owner/mailbox key. Email and
search behavior should therefore be treated as single-user local-development
behavior. Multi-user production safety requires a schema migration that adds
mailbox ownership and applies that filter to every email/search query.
The current `emails` table now has a minimal owner field (`Email.user_id`) and
the inbox/detail/thread read paths already filter on it. That closes the most
obvious single-user leakage, but it is still only a bridge. Multi-user
production safety still requires a real `Mailbox` aggregate with provider/source
identity plus mailbox/member/org scoped filtering for email, search, network,
attachments, and synthetic routing.

`MailboxAccount` is now the first mailbox-configuration aggregate: multiple
accounts per user, one default reply account, and explicit SMTP/IMAP credentials
separate from the legacy `TenantConfig` singleton. Compose/send flows can now
target a linked mailbox account, but stored emails still need a future
`mailbox_account_id` rollout across every real sync/import path before reply
routing becomes fully automatic for all stored messages. Fixture/ZIP imports now
attempt that routing, and the IMAP worker now enumerates active `MailboxAccount`
rows instead of the legacy singleton config, but real persisted IMAP/POP/OAuth
sync paths are still pending. The inbox
API and UI are now mailbox-aware as well: list items carry `mailbox_account_id`,
the inbox can filter by a linked mailbox account, and rows show their source
account label. Search now follows that same scope and keeps mailbox provenance in
its result items so the UI does not lose account context when a user searches.
During the bridge period, mailbox-filtered thread and search paths include
legacy `mailbox_account_id IS NULL` rows for the authenticated owner so restored
thread context is not lost before the mailbox migration is complete; the inbox UI
labels those bridge rows as `이전 복원 메일` when a mailbox filter is active.
Bootstrap now fails closed if ownerless legacy email rows remain and
`LEGACY_EMAIL_OWNER_USER_ID` is not set, preventing a silent deployment where
existing inbox/search/network data disappears behind the new owner filters.

`MailboxAccount` also now carries POP3 credentials and the background worker
enumerates active POP3 accounts from that aggregate with bounded socket timeouts,
and the app lifecycle now starts/stops that worker beside IMAP. Mailbox-account
create/update also normalizes mailbox strings, blocks internal-network mail
server hosts and non-mail ports, enforces server/port pair invariants, forces
default-reply accounts active, and returns stable 409/503 errors for duplicate
account or missing encryption-key failures. This is still only a
connection/scheduling foundation, not a persisted message ingestion path.

## Local deployment boundary

Expand Down Expand Up @@ -72,12 +113,47 @@ SMTP/IMAP providers as documented in
the current repo and physical replication/WAL restore remain future work per
`docs/operations/postgresql-physical-replication.md`.

Authentication still uses trusted request headers in local/dev, but the backend
now normalizes them into an auth context with `platform_admin`,
`organization_admin`, `group_admin`, and `member` roles plus optional
organization/group scope. This preserves the current `X-User-Id` development
flow while preparing the backend for future Keycloak/Casdoor claims and
organization-scoped resources that should not assume one workspace per user; see
`docs/operations/auth-key-management.md`. The current Kubernetes ingress assumes
NGINX, while Traefik is only an evaluated option in
Authentication is bearer/OIDC-derived at the backend boundary. `hybrid` remains
the fail-closed default and accepts verified bearer claims; `oidc` requires a
verified bearer token; the legacy `header` mode no longer authenticates
client-controlled identity headers. `DEBUG` and `TRUST_DEV_HEADERS` do not make
`X-User-*` request headers authoritative for user, role, organization, group, or
workspace scope. Local developer and live-E2E flows must use signed bearer tokens
or an OIDC provider/session.

In `oidc`/`hybrid`, bearer tokens are normalized into the shared
`AuthContext` with `platform_admin`, `organization_admin`, `group_admin`, and
`member` roles plus optional organization/group scope. The backend currently
accepts HS256 shared-secret tokens and RS256 bearer tokens validated against a
configured JWKS URL, which is enough for staged Keycloak/Casdoor integration.

The frontend no longer emits development identity headers and the legacy dev
identity switcher renders nothing. Admin settings and Prompt Studio controls are
claim-gated in the UI before the backend performs its own authorization checks.
Runner tokens are organization-scoped, while LLM provider access is now
org-scoped through `organization_id`. Shared prompt templates require both
organization scope and a workspace-admin role (`platform_admin` or
`organization_admin`), while user-owned private prompts remain visible to their
creator. Provider-backed prompt testing is also workspace-admin-only because it
uses the organization's configured LLM provider. Legacy provider rows require an
explicit bootstrap migration mapping (`LEGACY_LLM_PROVIDER_ORGANIZATION_ID`)
before they reappear in the new org scoped APIs. See
`docs/operations/auth-key-management.md`. The current
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
Kubernetes ingress assumes NGINX, while Traefik is only an evaluated option in
`docs/operations/traefik-evaluation.md`.

`ExecutionItem` is now a persisted personal queue fed from email swipe/actions.
It is intentionally self-owned (`user_id`) and currently uses a temporary
mailbox ownership check through `Email.user_id`, and list/detail/thread reads in
`/api/emails` now use that same owner field. This is the first real object-scope
boundary, but it is still only a per-user ownership column, not yet a full
`Mailbox` aggregate with account/provider/source provenance.

Execution items now also preserve source mailbox context and an excerpt from the
source email (`source_mailbox_account_id`, `source_snippet`) so the action board
can keep account provenance visible after the email leaves the inbox view.

Calendar sync is authenticated but intentionally has no body-token trust path:
`/api/calendar/sync` ignores any submitted `user_token` and returns 503 until a
server-side per-user calendar credential store is implemented. That keeps the UI
action honest without turning app identity claims into Google OAuth credentials.
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
## [Unreleased]

### 보안
- Seongho Bae (@seonghobae): backend 인증 경로에서 client-controlled `X-User-*` 개발 헤더 신뢰를 제거하고, 로컬/테스트 흐름을 서명된 bearer/OIDC claims 기반으로 전환했습니다.

## [0.14.1] - 2026-05-13

### 수정
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,15 +76,15 @@ Errors should tell a contributor what failed and avoid leaking internals:

## Current scope contract

This repo still uses trusted header auth in local/dev and does not persist an owner/mailbox key on email rows. The backend now derives an auth context with platform/organization/group/member scopes, but email data should still be treated as single-user development data until a mailbox ownership migration is added.
This repo now derives backend auth context from verified bearer/OIDC claims, not trusted local/dev identity headers. Email rows have a bridge owner field, but email data should still be treated as pre-production multi-user data until the full mailbox ownership migration lands.

## Operations and release docs

- `docs/operations/release-deployment-architecture.md`: release, CI, GHCR, and live E2E evidence path.
- `docs/operations/open-source-apm.md`: OpenTelemetry, Prometheus, Grafana, Loki, Tempo/Jaeger adoption plan.
- `docs/operations/email-relay-proxy-boundary.md`: Naruon is a web client relay/proxy, not an email server.
- `docs/operations/postgresql-physical-replication.md`: physical replication, WAL, restore, and read-routing plan.
- `docs/operations/auth-key-management.md`: dummy auth boundary, Fernet key management, Keycloak/Casdoor evaluation.
- `docs/operations/auth-key-management.md`: bearer/OIDC auth boundary, Fernet key management, Keycloak/Casdoor evaluation.
- `docs/operations/traefik-evaluation.md`: Traefik versus current NGINX ingress evaluation.

## Verification used for this hardening pass
Expand Down
Loading
Loading